Expressions

Guideline: Avoid as underscore pointer casts gui_HDnAZ7EZ4z6G

status: draft tags: readability, reduce-human-error category: required fls: fls_1qhsun1vyarz decidability: decidable scope: module release: <TODO> child needs: rat_h8LdJQ1MNKu9, non_compl_ex_V37Pl103aUW4, compl_ex_W08ckDrkOhkt

Code must not rely on Rust’s type inference when doing explicit pointer casts via var as Type or core::mem::transmute. Instead, explicitly specify the complete target type in the as expression or core::mem::transmute call expression. Rationale: rat_h8LdJQ1MNKu9 status: draft parent needs: gui_HDnAZ7EZ4z6G var as Type casts and core::mem::transmutes between raw pointer types are generally valid and unchecked by the compiler as long the target pointer type is a thin pointer. Not specifying the concrete target pointer type allows the compiler to infer it from the surroundings context which may result in the cast accidentally changing due to surrounding type changes resulting in semantically invalid pointer casts. Raw pointers have a variety of invariants to manually keep track of. Specifying the concrete types in these scenarios allows the compiler to catch some of these potential issues for the user. Non-Compliant Example: non_compl_ex_V37Pl103aUW4 status: draft parent needs: gui_HDnAZ7EZ4z6G The following code leaves it up to type inference to figure out the concrete types of the raw pointer casts, allowing changes to with_base’s function signature to affect the types the function body of non_compliant_example without incurring a compiler error. #[repr(C)] struct Base { position: (u32, u32) } #[repr(C)] struct Extended { base: Base, scale: f32 } fn non_compliant_example(extended: &Extended) { let extended = extended as *const _; with_base(unsafe { &*(extended as *const _) }) } fn with_base(_: &Base) { ... } Compliant Example: compl_ex_W08ckDrkOhkt status: draft parent needs: gui_HDnAZ7EZ4z6G We specify the concrete target types for our pointer casts resulting in a compilation error if the function signature of with_base is changed. #[repr(C)] struct Base { position: (u32, u32) } #[repr(C)] struct Extended { base: Base, scale: f32 } fn non_compliant_example(extended: &Extended) { let extended = extended as *const Extended; with_base(unsafe { &*(extended as *const Base) }) } fn with_base(_: &Base) { ... }

Guideline: Do not use builtin integer arithmetic expressions gui_7y0GAMmtMhch

status: draft tags: numerics category: required fls: fls_Q9dhNiICGIfr decidability: decidable scope: module release: latest child needs: rat_vLFlPWSCHRje, non_compl_ex_0XeioBrgfh5z, compl_ex_k1CD6xoZxhXb

This guideline applies when an ArithmeticExpression is used with operands of integer type. Rationale: rat_vLFlPWSCHRje status: draft parent needs: gui_7y0GAMmtMhch The built-in semantics for these expressions can result in panics, or silent wraparound upon overflow or division by zero occurs. It is recommended to explicitly declare what should happen during these events with checked arithmetic functions. Non-Compliant Example: non_compl_ex_0XeioBrgfh5z status: draft parent needs: gui_7y0GAMmtMhch When the division is performed, the right operand is evaluated to zero and the program panics. When the addition is performed, either silent overflow happens or a panic depending on the build configuration. let x = 0; let x = 5 / x; let y = 135u8 let y = 200u8 + y; Compliant Example: compl_ex_k1CD6xoZxhXb status: draft parent needs: gui_7y0GAMmtMhch The developer must explicitly indicate the intended behavior when a division by zero or arithmetic overflow occurs when using checked arithmetic methods. let x = 0; let result = match 5u32.checked_div(x) { None => 0 Some(r) => r } let y = 135u8 let y = 200u8.wrapping_add(y);

Guideline: Do not use unchecked integer arithmetic methods gui_mNEvznFjC3kG

status: draft tags: numerics category: advisory fls: fls_Q9dhNiICGIfr decidability: decidable scope: module release: latest child needs: rat_7tF18FIwSYws, non_compl_ex_JeRRIgVjq8IE, compl_ex_HIBS9PeBa41c

This guideline applies to any call to the integer type methods that begin with unchecked_. Rationale: rat_7tF18FIwSYws status: draft parent needs: gui_mNEvznFjC3kG The semantics for these expressions can result in panics, or silent wraparound upon overflow or division by zero occurs. It is recommended to explicitly declare what should happen during these events with checked arithmetic functions. In a particularly performance sensitive critical section of the code it may be necessary to use the unchecked methods in tandem with assurances that the arguments will never meet the panic conditions. Non-Compliant Example: non_compl_ex_JeRRIgVjq8IE status: draft parent needs: gui_mNEvznFjC3kG When the multiplication is performed, the evaluation could encounter wrapping or a panic that is not handled explicitly. let x = 13u8.unchecked_mul(y); Compliant Example: compl_ex_HIBS9PeBa41c status: draft parent needs: gui_mNEvznFjC3kG If arithmetic overflow would have occurred during the multiplication operation this method will ensure that the returned value is the bounding of the type. The intention is clear in that case. let x = 13u8.saturating_mul(y);