//! Utilities for formatting and printing strings.

#![stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

use crate::cell::{Cell, Ref, RefCell, RefMut, SyncUnsafeCell, UnsafeCell};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::char::{EscapeDebugExtArgs, MAX_LEN_UTF8};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::marker::{PhantomData, PointeeSized};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::num::fmt as numfmt;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::ops::Deref;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::{iter, result, str};

#[cfg(not(feature = "ferrocene_certified"))]

mod builders;

#[cfg(not(no_fp_fmt_parse))]

#[cfg(not(feature = "ferrocene_certified"))]

mod float;

#[cfg(no_fp_fmt_parse)]

#[cfg(not(feature = "ferrocene_certified"))]

mod nofloat;

#[cfg(not(feature = "ferrocene_certified"))]

mod num;

#[cfg(not(feature = "ferrocene_certified"))]

mod num_buffer;

#[cfg(not(feature = "ferrocene_certified"))]

mod rt;

#[stable(feature = "fmt_flags_align", since = "1.28.0")]

#[rustc_diagnostic_item = "Alignment"]

/// Possible alignments returned by `Formatter::align`

#[derive(Copy, Clone, Debug, PartialEq, Eq)]

#[cfg(not(feature = "ferrocene_certified"))]

pub enum Alignment {

    #[stable(feature = "fmt_flags_align", since = "1.28.0")]

    /// Indication that contents should be left-aligned.

    Left,

    #[stable(feature = "fmt_flags_align", since = "1.28.0")]

    /// Indication that contents should be right-aligned.

    Right,

    #[stable(feature = "fmt_flags_align", since = "1.28.0")]

    /// Indication that contents should be center-aligned.

    Center,

}

#[unstable(feature = "int_format_into", issue = "138215")]

#[cfg(not(feature = "ferrocene_certified"))]

pub use num_buffer::{NumBuffer, NumBufferTrait};

#[stable(feature = "debug_builders", since = "1.2.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub use self::builders::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple};

#[unstable(feature = "debug_closure_helpers", issue = "117729")]

#[cfg(not(feature = "ferrocene_certified"))]

pub use self::builders::{FromFn, from_fn};

/// The type returned by formatter methods.

///

/// # Examples

///

/// ```

/// use std::fmt;

///

/// #[derive(Debug)]

/// struct Triangle {

///     a: f32,

///     b: f32,

///     c: f32

/// }

///

/// impl fmt::Display for Triangle {

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

///         write!(f, "({}, {}, {})", self.a, self.b, self.c)

///     }

/// }

///

/// let pythagorean_triple = Triangle { a: 3.0, b: 4.0, c: 5.0 };

///

/// assert_eq!(format!("{pythagorean_triple}"), "(3, 4, 5)");

/// ```

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub type Result = result::Result<(), Error>;

/// The error type which is returned from formatting a message into a stream.

///

/// This type does not support transmission of an error other than that an error

/// occurred. This is because, despite the existence of this error,

/// string formatting is considered an infallible operation.

/// `fmt()` implementors should not return this `Error` unless they received it from their

/// [`Formatter`]. The only time your code should create a new instance of this

/// error is when implementing `fmt::Write`, in order to cancel the formatting operation when

/// writing to the underlying stream fails.

///

/// Any extra information must be arranged to be transmitted through some other means,

/// such as storing it in a field to be consulted after the formatting operation has been

/// cancelled. (For example, this is how [`std::io::Write::write_fmt()`] propagates IO errors

/// during writing.)

///

/// This type, `fmt::Error`, should not be

/// confused with [`std::io::Error`] or [`std::error::Error`], which you may also

/// have in scope.

///

/// [`std::io::Error`]: ../../std/io/struct.Error.html

/// [`std::io::Write::write_fmt()`]: ../../std/io/trait.Write.html#method.write_fmt

/// [`std::error::Error`]: ../../std/error/trait.Error.html

///

/// # Examples

///

/// ```rust

/// use std::fmt::{self, write};

///

/// let mut output = String::new();

/// if let Err(fmt::Error) = write(&mut output, format_args!("Hello {}!", "world")) {

///     panic!("An error occurred");

/// }

/// ```

#[stable(feature = "rust1", since = "1.0.0")]

#[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct Error;

/// A trait for writing or formatting into Unicode-accepting buffers or streams.

///

/// This trait only accepts UTF-8–encoded data and is not [flushable]. If you only

/// want to accept Unicode and you don't need flushing, you should implement this trait;

/// otherwise you should implement [`std::io::Write`].

///

/// [`std::io::Write`]: ../../std/io/trait.Write.html

/// [flushable]: ../../std/io/trait.Write.html#tymethod.flush

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait Write {

    /// Writes a string slice into this writer, returning whether the write

    /// succeeded.

    ///

    /// This method can only succeed if the entire string slice was successfully

    /// written, and this method will not return until all data has been

    /// written or an error occurs.

    ///

    /// # Errors

    ///

    /// This function will return an instance of [`std::fmt::Error`][Error] on error.

    ///

    /// The purpose of that error is to abort the formatting operation when the underlying

    /// destination encounters some error preventing it from accepting more text;

    /// in particular, it does not communicate any information about *what* error occurred.

    /// It should generally be propagated rather than handled, at least when implementing

    /// formatting traits.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::fmt::{Error, Write};

    ///

    /// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {

    ///     f.write_str(s)

    /// }

    ///

    /// let mut buf = String::new();

    /// writer(&mut buf, "hola")?;

    /// assert_eq!(&buf, "hola");

    /// # std::fmt::Result::Ok(())

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

    fn write_str(&mut self, s: &str) -> Result;

    /// Writes a [`char`] into this writer, returning whether the write succeeded.

    ///

    /// A single [`char`] may be encoded as more than one byte.

    /// This method can only succeed if the entire byte sequence was successfully

    /// written, and this method will not return until all data has been

    /// written or an error occurs.

    ///

    /// # Errors

    ///

    /// This function will return an instance of [`Error`] on error.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::fmt::{Error, Write};

    ///

    /// fn writer<W: Write>(f: &mut W, c: char) -> Result<(), Error> {

    ///     f.write_char(c)

    /// }

    ///

    /// let mut buf = String::new();

    /// writer(&mut buf, 'a')?;

    /// writer(&mut buf, 'b')?;

    /// assert_eq!(&buf, "ab");

    /// # std::fmt::Result::Ok(())

    /// ```

    #[stable(feature = "fmt_write_char", since = "1.1.0")]

    /// Glue for usage of the [`write!`] macro with implementors of this trait.

    ///

    /// This method should generally not be invoked manually, but rather through

    /// the [`write!`] macro itself.

    ///

    /// # Errors

    ///

    /// This function will return an instance of [`Error`] on error. Please see

    /// [write_str](Write::write_str) for details.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::fmt::{Error, Write};

    ///

    /// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {

    ///     f.write_fmt(format_args!("{s}"))

    /// }

    ///

    /// let mut buf = String::new();

    /// writer(&mut buf, "world")?;

    /// assert_eq!(&buf, "world");

    /// # std::fmt::Result::Ok(())

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

        // We use a specialization for `Sized` types to avoid an indirection

        // through `&mut self`

        trait SpecWriteFmt {

            fn spec_write_fmt(self, args: Arguments<'_>) -> Result;

        }

        impl<W: Write + ?Sized> SpecWriteFmt for &mut W {

            #[inline]

            default fn spec_write_fmt(mut self, args: Arguments<'_>) -> Result {

                if let Some(s) = args.as_statically_known_str() {

                    self.write_str(s)

                } else {

                    write(&mut self, args)

                }

            }

        }

        impl<W: Write> SpecWriteFmt for &mut W {

            #[inline]

                } else {

                }

        }

}

#[stable(feature = "fmt_write_blanket_impl", since = "1.4.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<W: Write + ?Sized> Write for &mut W {

    fn write_str(&mut self, s: &str) -> Result {

        (**self).write_str(s)

    }

    fn write_char(&mut self, c: char) -> Result {

        (**self).write_char(c)

    }

    fn write_fmt(&mut self, args: Arguments<'_>) -> Result {

        (**self).write_fmt(args)

    }

}

/// The signedness of a [`Formatter`] (or of a [`FormattingOptions`]).

#[derive(Copy, Clone, Debug, PartialEq, Eq)]

#[unstable(feature = "formatting_options", issue = "118117")]

#[cfg(not(feature = "ferrocene_certified"))]

pub enum Sign {

    /// Represents the `+` flag.

    Plus,

    /// Represents the `-` flag.

    Minus,

}

/// Specifies whether the [`Debug`] trait should use lower-/upper-case

/// hexadecimal or normal integers.

#[derive(Copy, Clone, Debug, PartialEq, Eq)]

#[unstable(feature = "formatting_options", issue = "118117")]

#[cfg(not(feature = "ferrocene_certified"))]

pub enum DebugAsHex {

    /// Use lower-case hexadecimal integers for the `Debug` trait (like [the `x?` type](../../std/fmt/index.html#formatting-traits)).

    Lower,

    /// Use upper-case hexadecimal integers for the `Debug` trait (like [the `X?` type](../../std/fmt/index.html#formatting-traits)).

    Upper,

}

/// Options for formatting.

///

/// `FormattingOptions` is a [`Formatter`] without an attached [`Write`] trait.

/// It is mainly used to construct `Formatter` instances.

#[derive(Copy, Clone, Debug, PartialEq, Eq)]

#[unstable(feature = "formatting_options", issue = "118117")]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct FormattingOptions {

    /// Flags, with the following bit fields:

    ///

    /// ```text

    ///   31  30  29  28  27  26  25  24  23  22  21  20                              0

    /// ┌───┬───────┬───┬───┬───┬───┬───┬───┬───┬───┬──────────────────────────────────┐

    /// │ 1 │ align │ p │ w │ X?│ x?│'0'│ # │ - │ + │               fill               │

    /// └───┴───────┴───┴───┴───┴───┴───┴───┴───┴───┴──────────────────────────────────┘

    ///   │     │     │   │  └─┬───────────────────┘ └─┬──────────────────────────────┘

    ///   │     │     │   │    │                       └─ The fill character (21 bits char).

    ///   │     │     │   │    └─ The debug upper/lower hex, zero pad, alternate, and plus/minus flags.

    ///   │     │     │   └─ Whether a width is set. (The value is stored separately.)

    ///   │     │     └─ Whether a precision is set. (The value is stored separately.)

    ///   │     ├─ 0: Align left. (<)

    ///   │     ├─ 1: Align right. (>)

    ///   │     ├─ 2: Align center. (^)

    ///   │     └─ 3: Alignment not set. (default)

    ///   └─ Always set.

    ///      This makes it possible to distinguish formatting flags from

    ///      a &str size when stored in (the upper bits of) the same field.

    ///      (fmt::Arguments will make use of this property in the future.)

    /// ```

    // Note: This could use a special niche type with range 0x8000_0000..=0xfdd0ffff.

    // It's unclear if that's useful, though.

    flags: u32,

    /// Width if width flag (bit 27) above is set. Otherwise, always 0.

    width: u16,

    /// Precision if precision flag (bit 28) above is set. Otherwise, always 0.

    precision: u16,

}

// This needs to match with compiler/rustc_ast_lowering/src/format.rs.

#[cfg(not(feature = "ferrocene_certified"))]

mod flags {

    pub(super) const SIGN_PLUS_FLAG: u32 = 1 << 21;

    pub(super) const SIGN_MINUS_FLAG: u32 = 1 << 22;

    pub(super) const ALTERNATE_FLAG: u32 = 1 << 23;

    pub(super) const SIGN_AWARE_ZERO_PAD_FLAG: u32 = 1 << 24;

    pub(super) const DEBUG_LOWER_HEX_FLAG: u32 = 1 << 25;

    pub(super) const DEBUG_UPPER_HEX_FLAG: u32 = 1 << 26;

    pub(super) const WIDTH_FLAG: u32 = 1 << 27;

    pub(super) const PRECISION_FLAG: u32 = 1 << 28;

    pub(super) const ALIGN_BITS: u32 = 0b11 << 29;

    pub(super) const ALIGN_LEFT: u32 = 0 << 29;

    pub(super) const ALIGN_RIGHT: u32 = 1 << 29;

    pub(super) const ALIGN_CENTER: u32 = 2 << 29;

    pub(super) const ALIGN_UNKNOWN: u32 = 3 << 29;

    pub(super) const ALWAYS_SET: u32 = 1 << 31;

}

#[cfg(not(feature = "ferrocene_certified"))]

impl FormattingOptions {

    /// Construct a new `FormatterBuilder` with the supplied `Write` trait

    /// object for output that is equivalent to the `{}` formatting

    /// specifier:

    ///

    /// - no flags,

    /// - filled with spaces,

    /// - no alignment,

    /// - no width,

    /// - no precision, and

    /// - no [`DebugAsHex`] output mode.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn new() -> Self {

        Self {

            flags: ' ' as u32 | flags::ALIGN_UNKNOWN | flags::ALWAYS_SET,

            width: 0,

            precision: 0,

        }

    }

    /// Sets or removes the sign (the `+` or the `-` flag).

    ///

    /// - `+`: This is intended for numeric types and indicates that the sign

    ///   should always be printed. By default only the negative sign of signed

    ///   values is printed, and the sign of positive or unsigned values is

    ///   omitted. This flag indicates that the correct sign (+ or -) should

    ///   always be printed.

    /// - `-`: Currently not used

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn sign(&mut self, sign: Option<Sign>) -> &mut Self {

        let sign = match sign {

            None => 0,

            Some(Sign::Plus) => flags::SIGN_PLUS_FLAG,

            Some(Sign::Minus) => flags::SIGN_MINUS_FLAG,

        };

        self.flags = self.flags & !(flags::SIGN_PLUS_FLAG | flags::SIGN_MINUS_FLAG) | sign;

        self

    }

    /// Sets or unsets the `0` flag.

    ///

    /// This is used to indicate for integer formats that the padding to width should both be done with a 0 character as well as be sign-aware

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn sign_aware_zero_pad(&mut self, sign_aware_zero_pad: bool) -> &mut Self {

        if sign_aware_zero_pad {

            self.flags |= flags::SIGN_AWARE_ZERO_PAD_FLAG;

        } else {

            self.flags &= !flags::SIGN_AWARE_ZERO_PAD_FLAG;

        }

        self

    }

    /// Sets or unsets the `#` flag.

    ///

    /// This flag indicates that the "alternate" form of printing should be

    /// used. The alternate forms are:

    /// - [`Debug`] : pretty-print the [`Debug`] formatting (adds linebreaks and indentation)

    /// - [`LowerHex`] as well as [`UpperHex`] - precedes the argument with a `0x`

    /// - [`Octal`] - precedes the argument with a `0b`

    /// - [`Binary`] - precedes the argument with a `0o`

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn alternate(&mut self, alternate: bool) -> &mut Self {

        if alternate {

            self.flags |= flags::ALTERNATE_FLAG;

        } else {

            self.flags &= !flags::ALTERNATE_FLAG;

        }

        self

    }

    /// Sets the fill character.

    ///

    /// The optional fill character and alignment is provided normally in

    /// conjunction with the width parameter. This indicates that if the value

    /// being formatted is smaller than width some extra characters will be

    /// printed around it.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn fill(&mut self, fill: char) -> &mut Self {

        self.flags = self.flags & (u32::MAX << 21) | fill as u32;

        self

    }

    /// Sets or removes the alignment.

    ///

    /// The alignment specifies how the value being formatted should be

    /// positioned if it is smaller than the width of the formatter.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn align(&mut self, align: Option<Alignment>) -> &mut Self {

        let align: u32 = match align {

            Some(Alignment::Left) => flags::ALIGN_LEFT,

            Some(Alignment::Right) => flags::ALIGN_RIGHT,

            Some(Alignment::Center) => flags::ALIGN_CENTER,

            None => flags::ALIGN_UNKNOWN,

        };

        self.flags = self.flags & !flags::ALIGN_BITS | align;

        self

    }

    /// Sets or removes the 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 padding specified by [`FormattingOptions::fill`]/[`FormattingOptions::align`]

    /// will be used to take up the required space.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn width(&mut self, width: Option<u16>) -> &mut Self {

        if let Some(width) = width {

            self.flags |= flags::WIDTH_FLAG;

            self.width = width;

        } else {

            self.flags &= !flags::WIDTH_FLAG;

            self.width = 0;

        }

        self

    }

    /// Sets or removes the 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 this many characters and that truncated value is emitted with

    ///   proper fill, alignment and width if those parameters are set.

    /// - For integral types, this is ignored.

    /// - For floating-point types, this indicates how many digits after the

    /// decimal point should be printed.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn precision(&mut self, precision: Option<u16>) -> &mut Self {

        if let Some(precision) = precision {

            self.flags |= flags::PRECISION_FLAG;

            self.precision = precision;

        } else {

            self.flags &= !flags::PRECISION_FLAG;

            self.precision = 0;

        }

        self

    }

    /// Specifies whether the [`Debug`] trait should use lower-/upper-case

    /// hexadecimal or normal integers

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn debug_as_hex(&mut self, debug_as_hex: Option<DebugAsHex>) -> &mut Self {

        let debug_as_hex = match debug_as_hex {

            None => 0,

            Some(DebugAsHex::Lower) => flags::DEBUG_LOWER_HEX_FLAG,

            Some(DebugAsHex::Upper) => flags::DEBUG_UPPER_HEX_FLAG,

        };

        self.flags = self.flags & !(flags::DEBUG_LOWER_HEX_FLAG | flags::DEBUG_UPPER_HEX_FLAG)

            | debug_as_hex;

        self

    }

    /// Returns the current sign (the `+` or the `-` flag).

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_sign(&self) -> Option<Sign> {

        if self.flags & flags::SIGN_PLUS_FLAG != 0 {

            Some(Sign::Plus)

        } else if self.flags & flags::SIGN_MINUS_FLAG != 0 {

            Some(Sign::Minus)

        } else {

            None

        }

    }

    /// Returns the current `0` flag.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_sign_aware_zero_pad(&self) -> bool {

        self.flags & flags::SIGN_AWARE_ZERO_PAD_FLAG != 0

    }

    /// Returns the current `#` flag.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_alternate(&self) -> bool {

        self.flags & flags::ALTERNATE_FLAG != 0

    }

    /// Returns the current fill character.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_fill(&self) -> char {

        // SAFETY: We only ever put a valid `char` in the lower 21 bits of the flags field.

        unsafe { char::from_u32_unchecked(self.flags & 0x1FFFFF) }

    }

    /// Returns the current alignment.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_align(&self) -> Option<Alignment> {

        match self.flags & flags::ALIGN_BITS {

            flags::ALIGN_LEFT => Some(Alignment::Left),

            flags::ALIGN_RIGHT => Some(Alignment::Right),

            flags::ALIGN_CENTER => Some(Alignment::Center),

            _ => None,

        }

    }

    /// Returns the current width.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_width(&self) -> Option<u16> {

        if self.flags & flags::WIDTH_FLAG != 0 { Some(self.width) } else { None }

    }

    /// Returns the current precision.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_precision(&self) -> Option<u16> {

        if self.flags & flags::PRECISION_FLAG != 0 { Some(self.precision) } else { None }

    }

    /// Returns the current precision.

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn get_debug_as_hex(&self) -> Option<DebugAsHex> {

        if self.flags & flags::DEBUG_LOWER_HEX_FLAG != 0 {

            Some(DebugAsHex::Lower)

        } else if self.flags & flags::DEBUG_UPPER_HEX_FLAG != 0 {

            Some(DebugAsHex::Upper)

        } else {

            None

        }

    }

    /// Creates a [`Formatter`] that writes its output to the given [`Write`] trait.

    ///

    /// You may alternatively use [`Formatter::new()`].

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn create_formatter<'a>(self, write: &'a mut (dyn Write + 'a)) -> Formatter<'a> {

        Formatter { options: self, buf: write }

    }

}

#[unstable(feature = "formatting_options", issue = "118117")]

#[cfg(not(feature = "ferrocene_certified"))]

impl Default for FormattingOptions {

    /// Same as [`FormattingOptions::new()`].

    fn default() -> Self {

        // The `#[derive(Default)]` implementation would set `fill` to `\0` instead of space.

        Self::new()

    }

}

/// Configuration for formatting.

///

/// A `Formatter` represents various options related to formatting. Users do not

/// construct `Formatter`s directly; a mutable reference to one is passed to

/// the `fmt` method of all formatting traits, like [`Debug`] and [`Display`].

///

/// To interact with a `Formatter`, you'll call various methods to change the

/// various options related to formatting. For examples, please see the

/// documentation of the methods defined on `Formatter` below.

#[allow(missing_debug_implementations)]

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_diagnostic_item = "Formatter"]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct Formatter<'a> {

    options: FormattingOptions,

    buf: &'a mut (dyn Write + 'a),

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<'a> Formatter<'a> {

    /// Creates a new formatter with given [`FormattingOptions`].

    ///

    /// If `write` is a reference to a formatter, it is recommended to use

    /// [`Formatter::with_options`] instead as this can borrow the underlying

    /// `write`, thereby bypassing one layer of indirection.

    ///

    /// You may alternatively use [`FormattingOptions::create_formatter()`].

    #[unstable(feature = "formatting_options", issue = "118117")]

    /// Creates a new formatter based on this one with given [`FormattingOptions`].

    #[unstable(feature = "formatting_options", issue = "118117")]

    pub const fn with_options<'b>(&'b mut self, options: FormattingOptions) -> Formatter<'b> {

        Formatter { options, buf: self.buf }

    }

}

/// 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!`.

///

/// ```rust

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

/// ```

///

/// [`format()`]: ../../std/fmt/fn.format.html

#[lang = "format_arguments"]

#[stable(feature = "rust1", since = "1.0.0")]

#[derive(Copy, Clone)]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct Arguments<'a> {

    // Format string pieces to print.

    pieces: &'a [&'static str],

    // Placeholder specs, or `None` if all specs are default (as in "{}{}").

    fmt: Option<&'a [rt::Placeholder]>,

    // Dynamic arguments for interpolation, to be interleaved with string

    // pieces. (Every argument is preceded by a string piece.)

    args: &'a [rt::Argument<'a>],

}

#[doc(hidden)]

#[unstable(feature = "fmt_internals", issue = "none")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<'a> Arguments<'a> {

    /// 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.

    #[inline]

    pub fn estimated_capacity(&self) -> usize {

        let pieces_length: usize = self.pieces.iter().map(|x| x.len()).sum();

        if self.args.is_empty() {

            pieces_length

        } else if !self.pieces.is_empty() && self.pieces[0].is_empty() && pieces_length < 16 {

            // If the format string starts with an argument,

            // don't preallocate anything, unless length

            // of pieces is significant.

            0

        } else {

            // There are some arguments, so any additional push

            // will reallocate the string. To avoid that,

            // we're "pre-doubling" the capacity here.

            pieces_length.checked_mul(2).unwrap_or(0)

        }

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<'a> Arguments<'a> {

    /// 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

    ///

    /// ```rust

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

    ///     }

    /// }

    /// ```

    ///

    /// ```rust

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

    /// ```

    #[stable(feature = "fmt_as_str", since = "1.52.0")]

    #[rustc_const_stable(feature = "const_arguments_as_str", since = "1.84.0")]

    #[must_use]

    #[inline]

        }

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

    #[unstable(feature = "fmt_internals", reason = "internal to standard library", issue = "none")]

    #[must_use]

    #[inline]

    #[doc(hidden)]

}

// Manually implementing these results in better error messages.

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl !Send for Arguments<'_> {}

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl !Sync for Arguments<'_> {}

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl Debug for Arguments<'_> {

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

        Display::fmt(self, fmt)

    }

}

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl Display for Arguments<'_> {

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

        write(fmt.buf, *self)

    }

}

/// `?` formatting.

///

/// `Debug` should format the output in a programmer-facing, debugging context.

///

/// Generally speaking, you should just `derive` a `Debug` implementation.

///

/// When used with the alternate format specifier `#?`, the output is pretty-printed.

///

/// For more information on formatters, see [the module-level documentation][module].

///

/// [module]: ../../std/fmt/index.html

///

/// This trait can be used with `#[derive]` if all fields implement `Debug`. When

/// `derive`d for structs, it will use the name of the `struct`, then `{`, then a

/// comma-separated list of each field's name and `Debug` value, then `}`. For

/// `enum`s, it will use the name of the variant and, if applicable, `(`, then the

/// `Debug` values of the fields, then `)`.

///

/// # Stability

///

/// Derived `Debug` formats are not stable, and so may change with future Rust

/// versions. Additionally, `Debug` implementations of types provided by the

/// standard library (`std`, `core`, `alloc`, etc.) are not stable, and

/// may also change with future Rust versions.

///

/// # Examples

///

/// Deriving an implementation:

///

/// ```

/// #[derive(Debug)]

/// struct Point {

///     x: i32,

///     y: i32,

/// }

///

/// let origin = Point { x: 0, y: 0 };

///

/// assert_eq!(

///     format!("The origin is: {origin:?}"),

///     "The origin is: Point { x: 0, y: 0 }",

/// );

/// ```

///

/// Manually implementing:

///

/// ```

/// use std::fmt;

///

/// struct Point {

///     x: i32,

///     y: i32,

/// }

///

/// impl fmt::Debug for Point {

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

///         f.debug_struct("Point")

///          .field("x", &self.x)

///          .field("y", &self.y)

///          .finish()

///     }

/// }

///

/// let origin = Point { x: 0, y: 0 };

///

/// assert_eq!(

///     format!("The origin is: {origin:?}"),

///     "The origin is: Point { x: 0, y: 0 }",

/// );

/// ```

///

/// There are a number of helper methods on the [`Formatter`] struct to help you with manual

/// implementations, such as [`debug_struct`].

///

/// [`debug_struct`]: Formatter::debug_struct

///

/// Types that do not wish to use the standard suite of debug representations

/// provided by the `Formatter` trait (`debug_struct`, `debug_tuple`,

/// `debug_list`, `debug_set`, `debug_map`) can do something totally custom by

/// manually writing an arbitrary representation to the `Formatter`.

///

/// ```

/// # use std::fmt;

/// # struct Point {

/// #     x: i32,

/// #     y: i32,

/// # }

/// #

/// impl fmt::Debug for Point {

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

///         write!(f, "Point [{} {}]", self.x, self.y)

///     }

/// }

/// ```

///

/// `Debug` implementations using either `derive` or the debug builder API

/// on [`Formatter`] support pretty-printing using the alternate flag: `{:#?}`.

///

/// Pretty-printing with `#?`:

///

/// ```

/// #[derive(Debug)]

/// struct Point {

///     x: i32,

///     y: i32,

/// }

///

/// let origin = Point { x: 0, y: 0 };

///

/// let expected = "The origin is: Point {

///     x: 0,

///     y: 0,

/// }";

/// assert_eq!(format!("The origin is: {origin:#?}"), expected);

/// ```

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_on_unimplemented(

    on(

        crate_local,

        note = "add `#[derive(Debug)]` to `{Self}` or manually `impl {This} for {Self}`"

    ),

    on(

        from_desugaring = "FormatLiteral",

        label = "`{Self}` cannot be formatted using `{{:?}}` because it doesn't implement `{This}`"

    ),

    message = "`{Self}` doesn't implement `{This}`"

)]

#[doc(alias = "{:?}")]

#[rustc_diagnostic_item = "Debug"]

#[rustc_trivial_field_reads]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait Debug: PointeeSized {

    #[doc = include_str!("fmt_trait_method_doc.md")]

    ///

    /// # Examples

    ///

    /// ```

    /// use std::fmt;

    ///

    /// struct Position {

    ///     longitude: f32,

    ///     latitude: f32,

    /// }

    ///

    /// impl fmt::Debug for Position {

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

    ///         f.debug_tuple("")

    ///          .field(&self.longitude)

    ///          .field(&self.latitude)

    ///          .finish()

    ///     }

    /// }

    ///

    /// let position = Position { longitude: 1.987, latitude: 2.983 };

    /// assert_eq!(format!("{position:?}"), "(1.987, 2.983)");

    ///

    /// assert_eq!(format!("{position:#?}"), "(

    ///     1.987,

    ///     2.983,

    /// )");

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

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

}

// Separate module to reexport the macro `Debug` from prelude without the trait `Debug`.

#[cfg(not(feature = "ferrocene_certified"))]

pub(crate) mod macros {

    /// Derive macro generating an impl of the trait `Debug`.

    #[rustc_builtin_macro]

    #[stable(feature = "builtin_macro_prelude", since = "1.38.0")]

    #[allow_internal_unstable(core_intrinsics, fmt_helpers_for_derive)]

    pub macro Debug($item:item) {

        /* compiler built-in */

    }

}

#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]

#[doc(inline)]

#[cfg(not(feature = "ferrocene_certified"))]

pub use macros::Debug;

/// Format trait for an empty format, `{}`.

///

/// Implementing this trait for a type will automatically implement the

/// [`ToString`][tostring] trait for the type, allowing the usage

/// of the [`.to_string()`][tostring_function] method. Prefer implementing

/// the `Display` trait for a type, rather than [`ToString`][tostring].

///

/// `Display` is similar to [`Debug`], but `Display` is for user-facing

/// output, and so cannot be derived.

///

/// For more information on formatters, see [the module-level documentation][module].

///

/// [module]: ../../std/fmt/index.html

/// [tostring]: ../../std/string/trait.ToString.html

/// [tostring_function]: ../../std/string/trait.ToString.html#tymethod.to_string

///

/// # Completeness and parseability

///

/// `Display` for a type might not necessarily be a lossless or complete representation of the type.

/// It may omit internal state, precision, or other information the type does not consider important

/// for user-facing output, as determined by the type. As such, the output of `Display` might not be

/// possible to parse, and even if it is, the result of parsing might not exactly match the original

/// value.

///

/// However, if a type has a lossless `Display` implementation whose output is meant to be

/// conveniently machine-parseable and not just meant for human consumption, then the type may wish

/// to accept the same format in `FromStr`, and document that usage. Having both `Display` and

/// `FromStr` implementations where the result of `Display` cannot be parsed with `FromStr` may

/// surprise users.

///

/// # Internationalization

///

/// Because a type can only have one `Display` implementation, it is often preferable

/// to only implement `Display` when there is a single most "obvious" way that

/// values can be formatted as text. This could mean formatting according to the

/// "invariant" culture and "undefined" locale, or it could mean that the type

/// display is designed for a specific culture/locale, such as developer logs.

///

/// If not all values have a justifiably canonical textual format or if you want

/// to support alternative formats not covered by the standard set of possible

/// [formatting traits], the most flexible approach is display adapters: methods

/// like [`str::escape_default`] or [`Path::display`] which create a wrapper

/// implementing `Display` to output the specific display format.

///

/// [formatting traits]: ../../std/fmt/index.html#formatting-traits

/// [`Path::display`]: ../../std/path/struct.Path.html#method.display

///

/// # Examples

///

/// Implementing `Display` on a type:

///

/// ```

/// use std::fmt;

///

/// struct Point {

///     x: i32,

///     y: i32,

/// }

///

/// impl fmt::Display for Point {

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

///         write!(f, "({}, {})", self.x, self.y)

///     }

/// }

///

/// let origin = Point { x: 0, y: 0 };

///

/// assert_eq!(format!("The origin is: {origin}"), "The origin is: (0, 0)");

/// ```

#[rustc_on_unimplemented(

    on(

        any(Self = "std::path::Path", Self = "std::path::PathBuf"),

        label = "`{Self}` cannot be formatted with the default formatter; call `.display()` on it",

        note = "call `.display()` or `.to_string_lossy()` to safely print paths, \

                as they may contain non-Unicode data",

    ),

    on(

        from_desugaring = "FormatLiteral",

        note = "in format strings you may be able to use `{{:?}}` (or {{:#?}} for pretty-print) instead",

        label = "`{Self}` cannot be formatted with the default formatter",

    ),

    message = "`{Self}` doesn't implement `{This}`"

)]

#[doc(alias = "{}")]

#[rustc_diagnostic_item = "Display"]

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait Display: PointeeSized {

    #[doc = include_str!("fmt_trait_method_doc.md")]

    ///

    /// # Examples

    ///

    /// ```

    /// use std::fmt;

    ///

    /// struct Position {

    ///     longitude: f32,

    ///     latitude: f32,

    /// }

    ///

    /// impl fmt::Display for Position {

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

    ///         write!(f, "({}, {})", self.longitude, self.latitude)

    ///     }

    /// }

    ///

    /// assert_eq!(

    ///     "(1.987, 2.983)",

    ///     format!("{}", Position { longitude: 1.987, latitude: 2.983, }),

    /// );

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

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

}

/// `o` formatting.

///

/// The `Octal` trait should format its output as a number in base-8.

///

/// For primitive signed integers (`i8` to `i128`, and `isize`),

/// negative values are formatted as the two’s complement representation.

///

/// The alternate flag, `#`, adds a `0o` in front of the output.

///

/// For more information on formatters, see [the module-level documentation][module].

///

/// [module]: ../../std/fmt/index.html

///

/// # Examples

///

/// Basic usage with `i32`:

///

/// ```

/// let x = 42; // 42 is '52' in octal

///

/// assert_eq!(format!("{x:o}"), "52");

/// assert_eq!(format!("{x:#o}"), "0o52");

///

/// assert_eq!(format!("{:o}", -16), "37777777760");

/// ```

///

/// Implementing `Octal` on a type:

///

/// ```

/// use std::fmt;

///

/// struct Length(i32);

///

/// impl fmt::Octal for Length {

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

///         let val = self.0;

///

///         fmt::Octal::fmt(&val, f) // delegate to i32's implementation

///     }

/// }

///

/// let l = Length(9);

///

/// assert_eq!(format!("l as octal is: {l:o}"), "l as octal is: 11");

///

/// assert_eq!(format!("l as octal is: {l:#06o}"), "l as octal is: 0o0011");

/// ```

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait Octal: PointeeSized {

    #[doc = include_str!("fmt_trait_method_doc.md")]

    #[stable(feature = "rust1", since = "1.0.0")]

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

}

/// `b` formatting.

///

/// The `Binary` trait should format its output as a number in binary.

///

/// For primitive signed integers ([`i8`] to [`i128`], and [`isize`]),

/// negative values are formatted as the two’s complement representation.

///

/// The alternate flag, `#`, adds a `0b` in front of the output.

///

/// For more information on formatters, see [the module-level documentation][module].

///

/// [module]: ../../std/fmt/index.html

///

/// # Examples

///

/// Basic usage with [`i32`]:

///

/// ```

/// let x = 42; // 42 is '101010' in binary

///

/// assert_eq!(format!("{x:b}"), "101010");

/// assert_eq!(format!("{x:#b}"), "0b101010");

///

/// assert_eq!(format!("{:b}", -16), "11111111111111111111111111110000");

/// ```

///

/// Implementing `Binary` on a type:

///

/// ```

/// use std::fmt;

///

/// struct Length(i32);

///

/// impl fmt::Binary for Length {

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

///         let val = self.0;

///

///         fmt::Binary::fmt(&val, f) // delegate to i32's implementation

///     }

/// }

///

/// let l = Length(107);

///

/// assert_eq!(format!("l as binary is: {l:b}"), "l as binary is: 1101011");

///

/// assert_eq!(

///     // Note that the `0b` prefix added by `#` is included in the total width, so we

///     // need to add two to correctly display all 32 bits.

///     format!("l as binary is: {l:#034b}"),

///     "l as binary is: 0b00000000000000000000000001101011"

/// );

/// ```

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait Binary: PointeeSized {

    #[doc = include_str!("fmt_trait_method_doc.md")]

    #[stable(feature = "rust1", since = "1.0.0")]

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

}

/// `x` formatting.

///

/// The `LowerHex` trait should format its output as a number in hexadecimal, with `a` through `f`

/// in lower case.

///

/// For primitive signed integers (`i8` to `i128`, and `isize`),

/// negative values are formatted as the two’s complement representation.

///

/// The alternate flag, `#`, adds a `0x` in front of the output.

///

/// For more information on formatters, see [the module-level documentation][module].

///

/// [module]: ../../std/fmt/index.html

///

/// # Examples

///

/// Basic usage with `i32`:

///

/// ```

/// let y = 42; // 42 is '2a' in hex

///

/// assert_eq!(format!("{y:x}"), "2a");

/// assert_eq!(format!("{y:#x}"), "0x2a");

///

/// assert_eq!(format!("{:x}", -16), "fffffff0");

/// ```

///

/// Implementing `LowerHex` on a type:

///

/// ```

/// use std::fmt;

///

/// struct Length(i32);

///

/// impl fmt::LowerHex for Length {

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

///         let val = self.0;

///

///         fmt::LowerHex::fmt(&val, f) // delegate to i32's implementation

///     }

/// }

///

/// let l = Length(9);

///

/// assert_eq!(format!("l as hex is: {l:x}"), "l as hex is: 9");

///

/// assert_eq!(format!("l as hex is: {l:#010x}"), "l as hex is: 0x00000009");

/// ```

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait LowerHex: PointeeSized {

    #[doc = include_str!("fmt_trait_method_doc.md")]

    #[stable(feature = "rust1", since = "1.0.0")]

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

}

/// `X` formatting.

///

/// The `UpperHex` trait should format its output as a number in hexadecimal, with `A` through `F`

/// in upper case.

///

/// For primitive signed integers (`i8` to `i128`, and `isize`),

/// negative values are formatted as the two’s complement representation.

///

/// The alternate flag, `#`, adds a `0x` in front of the output.

///

/// For more information on formatters, see [the module-level documentation][module].

///

/// [module]: ../../std/fmt/index.html

///

/// # Examples

///

/// Basic usage with `i32`:

///

/// ```

/// let y = 42; // 42 is '2A' in hex

///

/// assert_eq!(format!("{y:X}"), "2A");

/// assert_eq!(format!("{y:#X}"), "0x2A");

///

/// assert_eq!(format!("{:X}", -16), "FFFFFFF0");

/// ```

///

/// Implementing `UpperHex` on a type:

///

/// ```

/// use std::fmt;

///

/// struct Length(i32);

///

/// impl fmt::UpperHex for Length {

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

///         let val = self.0;

///

///         fmt::UpperHex::fmt(&val, f) // delegate to i32's implementation

///     }

/// }

///

/// let l = Length(i32::MAX);

///

/// assert_eq!(format!("l as hex is: {l:X}"), "l as hex is: 7FFFFFFF");

///

/// assert_eq!(format!("l as hex is: {l:#010X}"), "l as hex is: 0x7FFFFFFF");

/// ```

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub trait UpperHex: PointeeSized {

    #[doc = include_str!("fmt_trait_method_doc.md")]

    #[stable(feature = "rust1", since = "1.0.0")]

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

}

/// `p` formatting.

///

/// The `Pointer` trait should format its output as a memory location. This is commonly presented

/// as hexadecimal. For more information on formatters, see [the module-level documentation][module].

///

/// Printing of pointers is not a reliable way to discover how Rust programs are implemented.

/// The act of reading an address changes the program itself, and may change how the data is represented

/// in memory, and may affect which optimizations are applied to the code.

///

/// The printed pointer values are not guaranteed to be stable nor unique identifiers of objects.

/// Rust allows moving values to different memory locations, and may reuse the same memory locations

/// for different purposes.

///

/// There is no guarantee that the printed value can be converted back to a pointer.

///

/// [module]: ../../std/fmt/index.html

///

/// # Examples

///

/// Basic usage with `&i32`:

///

/// ```

/// let x = &42;

///

/// let address = format!("{x:p}"); // this produces something like '0x7f06092ac6d0'

/// ```

///

/// Implementing `Pointer` on a type:

///

/// ```

/// use std::fmt;

///

/// struct Length(i32);