diff options
Diffstat (limited to 'library/core/src')
| -rw-r--r-- | library/core/src/fmt/fmt_trait_method_doc.md | 8 | ||||
| -rw-r--r-- | library/core/src/fmt/mod.rs | 42 | ||||
| -rw-r--r-- | library/core/src/mem/manually_drop.rs | 2 | ||||
| -rw-r--r-- | library/core/src/primitive_docs.rs | 3 | ||||
| -rw-r--r-- | library/core/src/ptr/mod.rs | 38 | ||||
| -rw-r--r-- | library/core/src/slice/ascii.rs | 21 | ||||
| -rw-r--r-- | library/core/src/str/mod.rs | 15 |
7 files changed, 86 insertions, 43 deletions
diff --git a/library/core/src/fmt/fmt_trait_method_doc.md b/library/core/src/fmt/fmt_trait_method_doc.md new file mode 100644 index 00000000000..493d929243d --- /dev/null +++ b/library/core/src/fmt/fmt_trait_method_doc.md @@ -0,0 +1,8 @@ +Formats the value using the given formatter. + +# Errors + +This function should return [`Err`] if, and only if, the provided [`Formatter`] returns [`Err`]. +String formatting is considered an infallible operation; this function only +returns a [`Result`] because writing to the underlying stream might fail and it must +provide a way to propagate the fact that an error has occurred back up the stack. diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index ce0643a3f5e..9b372eac524 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -72,14 +72,24 @@ pub type Result = result::Result<(), Error>; /// The error type which is returned from formatting a message into a stream. /// /// This type does not support transmission of an error other than that an error -/// occurred. Any extra information must be arranged to be transmitted through -/// some other means. -/// -/// An important thing to remember is that the type `fmt::Error` should not be +/// occurred. This is because, despite the existence of this error, +/// string formatting is considered an infallible operation. +/// `fmt()` implementors should not return this `Error` unless they received it from their +/// [`Formatter`]. The only time your code should create a new instance of this +/// error is when implementing `fmt::Write`, in order to cancel the formatting operation when +/// writing to the underlying stream fails. +/// +/// Any extra information must be arranged to be transmitted through some other means, +/// such as storing it in a field to be consulted after the formatting operation has been +/// cancelled. (For example, this is how [`std::io::Write::write_fmt()`] propagates IO errors +/// during writing.) +/// +/// This type, `fmt::Error`, should not be /// confused with [`std::io::Error`] or [`std::error::Error`], which you may also /// have in scope. /// /// [`std::io::Error`]: ../../std/io/struct.Error.html +/// [`std::io::Write::write_fmt()`]: ../../std/io/trait.Write.html#method.write_fmt /// [`std::error::Error`]: ../../std/error/trait.Error.html /// /// # Examples @@ -118,8 +128,10 @@ pub trait Write { /// This function will return an instance of [`std::fmt::Error`][Error] on error. /// /// The purpose of that error is to abort the formatting operation when the underlying - /// destination encounters some error preventing it from accepting more text; it should - /// generally be propagated rather than handled, at least when implementing formatting traits. + /// destination encounters some error preventing it from accepting more text; + /// in particular, it does not communicate any information about *what* error occurred. + /// It should generally be propagated rather than handled, at least when implementing + /// formatting traits. /// /// # Examples /// @@ -586,7 +598,7 @@ impl Display for Arguments<'_> { #[rustc_diagnostic_item = "Debug"] #[rustc_trivial_field_reads] pub trait Debug { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] /// /// # Examples /// @@ -703,7 +715,7 @@ pub use macros::Debug; #[rustc_diagnostic_item = "Display"] #[stable(feature = "rust1", since = "1.0.0")] pub trait Display { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] /// /// # Examples /// @@ -777,7 +789,7 @@ pub trait Display { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait Octal { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] #[stable(feature = "rust1", since = "1.0.0")] fn fmt(&self, f: &mut Formatter<'_>) -> Result; } @@ -836,7 +848,7 @@ pub trait Octal { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait Binary { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] #[stable(feature = "rust1", since = "1.0.0")] fn fmt(&self, f: &mut Formatter<'_>) -> Result; } @@ -891,7 +903,7 @@ pub trait Binary { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait LowerHex { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] #[stable(feature = "rust1", since = "1.0.0")] fn fmt(&self, f: &mut Formatter<'_>) -> Result; } @@ -946,7 +958,7 @@ pub trait LowerHex { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait UpperHex { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] #[stable(feature = "rust1", since = "1.0.0")] fn fmt(&self, f: &mut Formatter<'_>) -> Result; } @@ -997,7 +1009,7 @@ pub trait UpperHex { #[stable(feature = "rust1", since = "1.0.0")] #[rustc_diagnostic_item = "Pointer"] pub trait Pointer { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] #[stable(feature = "rust1", since = "1.0.0")] fn fmt(&self, f: &mut Formatter<'_>) -> Result; } @@ -1048,7 +1060,7 @@ pub trait Pointer { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait LowerExp { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] #[stable(feature = "rust1", since = "1.0.0")] fn fmt(&self, f: &mut Formatter<'_>) -> Result; } @@ -1099,7 +1111,7 @@ pub trait LowerExp { /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait UpperExp { - /// Formats the value using the given formatter. + #[doc = include_str!("fmt_trait_method_doc.md")] #[stable(feature = "rust1", since = "1.0.0")] fn fmt(&self, f: &mut Formatter<'_>) -> Result; } diff --git a/library/core/src/mem/manually_drop.rs b/library/core/src/mem/manually_drop.rs index 955efb9b0f9..e0c3b9f3b51 100644 --- a/library/core/src/mem/manually_drop.rs +++ b/library/core/src/mem/manually_drop.rs @@ -1,7 +1,7 @@ use crate::ops::{Deref, DerefMut, DerefPure}; use crate::ptr; -/// A wrapper to inhibit compiler from automatically calling `T`’s destructor. +/// A wrapper to inhibit the compiler from automatically calling `T`’s destructor. /// This wrapper is 0-cost. /// /// `ManuallyDrop<T>` is guaranteed to have the same layout and bit validity as diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index d8597369b9b..8283fdc459b 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1467,8 +1467,9 @@ mod prim_usize {} /// For all types, `T: ?Sized`, and for all `t: &T` or `t: &mut T`, when such values cross an API /// boundary, the following invariants must generally be upheld: /// +/// * `t` is non-null /// * `t` is aligned to `align_of_val(t)` -/// * `t` is dereferenceable for `size_of_val(t)` many bytes +/// * if `size_of_val(t) > 0`, then `t` is dereferenceable for `size_of_val(t)` many bytes /// /// If `t` points at address `a`, being "dereferenceable" for N bytes means that the memory range /// `[a, a + N)` is all contained within a single [allocated object]. diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs index 8d7192c1b0f..f87b6bbfcfb 100644 --- a/library/core/src/ptr/mod.rs +++ b/library/core/src/ptr/mod.rs @@ -63,11 +63,39 @@ //! //! ## Allocated object //! -//! For several operations, such as [`offset`] or field projections (`expr.field`), the notion of an -//! "allocated object" becomes relevant. An allocated object is a contiguous region of memory. -//! Common examples of allocated objects include stack-allocated variables (each variable is a -//! separate allocated object), heap allocations (each allocation created by the global allocator is -//! a separate allocated object), and `static` variables. +//! An *allocated object* is a subset of program memory which is addressable +//! from Rust, and within which pointer arithmetic is possible. Examples of +//! allocated objects include heap allocations, stack-allocated variables, +//! statics, and consts. The safety preconditions of some Rust operations - +//! such as `offset` and field projections (`expr.field`) - are defined in +//! terms of the allocated objects on which they operate. +//! +//! An allocated object has a base address, a size, and a set of memory +//! addresses. It is possible for an allocated object to have zero size, but +//! such an allocated object will still have a base address. The base address +//! of an allocated object is not necessarily unique. While it is currently the +//! case that an allocated object always has a set of memory addresses which is +//! fully contiguous (i.e., has no "holes"), there is no guarantee that this +//! will not change in the future. +//! +//! For any allocated object with `base` address, `size`, and a set of +//! `addresses`, the following are guaranteed: +//! - For all addresses `a` in `addresses`, `a` is in the range `base .. (base + +//! size)` (note that this requires `a < base + size`, not `a <= base + size`) +//! - `base` is not equal to [`null()`] (i.e., the address with the numerical +//! value 0) +//! - `base + size <= usize::MAX` +//! - `size <= isize::MAX` +//! +//! As a consequence of these guarantees, given any address `a` within the set +//! of addresses of an allocated object: +//! - It is guaranteed that `a - base` does not overflow `isize` +//! - It is guaranteed that `a - base` is non-negative +//! - It is guaranteed that, given `o = a - base` (i.e., the offset of `a` within +//! the allocated object), `base + o` will not wrap around the address space (in +//! other words, will not overflow `usize`) +//! +//! [`null()`]: null //! //! # Strict Provenance //! diff --git a/library/core/src/slice/ascii.rs b/library/core/src/slice/ascii.rs index 5c4f0bf9b2b..8ad045275ad 100644 --- a/library/core/src/slice/ascii.rs +++ b/library/core/src/slice/ascii.rs @@ -114,18 +114,17 @@ impl [u8] { /// Returns a byte slice with leading ASCII whitespace bytes removed. /// /// 'Whitespace' refers to the definition used by - /// `u8::is_ascii_whitespace`. + /// [`u8::is_ascii_whitespace`]. /// /// # Examples /// /// ``` - /// #![feature(byte_slice_trim_ascii)] - /// /// assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n"); /// assert_eq!(b" ".trim_ascii_start(), b""); /// assert_eq!(b"".trim_ascii_start(), b""); /// ``` - #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")] + #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] #[inline] pub const fn trim_ascii_start(&self) -> &[u8] { let mut bytes = self; @@ -144,18 +143,17 @@ impl [u8] { /// Returns a byte slice with trailing ASCII whitespace bytes removed. /// /// 'Whitespace' refers to the definition used by - /// `u8::is_ascii_whitespace`. + /// [`u8::is_ascii_whitespace`]. /// /// # Examples /// /// ``` - /// #![feature(byte_slice_trim_ascii)] - /// /// assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world"); /// assert_eq!(b" ".trim_ascii_end(), b""); /// assert_eq!(b"".trim_ascii_end(), b""); /// ``` - #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")] + #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] #[inline] pub const fn trim_ascii_end(&self) -> &[u8] { let mut bytes = self; @@ -175,18 +173,17 @@ impl [u8] { /// removed. /// /// 'Whitespace' refers to the definition used by - /// `u8::is_ascii_whitespace`. + /// [`u8::is_ascii_whitespace`]. /// /// # Examples /// /// ``` - /// #![feature(byte_slice_trim_ascii)] - /// /// assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world"); /// assert_eq!(b" ".trim_ascii(), b""); /// assert_eq!(b"".trim_ascii(), b""); /// ``` - #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")] + #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] #[inline] pub const fn trim_ascii(&self) -> &[u8] { self.trim_ascii_start().trim_ascii_end() diff --git a/library/core/src/str/mod.rs b/library/core/src/str/mod.rs index b6f65907d3c..669cdc92e35 100644 --- a/library/core/src/str/mod.rs +++ b/library/core/src/str/mod.rs @@ -2531,15 +2531,14 @@ impl str { /// # Examples /// /// ``` - /// #![feature(byte_slice_trim_ascii)] - /// /// assert_eq!(" \t \u{3000}hello world\n".trim_ascii_start(), "\u{3000}hello world\n"); /// assert_eq!(" ".trim_ascii_start(), ""); /// assert_eq!("".trim_ascii_start(), ""); /// ``` - #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")] #[must_use = "this returns the trimmed string as a new slice, \ without modifying the original"] + #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] #[inline] pub const fn trim_ascii_start(&self) -> &str { // SAFETY: Removing ASCII characters from a `&str` does not invalidate @@ -2557,15 +2556,14 @@ impl str { /// # Examples /// /// ``` - /// #![feature(byte_slice_trim_ascii)] - /// /// assert_eq!("\r hello world\u{3000}\n ".trim_ascii_end(), "\r hello world\u{3000}"); /// assert_eq!(" ".trim_ascii_end(), ""); /// assert_eq!("".trim_ascii_end(), ""); /// ``` - #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")] #[must_use = "this returns the trimmed string as a new slice, \ without modifying the original"] + #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] #[inline] pub const fn trim_ascii_end(&self) -> &str { // SAFETY: Removing ASCII characters from a `&str` does not invalidate @@ -2584,15 +2582,14 @@ impl str { /// # Examples /// /// ``` - /// #![feature(byte_slice_trim_ascii)] - /// /// assert_eq!("\r hello world\n ".trim_ascii(), "hello world"); /// assert_eq!(" ".trim_ascii(), ""); /// assert_eq!("".trim_ascii(), ""); /// ``` - #[unstable(feature = "byte_slice_trim_ascii", issue = "94035")] #[must_use = "this returns the trimmed string as a new slice, \ without modifying the original"] + #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] + #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] #[inline] pub const fn trim_ascii(&self) -> &str { // SAFETY: Removing ASCII characters from a `&str` does not invalidate |