[Guideline] Add safe division guideline to avoid dividing by zero (rustfoundation#136)

* Add checked arithmetic guidelines

* Add more typo ignore patterns

These correspond to the unique ID's for each section.

* Remove floating point types from these guidelines

* Ensure example match

* Add statement to rationale justifying the Advisory

* Correct typos

* Update comment for directive typo check

Co-authored-by: Pete LeVasseur <plevasseur@gmail.com>

* Expound upon `unchecked_` functions

Additionally the code block formatting was updating, and a link was added.

Co-authored-by: Pete LeVasseur <plevasseur@gmail.com>

* Fix grammar of wrap around

* Change sphinx link syntax

* Add link to FLS ArithmeticExpression

* Correct description of unchecked function

As pointed out, they result in UB not necessarily panics

* Remove other mention of panics

* Narrow guideline to just integer division.

* Remove guideline on unchecked methods

As those are marked unsafe anyway

* Add remainder expression example

* Downgrade this to an advisory guideline

It could get annoying in existing codebases

* Fix missing commas for syntax

* Add subset tag

* Word choice as suggested by Felix

* Formatting

* Apply suggestions from code review

Spelling and word choice from review

Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>

* Example clarification from code review

Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>

* Note clarity and rewording

Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>

---------

Co-authored-by: Pete LeVasseur <plevasseur@gmail.com>
Co-authored-by: Félix Fischer <felix91gr@users.noreply.github.com>

Author: 3 people

_typos.toml

@@ -1,6 +1,9 @@
 [default]
 extend-ignore-identifiers-re = [
-  # Ignore things that look like gui_xztNdXA2oFNB
+  # Ignore Sphinx directives for typos
   "gui_.*",
+  "rat_.*",
+  "compl_ex_.*",
+  "non_compl_ex_.*",
 ]
 

src/coding-guidelines/expressions.rst

@@ -82,6 +82,70 @@ Expressions
 
          fn with_base(_: &Base) { ... }
 
+.. guideline:: Do not use integer type as divisor
+   :id: gui_7y0GAMmtMhch
+   :category: advisory
+   :status: draft
+   :release: latest
+   :fls: fls_Q9dhNiICGIfr
+   :decidability: decidable
+   :scope: module
+   :tags: numerics, subset
+
+   This guideline applies when a `DivisionExpression
+   <https://rust-lang.github.io/fls/expressions.html#syntax_divisionexpression>`_ or `RemainderExpression
+   <https://rust-lang.github.io/fls/expressions.html#syntax_remainderexpression>`_ is used with a RightOperand of
+   `integer type <https://rust-lang.github.io/fls/types-and-traits.html#integer-types>`_.
+
+   .. rationale::
+      :id: rat_vLFlPWSCHRje
+      :status: draft
+
+      The built-in semantics for these expressions can result in panics when division by zero occurs. It is
+      recommended to either:
+
+      * Use checked division functions, which ensure the programmer handles the case when the divisor is zero, or
+      * To create divisors using :std:`std::num::NonZero`, which then allows the programmer to perform those
+        operations knowing that their divisor is not zero.
+
+      **Note:** since the compiler can assume the value of a :std:`std::num::NonZero`
+      variable to not be zero, checks for zero when dividing by it can be elided in the
+      final binary, increasing overall performance beyond what normal division can have.
+
+   .. non_compliant_example::
+      :id: non_compl_ex_0XeioBrgfh5z
+      :status: draft
+
+      When either the division or remainder are performed, the right operand is evaluated to zero and the
+      program panics.
+
+      .. code-block:: rust
+
+         let x = 0;
+         let y = 5 / x; // This line will panic.
+         let z = 5 % x; // This line would also panic.
+
+   .. compliant_example::
+      :id: compl_ex_k1CD6xoZxhXb
+      :status: draft
+
+      There is no compliant way to divide with an integer type. Here, instead, the developer explicitly:
+
+      * Uses a checked division function, which ensures a zero divisor is handled separately, and
+      * Creates a divisor using :std:`std::num::NonZero`, which outsources the check for zero to the
+        construction of that struct. It's worth noting that such a divisor can be used multiple times after it's been created, whilst keeping the guarantee that such divisions will be safe.
+
+      .. code-block:: rust
+
+         let x = 0;
+         if let Some(divisor) = match NonZero::<u32>::new(x) {
+           let result = 5 / divisor;
+         }
+         let result = match 5u32.checked_rem(x) {
+           None => 0,
+           Some(r) => r,
+         }
+
 
 .. guideline:: Do not divide by 0
    :id: gui_kMbiWbn8Z6g5