mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #124954 - kpreid:fmterr, r=Nilstrieb

Browse Source 
Document proper usage of `fmt::Error` and `fmt()`'s `Result`.

I've seen several newcomers wonder why `fmt::Error` doesn't have any error detail information, or propose to return it in response to an error condition found inside a `impl fmt::Display for MyType`.

That is incorrect, per [a lone paragraph of the `fmt` module's documentation](https://doc.rust-lang.org/1.78.0/std/fmt/index.html#formatting-traits). However, users looking to implement a formatting trait won't necessarily look there. Therefore, let's add the critical information (that formatting per se is infallible) to all the involved items: every `fmt()` method, and `fmt::Error`.

This PR is not intended to make any novel claims about `fmt`; only to repeat an existing one in places where it will be more visible.
This commit is contained in:
Matthias Krüger 2024-05-11 13:16:40 +02:00 committed by GitHub
commit 6c3fce90cc
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 35 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
library/alloc/src/fmt.rs
View File

@ -403,7 +403,7 @@
//! is, a formatting implementation must and may only return an error if the //! is, a formatting implementation must and may only return an error if the
//! passed-in [`Formatter`] returns an error. This is because, contrary to what //! passed-in [`Formatter`] returns an error. This is because, contrary to what
//! the function signature might suggest, string formatting is an infallible //! the function signature might suggest, string formatting is an infallible
//! operation. This function only returns a result because writing to the //! 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 //! underlying stream might fail and it must provide a way to propagate the fact
//! that an error has occurred back up the stack. //! that an error has occurred back up the stack.
//! //!

8
library/core/src/fmt/fmt_trait_method_doc.md Normal file
View File

@ -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.

40
library/core/src/fmt/mod.rs
View File

@ -72,14 +72,24 @@ pub type Result = result::Result<(), Error>;
/// The error type which is returned from formatting a message into a stream. /// 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 /// 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 /// occurred. This is because, despite the existence of this error,
/// some other means. /// 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.
/// ///
/// An important thing to remember is that the type `fmt::Error` should not be /// 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 /// confused with [`std::io::Error`] or [`std::error::Error`], which you may also
/// have in scope. /// have in scope.
/// ///
/// [`std::io::Error`]: ../../std/io/struct.Error.html /// [`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 /// [`std::error::Error`]: ../../std/error/trait.Error.html
/// ///
/// # Examples /// # Examples
@ -118,8 +128,10 @@ pub trait Write {
/// This function will return an instance of [`std::fmt::Error`][Error] on error. /// 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 /// 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 /// destination encounters some error preventing it from accepting more text;
/// generally be propagated rather than handled, at least when implementing formatting traits. /// 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 /// # Examples
/// ///
@ -586,7 +598,7 @@ impl Display for Arguments<'_> {
#[rustc_diagnostic_item = "Debug"] #[rustc_diagnostic_item = "Debug"]
#[rustc_trivial_field_reads] #[rustc_trivial_field_reads]
pub trait Debug { pub trait Debug {
/// Formats the value using the given formatter. #[doc = include_str!("fmt_trait_method_doc.md")]
/// ///
/// # Examples /// # Examples
/// ///
@ -703,7 +715,7 @@ pub use macros::Debug;
#[rustc_diagnostic_item = "Display"] #[rustc_diagnostic_item = "Display"]
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait Display { pub trait Display {
/// Formats the value using the given formatter. #[doc = include_str!("fmt_trait_method_doc.md")]
/// ///
/// # Examples /// # Examples
/// ///
@ -777,7 +789,7 @@ pub trait Display {
/// ``` /// ```
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait Octal { 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")] #[stable(feature = "rust1", since = "1.0.0")]
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }
@ -836,7 +848,7 @@ pub trait Octal {
/// ``` /// ```
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait Binary { 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")] #[stable(feature = "rust1", since = "1.0.0")]
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }
@ -891,7 +903,7 @@ pub trait Binary {
/// ``` /// ```
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait LowerHex { 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")] #[stable(feature = "rust1", since = "1.0.0")]
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }
@ -946,7 +958,7 @@ pub trait LowerHex {
/// ``` /// ```
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait UpperHex { 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")] #[stable(feature = "rust1", since = "1.0.0")]
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }
@ -997,7 +1009,7 @@ pub trait UpperHex {
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[rustc_diagnostic_item = "Pointer"] #[rustc_diagnostic_item = "Pointer"]
pub trait 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")] #[stable(feature = "rust1", since = "1.0.0")]
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }
@ -1048,7 +1060,7 @@ pub trait Pointer {
/// ``` /// ```
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait LowerExp { 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")] #[stable(feature = "rust1", since = "1.0.0")]
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }
@ -1099,7 +1111,7 @@ pub trait LowerExp {
/// ``` /// ```
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub trait UpperExp { 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")] #[stable(feature = "rust1", since = "1.0.0")]
fn fmt(&self, f: &mut Formatter<'_>) -> Result; fn fmt(&self, f: &mut Formatter<'_>) -> Result;
} }