doc: expand description for f32 and f64 associated constants

[tspiteri]

This explains the meaning of some of the floating-point associated constants.

[rustbot]

r? @Mark-Simulacrum

(rustbot has picked a reviewer for you, use r? to override)

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[tspiteri]

Rendered f64:

[fmease]

Thanks for the improvements! :)

[Mark-Simulacrum]

I admit I've not paged discussion on #89238 into cache, but since that annotates this with "A minimum number of significant digits in base 10." it feels somewhat surprising to have "maximum" here.

cc @workingjubilee

(Perhaps the language is actually equivalent, I would need to actually thoroughly understand what the significance is to make a call there).

[tspiteri]

If I understand correctly, f32::DIGITS is Rust's version of C's FLT_DIG, and f64::DIGITS is Rust's version of DBL_DIG. The working draft N3054 of the C standard describes those like this (with radix b = 2 in our case):

number of decimal digits, q, such that any floating-point number with q decimal digits can be rounded into a floating-point number with p radix b digits and back again without change to the q decimal digits,

I wrote "maximum" there because if f32::DIGITS is 6, then 6 is the maximum number of decimal digits that can be converted to f32 losslessly. A 7-digit decimal converted to f32 and back can be altered by the conversions.

[tspiteri]

An example for f32 where a 7-digit number has a lossy conversion:

let s1 = "8.589973e9";
let float: f32 = s1.parse().unwrap();
let s2 = format!("{float:.6e}");
assert_eq!(s1, s2);

panics with

assertion failed: `(left == right)`
  left: `"8.589973e9"`,
 right: `"8.589974e9"`

[Mark-Simulacrum]

I'm going to re-roll the reviewer here r? libs

I think this seems broadly OK, though I'm not sure how helpful the new descriptions are -- they still rely on jargon (e.g., "normal") which may not be familiar to folks reading. The descriptions of what the value is intended to be seem maybe helpful but still pretty far removed from actual utility. Examples might be the best thing, but I imagine short examples are hard for these constants.

[workingjubilee]

Oh, hello. Will get to this in a bit.

r? @workingjubilee

[workingjubilee]

Sorry for taking so long, finally managed to clear my inbox. I agree with Mark that this isn't necessarily ideal, but it seems like a strict improvement, so I think we should accept it.

@bors r+

[bors]

📌 Commit c953b6c has been approved by workingjubilee

It is now in the queue for this repository.

[bors]

⌛ Testing commit c953b6c with merge 90f3a6f...

[bors]

☀️ Test successful - checks-actions
Approved by: workingjubilee
Pushing 90f3a6f to master...

[rust-timer]

Finished benchmarking commit (90f3a6f): comparison URL.

Overall result: no relevant changes - no action needed

@rustbot label: -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-2.0%	[-2.0%, -2.0%]	1
All ❌✅ (primary)	-	-	0

Cycles

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-3.0%	[-4.0%, -2.0%]	2
All ❌✅ (primary)	-	-	0

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 620.986s -> 621.055s (0.01%)
Artifact size: 271.97 MiB -> 271.92 MiB (-0.02%)