From c17d0670185e67ed6edb0aca5d305b4b25072d35 Mon Sep 17 00:00:00 2001 From: Camelid Date: Tue, 15 Sep 2020 10:22:48 -0700 Subject: [PATCH] Don't discourage implementing `core::fmt::Write` Explain when you should use it and when you should not. --- library/core/src/fmt/mod.rs | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index 54772ebb523..0963c6d6cd7 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -92,18 +92,14 @@ pub type Result = result::Result<(), Error>; #[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct Error; -/// A collection of methods that are required to format a message into a stream. +/// A trait for writing or formatting into Unicode-accepting buffers or streams. /// -/// This trait is the type which this modules requires when formatting -/// information. This is similar to the standard library's [`io::Write`] trait, -/// but it is only intended for use in libcore. +/// This trait only accepts UTF-8–encoded data and is not [flushable]. If you only +/// want to accept Unicode and you don't need flushing, you should implement this trait; +/// otherwise you should implement [`std::io::Write`]. /// -/// This trait should generally not be implemented by consumers of the standard -/// library. The [`write!`] macro accepts an instance of [`io::Write`], and the -/// [`io::Write`] trait is favored over implementing this trait. -/// -/// [`write!`]: crate::write! -/// [`io::Write`]: ../../std/io/trait.Write.html +/// [`std::io::Write`]: ../../std/io/trait.Write.html +/// [flushable]: ../../std/io/trait.Write.html#tymethod.flush #[stable(feature = "rust1", since = "1.0.0")] pub trait Write { /// Writes a string slice into this writer, returning whether the write