Skip to content
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
06933f9
Add checked arithmetic guidelines
vapdrs Jun 24, 2025
b2a3143
Add more typo ignore patterns
vapdrs Jun 24, 2025
8d2392d
Remove floating point types from these guidelines
vapdrs Jun 27, 2025
752ba7a
Ensure example match
vapdrs Jun 27, 2025
9d1e817
Add statement to rationale justifying the Advisory
vapdrs Jun 27, 2025
1ad9181
Correct typos
vapdrs Jun 27, 2025
ee853e0
Update comment for directive typo check
vapdrs Jul 14, 2025
03d7bbc
Expound upon `unchecked_` functions
vapdrs Jul 14, 2025
9dc042f
Fix grammar of wrap around
vapdrs Jul 14, 2025
357c012
Change sphinx link syntax
vapdrs Jul 14, 2025
36f60e2
Add link to FLS ArithmeticExpression
vapdrs Jul 14, 2025
2fb316f
Correct description of unchecked function
vapdrs Jul 16, 2025
9291002
Remove other mention of panics
vapdrs Jul 16, 2025
c9254d0
Merge remote-tracking branch 'upstream/main' into feature/use-check-a…
vapdrs Jul 17, 2025
b28f8ce
Narrow guideline to just integer division.
vapdrs Jul 31, 2025
296df27
Remove guideline on unchecked methods
vapdrs Jul 31, 2025
bc8ed67
Merge remote-tracking branch 'upstream/main' into feature/use-check-a…
vapdrs Jul 31, 2025
fbb4429
Add remainder expression example
vapdrs Aug 6, 2025
c2669a7
Downgrade this to an advisory guideline
vapdrs Aug 6, 2025
e6c1aaf
Fix missing commas for syntax
vapdrs Aug 7, 2025
ef44809
Add subset tag
vapdrs Aug 11, 2025
557bb5c
Merge remote-tracking branch 'upstream/main' into feature/use-check-a…
vapdrs Aug 11, 2025
4a2e017
Merge remote-tracking branch 'upstream/main' into feature/use-check-a…
vapdrs Aug 11, 2025
34dc8a9
Word choice as suggested by Felix
vapdrs Aug 12, 2025
11662cf
Formatting
vapdrs Aug 12, 2025
52834f8
Apply suggestions from code review
vapdrs Aug 15, 2025
cd22b39
Example clarification from code review
vapdrs Aug 15, 2025
e9cdb3b
Note clarity and rewording
vapdrs Aug 25, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions _typos.toml
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,8 @@
extend-ignore-identifiers-re = [
# Ignore things that look like gui_xztNdXA2oFNB
"gui_.*",
"rat_.*",
"compl_ex_.*",
"non_compl_ex_.*",
]

98 changes: 98 additions & 0 deletions src/coding-guidelines/expressions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -81,3 +81,101 @@ Expressions
}

fn with_base(_: &Base) { ... }

.. guideline:: Do not use builtin integer arithmetic expressions
:id: gui_7y0GAMmtMhch
:category: required
:status: draft
:release: latest
:fls: fls_Q9dhNiICGIfr
:decidability: decidable
:scope: module
:tags: numerics

This guideline applies when an `ArithmeticExpression` is used with operands of integer type.

.. rationale::
:id: rat_vLFlPWSCHRje
:status: draft

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::
:id: non_compl_ex_0XeioBrgfh5z
:status: draft

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.

.. code-block:: rust

let x = 0;
let x = 5 / x;
let y = 135u8
let y = 200u8 + y;

.. compliant_example::
:id: compl_ex_k1CD6xoZxhXb
:status: draft

The developer must explicitly indicate the intended behavior when a division by zero or arithmetic
overflow occurs when using checked arithmetic methods.

.. code-block:: rust

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
:id: gui_mNEvznFjC3kG
:category: advisory
:status: draft
:release: latest
:fls: fls_Q9dhNiICGIfr
:decidability: decidable
:scope: module
:tags: numerics

This guideline applies to any call to the integer type methods that begin with `unchecked_`.

.. rationale::
:id: rat_7tF18FIwSYws
:status: draft

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::
:id: non_compl_ex_JeRRIgVjq8IE
:status: draft

When the multiplication is performed, the evaluation could encounter wrapping or a panic that is not
handled explicitly.

.. code-block:: rust

let x = 13u8.unchecked_mul(y);

.. compliant_example::
:id: compl_ex_HIBS9PeBa41c
:status: draft

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.

.. code-block:: rust

let x = 13u8.saturating_mul(y);