fmt.rs - source
Description: Source of the Rust file `library/alloc/src/fmt.rs`.

#
alloc/
fmt.rs

    1//! Utilities for formatting and printing `String`s.
    2//!
    3//! This module contains the runtime support for the [`format!`] syntax extension.
    4//! This macro is implemented in the compiler to emit calls to this module in
    5//! order to format arguments at runtime into strings.
    6//!
    7//! # Usage
    8//!
    9//! The [`format!`] macro is intended to be familiar to those coming from C's
    10//! `printf`/`fprintf` functions or Python's `str.format` function.
    11//!
    12//! Some examples of the [`format!`] extension are:
    13//!
    14//! ```
    15//! # #![allow(unused_must_use)]
    16//! format!("Hello");                 // => "Hello"
    17//! format!("Hello, {}!", "world");   // => "Hello, world!"
    18//! format!("The number is {}", 1);   // => "The number is 1"
    19//! format!("{:?}", (3, 4));          // => "(3, 4)"
    20//! format!("{value}", value=4);      // => "4"
    21//! let people = "Rustaceans";
    22//! format!("Hello {people}!");       // => "Hello Rustaceans!"
    23//! format!("{} {}", 1, 2);           // => "1 2"
    24//! format!("{:04}", 42);             // => "0042" with leading zeros
    25//! format!("{:#?}", (100, 200));     // => "(
    26//!                                   //       100,
    27//!                                   //       200,
    28//!                                   //     )"
    29//! ```
    30//!
    31//! From these, you can see that the first argument is a format string. It is
    32//! required by the compiler for this to be a string literal; it cannot be a
    33//! variable passed in (in order to perform validity checking). The compiler
    34//! will then parse the format string and determine if the list of arguments
    35//! provided is suitable to pass to this format string.
    36//!
    37//! To convert a single value to a string, use the [`to_string`] method. This
    38//! will use the [`Display`] formatting trait.
    39//!
    40//! ## Positional parameters
    41//!
    42//! Each formatting argument is allowed to specify which value argument it's
    43//! referencing, and if omitted it is assumed to be "the next argument". For
    44//! example, the format string `{} {} {}` would take three parameters, and they
    45//! would be formatted in the same order as they're given. The format string
    46//! `{2} {1} {0}`, however, would format arguments in reverse order.
    47//!
    48//! Things can get a little tricky once you start intermingling the two types of
    49//! positional specifiers. The "next argument" specifier can be thought of as an
    50//! iterator over the argument. Each time a "next argument" specifier is seen,
    51//! the iterator advances. This leads to behavior like this:
    52//!
    53//! ```
    54//! # #![allow(unused_must_use)]
    55//! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2"
    56//! ```
    57//!
    58//! The internal iterator over the argument has not been advanced by the time
    59//! the first `{}` is seen, so it prints the first argument. Then upon reaching
    60//! the second `{}`, the iterator has advanced forward to the second argument.
    61//! Essentially, parameters that explicitly name their argument do not affect
    62//! parameters that do not name an argument in terms of positional specifiers.
    63//!
    64//! A format string is required to use all of its arguments, otherwise it is a
    65//! compile-time error. You may refer to the same argument more than once in the
    66//! format string.
    67//!
    68//! ## Named parameters
    69//!
    70//! Rust itself does not have a Python-like equivalent of named parameters to a
    71//! function, but the [`format!`] macro is a syntax extension that allows it to
    72//! leverage named parameters. Named parameters are listed at the end of the
    73//! argument list and have the syntax:
    74//!
    75//! ```text
    76//! identifier '=' expression
    77//! ```
    78//!
    79//! For example, the following [`format!`] expressions all use named arguments:
    80//!
    81//! ```
    82//! # #![allow(unused_must_use)]
    83//! format!("{argument}", argument = "test");   // => "test"
    84//! format!("{name} {}", 1, name = 2);          // => "2 1"
    85//! format!("{a} {c} {b}", a="a", b='b', c=3);  // => "a 3 b"
    86//! ```
    87//!
    88//! If a named parameter does not appear in the argument list, `format!` will
    89//! reference a variable with that name in the current scope.
    90//!
    91//! ```
    92//! # #![allow(unused_must_use)]
    93//! let argument = 2 + 2;
    94//! format!("{argument}");   // => "4"
    95//!
    96//! fn make_string(a: u32, b: &str) -> String {
    97//!     format!("{b} {a}")
    98//! }
    99//! make_string(927, "label"); // => "label 927"
    100//! ```
    101//!
    102//! It is not valid to put positional parameters (those without names) after
    103//! arguments that have names. Like with positional parameters, it is not
    104//! valid to provide named parameters that are unused by the format string.
    105//!
    106//! # Formatting Parameters
    107//!
    108//! Each argument being formatted can be transformed by a number of formatting
    109//! parameters (corresponding to `format_spec` in [the syntax](#syntax)). These
    110//! parameters affect the string representation of what's being formatted.
    111//!
    112//! The colon `:` in format syntax divides identifier of the input data and
    113//! the formatting options, the colon itself does not change anything, only
    114//! introduces the options.
    115//!
    116//! ```
    117//! let a = 5;
    118//! let b = &a;
    119//! println!("{a:e} {b:p}"); // => 5e0 0x7ffe37b7273c
    120//! ```
    121//!
    122//! ## Width
    123//!
    124//! ```
    125//! // All of these print "Hello x    !"
    126//! println!("Hello {:5}!", "x");
    127//! println!("Hello {:1$}!", "x", 5);
    128//! println!("Hello {1:0$}!", 5, "x");
    129//! println!("Hello {:width$}!", "x", width = 5);
    130//! let width = 5;
    131//! println!("Hello {:width$}!", "x");
    132//! ```
    133//!
    134//! This is a parameter for the "minimum width" that the format should take up.
    135//! If the value's string does not fill up this many characters, then the
    136//! padding specified by fill/alignment will be used to take up the required
    137//! space (see below).
    138//!
    139//! The value for the width can also be provided as a [`usize`] in the list of
    140//! parameters by adding a postfix `$`, indicating that the second argument is
    141//! a [`usize`] specifying the width.
    142//!
    143//! Referring to an argument with the dollar syntax does not affect the "next
    144//! argument" counter, so it's usually a good idea to refer to arguments by
    145//! position, or use named arguments.
    146//!
    147//! ## Fill/Alignment
    148//!
    149//! ```
    150//! assert_eq!(format!("Hello {:<5}!", "x"),  "Hello x    !");
    151//! assert_eq!(format!("Hello {:-<5}!", "x"), "Hello x----!");
    152//! assert_eq!(format!("Hello {:^5}!", "x"),  "Hello   x  !");
    153//! assert_eq!(format!("Hello {:>5}!", "x"),  "Hello     x!");
    154//! ```
    155//!
    156//! The optional fill character and alignment is provided normally in conjunction with the
    157//! [`width`](#width) parameter. It must be defined before `width`, right after the `:`.
    158//! This indicates that if the value being formatted is smaller than
    159//! `width` some extra characters will be printed around it.
    160//! Filling comes in the following variants for different alignments:
    161//!
    162//! * `[fill]<` - the argument is left-aligned in `width` columns
    163//! * `[fill]^` - the argument is center-aligned in `width` columns
    164//! * `[fill]>` - the argument is right-aligned in `width` columns
    165//!
    166//! The default [fill/alignment](#fillalignment) for non-numerics is a space and
    167//! left-aligned. The
    168//! default for numeric formatters is also a space character but with right-alignment. If
    169//! the `0` flag (see below) is specified for numerics, then the implicit fill character is
    170//! `0`.
    171//!
    172//! Note that alignment might not be implemented by some types. In particular, it
    173//! is not generally implemented for the `Debug` trait.  A good way to ensure
    174//! padding is applied is to format your input, then pad this resulting string
    175//! to obtain your output:
    176//!
    177//! ```
    178//! println!("Hello {:^15}!", format!("{:?}", Some("hi"))); // => "Hello   Some("hi")   !"
    179//! ```
    180//!
    181//! ## Sign/`#`/`0`
    182//!
    183//! ```
    184//! assert_eq!(format!("Hello {:+}!", 5), "Hello +5!");
    185//! assert_eq!(format!("{:#x}!", 27), "0x1b!");
    186//! assert_eq!(format!("Hello {:05}!", 5),  "Hello 00005!");
    187//! assert_eq!(format!("Hello {:05}!", -5), "Hello -0005!");
    188//! assert_eq!(format!("{:#010x}!", 27), "0x0000001b!");
    189//! ```
    190//!
    191//! These are all flags altering the behavior of the formatter.
    192//!
    193//! * `+` - This is intended for numeric types and indicates that the sign
    194//!         should always be printed. By default only the negative sign of signed values
    195//!         is printed, and the sign of positive or unsigned values is omitted.
    196//!         This flag indicates that the correct sign (`+` or `-`) should always be printed.
    197//! * `-` - Currently not used
    198//! * `#` - This flag indicates that the "alternate" form of printing should
    199//!         be used. The alternate forms are:
    200//!     * `#?` - pretty-print the [`Debug`] formatting (adds linebreaks and indentation)
    201//!     * `#x` - precedes the argument with a `0x`
    202//!     * `#X` - precedes the argument with a `0x`
    203//!     * `#b` - precedes the argument with a `0b`
    204//!     * `#o` - precedes the argument with a `0o`
    205//!
    206//!   See [Formatting traits](#formatting-traits) for a description of what the `?`, `x`, `X`,
    207//!   `b`, and `o` flags do.
    208//!
    209//! * `0` - This is used to indicate for integer formats that the padding to `width` should
    210//!         both be done with a `0` character as well as be sign-aware. A format
    211//!         like `{:08}` would yield `00000001` for the integer `1`, while the
    212//!         same format would yield `-0000001` for the integer `-1`. Notice that
    213//!         the negative version has one fewer zero than the positive version.
    214//!         Note that padding zeros are always placed after the sign (if any)
    215//!         and before the digits. When used together with the `#` flag, a similar
    216//!         rule applies: padding zeros are inserted after the prefix but before
    217//!         the digits. The prefix is included in the total width.
    218//!         This flag overrides the [fill character and alignment flag](#fillalignment).
    219//!
    220//! ## Precision
    221//!
    222//! For non-numeric types, this can be considered a "maximum width". If the resulting string is
    223//! longer than this width, then it is truncated down to this many characters and that truncated
    224//! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set.
    225//!
    226//! For integral types, this is ignored.
    227//!
    228//! For floating-point types, this indicates how many digits after the decimal point should be
    229//! printed.
    230//!
    231//! There are three possible ways to specify the desired `precision`:
    232//!
    233//! 1. An integer `.N`:
    234//!
    235//!    the integer `N` itself is the precision.
    236//!
    237//! 2. An integer or name followed by dollar sign `.N$`:
    238//!
    239//!    use format *argument* `N` (which must be a `usize`) as the precision.
    240//!
    241//! 3. An asterisk `.*`:
    242//!
    243//!    `.*` means that this `{...}` is associated with *two* format inputs rather than one:
    244//!    - If a format string in the fashion of `{:<spec>.*}` is used, then the first input holds
    245//!      the `usize` precision, and the second holds the value to print.
    246//!    - If a format string in the fashion of `{<arg>:<spec>.*}` is used, then the `<arg>` part
    247//!      refers to the value to print, and the `precision` is taken like it was specified with an
    248//!      omitted positional parameter (`{}` instead of `{<arg>:}`).
    249//!
    250//! For example, the following calls all print the same thing `Hello x is 0.01000`:
    251//!
    252//! ```
    253//! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)}
    254//! println!("Hello {0} is {1:.5}", "x", 0.01);
    255//!
    256//! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)}
    257//! println!("Hello {1} is {2:.0$}", 5, "x", 0.01);
    258//!
    259//! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)}
    260//! println!("Hello {0} is {2:.1$}", "x", 5, 0.01);
    261//!
    262//! // Hello {next arg -> arg 0 ("x")} is {second of next two args -> arg 2 (0.01) with precision
    263//! //                          specified in first of next two args -> arg 1 (5)}
    264//! println!("Hello {} is {:.*}",    "x", 5, 0.01);
    265//!
    266//! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision
    267//! //                          specified in next arg -> arg 0 (5)}
    268//! println!("Hello {1} is {2:.*}",  5, "x", 0.01);
    269//!
    270//! // Hello {next arg -> arg 0 ("x")} is {arg 2 (0.01) with precision
    271//! //                          specified in next arg -> arg 1 (5)}
    272//! println!("Hello {} is {2:.*}",   "x", 5, 0.01);
    273//!
    274//! // Hello {next arg -> arg 0 ("x")} is {arg "number" (0.01) with precision specified
    275//! //                          in arg "prec" (5)}
    276//! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01);
    277//! ```
    278//!
    279//! While these:
    280//!
    281//! ```
    282//! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56);
    283//! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56");
    284//! println!("{}, `{name:>8.*}` has 3 right-aligned characters", "Hello", 3, name="1234.56");
    285//! ```
    286//!
    287//! print three significantly different things:
    288//!
    289//! ```text
    290//! Hello, `1234.560` has 3 fractional digits
    291//! Hello, `123` has 3 characters
    292//! Hello, `     123` has 3 right-aligned characters
    293//! ```
    294//!
    295//! When truncating these values, Rust uses [round half-to-even](https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even),
    296//! which is the default rounding mode in IEEE 754.
    297//! For example,
    298//!
    299//! ```
    300//! print!("{0:.1$e}", 12345, 3);
    301//! print!("{0:.1$e}", 12355, 3);
    302//! ```
    303//!
    304//! Would return:
    305//!
    306//! ```text
    307//! 1.234e4
    308//! 1.236e4
    309//! ```
    310//!
    311//! ## Localization
    312//!
    313//! In some programming languages, the behavior of string formatting functions
    314//! depends on the operating system's locale setting. The format functions
    315//! provided by Rust's standard library do not have any concept of locale and
    316//! will produce the same results on all systems regardless of user
    317//! configuration.
    318//!
    319//! For example, the following code will always print `1.5` even if the system
    320//! locale uses a decimal separator other than a dot.
    321//!
    322//! ```
    323//! println!("The value is {}", 1.5);
    324//! ```
    325//!
    326//! # Escaping
    327//!
    328//! The literal characters `{` and `}` may be included in a string by preceding
    329//! them with the same character. For example, the `{` character is escaped with
    330//! `{{` and the `}` character is escaped with `}}`.
    331//!
    332//! ```
    333//! assert_eq!(format!("Hello {{}}"), "Hello {}");
    334//! assert_eq!(format!("{{ Hello"), "{ Hello");
    335//! ```
    336//!
    337//! # Syntax
    338//!
    339//! To summarize, here you can find the full grammar of format strings.
    340//! The syntax for the formatting language used is drawn from other languages,
    341//! so it should not be too alien. Arguments are formatted with Python-like
    342//! syntax, meaning that arguments are surrounded by `{}` instead of the C-like
    343//! `%`. The actual grammar for the formatting syntax is:
    344//!
    345//! ```text
    346//! format_string := text [ maybe_format text ] *
    347//! maybe_format := '{' '{' | '}' '}' | format
    348//! format := '{' [ argument ] [ ':' format_spec ] [ ws ] * '}'
    349//! argument := integer | identifier
    350//!
    351//! format_spec := [[fill]align][sign]['#']['0'][width]['.' precision][type]
    352//! fill := character
    353//! align := '<' | '^' | '>'
    354//! sign := '+' | '-'
    355//! width := count
    356//! precision := count | '*'
    357//! type := '?' | 'x?' | 'X?' | 'o' | 'x' | 'X' | 'p' | 'b' | 'e' | 'E'
    358//! count := parameter | integer
    359//! parameter := argument '$'
    360//! ```
    361//! In the above grammar,
    362//! - `text` must not contain any `'{'` or `'}'` characters,
    363//! - `ws` is any character for which [`char::is_whitespace`] returns `true`, has no semantic
    364//!   meaning and is completely optional,
    365//! - `integer` is a decimal integer that may contain leading zeroes and must fit into an `usize` and
    366//! - `identifier` is an `IDENTIFIER_OR_KEYWORD` (not an `IDENTIFIER`) as defined by the [Rust language reference](https://doc.rust-lang.org/reference/identifiers.html).
    367//!
    368//! # Formatting traits
    369//!
    370//! When requesting that an argument be formatted with a particular type, you
    371//! are actually requesting that an argument ascribes to a particular trait.
    372//! This allows multiple actual types to be formatted via `{:x}` (like [`i8`] as
    373//! well as [`isize`]). The current mapping of types to traits is:
    374//!
    375//! * *nothing* ⇒ [`Display`]
    376//! * `?` ⇒ [`Debug`]
    377//! * `x?` ⇒ [`Debug`] with lower-case hexadecimal integers
    378//! * `X?` ⇒ [`Debug`] with upper-case hexadecimal integers
    379//! * `o` ⇒ [`Octal`]
    380//! * `x` ⇒ [`LowerHex`]
    381//! * `X` ⇒ [`UpperHex`]
    382//! * `p` ⇒ [`Pointer`]
    383//! * `b` ⇒ [`Binary`]
    384//! * `e` ⇒ [`LowerExp`]
    385//! * `E` ⇒ [`UpperExp`]
    386//!
    387//! What this means is that any type of argument which implements the
    388//! [`fmt::Binary`][`Binary`] trait can then be formatted with `{:b}`. Implementations
    389//! are provided for these traits for a number of primitive types by the
    390//! standard library as well. If no format is specified (as in `{}` or `{:6}`),
    391//! then the format trait used is the [`Display`] trait.
    392//!
    393//! When implementing a format trait for your own type, you will have to
    394//! implement a method of the signature:
    395//!
    396//! ```
    397//! # #![allow(dead_code)]
    398//! # use std::fmt;
    399//! # struct Foo; // our custom type
    400//! # impl fmt::Display for Foo {
    401//! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    402//! # write!(f, "testing, testing")
    403//! # } }
    404//! ```
    405//!
    406//! Your type will be passed as `self` by-reference, and then the function
    407//! should emit output into the Formatter `f` which implements `fmt::Write`. It is up to each
    408//! format trait implementation to correctly adhere to the requested formatting parameters.
    409//! The values of these parameters can be accessed with methods of the
    410//! [`Formatter`] struct. In order to help with this, the [`Formatter`] struct also
    411//! provides some helper methods.
    412//!
    413//! Additionally, the return value of this function is [`fmt::Result`] which is a
    414//! type alias of <code>[Result]<(), [std::fmt::Error]></code>. Formatting implementations
    415//! should ensure that they propagate errors from the [`Formatter`] (e.g., when
    416//! calling [`write!`]). However, they should never return errors spuriously. That
    417//! is, a formatting implementation must and may only return an error if the
    418//! passed-in [`Formatter`] returns an error. This is because, contrary to what
    419//! the function signature might suggest, string formatting is an infallible
    420//! operation. This function only returns a [`Result`] because writing to the
    421//! underlying stream might fail and it must provide a way to propagate the fact
    422//! that an error has occurred back up the stack.
    423//!
    424//! An example of implementing the formatting traits would look
    425//! like:
    426//!
    427//! ```
    428//! use std::fmt;
    429//!
    430//! #[derive(Debug)]
    431//! struct Vector2D {
    432//!     x: isize,
    433//!     y: isize,
    434//! }
    435//!
    436//! impl fmt::Display for Vector2D {
    437//!     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    438//!         // The `f` value implements the `Write` trait, which is what the
    439//!         // write! macro is expecting. Note that this formatting ignores the
    440//!         // various flags provided to format strings.
    441//!         write!(f, "({}, {})", self.x, self.y)
    442//!     }
    443//! }
    444//!
    445//! // Different traits allow different forms of output of a type. The meaning
    446//! // of this format is to print the magnitude of a vector.
    447//! impl fmt::Binary for Vector2D {
    448//!     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    449//!         let magnitude = (self.x * self.x + self.y * self.y) as f64;
    450//!         let magnitude = magnitude.sqrt();
    451//!
    452//!         // Respect the formatting flags by using the helper method
    453//!         // `pad_integral` on the Formatter object. See the method
    454//!         // documentation for details, and the function `pad` can be used
    455//!         // to pad strings.
    456//!         let decimals = f.precision().unwrap_or(3);
    457//!         let string = format!("{magnitude:.decimals$}");
    458//!         f.pad_integral(true, "", &string)
    459//!     }
    460//! }
    461//!
    462//! fn main() {
    463//!     let myvector = Vector2D { x: 3, y: 4 };
    464//!
    465//!     println!("{myvector}");       // => "(3, 4)"
    466//!     println!("{myvector:?}");     // => "Vector2D {x: 3, y:4}"
    467//!     println!("{myvector:10.3b}"); // => "     5.000"
    468//! }
    469//! ```
    470//!
    471//! ### `fmt::Display` vs `fmt::Debug`
    472//!
    473//! These two formatting traits have distinct purposes:
    474//!
    475//! - [`fmt::Display`][`Display`] implementations assert that the type can be faithfully
    476//!   represented as a UTF-8 string at all times. It is **not** expected that
    477//!   all types implement the [`Display`] trait.
    478//! - [`fmt::Debug`][`Debug`] implementations should be implemented for **all** public types.
    479//!   Output will typically represent the internal state as faithfully as possible.
    480//!   The purpose of the [`Debug`] trait is to facilitate debugging Rust code. In
    481//!   most cases, using `#[derive(Debug)]` is sufficient and recommended.
    482//!
    483//! Some examples of the output from both traits:
    484//!
    485//! ```
    486//! assert_eq!(format!("{} {:?}", 3, 4), "3 4");
    487//! assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'");
    488//! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
    489//! ```
    490//!
    491//! # Related macros
    492//!
    493//! There are a number of related macros in the [`format!`] family. The ones that
    494//! are currently implemented are:
    495//!
    496//! ```ignore (only-for-syntax-highlight)
    497//! format!      // described above
    498//! write!       // first argument is either a &mut io::Write or a &mut fmt::Write, the destination
    499//! writeln!     // same as write but appends a newline
    500//! print!       // the format string is printed to the standard output
    501//! println!     // same as print but appends a newline
    502//! eprint!      // the format string is printed to the standard error
    503//! eprintln!    // same as eprint but appends a newline
    504//! format_args! // described below.
    505//! ```
    506//!
    507//! ### `write!`
    508//!
    509//! [`write!`] and [`writeln!`] are two macros which are used to emit the format string
    510//! to a specified stream. This is used to prevent intermediate allocations of
    511//! format strings and instead directly write the output. Under the hood, this
    512//! function is actually invoking the [`write_fmt`] function defined on the
    513//! [`std::io::Write`] and the [`std::fmt::Write`] trait. Example usage is:
    514//!
    515//! ```
    516//! # #![allow(unused_must_use)]
    517//! use std::io::Write;
    518//! let mut w = Vec::new();
    519//! write!(&mut w, "Hello {}!", "world");
    520//! ```
    521//!
    522//! ### `print!`
    523//!
    524//! This and [`println!`] emit their output to stdout. Similarly to the [`write!`]
    525//! macro, the goal of these macros is to avoid intermediate allocations when
    526//! printing output. Example usage is:
    527//!
    528//! ```
    529//! print!("Hello {}!", "world");
    530//! println!("I have a newline {}", "character at the end");
    531//! ```
    532//! ### `eprint!`
    533//!
    534//! The [`eprint!`] and [`eprintln!`] macros are identical to
    535//! [`print!`] and [`println!`], respectively, except they emit their
    536//! output to stderr.
    537//!
    538//! ### `format_args!`
    539//!
    540//! [`format_args!`] is a curious macro used to safely pass around
    541//! an opaque object describing the format string. This object
    542//! does not require any heap allocations to create, and it only
    543//! references information on the stack. Under the hood, all of
    544//! the related macros are implemented in terms of this. First
    545//! off, some example usage is:
    546//!
    547//! ```
    548//! # #![allow(unused_must_use)]
    549//! use std::fmt;
    550//! use std::io::{self, Write};
    551//!
    552//! let mut some_writer = io::stdout();
    553//! write!(&mut some_writer, "{}", format_args!("print with a {}", "macro"));
    554//!
    555//! fn my_fmt_fn(args: fmt::Arguments<'_>) {
    556//!     write!(&mut io::stdout(), "{args}");
    557//! }
    558//! my_fmt_fn(format_args!(", or a {} too", "function"));
    559//! ```
    560//!
    561//! The result of the [`format_args!`] macro is a value of type [`fmt::Arguments`].
    562//! This structure can then be passed to the [`write`] and [`format`] functions
    563//! inside this module in order to process the format string.
    564//! The goal of this macro is to even further prevent intermediate allocations
    565//! when dealing with formatting strings.
    566//!
    567//! For example, a logging library could use the standard formatting syntax, but
    568//! it would internally pass around this structure until it has been determined
    569//! where output should go to.
    570//!
    571//! [`fmt::Result`]: Result "fmt::Result"
    572//! [Result]: core::result::Result "std::result::Result"
    573//! [std::fmt::Error]: Error "fmt::Error"
    574//! [`write`]: write() "fmt::write"
    575//! [`to_string`]: crate::string::ToString::to_string "ToString::to_string"
    576//! [`write_fmt`]: ../../std/io/trait.Write.html#method.write_fmt
    577//! [`std::io::Write`]: ../../std/io/trait.Write.html
    578//! [`std::fmt::Write`]: ../../std/fmt/trait.Write.html
    579//! [`print!`]: ../../std/macro.print.html "print!"
    580//! [`println!`]: ../../std/macro.println.html "println!"
    581//! [`eprint!`]: ../../std/macro.eprint.html "eprint!"
    582//! [`eprintln!`]: ../../std/macro.eprintln.html "eprintln!"
    583//! [`format_args!`]: ../../std/macro.format_args.html "format_args!"
    584//! [`fmt::Arguments`]: Arguments "fmt::Arguments"
    585//! [`format`]: format() "fmt::format"
    586
    587#![stable(feature = "rust1", since = "1.0.0")]
    588
    589#[stable(feature = "fmt_flags_align", since = "1.28.0")]
    590pub use core::fmt::Alignment;
    591#[stable(feature = "rust1", since = "1.0.0")]
    592pub use core::fmt::Error;
    593#[stable(feature = "rust1", since = "1.0.0")]
    594pub use core::fmt::{Arguments, write};
    595#[stable(feature = "rust1", since = "1.0.0")]
    596pub use core::fmt::{Binary, Octal};
    597#[stable(feature = "rust1", since = "1.0.0")]
    598pub use core::fmt::{Debug, Display};
    599#[unstable(feature = "formatting_options", issue = "118117")]
    600pub use core::fmt::{DebugAsHex, FormattingOptions, Sign};
    601#[stable(feature = "rust1", since = "1.0.0")]
    602pub use core::fmt::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple};
    603#[stable(feature = "rust1", since = "1.0.0")]
    604pub use core::fmt::{Formatter, Result, Write};
    605#[stable(feature = "fmt_from_fn", since = "1.93.0")]
    606pub use core::fmt::{FromFn, from_fn};
    607#[stable(feature = "rust1", since = "1.0.0")]
    608pub use core::fmt::{LowerExp, UpperExp};
    609#[stable(feature = "rust1", since = "1.0.0")]
    610pub use core::fmt::{LowerHex, Pointer, UpperHex};
    611
    612#[cfg(not(no_global_oom_handling))]
    613use crate::string;
    614
    615/// Takes an [`Arguments`] struct and returns the resulting formatted string.
    616///
    617/// The [`Arguments`] instance can be created with the [`format_args!`] macro.
    618///
    619/// # Examples
    620///
    621/// Basic usage:
    622///
    623/// ```
    624/// use std::fmt;
    625///
    626/// let s = fmt::format(format_args!("Hello, {}!", "world"));
    627/// assert_eq!(s, "Hello, world!");
    628/// ```
    629///
    630/// Please note that using [`format!`] might be preferable.
    631/// Example:
    632///
    633/// ```
    634/// let s = format!("Hello, {}!", "world");
    635/// assert_eq!(s, "Hello, world!");
    636/// ```
    637///
    638/// [`format_args!`]: core::format_args
    639/// [`format!`]: crate::format
    640#[cfg(not(no_global_oom_handling))]
    641#[must_use]
    642#[stable(feature = "rust1", since = "1.0.0")]
    643#[inline]
    644pub fn format(args: Arguments<'_>) -> string::String {
    645    fn format_inner(args: Arguments<'_>) -> string::String {
    646        let capacity = args.estimated_capacity();
    647        let mut output = string::String::with_capacity(capacity);
    648        output
    649            .write_fmt(args)
    650            .expect("a formatting trait implementation returned an error when the underlying stream did not");
    651        output
    652    }
    653
    654    args.as_str().map_or_else(|| format_inner(args), crate::borrow::ToOwned::to_owned)
    655}