From 351721cde6534d0a20bda8cbacc0019fca6caf3f Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 18 Mar 2015 19:00:51 -0400 Subject: [PATCH] Small formatting fixes to fmt.rs --- src/libcollections/fmt.rs | 45 ++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs index 1deb08ad0d1..fbd07e48a84 100644 --- a/src/libcollections/fmt.rs +++ b/src/libcollections/fmt.rs @@ -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 @@ -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 @@ -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" //! ``` //! @@ -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 @@ -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 @@ -116,7 +116,7 @@ //! {:.*} {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. @@ -142,7 +142,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 { @@ -166,7 +166,7 @@ //! An example of implementing the formatting traits would look //! like: //! -//! ```rust +//! ``` //! use std::fmt; //! use std::f64; //! use std::num::Float; @@ -211,7 +211,7 @@ //! } //! ``` //! -//! #### fmt::Display vs fmt::Debug +//! ### fmt::Display vs fmt::Debug //! //! These two formatting traits have distinct purposes: //! @@ -231,7 +231,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: @@ -245,7 +245,7 @@ //! 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 @@ -253,24 +253,25 @@ //! 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 @@ -303,7 +304,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 @@ -326,14 +327,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 @@ -345,7 +346,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. //! @@ -368,7 +369,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 @@ -384,7 +385,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 @@ -395,7 +396,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