Struct Arguments

pub struct Arguments<'a> { pub(in ::fmt) template: NonNull<u8>, pub(in ::fmt) args: NonNull<Argument<'a>> }

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);

Fields

template: NonNull<u8>
args: NonNull<Argument<'a>>

Implementations

impl<'a> Arguments<'a>

fn estimated_capacity(&self) -> usize

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>

unsafe fn new<const N: usize, const M: usize>(template: &'a [u8; N], args: &'a [Argument<'a>; M]) -> Arguments<'a>
fn from_str_nonconst(s: &'static str) -> Arguments<'a>

impl<'a> Arguments<'a>

const fn from_str(s: &'static str) -> Arguments<'a>

Create a fmt::Arguments object for a single static string.

Formatting this fmt::Arguments will just produce the string as-is.

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);

fn as_statically_known_str(&self) -> Option<&'static str>

Same as Arguments::as_str, but will only return Some(s) if it can be determined at compile time.

Trait Implementations

impl !Send for Arguments<'_>

impl !Sync for Arguments<'_>

impl Debug for Arguments<'_>

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

impl Display for Arguments<'_>

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

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

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

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

impl<'a> TrivialClone for Arguments<'a>

Auto Trait Implementations

impl<'a> Freeze for Arguments<'a>

impl<'a> RefUnwindSafe for Arguments<'a>

impl<'a> Unpin for Arguments<'a>

impl<'a> UnsafeUnpin for Arguments<'a>

impl<'a> UnwindSafe for Arguments<'a>

Blanket Implementations

impl<T> Any for Arguments<'a> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Arguments<'a> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Arguments<'a> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for Arguments<'a> where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> From<T> for Arguments<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Printable for Arguments<'a> where T: Copy + Debug,

impl<T> SizeHint for Arguments<'a> where T: ?Sized,

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

impl<T> SizedTypeProperties for Arguments<'a>

impl<T, U> Into<U> for Arguments<'a> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for Arguments<'a> where U: Into<T>,

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for Arguments<'a> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>