Struct Arguments

pub struct Arguments<'a> { /* private fields */ }

This structure represents a safely precompiled version of a format string and its arguments. This cannot be generated at runtime because it cannot safely be done, so no constructors are given and the fields are private to prevent modification.

The format_args! macro will safely create an instance of this structure. The macro validates the format string at compile-time so usage of the write() and format() functions can be safely performed.

You can use the Arguments<'a> that format_args! returns in Debug and Display contexts as seen below. The example also shows that Debug and Display format to the same thing: the interpolated format string in format_args!.

let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2));
let display = format!("{}", format_args!("{} foo {:?}", 1, 2));
assert_eq!("1 foo 2", display);
assert_eq!(display, debug);

Implementations

impl<'a> Arguments<'a>

Used by the format_args!() macro to create a fmt::Arguments object.

pub const fn new_const<const N: usize>( pieces: &'a [&'static str; N], ) -> Arguments<'a>

🔬This is a nightly-only experimental API. (fmt_internals)

pub fn new_v1<const P: usize, const A: usize>( pieces: &'a [&'static str; P], args: &'a [Argument<'a>; A], ) -> Arguments<'a>

🔬This is a nightly-only experimental API. (fmt_internals)

When using the format_args!() macro, this function is used to generate the Arguments structure.

pub fn new_v1_formatted( pieces: &'a [&'static str], args: &'a [Argument<'a>], fmt: &'a [Placeholder], _unsafe_arg: UnsafeArg, ) -> Arguments<'a>

🔬This is a nightly-only experimental API. (fmt_internals)

Specifies nonstandard formatting parameters.

An rt::UnsafeArg is required because the following invariants must be held in order for this function to be safe:

1. The pieces slice must be at least as long as fmt.
2. Every rt::Placeholder::position value within fmt must be a valid index of args.
3. Every rt::Count::Param within fmt must contain a valid index of args.

pub fn estimated_capacity(&self) -> usize

🔬This is a nightly-only experimental API. (fmt_internals)

Estimates the length of the formatted text.

This is intended to be used for setting initial String capacity when using format!. Note: this is neither the lower nor upper bound.

impl<'a> Arguments<'a>

pub const fn as_str(&self) -> Option<&'static str>

Gets the formatted string, if it has no arguments to be formatted at runtime.

This can be used to avoid allocations in some cases.

Guarantees

For format_args!("just a literal"), this function is guaranteed to return Some("just a literal").

For most cases with placeholders, this function will return None.

However, the compiler may perform optimizations that can cause this function to return Some(_) even if the format string contains placeholders. For example, format_args!("Hello, {}!", "world") may be optimized to format_args!("Hello, world!"), such that as_str() returns Some("Hello, world!").

The behavior for anything but the trivial case (without placeholders) is not guaranteed, and should not be relied upon for anything other than optimization.

Examples

use std::fmt::Arguments;

fn write_str(_: &str) { /* ... */ }

fn write_fmt(args: &Arguments<'_>) {
    if let Some(s) = args.as_str() {
        write_str(s)
    } else {
        write_str(&args.to_string());
    }
}

assert_eq!(format_args!("hello").as_str(), Some("hello"));
assert_eq!(format_args!("").as_str(), Some(""));
assert_eq!(format_args!("{:?}", std::env::current_dir()).as_str(), None);

Trait Implementations

impl<'a> Clone for Arguments<'a>

fn clone(&self) -> Arguments<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Arguments<'_>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Arguments<'_>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a> Serialize for Arguments<'a>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> Copy for Arguments<'a>

impl !Send for Arguments<'_>

impl !Sync for Arguments<'_>