[Guideline] Add checked arithmetic guidelines #136

vapdrs · 2025-06-24T19:29:13Z

Add two new guidlelines disallowing most ArithmeticExpressions and unchecked arithmetic. The reason there are two rules is such that if a project really needs the performance afforded by unchecked_mul, they can disregard the advisory rule and use the required one.

netlify · 2025-06-24T19:29:17Z

✅ Deploy Preview for scrc-coding-guidelines ready!

Name	Link
🔨 Latest commit	`b2a3143`
🔍 Latest deploy log	https://app.netlify.com/projects/scrc-coding-guidelines/deploys/685bf59cf5775200086d6eff
😎 Deploy Preview	https://deploy-preview-136--scrc-coding-guidelines.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

vapdrs · 2025-06-24T20:01:32Z

The check_typos job seems to have encountered a false positive looking at one of the ids

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

felix91gr · 2025-06-26T21:55:11Z

src/coding-guidelines/expressions.rst

+   This guideline applies when an ArithmeticExpression is used with operands whose types evaluates integer or
+   floating-point types.


You know, I'm not sure floating-point types fit here.

One one hand, the f32 and other such types are defined to be compliant with a specific IEEE standard.

On the other hand, neither looking at that type's methods nor doing a search for checked_ methods in stdlib I've been able to find anything like the safe/checked operations we have for integer types. I suspect they do not exist for floats.

Suggested change

This guideline applies when an ArithmeticExpression is used with operands whose types evaluates integer or

floating-point types.

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

floating-point type.

I think I agree I would separate integer from floating point types.

felix91gr · 2025-06-26T21:55:50Z

src/coding-guidelines/expressions.rst

+   .. rationale::
+      :id: rat_vLFlPWSCHRje
+      :status: draft
+
+      The built-in semantics for these expressions can result in panics, or silent wraparound when overflow,
+      underflow, or division by zero occurs. It is better to explicitly declare what should happen during
+      these events with checked arithmetic functions.


This seems perfect to me 👌

Underflow is only a condition that occurs during floating point operations. Integers can only overflow. At least that's true in C.

Suggested change

.. rationale::

:id: rat_vLFlPWSCHRje

:status: draft

The built-in semantics for these expressions can result in panics, or silent wraparound when overflow,

underflow, or division by zero occurs. It is better to explicitly declare what should happen during

these events with checked arithmetic functions.

.. rationale::

:id: rat_vLFlPWSCHRje

:status: draft

The built-in semantics for these expressions can result in panics, or silent wraparound when overflow,

underflow, or division by zero errors.

Explicitly declare what should happen during using checked arithmetic functions.

Underflow is only a condition that occurs during floating point operations. Integers can only overflow. At least that's true in C.

I think that's true, but it's only true regarding the name – Underflow does occur in Rust, in the sense of attempting to go below the minimum value, but (I've just come to realize) we call it Overflow just the same.

Underflow is typically a floating point property. Floating point is really weird though because almost nothing is an error if you anticipate it.

Floating point is really weird though because almost nothing is an error if you anticipate it.

I have so many questions. Though floating point handling and its semantics are outside the topic of this PR. I'd like to ask you about floats in the context of SC. Are you perchance in the rust-lang Zulip?

felix91gr · 2025-06-26T21:57:46Z

src/coding-guidelines/expressions.rst

+   .. 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.
+
+      .. code-block:: rust
+
+         let x = 0;
+         let x = 5 / x;
+
+   .. compliant_example::
+      :id: compl_ex_k1CD6xoZxhXb
+      :status: draft
+
+      If an overflow occurs, it is explicit that the addition should wrap.
+
+      .. code-block:: rust
+
+         let y = 135u8
+         let x = 200u8.wrapping_add(y);
+


Is the document allowed to have more than one non-compliant and more than one compliant example?

Since this guideline covers both the divide-by-zero and the arithmetic-overflow cases, I think it's only natural that it would have an example for both :)

you should have a compliant solution corresponding to each noncompliant example. For example, how do I deal with divide by zero on a compliant solution. Also show the incorrect version of the wrapping example.

felix91gr · 2025-06-26T22:04:58Z

src/coding-guidelines/expressions.rst

+   :id: gui_mNEvznFjC3kG
+   :category: advisory
+   :status: draft
+   :release: latest
+   :fls: fls_Q9dhNiICGIfr
+   :decidability: decidable
+   :scope: module
+   :tags: numerics
+
+   This guideline applies to ArithmeticExpressions as well as any call to the integer or floating point type
+   methods that begin with `unchecked_`.
+
+   .. rationale::
+      :id: rat_7tF18FIwSYws
+      :status: draft
+
+      The built-in semantics for these expressions can result in panics, or silent wraparound when overflow,
+      underflow, or division by zero occurs. It is better to explicitly declare what should happen during
+      these events with checked arithmetic functions.
+
+   .. 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
+
+      When the addition is performed, the overflow will be detected and the author will need to explicitly
+      deal with the Option value returned.
+
+      .. code-block:: rust
+
+         let y = 135u8
+         let x = 200u8.checked_add(y);
+


There are many unchecked functions in stdlib. I reckon we might want to add a rule against all of them? I'm not sure. Some of them might be reasonable for SC contexts.

Regardless: just like for the rule above, the unchecked_ arithmetic functions mentioned here only exist for integer types. Floats do have a to_int_unchecked method, though.

felix91gr · 2025-06-26T22:16:48Z

Resolves #20

Add checked arithmetic guidelines

06933f9

vapdrs mentioned this pull request Jun 24, 2025

[Guideline] Add do not divide by 0 #132

Open

vapdrs mentioned this pull request Jun 24, 2025

Install typos GHA and fix typos #129

Merged

Add more typo ignore patterns

b2a3143

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

vapdrs changed the title ~~Add checked arithmetic guidelines~~ [Guideline] Add checked arithmetic guidelines Jun 25, 2025

felix91gr mentioned this pull request Jun 26, 2025

Define the tag "decidability" #139

Open

felix91gr reviewed Jun 26, 2025

View reviewed changes

felix91gr mentioned this pull request Jun 26, 2025

std::i32::MIN % -1 and related #20

Open

		This guideline applies when an ArithmeticExpression is used with operands whose types evaluates integer or
		floating-point types.

[Guideline] Add checked arithmetic guidelines #136

Are you sure you want to change the base?

[Guideline] Add checked arithmetic guidelines #136

Uh oh!

Conversation

vapdrs commented Jun 24, 2025

Uh oh!

netlify bot commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for scrc-coding-guidelines ready!

Uh oh!

vapdrs commented Jun 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felix91gr commented Jun 26, 2025

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

netlify bot commented Jun 24, 2025 •

edited

Loading