Skip to content

docs: clarify that float Rem formula uses exact arithmetic#153981

Open
mango766 wants to merge 1 commit intorust-lang:mainfrom
mango766:fix-rem-float-doc-misleading-formula
Open

docs: clarify that float Rem formula uses exact arithmetic#153981
mango766 wants to merge 1 commit intorust-lang:mainfrom
mango766:fix-rem-float-doc-misleading-formula

Conversation

@mango766
Copy link

@mango766 mango766 commented Mar 17, 2026

Summary

Fixes #133758.

The documentation for <{f16,f32,f64,f128} as Rem>::rem previously described the remainder as being "computed as: x - (x / y).trunc() * y", which reads as a literal Rust expression. In reality, the operation is mathematically defined as exact x - trunc(x/y) * y (computed in infinite precision, then rounded to the result type), equivalent to C's fmod. Evaluating the expression literally in Rust produces different results for many inputs due to intermediate floating-point rounding.

For example, as noted in the issue:

let (x, y) = (11f64, 1.1f64);
// These are NOT equal:
assert_eq!(x - (x / y).trunc() * y, x % y);  // panics: left=0.0, right≈1.1

This PR:

  • Rewrites the formula using mathematical notation (trunc(x / y)) rather than Rust method syntax, making it clear this is not meant as literal code
  • Explicitly states the computation uses infinite precision arithmetic
  • Adds a note explaining why the literal Rust expression differs
  • Simplifies the example to avoid suggesting the expressions are equivalent

This aligns with the consensus in #133758 and the IEEE 754 / C fmod semantics documented in RFC 3514.

…semantics

The documentation for `<float as Rem>::rem` previously presented the
formula `x - (x / y).trunc() * y` as if it were a Rust expression, but
this operation is actually computed using infinite precision (exact)
arithmetic, then rounded to the result type (equivalent to C's `fmod`).

Evaluating the expression literally in Rust can produce different results
due to intermediate rounding at each floating-point operation.

This clarifies the docs to explicitly state the formula is mathematical
and notes the discrepancy with the literal Rust expression. The example
is also simplified to avoid suggesting the two are equivalent.

Fixes rust-lang#133758

Co-Authored-By: Claude (claude-opus-4-6) <noreply@anthropic.com>
@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Mar 17, 2026
@rustbot
Copy link
Collaborator

rustbot commented Mar 17, 2026

r? @joboet

rustbot has assigned @joboet.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

  • Owners of files modified in this PR: @scottmcm, libs
  • @scottmcm, libs expanded to 8 candidates
  • Random selection from Mark-Simulacrum, joboet, scottmcm

@rustbot
Copy link
Collaborator

rustbot commented Mar 17, 2026

⚠️ Warning ⚠️

  • There are issue links (such as #123) in the commit messages of the following commits.
    Please move them to the PR description, to avoid spamming the issues with references to the commit, and so this bot can automatically canonicalize them to avoid issues with subtree.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

<{f16,f32,f64,f128} as Rem>::rem documented definition is misleading w.r.t. intermediate rounding

3 participants