Skip to content

Document which methods on f32 are precise #121793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 29, 2024
+184 −0
Merged

Document which methods on f32 are precise #121793

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 184 additions & 0 deletions library/std/src/f32.rs
View file
Original file line number Diff line number Diff line change
@@ -31,6 +31,8 @@ pub use core::f32::{
impl f32 {
/// Returns the largest integer less than or equal to `self`.
///
/// This function always returns the precise result.
///
/// # Examples
///
/// ```
@@ -52,6 +54,8 @@ impl f32 {

/// Returns the smallest integer greater than or equal to `self`.
///
/// This function always returns the precise result.
///
/// # Examples
///
/// ```
@@ -73,6 +77,8 @@ impl f32 {
/// Returns the nearest integer to `self`. If a value is half-way between two
/// integers, round away from `0.0`.
///
/// This function always returns the precise result.
///
/// # Examples
///
/// ```
@@ -99,6 +105,8 @@ impl f32 {
/// Returns the nearest integer to a number. Rounds half-way cases to the number
/// with an even least significant digit.
///
/// This function always returns the precise result.
///
/// # Examples
///
/// ```
@@ -123,6 +131,8 @@ impl f32 {
/// Returns the integer part of `self`.
/// This means that non-integer numbers are always truncated towards zero.
///
/// This function always returns the precise result.
///
/// # Examples
///
/// ```
@@ -145,6 +155,8 @@ impl f32 {

/// Returns the fractional part of `self`.
///
/// This function always returns the precise result.
///
/// # Examples
///
/// ```
@@ -166,6 +178,8 @@ impl f32 {

/// Computes the absolute value of `self`.
///
/// This function always returns the precise result.
///
/// # Examples
///
/// ```
@@ -249,6 +263,12 @@ impl f32 {
/// this is not always true, and will be heavily dependant on designing
/// algorithms with specific target hardware in mind.
///
/// # Precision
///
/// The result of this operation is guaranteed to be the rounded
/// infinite-precision result. It is specified by IEEE 754 as
/// `fusedMultiplyAdd` and guaranteed not to change.
///
/// # Examples
///
/// ```
@@ -276,6 +296,11 @@ impl f32 {
/// In other words, the result is `self / rhs` rounded to the integer `n`
/// such that `self >= n * rhs`.
///
/// # Precision
///
/// The result of this operation is guaranteed to be the rounded
/// infinite-precision result.
///
/// # Examples
///
/// ```
@@ -309,6 +334,11 @@ impl f32 {
/// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)`
/// approximately.
///
/// # Precision
///
/// The result of this operation is guaranteed to be the rounded
/// infinite-precision result.
///
/// # Examples
///
/// ```
@@ -337,6 +367,10 @@ impl f32 {
/// It might have a different sequence of rounding operations than `powf`,
/// so the results are not guaranteed to agree.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -355,6 +389,10 @@ impl f32 {

/// Raises a number to a floating point power.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -375,6 +413,12 @@ impl f32 {
///
/// Returns NaN if `self` is a negative number other than `-0.0`.
///
/// # Precision
///
/// The result of this operation is guaranteed to be the rounded
/// infinite-precision result. It is specified by IEEE 754 as `squareRoot`
/// and guaranteed not to change.
///
/// # Examples
///
/// ```
@@ -398,6 +442,10 @@ impl f32 {

/// Returns `e^(self)`, (the exponential function).
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -420,6 +468,10 @@ impl f32 {

/// Returns `2^(self)`.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -440,6 +492,10 @@ impl f32 {

/// Returns the natural logarithm of the number.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -466,6 +522,10 @@ impl f32 {
/// `self.log2()` can produce more accurate results for base 2, and
/// `self.log10()` can produce more accurate results for base 10.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -486,6 +546,10 @@ impl f32 {

/// Returns the base 2 logarithm of the number.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -506,6 +570,10 @@ impl f32 {

/// Returns the base 10 logarithm of the number.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -529,6 +597,12 @@ impl f32 {
/// * If `self <= other`: `0.0`
/// * Else: `self - other`
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `fdimf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -561,6 +635,12 @@ impl f32 {

/// Returns the cube root of a number.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `cbrtf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -584,6 +664,12 @@ impl f32 {
/// right-angle triangle with other sides having length `x.abs()` and
/// `y.abs()`.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `hypotf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -605,6 +691,10 @@ impl f32 {

/// Computes the sine of a number (in radians).
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -624,6 +714,10 @@ impl f32 {

/// Computes the cosine of a number (in radians).
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -643,6 +737,12 @@ impl f32 {

/// Computes the tangent of a number (in radians).
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `tanf` from libc on Unix and
/// Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -663,6 +763,12 @@ impl f32 {
/// the range [-pi/2, pi/2] or NaN if the number is outside the range
/// [-1, 1].
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `asinf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -686,6 +792,12 @@ impl f32 {
/// the range [0, pi] or NaN if the number is outside the range
/// [-1, 1].
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `acosf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -708,6 +820,12 @@ impl f32 {
/// Computes the arctangent of a number. Return value is in radians in the
/// range [-pi/2, pi/2];
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `atanf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -734,6 +852,12 @@ impl f32 {
/// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
/// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `atan2f` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -764,6 +888,12 @@ impl f32 {
/// Simultaneously computes the sine and cosine of the number, `x`. Returns
/// `(sin(x), cos(x))`.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `(f32::sin(x),
/// f32::cos(x))`. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -787,6 +917,12 @@ impl f32 {
/// Returns `e^(self) - 1` in a way that is accurate even if the
/// number is close to zero.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `expm1f` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -809,6 +945,12 @@ impl f32 {
/// Returns `ln(1+n)` (natural logarithm) more accurately than if
/// the operations were performed separately.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `log1pf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -831,6 +973,12 @@ impl f32 {

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

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

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

/// Inverse hyperbolic sine function.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -923,6 +1087,10 @@ impl f32 {

/// Inverse hyperbolic cosine function.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -948,6 +1116,10 @@ impl f32 {

/// Inverse hyperbolic tangent function.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
///
/// # Examples
///
/// ```
@@ -969,6 +1141,12 @@ impl f32 {

/// Gamma function.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `tgammaf` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```
@@ -991,6 +1169,12 @@ impl f32 {
///
/// The integer part of the tuple indicates the sign of the gamma function.
///
/// # Platform-specific precision
///
/// The precision of this function varies by platform and Rust version.
/// This function currently corresponds to the `lgamma_r` from libc on Unix
/// and Windows. Note that this might change in the future.
///
/// # Examples
///
/// ```