Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document {:.*} #23493

Closed
wants to merge 2 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 35 additions & 27 deletions src/libcollections/fmt.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
//! This macro is implemented in the compiler to emit calls to this module in
//! order to format arguments at runtime into strings and streams.
//!
//! ## Usage
//! # 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
Expand All @@ -41,7 +41,7 @@
//! will then parse the format string and determine if the list of arguments
//! provided is suitable to pass to this format string.
//!
//! ### Positional parameters
//! ## Positional parameters
//!
//! Each formatting argument is allowed to specify which value argument it's
//! referencing, and if omitted it is assumed to be "the next argument". For
Expand All @@ -54,7 +54,7 @@
//! iterator over the argument. Each time a "next argument" specifier is seen,
//! the iterator advances. This leads to behavior like this:
//!
//! ```rust
//! ```
//! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2"
//! ```
//!
Expand All @@ -68,7 +68,7 @@
//! compile-time error. You may refer to the same argument more than once in the
//! format string, although it must always be referred to with the same type.
//!
//! ### Named parameters
//! ## Named parameters
//!
//! Rust itself does not have a Python-like equivalent of named parameters to a
//! function, but the `format!` macro is a syntax extension which allows it to
Expand All @@ -91,7 +91,7 @@
//! arguments which have names. Like with positional parameters, it is illegal
//! to provide named parameters that are unused by the format string.
//!
//! ### Argument types
//! ## Argument types
//!
//! Each argument's type is dictated by the format string. It is a requirement
//! that every argument is only ever referred to by one type. For example, this
Expand All @@ -105,18 +105,25 @@
//! hexadecimal as well as an
//! octal.
//!
//! There are various parameters which do require a particular type, however.
//! Namely if the syntax `{:.*}` is used, then the number of characters to print
//! precedes the actual object being formatted, and the number of characters
//! must have the type `usize`. Although a `usize` can be printed with `{}`, it is
//! illegal to reference an argument as such. For example this is another
//! 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:
//!
//! ```
//! let formatted_number = format!("{:.*}", 2, 1.234567);
//!
//! assert_eq!("1.23", formatted_number)
//! ```
//!
//! If this syntax is used, then the number of characters to print precedes the actual object being
//! formatted, and the number of characters must have the type `usize`. Although a `usize` can be
//! printed with `{}`, it is illegal to reference an argument as such. For example this is another
//! invalid format string:
//!
//! ```text
//! {:.*} {0}
//! ```
//!
//! ### Formatting traits
//! ## Formatting traits
//!
//! When requesting that an argument be formatted with a particular type, you
//! are actually requesting that an argument ascribes to a particular trait.
Expand All @@ -142,7 +149,7 @@
//! When implementing a format trait for your own type, you will have to
//! implement a method of the signature:
//!
//! ```rust
//! ```
//! # use std::fmt;
//! # struct Foo; // our custom type
//! # impl fmt::Display for Foo {
Expand All @@ -166,7 +173,7 @@
//! An example of implementing the formatting traits would look
//! like:
//!
//! ```rust
//! ```
//! use std::fmt;
//! use std::f64;
//! use std::num::Float;
Expand Down Expand Up @@ -211,7 +218,7 @@
//! }
//! ```
//!
//! #### fmt::Display vs fmt::Debug
//! ### fmt::Display vs fmt::Debug
//!
//! These two formatting traits have distinct purposes:
//!
Expand All @@ -231,7 +238,7 @@
//! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
//! ```
//!
//! ### Related macros
//! ## Related macros
//!
//! There are a number of related macros in the `format!` family. The ones that
//! are currently implemented are:
Expand All @@ -245,32 +252,33 @@
//! format_args! // described below.
//! ```
//!
//! #### `write!`
//! ### `write!`
//!
//! This and `writeln` are two macros which are used to emit the format string
//! to a specified stream. This is used to prevent intermediate allocations of
//! format strings and instead directly write the output. Under the hood, this
//! function is actually invoking the `write` function defined in this module.
//! Example usage is:
//!
//! ```rust
//! ```
//! # #![allow(unused_must_use)]
//! let mut w = Vec::new();
//! write!(&mut w, "Hello {}!", "world");
//! ```
//!
//! #### `print!`
//! ### `print!`
//!
//! This and `println` emit their output to stdout. Similarly to the `write!`
//! macro, the goal of these macros is to avoid intermediate allocations when
//! printing output. Example usage is:
//!
//! ```rust
//! ```
//! print!("Hello {}!", "world");
//! println!("I have a newline {}", "character at the end");
//! ```
//!
//! #### `format_args!`
//! ### `format_args!`
//!
//! This is a curious macro which is used to safely pass around
//! an opaque object describing the format string. This object
//! does not require any heap allocations to create, and it only
Expand Down Expand Up @@ -303,7 +311,7 @@
//! it would internally pass around this structure until it has been determined
//! where output should go to.
//!
//! ## Syntax
//! # 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
Expand All @@ -326,14 +334,14 @@
//! parameter := integer '$'
//! ```
//!
//! ## Formatting Parameters
//! # Formatting Parameters
//!
//! Each argument being formatted can be transformed by a number of formatting
//! parameters (corresponding to `format_spec` in the syntax above). These
//! parameters affect the string representation of what's being formatted. This
//! syntax draws heavily from Python's, so it may seem a bit familiar.
//!
//! ### Fill/Alignment
//! ## Fill/Alignment
//!
//! The fill character is provided normally in conjunction with the `width`
//! parameter. This indicates that if the value being formatted is smaller than
Expand All @@ -345,7 +353,7 @@
//! * `^` - the argument is center-aligned in `width` columns
//! * `>` - the argument is right-aligned in `width` columns
//!
//! ### Sign/#/0
//! ## Sign/#/0
//!
//! These can all be interpreted as flags for a particular formatter.
//!
Expand All @@ -368,7 +376,7 @@
//! same format would yield `-0000001` for the integer `-1`. Notice that
//! the negative version has one fewer zero than the positive version.
//!
//! ### Width
//! ## Width
//!
//! This is a parameter for the "minimum width" that the format should take up.
//! If the value's string does not fill up this many characters, then the
Expand All @@ -384,7 +392,7 @@
//! parameters by using the `2$` syntax indicating that the second argument is a
//! `usize` specifying the width.
//!
//! ### Precision
//! ## Precision
//!
//! For non-numeric types, this can be considered a "maximum width". If the
//! resulting string is longer than this width, then it is truncated down to
Expand All @@ -395,7 +403,7 @@
//! For floating-point types, this indicates how many digits after the decimal
//! point should be printed.
//!
//! ## Escaping
//! # Escaping
//!
//! The literal characters `{` and `}` may be included in a string by preceding
//! them with the same character. For example, the `{` character is escaped with
Expand Down