//! format!("Hello"); // => "Hello"
//! format!("Hello, {}!", "world"); // => "Hello, world!"
//! format!("The number is {}", 1i); // => "The number is 1"
-//! format!("{}", (3i, 4i)); // => "(3, 4)"
+//! format!("{:?}", (3i, 4i)); // => "(3i, 4i)"
//! format!("{value}", value=4i); // => "4"
//! format!("{} {}", 1i, 2u); // => "1 2"
//! # }
//! # fn main() {
//! format!("{argument}", argument = "test"); // => "test"
//! format!("{name} {}", 1i, name = 2i); // => "2 1"
-//! format!("{a} {c} {b}", a="a", b=(), c=3i); // => "a 3 ()"
+//! format!("{a} {c} {b}", a="a", b='b', c=3i); // => "a 3 b"
//! # }
//! ```
//!
//! ```
//!
//! This is invalid because the first argument is both referred to as a
-//! hexidecimal as well as an
+//! hexadecimal as well as an
//! octal.
//!
//! There are various parameters which do require a particular type, however.
//! This allows multiple actual types to be formatted via `{:x}` (like `i8` as
//! well as `int`). The current mapping of types to traits is:
//!
-//! * *nothing* ⇒ `Show`
+//! * *nothing* ⇒ `String`
+//! * `?` ⇒ `Show`
//! * `o` ⇒ `Octal`
//! * `x` ⇒ `LowerHex`
//! * `X` ⇒ `UpperHex`
//! `std::fmt::Binary` trait can then be formatted with `{:b}`. Implementations
//! are provided for these traits for a number of primitive types by the
//! standard library as well. If no format is specified (as in `{}` or `{:6}`),
-//! then the format trait used is the `Show` trait. This is one of the more
-//! commonly implemented traits when formatting a custom type.
+//! then the format trait used is the `String` trait.
//!
//! When implementing a format trait for your own type, you will have to
//! implement a method of the signature:
//! use std::f64;
//! use std::num::Float;
//!
+//! #[deriving(Show)]
//! struct Vector2D {
//! x: int,
//! y: int,
//! }
//!
-//! impl fmt::Show for Vector2D {
+//! impl fmt::String for Vector2D {
//! fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
//! // The `f` value implements the `Writer` trait, which is what the
//! // write! macro is expecting. Note that this formatting ignores the
//! // for details, and the function `pad` can be used to pad strings.
//! let decimals = f.precision().unwrap_or(3);
//! let string = f64::to_str_exact(magnitude, decimals);
-//! f.pad_integral(true, "", string.as_bytes())
+//! f.pad_integral(true, "", string.as_slice())
//! }
//! }
//!
//! let myvector = Vector2D { x: 3, y: 4 };
//!
//! println!("{}", myvector); // => "(3, 4)"
+//! println!("{:?}", myvector); // => "Vector2D {x: 3i, y:4i}"
//! println!("{:10.3b}", myvector); // => " 5.000"
//! }
//! ```
//!
+//! #### fmt::String vs fmt::Show
+//!
+//! These two formatting traits have distinct purposes:
+//!
+//! - `fmt::String` implementations assert that the type can be faithfully
+//! represented as a UTF-8 string at all times. It is **not** expected that
+//! all types implement the `String` trait.
+//! - `fmt::Show` implementations should be implemented for **all** public types.
+//! Output will typically represent the internal state as faithfully as possible.
+//! The purpose of the `Show` trait is to facilitate debugging Rust code. In
+//! most cases, using `#[deriving(Show)]` is sufficient and recommended.
+//!
+//! Some examples of the output from both traits:
+//!
+//! ```
+//! assert_eq!(format!("{} {:?}", 3i32, 4i32), "3 4i32");
+//! assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'");
+//! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
+//! ```
+//!
//! ### Related macros
//!
//! There are a number of related macros in the `format!` family. The ones that
#![experimental]
-use io::Writer;
-use io;
-use result::Result::{Ok, Err};
use string;
-use vec::Vec;
-pub use core::fmt::{Formatter, Result, FormatWriter, rt};
-pub use core::fmt::{Show, Octal, Binary};
+pub use core::fmt::{Formatter, Result, Writer, rt};
+pub use core::fmt::{Show, String, Octal, Binary};
pub use core::fmt::{LowerHex, UpperHex, Pointer};
pub use core::fmt::{LowerExp, UpperExp};
pub use core::fmt::Error;
#[doc(hidden)]
pub use core::fmt::{argument, argumentuint};
-// NOTE(stage0): Remove cfg after a snapshot
-#[cfg(not(stage0))]
/// The format function takes a precompiled format string and a list of
/// arguments, to return the resulting formatted string.
///
#[experimental = "this is an implementation detail of format! and should not \
be called directly"]
pub fn format(args: Arguments) -> string::String {
- let mut output = Vec::new();
- let _ = write!(&mut output as &mut Writer, "{}", args);
- string::String::from_utf8(output).unwrap()
-}
-
-// NOTE(stage0): Remove function after a snapshot
-#[cfg(stage0)]
-/// The format function takes a precompiled format string and a list of
-/// arguments, to return the resulting formatted string.
-///
-/// # Arguments
-///
-/// * args - a structure of arguments generated via the `format_args!` macro.
-///
-/// # Example
-///
-/// ```rust
-/// use std::fmt;
-///
-/// let s = format_args!(fmt::format, "Hello, {}!", "world");
-/// assert_eq!(s, "Hello, world!".to_string());
-/// ```
-#[experimental = "this is an implementation detail of format! and should not \
- be called directly"]
-pub fn format(args: &Arguments) -> string::String {
- let mut output = Vec::new();
- let _ = write!(&mut output as &mut Writer, "{}", args);
- string::String::from_utf8(output).unwrap()
-}
-
-impl<'a> Writer for Formatter<'a> {
- fn write(&mut self, b: &[u8]) -> io::IoResult<()> {
- match (*self).write(b) {
- Ok(()) => Ok(()),
- Err(Error) => Err(io::standard_error(io::OtherIoError))
- }
- }
+ let mut output = string::String::new();
+ let _ = write!(&mut output, "{}", args);
+ output
}