diff options
Diffstat (limited to 'libcollections/fmt.rs')
| -rw-r--r-- | libcollections/fmt.rs | 48 |
1 files changed, 30 insertions, 18 deletions
diff --git a/libcollections/fmt.rs b/libcollections/fmt.rs index 710a30f..6f77d79 100644 --- a/libcollections/fmt.rs +++ b/libcollections/fmt.rs @@ -8,19 +8,16 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Utilities for formatting and printing strings +//! Utilities for formatting and printing `String`s //! //! This module contains the runtime support for the `format!` syntax extension. //! This macro is implemented in the compiler to emit calls to this module in -//! order to format arguments at runtime into strings and streams. +//! order to format arguments at runtime into strings. //! //! # Usage //! //! The `format!` macro is intended to be familiar to those coming from C's -//! printf/fprintf functions or Python's `str.format` function. In its current -//! revision, the `format!` macro returns a `String` type which is the result of -//! the formatting. In the future it will also be able to pass in a stream to -//! format arguments directly while performing minimal allocations. +//! printf/fprintf functions or Python's `str.format` function. //! //! Some examples of the `format!` extension are: //! @@ -81,7 +78,7 @@ //! //! ``` //! format!("{argument}", argument = "test"); // => "test" -//! format!("{name} {}", 1, name = 2); // => "2 1" +//! format!("{name} {}", 1, name = 2); // => "2 1" //! format!("{a} {c} {b}", a="a", b='b', c=3); // => "a 3 b" //! ``` //! @@ -104,8 +101,8 @@ //! octal. //! //! There are various parameters which do require a particular type, however. -//! Namely, the `{:.*}` syntax, which sets the number of numbers after the -//! decimal in floating-point types: +//! An example is the `{:.*}` syntax, which sets the number of decimal places +//! in floating-point types: //! //! ``` //! let formatted_number = format!("{:.*}", 2, 1.234567); @@ -292,15 +289,13 @@ //! use std::fmt; //! use std::io::{self, Write}; //! -//! fmt::format(format_args!("this returns {}", "String")); -//! //! let mut some_writer = io::stdout(); //! write!(&mut some_writer, "{}", format_args!("print with a {}", "macro")); //! //! fn my_fmt_fn(args: fmt::Arguments) { //! write!(&mut io::stdout(), "{}", args); //! } -//! my_fmt_fn(format_args!("or a {} too", "function")); +//! my_fmt_fn(format_args!(", or a {} too", "function")); //! ``` //! //! The result of the `format_args!` macro is a value of type `fmt::Arguments`. @@ -316,7 +311,7 @@ //! # Syntax //! //! The syntax for the formatting language used is drawn from other languages, -//! so it should not be too alien. Arguments are formatted with python-like +//! so it should not be too alien. Arguments are formatted with Python-like //! syntax, meaning that arguments are surrounded by `{}` instead of the C-like //! `%`. The actual grammar for the formatting syntax is: //! @@ -333,7 +328,7 @@ //! precision := count | '*' //! type := identifier | '' //! count := parameter | integer -//! parameter := integer '$' +//! parameter := argument '$' //! ``` //! //! # Formatting Parameters @@ -403,11 +398,12 @@ //! println!("Hello {:5}!", "x"); //! println!("Hello {:1$}!", "x", 5); //! println!("Hello {1:0$}!", 5, "x"); +//! println!("Hello {:width$}!", "x", width = 5); //! ``` //! //! Referring to an argument with the dollar syntax does not affect the "next -//! argument" counter, so it's usually a good idea to refer to all arguments by -//! their position explicitly. +//! argument" counter, so it's usually a good idea to refer to arguments by +//! position, or use named arguments. //! //! ## Precision //! @@ -426,7 +422,7 @@ //! //! the integer `N` itself is the precision. //! -//! 2. An integer followed by dollar sign `.N$`: +//! 2. An integer or name followed by dollar sign `.N$`: //! //! use format *argument* `N` (which must be a `usize`) as the precision. //! @@ -456,6 +452,10 @@ //! // Hello {next arg (x)} is {arg 2 (0.01) with precision //! // specified in its predecessor (5)} //! println!("Hello {} is {2:.*}", "x", 5, 0.01); +//! +//! // Hello {next arg (x)} is {arg "number" (0.01) with precision specified +//! // in arg "prec" (5)} +//! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01); //! ``` //! //! All print the same thing: @@ -516,12 +516,24 @@ use string; /// /// # Examples /// +/// Basic usage: +/// /// ``` /// use std::fmt; /// /// let s = fmt::format(format_args!("Hello, {}!", "world")); -/// assert_eq!(s, "Hello, world!".to_string()); +/// assert_eq!(s, "Hello, world!"); +/// ``` +/// +/// Please note that using [`format!`][format!] might be preferrable. +/// Example: +/// /// ``` +/// let s = format!("Hello, {}!", "world"); +/// assert_eq!(s, "Hello, world!"); +/// ``` +/// +/// [format!]: ../macro.format!.html #[stable(feature = "rust1", since = "1.0.0")] pub fn format(args: Arguments) -> string::String { let mut output = string::String::new(); |