From 35611872210094bfa7d9eaacc83badb218ed045e Mon Sep 17 00:00:00 2001 From: Pyry Kontio Date: Thu, 31 Mar 2022 00:58:43 +0900 Subject: Improve floating point documentation: - Refine the "NaN as a special value" top level explanation of f32 - Refine `const NAN` docstring. - Refine `fn is_sign_positive` and `fn is_sign_negative` docstrings. - Refine `fn min` and `fn max` docstrings. - Refine `fn trunc` docstrings. - Refine `fn powi` docstrings. - Refine `fn copysign` docstrings. - Reword `NaN` and `NAN` as plain "NaN", unless they refer to the specific `const NAN`. - Reword "a number" to `self` in function docstrings to clarify. - Remove "Returns NAN if the number is NAN" as this is told to be the default behavior in the top explanation. - Remove "propagating NaNs", as full propagation (preservation of payloads) is not guaranteed. --- library/std/src/f32.rs | 26 +++++++++++++++----------- library/std/src/f64.rs | 26 +++++++++++++++----------- library/std/src/primitive_docs.rs | 18 ++++++++++++++---- 3 files changed, 44 insertions(+), 26 deletions(-) (limited to 'library/std/src') diff --git a/library/std/src/f32.rs b/library/std/src/f32.rs index 70b5941c7c7..469db1b7c28 100644 --- a/library/std/src/f32.rs +++ b/library/std/src/f32.rs @@ -30,7 +30,7 @@ pub use core::f32::{ #[cfg(not(test))] #[cfg_attr(bootstrap, lang = "f32_runtime")] impl f32 { - /// Returns the largest integer less than or equal to a number. + /// Returns the largest integer less than or equal to `self`. /// /// # Examples /// @@ -51,7 +51,7 @@ impl f32 { unsafe { intrinsics::floorf32(self) } } - /// Returns the smallest integer greater than or equal to a number. + /// Returns the smallest integer greater than or equal to `self`. /// /// # Examples /// @@ -70,7 +70,7 @@ impl f32 { unsafe { intrinsics::ceilf32(self) } } - /// Returns the nearest integer to a number. Round half-way cases away from + /// Returns the nearest integer to `self`. Round half-way cases away from /// `0.0`. /// /// # Examples @@ -90,7 +90,8 @@ impl f32 { unsafe { intrinsics::roundf32(self) } } - /// Returns the integer part of a number. + /// Returns the integer part of `self`. + /// This means that non-integer numbers are always truncated towards zero. /// /// # Examples /// @@ -111,7 +112,7 @@ impl f32 { unsafe { intrinsics::truncf32(self) } } - /// Returns the fractional part of a number. + /// Returns the fractional part of `self`. /// /// # Examples /// @@ -132,8 +133,7 @@ impl f32 { self - self.trunc() } - /// Computes the absolute value of `self`. Returns `NAN` if the - /// number is `NAN`. + /// Computes the absolute value of `self`. /// /// # Examples /// @@ -161,7 +161,7 @@ impl f32 { /// /// - `1.0` if the number is positive, `+0.0` or `INFINITY` /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` - /// - `NAN` if the number is `NAN` + /// - NaN if the number is NaN /// /// # Examples /// @@ -185,8 +185,10 @@ impl f32 { /// `sign`. /// /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise - /// equal to `-self`. If `self` is a `NAN`, then a `NAN` with the sign of - /// `sign` is returned. + /// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of + /// `sign` is returned. Note, however, that conserving the sign bit on NaN + /// across arithmetical operations is not generally guaranteed. + /// See [explanation of NaN as a special value](primitive@f32) for more info. /// /// # Examples /// @@ -299,7 +301,9 @@ impl f32 { /// Raises a number to an integer power. /// - /// Using this function is generally faster than using `powf` + /// Using this function is generally faster than using `powf`. + /// It might have different sequence of rounding operations than `powf`, + /// so the results are not guaranteed to agree. /// /// # Examples /// diff --git a/library/std/src/f64.rs b/library/std/src/f64.rs index b90d068ec10..a291a777e55 100644 --- a/library/std/src/f64.rs +++ b/library/std/src/f64.rs @@ -30,7 +30,7 @@ pub use core::f64::{ #[cfg(not(test))] #[cfg_attr(bootstrap, lang = "f64_runtime")] impl f64 { - /// Returns the largest integer less than or equal to a number. + /// Returns the largest integer less than or equal to `self`. /// /// # Examples /// @@ -51,7 +51,7 @@ impl f64 { unsafe { intrinsics::floorf64(self) } } - /// Returns the smallest integer greater than or equal to a number. + /// Returns the smallest integer greater than or equal to `self`. /// /// # Examples /// @@ -70,7 +70,7 @@ impl f64 { unsafe { intrinsics::ceilf64(self) } } - /// Returns the nearest integer to a number. Round half-way cases away from + /// Returns the nearest integer to `self`. Round half-way cases away from /// `0.0`. /// /// # Examples @@ -90,7 +90,8 @@ impl f64 { unsafe { intrinsics::roundf64(self) } } - /// Returns the integer part of a number. + /// Returns the integer part of `self`. + /// This means that non-integer numbers are always truncated towards zero. /// /// # Examples /// @@ -111,7 +112,7 @@ impl f64 { unsafe { intrinsics::truncf64(self) } } - /// Returns the fractional part of a number. + /// Returns the fractional part of `self`. /// /// # Examples /// @@ -132,8 +133,7 @@ impl f64 { self - self.trunc() } - /// Computes the absolute value of `self`. Returns `NAN` if the - /// number is `NAN`. + /// Computes the absolute value of `self`. /// /// # Examples /// @@ -161,7 +161,7 @@ impl f64 { /// /// - `1.0` if the number is positive, `+0.0` or `INFINITY` /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` - /// - `NAN` if the number is `NAN` + /// - NaN if the number is NaN /// /// # Examples /// @@ -185,8 +185,10 @@ impl f64 { /// `sign`. /// /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise - /// equal to `-self`. If `self` is a `NAN`, then a `NAN` with the sign of - /// `sign` is returned. + /// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of + /// `sign` is returned. Note, however, that conserving the sign bit on NaN + /// across arithmetical operations is not generally guaranteed. + /// See [explanation of NaN as a special value](primitive@f32) for more info. /// /// # Examples /// @@ -299,7 +301,9 @@ impl f64 { /// Raises a number to an integer power. /// - /// Using this function is generally faster than using `powf` + /// Using this function is generally faster than using `powf`. + /// It might have different sequence of rounding operations than `powf`, + /// so the results are not guaranteed to agree. /// /// # Examples /// diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs index 225a679efd2..188cb8f983b 100644 --- a/library/std/src/primitive_docs.rs +++ b/library/std/src/primitive_docs.rs @@ -977,10 +977,20 @@ mod prim_tuple {} /// like `1.0 / 0.0`. /// - [NaN (not a number)](#associatedconstant.NAN): this value results from /// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected -/// behavior: it is unequal to any float, including itself! It is also neither -/// smaller nor greater than any float, making it impossible to sort. Lastly, -/// it is considered infectious as almost all calculations where one of the -/// operands is NaN will also result in NaN. +/// behavior: +/// - It is unequal to any float, including itself! +/// - It is also neither smaller nor greater than any float, making it +/// impossible to sort by the default comparison operation. This is the +/// reason `f32` doesn't implement the `Ord` and `Eq` traits. +/// - It is also considered *infectious* as almost all calculations where one +/// of the operands is NaN will also result in NaN. The explanations on this +/// page only explicitly document behavior on NaN operands if this default +/// is *not* observed by the operation. +/// - Lastly, there are multiple bit patterns that are considered NaN. +/// Rust does not currently guarantee that the bit patterns of NaN are +/// preserved over arithmetic operations, +/// so there may be some surprising results upon inspecting the bit patterns, +/// as the same calculations might produce NaNs with different bit patterns. /// /// For more information on floating point numbers, see [Wikipedia][wikipedia]. /// -- cgit 1.4.1-3-g733a5 From 4ee8b64a81b2e518d24f2e8acd2dfeebc686dd5d Mon Sep 17 00:00:00 2001 From: Pyry Kontio Date: Thu, 31 Mar 2022 11:27:23 +0900 Subject: Improve wording of "NaN as a special value" top level explanation --- library/core/src/primitive_docs.rs | 9 +++++---- library/std/src/primitive_docs.rs | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) (limited to 'library/std/src') diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 188cb8f983b..ab4bb0f2669 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -978,14 +978,15 @@ mod prim_tuple {} /// - [NaN (not a number)](#associatedconstant.NAN): this value results from /// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected /// behavior: -/// - It is unequal to any float, including itself! +/// - It is unequal to any float, including itself! This is the reason `f32` +/// doesn't implement the `Eq` trait. /// - It is also neither smaller nor greater than any float, making it -/// impossible to sort by the default comparison operation. This is the -/// reason `f32` doesn't implement the `Ord` and `Eq` traits. +/// impossible to sort by the default comparison operation, which is the +/// reason `f32` doesn't implement the `Ord` trait. /// - It is also considered *infectious* as almost all calculations where one /// of the operands is NaN will also result in NaN. The explanations on this /// page only explicitly document behavior on NaN operands if this default -/// is *not* observed by the operation. +/// is deviated from. /// - Lastly, there are multiple bit patterns that are considered NaN. /// Rust does not currently guarantee that the bit patterns of NaN are /// preserved over arithmetic operations, diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs index 188cb8f983b..ab4bb0f2669 100644 --- a/library/std/src/primitive_docs.rs +++ b/library/std/src/primitive_docs.rs @@ -978,14 +978,15 @@ mod prim_tuple {} /// - [NaN (not a number)](#associatedconstant.NAN): this value results from /// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected /// behavior: -/// - It is unequal to any float, including itself! +/// - It is unequal to any float, including itself! This is the reason `f32` +/// doesn't implement the `Eq` trait. /// - It is also neither smaller nor greater than any float, making it -/// impossible to sort by the default comparison operation. This is the -/// reason `f32` doesn't implement the `Ord` and `Eq` traits. +/// impossible to sort by the default comparison operation, which is the +/// reason `f32` doesn't implement the `Ord` trait. /// - It is also considered *infectious* as almost all calculations where one /// of the operands is NaN will also result in NaN. The explanations on this /// page only explicitly document behavior on NaN operands if this default -/// is *not* observed by the operation. +/// is deviated from. /// - Lastly, there are multiple bit patterns that are considered NaN. /// Rust does not currently guarantee that the bit patterns of NaN are /// preserved over arithmetic operations, -- cgit 1.4.1-3-g733a5 From 7175c499ecc32cb3ff713be0bbac9fd12990a34e Mon Sep 17 00:00:00 2001 From: Pyry Kontio Date: Thu, 31 Mar 2022 18:50:14 +0900 Subject: match std f32 primitive docs to core f32 primitive docs --- library/std/src/primitive_docs.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'library/std/src') diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs index ab4bb0f2669..ac4e668112b 100644 --- a/library/std/src/primitive_docs.rs +++ b/library/std/src/primitive_docs.rs @@ -989,8 +989,9 @@ mod prim_tuple {} /// is deviated from. /// - Lastly, there are multiple bit patterns that are considered NaN. /// Rust does not currently guarantee that the bit patterns of NaN are -/// preserved over arithmetic operations, -/// so there may be some surprising results upon inspecting the bit patterns, +/// preserved over arithmetic operations, and they are not guaranteed to be +/// portable or even fully deterministic! This means that there may be some +/// surprising results upon inspecting the bit patterns, /// as the same calculations might produce NaNs with different bit patterns. /// /// For more information on floating point numbers, see [Wikipedia][wikipedia]. -- cgit 1.4.1-3-g733a5 From dea776512b07469092ee98e8c3d4543c6f377729 Mon Sep 17 00:00:00 2001 From: Pyry Kontio Date: Mon, 2 May 2022 23:29:02 +0900 Subject: Fix nits --- library/core/src/num/f32.rs | 8 ++++---- library/core/src/num/f64.rs | 8 ++++---- library/std/src/f32.rs | 2 +- library/std/src/f64.rs | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) (limited to 'library/std/src') diff --git a/library/core/src/num/f32.rs b/library/core/src/num/f32.rs index e3d40b58a38..74d337f1dc0 100644 --- a/library/core/src/num/f32.rs +++ b/library/core/src/num/f32.rs @@ -747,8 +747,8 @@ impl f32 { /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. /// Note that this follows the semantics specified in IEEE 754-2019. /// - /// Also note that "propagation" of NaNs here doesn't mean that the bitpattern of a NaN operand - /// is necessarily conserved; see [explanation of NaN as a special value](f32) for more info. + /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN + /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. #[must_use = "this returns the result of the comparison, without modifying either input"] #[unstable(feature = "float_minimum_maximum", issue = "91079")] #[inline] @@ -782,8 +782,8 @@ impl f32 { /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. /// Note that this follows the semantics specified in IEEE 754-2019. /// - /// Also note that "propagation" of NaNs here doesn't mean that the bitpattern of a NaN operand - /// is necessarily conserved; see [explanation of NaN as a special value](f32) for more info. + /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN + /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. #[must_use = "this returns the result of the comparison, without modifying either input"] #[unstable(feature = "float_minimum_maximum", issue = "91079")] #[inline] diff --git a/library/core/src/num/f64.rs b/library/core/src/num/f64.rs index 51ccf7e8554..c8ce6f0e3a8 100644 --- a/library/core/src/num/f64.rs +++ b/library/core/src/num/f64.rs @@ -763,8 +763,8 @@ impl f64 { /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. /// Note that this follows the semantics specified in IEEE 754-2019. /// - /// Also note that "propagation" of NaNs here doesn't mean that the bitpattern of a NaN operand - /// is necessarily conserved; see [explanation of NaN as a special value](f32) for more info. + /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN + /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. #[must_use = "this returns the result of the comparison, without modifying either input"] #[unstable(feature = "float_minimum_maximum", issue = "91079")] #[inline] @@ -798,8 +798,8 @@ impl f64 { /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. /// Note that this follows the semantics specified in IEEE 754-2019. /// - /// Also note that "propagation" of NaNs here doesn't mean that the bitpattern of a NaN operand - /// is necessarily conserved; see [explanation of NaN as a special value](f32) for more info. + /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN + /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. #[must_use = "this returns the result of the comparison, without modifying either input"] #[unstable(feature = "float_minimum_maximum", issue = "91079")] #[inline] diff --git a/library/std/src/f32.rs b/library/std/src/f32.rs index 469db1b7c28..4cf234a527d 100644 --- a/library/std/src/f32.rs +++ b/library/std/src/f32.rs @@ -302,7 +302,7 @@ impl f32 { /// Raises a number to an integer power. /// /// Using this function is generally faster than using `powf`. - /// It might have different sequence of rounding operations than `powf`, + /// It might have a different sequence of rounding operations than `powf`, /// so the results are not guaranteed to agree. /// /// # Examples diff --git a/library/std/src/f64.rs b/library/std/src/f64.rs index a291a777e55..d28bd386c2a 100644 --- a/library/std/src/f64.rs +++ b/library/std/src/f64.rs @@ -302,7 +302,7 @@ impl f64 { /// Raises a number to an integer power. /// /// Using this function is generally faster than using `powf`. - /// It might have different sequence of rounding operations than `powf`, + /// It might have a different sequence of rounding operations than `powf`, /// so the results are not guaranteed to agree. /// /// # Examples -- cgit 1.4.1-3-g733a5 From df446cb2afd1d968abe4ac47cb8cb4076730a4f0 Mon Sep 17 00:00:00 2001 From: Thom Chiovoloni Date: Sun, 8 May 2022 09:37:36 -0700 Subject: Revert "Implement [OsStr]::join", which was merged without FCP This reverts commit 4fcbc53820ab423bbeb41f07822369aa05da1d68. --- library/std/src/ffi/os_str.rs | 17 ----------------- library/std/src/ffi/os_str/tests.rs | 14 -------------- library/std/src/lib.rs | 2 -- 3 files changed, 33 deletions(-) (limited to 'library/std/src') diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs index dd316bdb2c6..9b5e5d6c0cc 100644 --- a/library/std/src/ffi/os_str.rs +++ b/library/std/src/ffi/os_str.rs @@ -1222,23 +1222,6 @@ impl OsStr { } } -#[unstable(feature = "slice_concat_ext", issue = "27747")] -impl> alloc::slice::Join<&OsStr> for [S] { - type Output = OsString; - - fn join(slice: &Self, sep: &OsStr) -> OsString { - let Some(first) = slice.first() else { - return OsString::new(); - }; - let first = first.borrow().to_owned(); - slice[1..].iter().fold(first, |mut a, b| { - a.push(sep); - a.push(b.borrow()); - a - }) - } -} - #[stable(feature = "rust1", since = "1.0.0")] impl Borrow for OsString { #[inline] diff --git a/library/std/src/ffi/os_str/tests.rs b/library/std/src/ffi/os_str/tests.rs index d7926749aae..283f2b577e8 100644 --- a/library/std/src/ffi/os_str/tests.rs +++ b/library/std/src/ffi/os_str/tests.rs @@ -84,20 +84,6 @@ fn test_os_string_reserve_exact() { assert!(os_string.capacity() >= 33) } -#[test] -fn test_os_string_join() { - let strings = [OsStr::new("hello"), OsStr::new("dear"), OsStr::new("world")]; - assert_eq!("hello", strings[..1].join(OsStr::new(" "))); - assert_eq!("hello dear world", strings.join(OsStr::new(" "))); - assert_eq!("hellodearworld", strings.join(OsStr::new(""))); - assert_eq!("hello.\n dear.\n world", strings.join(OsStr::new(".\n "))); - - assert_eq!("dear world", strings[1..].join(&OsString::from(" "))); - - let strings_abc = [OsString::from("a"), OsString::from("b"), OsString::from("c")]; - assert_eq!("a b c", strings_abc.join(OsStr::new(" "))); -} - #[test] fn test_os_string_default() { let os_string: OsString = Default::default(); diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs index c394865d886..8ee50925f85 100644 --- a/library/std/src/lib.rs +++ b/library/std/src/lib.rs @@ -241,7 +241,6 @@ #![feature(intra_doc_pointers)] #![feature(lang_items)] #![feature(let_chains)] -#![feature(let_else)] #![feature(linkage)] #![feature(min_specialization)] #![feature(must_not_suspend)] @@ -302,7 +301,6 @@ #![feature(toowned_clone_into)] #![feature(try_reserve_kind)] #![feature(vec_into_raw_parts)] -#![feature(slice_concat_trait)] // // Library features (unwind): #![feature(panic_unwind)] -- cgit 1.4.1-3-g733a5