Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit bc23b84

Browse files
GuillaumeGomezGuillaumeGomez
authoredFeb 29, 2024
Rollup merge of #121793 - tbu-:pr_floating_point_32, r=Amanieu
Document which methods on `f32` are precise Same as #118217 but for `f32`.
2 parents 8a74df9 + 7400f22 commit bc23b84

File tree

1 file changed

+184
-0
lines changed

1 file changed

+184
-0
lines changed
 

‎library/std/src/f32.rs

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ pub use core::f32::{
3131
impl f32 {
3232
/// Returns the largest integer less than or equal to `self`.
3333
///
34+
/// This function always returns the precise result.
35+
///
3436
/// # Examples
3537
///
3638
/// ```
@@ -52,6 +54,8 @@ impl f32 {
5254

5355
/// Returns the smallest integer greater than or equal to `self`.
5456
///
57+
/// This function always returns the precise result.
58+
///
5559
/// # Examples
5660
///
5761
/// ```
@@ -73,6 +77,8 @@ impl f32 {
7377
/// Returns the nearest integer to `self`. If a value is half-way between two
7478
/// integers, round away from `0.0`.
7579
///
80+
/// This function always returns the precise result.
81+
///
7682
/// # Examples
7783
///
7884
/// ```
@@ -99,6 +105,8 @@ impl f32 {
99105
/// Returns the nearest integer to a number. Rounds half-way cases to the number
100106
/// with an even least significant digit.
101107
///
108+
/// This function always returns the precise result.
109+
///
102110
/// # Examples
103111
///
104112
/// ```
@@ -123,6 +131,8 @@ impl f32 {
123131
/// Returns the integer part of `self`.
124132
/// This means that non-integer numbers are always truncated towards zero.
125133
///
134+
/// This function always returns the precise result.
135+
///
126136
/// # Examples
127137
///
128138
/// ```
@@ -145,6 +155,8 @@ impl f32 {
145155

146156
/// Returns the fractional part of `self`.
147157
///
158+
/// This function always returns the precise result.
159+
///
148160
/// # Examples
149161
///
150162
/// ```
@@ -166,6 +178,8 @@ impl f32 {
166178

167179
/// Computes the absolute value of `self`.
168180
///
181+
/// This function always returns the precise result.
182+
///
169183
/// # Examples
170184
///
171185
/// ```
@@ -249,6 +263,12 @@ impl f32 {
249263
/// this is not always true, and will be heavily dependant on designing
250264
/// algorithms with specific target hardware in mind.
251265
///
266+
/// # Precision
267+
///
268+
/// The result of this operation is guaranteed to be the rounded
269+
/// infinite-precision result. It is specified by IEEE 754 as
270+
/// `fusedMultiplyAdd` and guaranteed not to change.
271+
///
252272
/// # Examples
253273
///
254274
/// ```
@@ -276,6 +296,11 @@ impl f32 {
276296
/// In other words, the result is `self / rhs` rounded to the integer `n`
277297
/// such that `self >= n * rhs`.
278298
///
299+
/// # Precision
300+
///
301+
/// The result of this operation is guaranteed to be the rounded
302+
/// infinite-precision result.
303+
///
279304
/// # Examples
280305
///
281306
/// ```
@@ -309,6 +334,11 @@ impl f32 {
309334
/// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)`
310335
/// approximately.
311336
///
337+
/// # Precision
338+
///
339+
/// The result of this operation is guaranteed to be the rounded
340+
/// infinite-precision result.
341+
///
312342
/// # Examples
313343
///
314344
/// ```
@@ -337,6 +367,10 @@ impl f32 {
337367
/// It might have a different sequence of rounding operations than `powf`,
338368
/// so the results are not guaranteed to agree.
339369
///
370+
/// # Platform-specific precision
371+
///
372+
/// The precision of this function varies by platform and Rust version.
373+
///
340374
/// # Examples
341375
///
342376
/// ```
@@ -355,6 +389,10 @@ impl f32 {
355389

356390
/// Raises a number to a floating point power.
357391
///
392+
/// # Platform-specific precision
393+
///
394+
/// The precision of this function varies by platform and Rust version.
395+
///
358396
/// # Examples
359397
///
360398
/// ```
@@ -375,6 +413,12 @@ impl f32 {
375413
///
376414
/// Returns NaN if `self` is a negative number other than `-0.0`.
377415
///
416+
/// # Precision
417+
///
418+
/// The result of this operation is guaranteed to be the rounded
419+
/// infinite-precision result. It is specified by IEEE 754 as `squareRoot`
420+
/// and guaranteed not to change.
421+
///
378422
/// # Examples
379423
///
380424
/// ```
@@ -398,6 +442,10 @@ impl f32 {
398442

399443
/// Returns `e^(self)`, (the exponential function).
400444
///
445+
/// # Platform-specific precision
446+
///
447+
/// The precision of this function varies by platform and Rust version.
448+
///
401449
/// # Examples
402450
///
403451
/// ```
@@ -420,6 +468,10 @@ impl f32 {
420468

421469
/// Returns `2^(self)`.
422470
///
471+
/// # Platform-specific precision
472+
///
473+
/// The precision of this function varies by platform and Rust version.
474+
///
423475
/// # Examples
424476
///
425477
/// ```
@@ -440,6 +492,10 @@ impl f32 {
440492

441493
/// Returns the natural logarithm of the number.
442494
///
495+
/// # Platform-specific precision
496+
///
497+
/// The precision of this function varies by platform and Rust version.
498+
///
443499
/// # Examples
444500
///
445501
/// ```
@@ -466,6 +522,10 @@ impl f32 {
466522
/// `self.log2()` can produce more accurate results for base 2, and
467523
/// `self.log10()` can produce more accurate results for base 10.
468524
///
525+
/// # Platform-specific precision
526+
///
527+
/// The precision of this function varies by platform and Rust version.
528+
///
469529
/// # Examples
470530
///
471531
/// ```
@@ -486,6 +546,10 @@ impl f32 {
486546

487547
/// Returns the base 2 logarithm of the number.
488548
///
549+
/// # Platform-specific precision
550+
///
551+
/// The precision of this function varies by platform and Rust version.
552+
///
489553
/// # Examples
490554
///
491555
/// ```
@@ -506,6 +570,10 @@ impl f32 {
506570

507571
/// Returns the base 10 logarithm of the number.
508572
///
573+
/// # Platform-specific precision
574+
///
575+
/// The precision of this function varies by platform and Rust version.
576+
///
509577
/// # Examples
510578
///
511579
/// ```
@@ -529,6 +597,12 @@ impl f32 {
529597
/// * If `self <= other`: `0.0`
530598
/// * Else: `self - other`
531599
///
600+
/// # Platform-specific precision
601+
///
602+
/// The precision of this function varies by platform and Rust version.
603+
/// This function currently corresponds to the `fdimf` from libc on Unix
604+
/// and Windows. Note that this might change in the future.
605+
///
532606
/// # Examples
533607
///
534608
/// ```
@@ -561,6 +635,12 @@ impl f32 {
561635

562636
/// Returns the cube root of a number.
563637
///
638+
/// # Platform-specific precision
639+
///
640+
/// The precision of this function varies by platform and Rust version.
641+
/// This function currently corresponds to the `cbrtf` from libc on Unix
642+
/// and Windows. Note that this might change in the future.
643+
///
564644
/// # Examples
565645
///
566646
/// ```
@@ -584,6 +664,12 @@ impl f32 {
584664
/// right-angle triangle with other sides having length `x.abs()` and
585665
/// `y.abs()`.
586666
///
667+
/// # Platform-specific precision
668+
///
669+
/// The precision of this function varies by platform and Rust version.
670+
/// This function currently corresponds to the `hypotf` from libc on Unix
671+
/// and Windows. Note that this might change in the future.
672+
///
587673
/// # Examples
588674
///
589675
/// ```
@@ -605,6 +691,10 @@ impl f32 {
605691

606692
/// Computes the sine of a number (in radians).
607693
///
694+
/// # Platform-specific precision
695+
///
696+
/// The precision of this function varies by platform and Rust version.
697+
///
608698
/// # Examples
609699
///
610700
/// ```
@@ -624,6 +714,10 @@ impl f32 {
624714

625715
/// Computes the cosine of a number (in radians).
626716
///
717+
/// # Platform-specific precision
718+
///
719+
/// The precision of this function varies by platform and Rust version.
720+
///
627721
/// # Examples
628722
///
629723
/// ```
@@ -643,6 +737,12 @@ impl f32 {
643737

644738
/// Computes the tangent of a number (in radians).
645739
///
740+
/// # Platform-specific precision
741+
///
742+
/// The precision of this function varies by platform and Rust version.
743+
/// This function currently corresponds to the `tanf` from libc on Unix and
744+
/// Windows. Note that this might change in the future.
745+
///
646746
/// # Examples
647747
///
648748
/// ```
@@ -663,6 +763,12 @@ impl f32 {
663763
/// the range [-pi/2, pi/2] or NaN if the number is outside the range
664764
/// [-1, 1].
665765
///
766+
/// # Platform-specific precision
767+
///
768+
/// The precision of this function varies by platform and Rust version.
769+
/// This function currently corresponds to the `asinf` from libc on Unix
770+
/// and Windows. Note that this might change in the future.
771+
///
666772
/// # Examples
667773
///
668774
/// ```
@@ -686,6 +792,12 @@ impl f32 {
686792
/// the range [0, pi] or NaN if the number is outside the range
687793
/// [-1, 1].
688794
///
795+
/// # Platform-specific precision
796+
///
797+
/// The precision of this function varies by platform and Rust version.
798+
/// This function currently corresponds to the `acosf` from libc on Unix
799+
/// and Windows. Note that this might change in the future.
800+
///
689801
/// # Examples
690802
///
691803
/// ```
@@ -708,6 +820,12 @@ impl f32 {
708820
/// Computes the arctangent of a number. Return value is in radians in the
709821
/// range [-pi/2, pi/2];
710822
///
823+
/// # Platform-specific precision
824+
///
825+
/// The precision of this function varies by platform and Rust version.
826+
/// This function currently corresponds to the `atanf` from libc on Unix
827+
/// and Windows. Note that this might change in the future.
828+
///
711829
/// # Examples
712830
///
713831
/// ```
@@ -734,6 +852,12 @@ impl f32 {
734852
/// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
735853
/// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
736854
///
855+
/// # Platform-specific precision
856+
///
857+
/// The precision of this function varies by platform and Rust version.
858+
/// This function currently corresponds to the `atan2f` from libc on Unix
859+
/// and Windows. Note that this might change in the future.
860+
///
737861
/// # Examples
738862
///
739863
/// ```
@@ -764,6 +888,12 @@ impl f32 {
764888
/// Simultaneously computes the sine and cosine of the number, `x`. Returns
765889
/// `(sin(x), cos(x))`.
766890
///
891+
/// # Platform-specific precision
892+
///
893+
/// The precision of this function varies by platform and Rust version.
894+
/// This function currently corresponds to the `(f32::sin(x),
895+
/// f32::cos(x))`. Note that this might change in the future.
896+
///
767897
/// # Examples
768898
///
769899
/// ```
@@ -787,6 +917,12 @@ impl f32 {
787917
/// Returns `e^(self) - 1` in a way that is accurate even if the
788918
/// number is close to zero.
789919
///
920+
/// # Platform-specific precision
921+
///
922+
/// The precision of this function varies by platform and Rust version.
923+
/// This function currently corresponds to the `expm1f` from libc on Unix
924+
/// and Windows. Note that this might change in the future.
925+
///
790926
/// # Examples
791927
///
792928
/// ```
@@ -809,6 +945,12 @@ impl f32 {
809945
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
810946
/// the operations were performed separately.
811947
///
948+
/// # Platform-specific precision
949+
///
950+
/// The precision of this function varies by platform and Rust version.
951+
/// This function currently corresponds to the `log1pf` from libc on Unix
952+
/// and Windows. Note that this might change in the future.
953+
///
812954
/// # Examples
813955
///
814956
/// ```
@@ -831,6 +973,12 @@ impl f32 {
831973

832974
/// Hyperbolic sine function.
833975
///
976+
/// # Platform-specific precision
977+
///
978+
/// The precision of this function varies by platform and Rust version.
979+
/// This function currently corresponds to the `sinhf` from libc on Unix
980+
/// and Windows. Note that this might change in the future.
981+
///
834982
/// # Examples
835983
///
836984
/// ```
@@ -854,6 +1002,12 @@ impl f32 {
8541002

8551003
/// Hyperbolic cosine function.
8561004
///
1005+
/// # Platform-specific precision
1006+
///
1007+
/// The precision of this function varies by platform and Rust version.
1008+
/// This function currently corresponds to the `coshf` from libc on Unix
1009+
/// and Windows. Note that this might change in the future.
1010+
///
8571011
/// # Examples
8581012
///
8591013
/// ```
@@ -877,6 +1031,12 @@ impl f32 {
8771031

8781032
/// Hyperbolic tangent function.
8791033
///
1034+
/// # Platform-specific precision
1035+
///
1036+
/// The precision of this function varies by platform and Rust version.
1037+
/// This function currently corresponds to the `tanhf` from libc on Unix
1038+
/// and Windows. Note that this might change in the future.
1039+
///
8801040
/// # Examples
8811041
///
8821042
/// ```
@@ -900,6 +1060,10 @@ impl f32 {
9001060

9011061
/// Inverse hyperbolic sine function.
9021062
///
1063+
/// # Platform-specific precision
1064+
///
1065+
/// The precision of this function varies by platform and Rust version.
1066+
///
9031067
/// # Examples
9041068
///
9051069
/// ```
@@ -923,6 +1087,10 @@ impl f32 {
9231087

9241088
/// Inverse hyperbolic cosine function.
9251089
///
1090+
/// # Platform-specific precision
1091+
///
1092+
/// The precision of this function varies by platform and Rust version.
1093+
///
9261094
/// # Examples
9271095
///
9281096
/// ```
@@ -948,6 +1116,10 @@ impl f32 {
9481116

9491117
/// Inverse hyperbolic tangent function.
9501118
///
1119+
/// # Platform-specific precision
1120+
///
1121+
/// The precision of this function varies by platform and Rust version.
1122+
///
9511123
/// # Examples
9521124
///
9531125
/// ```
@@ -969,6 +1141,12 @@ impl f32 {
9691141

9701142
/// Gamma function.
9711143
///
1144+
/// # Platform-specific precision
1145+
///
1146+
/// The precision of this function varies by platform and Rust version.
1147+
/// This function currently corresponds to the `tgammaf` from libc on Unix
1148+
/// and Windows. Note that this might change in the future.
1149+
///
9721150
/// # Examples
9731151
///
9741152
/// ```
@@ -991,6 +1169,12 @@ impl f32 {
9911169
///
9921170
/// The integer part of the tuple indicates the sign of the gamma function.
9931171
///
1172+
/// # Platform-specific precision
1173+
///
1174+
/// The precision of this function varies by platform and Rust version.
1175+
/// This function currently corresponds to the `lgamma_r` from libc on Unix
1176+
/// and Windows. Note that this might change in the future.
1177+
///
9941178
/// # Examples
9951179
///
9961180
/// ```

0 commit comments

Comments
 (0)
Please sign in to comment.