mod.rs source code [crates/core/src/fmt/mod.rs]

1	//! Utilities for formatting and printing strings.
2
3	#![stable(feature = "rust1", since = "1.0.0")]
4
5	use crate::cell::{Cell, Ref, RefCell, RefMut, SyncUnsafeCell, UnsafeCell};
6	use crate::char::{EscapeDebugExtArgs, MAX_LEN_UTF8};
7	use crate::marker::PhantomData;
8	use crate::num::fmt as numfmt;
9	use crate::ops::Deref;
10	use crate::{iter, result, str};
11
12	mod builders;
13	#[cfg(not(no_fp_fmt_parse))]
14	mod float;
15	#[cfg(no_fp_fmt_parse)]
16	mod nofloat;
17	mod num;
18	mod rt;
19
20	#[stable(feature = "fmt_flags_align", since = "1.28.0")]
21	#[rustc_diagnostic_item = "Alignment"]
22	/// Possible alignments returned by `Formatter::align`
23	#[derive(Copy, Clone, Debug, PartialEq, Eq)]
24	pub enum Alignment {
25	#[stable(feature = "fmt_flags_align", since = "1.28.0")]
26	/// Indication that contents should be left-aligned.
27	Left,
28	#[stable(feature = "fmt_flags_align", since = "1.28.0")]
29	/// Indication that contents should be right-aligned.
30	Right,
31	#[stable(feature = "fmt_flags_align", since = "1.28.0")]
32	/// Indication that contents should be center-aligned.
33	Center,
34	}
35
36	#[stable(feature = "debug_builders", since = "1.2.0")]
37	pub use self::builders::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple};
38	#[unstable(feature = "debug_closure_helpers", issue = "117729")]
39	pub use self::builders::{FromFn, from_fn};
40
41	/// The type returned by formatter methods.
42	///
43	/// # Examples
44	///
45	/// ```
46	/// use std::fmt;
47	///
48	/// #[derive(Debug)]
49	/// struct Triangle {
50	/// a: f32,
51	/// b: f32,
52	/// c: f32
53	/// }
54	///
55	/// impl fmt::Display for Triangle {
56	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
57	/// write!(f, "({}, {}, {})", self.a, self.b, self.c)
58	/// }
59	/// }
60	///
61	/// let pythagorean_triple = Triangle { a: `3.0`, b: `4.0`, c: `5.0` };
62	///
63	/// assert_eq!(format!("{pythagorean_triple}"), "(3, 4, 5)");
64	/// ```
65	#[stable(feature = "rust1", since = "1.0.0")]
66	pub type Result = result::Result<(), Error>;
67
68	/// The error type which is returned from formatting a message into a stream.
69	///
70	/// This type does not support transmission of an error other than that an error
71	/// occurred. This is because, despite the existence of this error,
72	/// string formatting is considered an infallible operation.
73	/// `fmt()` implementors should not return this `Error` unless they received it from their
74	/// [`Formatter`]. The only time your code should create a new instance of this
75	/// error is when implementing `fmt::Write`, in order to cancel the formatting operation when
76	/// writing to the underlying stream fails.
77	///
78	/// Any extra information must be arranged to be transmitted through some other means,
79	/// such as storing it in a field to be consulted after the formatting operation has been
80	/// cancelled. (For example, this is how [`std::io::Write::write_fmt()`] propagates IO errors
81	/// during writing.)
82	///
83	/// This type, `fmt::Error`, should not be
84	/// confused with [`std::io::Error`] or [`std::error::Error`], which you may also
85	/// have in scope.
86	///
87	/// [`std::io::Error`]: ../../std/io/struct.Error.html
88	/// [`std::io::Write::write_fmt()`]: ../../std/io/trait.Write.html#method.write_fmt
89	/// [`std::error::Error`]: ../../std/error/trait.Error.html
90	///
91	/// # Examples
92	///
93	/// ```rust
94	/// use std::fmt::{self, write};
95	///
96	/// let mut output = String::new();
97	/// if let Err(fmt::Error) = write(&mut output, format_args!("Hello {}!", "world")) {
98	/// panic!("An error occurred");
99	/// }
100	/// ```
101	#[stable(feature = "rust1", since = "1.0.0")]
102	#[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
103	pub struct Error;
104
105	/// A trait for writing or formatting into Unicode-accepting buffers or streams.
106	///
107	/// This trait only accepts UTF-8–encoded data and is not [flushable]. If you only
108	/// want to accept Unicode and you don't need flushing, you should implement this trait;
109	/// otherwise you should implement [`std::io::Write`].
110	///
111	/// [`std::io::Write`]: ../../std/io/trait.Write.html
112	/// [flushable]: ../../std/io/trait.Write.html#tymethod.flush
113	#[stable(feature = "rust1", since = "1.0.0")]
114	pub trait Write {
115	/// Writes a string slice into this writer, returning whether the write
116	/// succeeded.
117	///
118	/// This method can only succeed if the entire string slice was successfully
119	/// written, and this method will not return until all data has been
120	/// written or an error occurs.
121	///
122	/// # Errors
123	///
124	/// This function will return an instance of [`std::fmt::Error`][Error] on error.
125	///
126	/// The purpose of that error is to abort the formatting operation when the underlying
127	/// destination encounters some error preventing it from accepting more text;
128	/// in particular, it does not communicate any information about what* error occurred.*
129	/// It should generally be propagated rather than handled, at least when implementing
130	/// formatting traits.
131	///
132	/// # Examples
133	///
134	/// ```
135	/// use std::fmt::{Error, Write};
136	///
137	/// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {
138	/// f.write_str(s)
139	/// }
140	///
141	/// let mut buf = String::new();
142	/// writer(&mut buf, "hola")?;
143	/// assert_eq!(&buf, "hola");
144	/// # std::fmt::Result::Ok(())
145	/// ```
146	#[stable(feature = "rust1", since = "1.0.0")]
147	fn write_str(&mut self, s: &str) -> Result;
148
149	/// Writes a [`char`] into this writer, returning whether the write succeeded.
150	///
151	/// A single [`char`] may be encoded as more than one byte.
152	/// This method can only succeed if the entire byte sequence was successfully
153	/// written, and this method will not return until all data has been
154	/// written or an error occurs.
155	///
156	/// # Errors
157	///
158	/// This function will return an instance of [`Error`] on error.
159	///
160	/// # Examples
161	///
162	/// ```
163	/// use std::fmt::{Error, Write};
164	///
165	/// fn writer<W: Write>(f: &mut W, c: char) -> Result<(), Error> {
166	/// f.write_char(c)
167	/// }
168	///
169	/// let mut buf = String::new();
170	/// writer(&mut buf, 'a')?;
171	/// writer(&mut buf, 'b')?;
172	/// assert_eq!(&buf, "ab");
173	/// # std::fmt::Result::Ok(())
174	/// ```
175	#[stable(feature = "fmt_write_char", since = "1.1.0")]
176	fn write_char(&mut self, c: char) -> Result {
177	self.write_str(c.encode_utf8(&mut [`0`; MAX_LEN_UTF8]))
178	}
179
180	/// Glue for usage of the [`write!`] macro with implementors of this trait.
181	///
182	/// This method should generally not be invoked manually, but rather through
183	/// the [`write!`] macro itself.
184	///
185	/// # Errors
186	///
187	/// This function will return an instance of [`Error`] on error. Please see
188	/// [write_str](Write::write_str) for details.
189	///
190	/// # Examples
191	///
192	/// ```
193	/// use std::fmt::{Error, Write};
194	///
195	/// fn writer<W: Write>(f: &mut W, s: &str) -> Result<(), Error> {
196	/// f.write_fmt(format_args!("{s}"))
197	/// }
198	///
199	/// let mut buf = String::new();
200	/// writer(&mut buf, "world")?;
201	/// assert_eq!(&buf, "world");
202	/// # std::fmt::Result::Ok(())
203	/// ```
204	#[stable(feature = "rust1", since = "1.0.0")]
205	fn write_fmt(&mut self, args: Arguments<'_>) -> Result {
206	// We use a specialization for `Sized` types to avoid an indirection
207	// through `&mut self`
208	trait SpecWriteFmt {
209	fn spec_write_fmt(self, args: Arguments<'_>) -> Result;
210	}
211
212	impl<W: Write + ?Sized> SpecWriteFmt for &mut W {
213	#[inline]
214	default fn spec_write_fmt(mut self, args: Arguments<'_>) -> Result {
215	if let Some(s) = args.as_statically_known_str() {
216	self.write_str(s)
217	} else {
218	write(&mut self, args)
219	}
220	}
221	}
222
223	impl<W: Write> SpecWriteFmt for &mut W {
224	#[inline]
225	fn spec_write_fmt(self, args: Arguments<'_>) -> Result {
226	if let Some(s) = args.as_statically_known_str() {
227	self.write_str(s)
228	} else {
229	write(self, args)
230	}
231	}
232	}
233
234	self.spec_write_fmt(args)
235	}
236	}
237
238	#[stable(feature = "fmt_write_blanket_impl", since = "1.4.0")]
239	impl<W: Write + ?Sized> Write for &mut W {
240	fn write_str(&mut self, s: &str) -> Result {
241	(**self).write_str(s)
242	}
243
244	fn write_char(&mut self, c: char) -> Result {
245	(**self).write_char(c)
246	}
247
248	fn write_fmt(&mut self, args: Arguments<'_>) -> Result {
249	(**self).write_fmt(args)
250	}
251	}
252
253	/// The signedness of a [`Formatter`] (or of a [`FormattingOptions`]).
254	#[derive(Copy, Clone, Debug, PartialEq, Eq)]
255	#[unstable(feature = "formatting_options", issue = "118117")]
256	pub enum Sign {
257	/// Represents the `+` flag.
258	Plus,
259	/// Represents the `-` flag.
260	Minus,
261	}
262
263	/// Specifies whether the [`Debug`] trait should use lower-/upper-case
264	/// hexadecimal or normal integers.
265	#[derive(Copy, Clone, Debug, PartialEq, Eq)]
266	#[unstable(feature = "formatting_options", issue = "118117")]
267	pub enum DebugAsHex {
268	/// Use lower-case hexadecimal integers for the `Debug` trait (like [the `x?` type](../../std/fmt/index.html#formatting-traits)).
269	Lower,
270	/// Use upper-case hexadecimal integers for the `Debug` trait (like [the `X?` type](../../std/fmt/index.html#formatting-traits)).
271	Upper,
272	}
273
274	/// Options for formatting.
275	///
276	/// `FormattingOptions` is a [`Formatter`] without an attached [`Write`] trait.
277	/// It is mainly used to construct `Formatter` instances.
278	#[derive(Copy, Clone, Debug, PartialEq, Eq)]
279	#[unstable(feature = "formatting_options", issue = "118117")]
280	pub struct FormattingOptions {
281	/// Flags, with the following bit fields:
282	///
283	/// ```text
284	/// 31 30 29 28 27 26 25 24 23 22 21 20 0
285	/// ┌───┬───────┬───┬───┬───┬───┬───┬───┬───┬───┬──────────────────────────────────┐
286	/// │ 1 │ align │ p │ w │ X?│ x?│'0'│ # │ - │ + │ fill │
287	/// └───┴───────┴───┴───┴───┴───┴───┴───┴───┴───┴──────────────────────────────────┘
288	/// │ │ │ │ └─┬───────────────────┘ └─┬──────────────────────────────┘
289	/// │ │ │ │ │ └─ The fill character (21 bits char).
290	/// │ │ │ │ └─ The debug upper/lower hex, zero pad, alternate, and plus/minus flags.
291	/// │ │ │ └─ Whether a width is set. (The value is stored separately.)
292	/// │ │ └─ Whether a precision is set. (The value is stored separately.)
293	/// │ ├─ 0: Align left. (<)
294	/// │ ├─ 1: Align right. (>)
295	/// │ ├─ 2: Align center. (^)
296	/// │ └─ 3: Alignment not set. (default)
297	/// └─ Always set.
298	/// This makes it possible to distinguish formatting flags from
299	/// a &str size when stored in (the upper bits of) the same field.
300	/// (fmt::Arguments will make use of this property in the future.)
301	/// ```
302	// Note: This could use a special niche type with range 0x8000_0000..=0xfdd0ffff.
303	// It's unclear if that's useful, though.
304	flags: u32,
305	/// Width if width flag (bit 27) above is set. Otherwise, always 0.
306	width: u16,
307	/// Precision if precision flag (bit 28) above is set. Otherwise, always 0.
308	precision: u16,
309	}
310
311	// This needs to match with compiler/rustc_ast_lowering/src/format.rs.
312	mod flags {
313	pub(super) const SIGN_PLUS_FLAG: u32 = `1` << `21`;
314	pub(super) const SIGN_MINUS_FLAG: u32 = `1` << `22`;
315	pub(super) const ALTERNATE_FLAG: u32 = `1` << `23`;
316	pub(super) const SIGN_AWARE_ZERO_PAD_FLAG: u32 = `1` << `24`;
317	pub(super) const DEBUG_LOWER_HEX_FLAG: u32 = `1` << `25`;
318	pub(super) const DEBUG_UPPER_HEX_FLAG: u32 = `1` << `26`;
319	pub(super) const WIDTH_FLAG: u32 = `1` << `27`;
320	pub(super) const PRECISION_FLAG: u32 = `1` << `28`;
321	pub(super) const ALIGN_BITS: u32 = `0b11` << `29`;
322	pub(super) const ALIGN_LEFT: u32 = `0` << `29`;
323	pub(super) const ALIGN_RIGHT: u32 = `1` << `29`;
324	pub(super) const ALIGN_CENTER: u32 = `2` << `29`;
325	pub(super) const ALIGN_UNKNOWN: u32 = `3` << `29`;
326	pub(super) const ALWAYS_SET: u32 = `1` << `31`;
327	}
328
329	impl FormattingOptions {
330	/// Construct a new `FormatterBuilder` with the supplied `Write` trait
331	/// object for output that is equivalent to the `{}` formatting
332	/// specifier:
333	///
334	/// - no flags,
335	/// - filled with spaces,
336	/// - no alignment,
337	/// - no width,
338	/// - no precision, and
339	/// - no [`DebugAsHex`] output mode.
340	#[unstable(feature = "formatting_options", issue = "118117")]
341	pub const fn new() -> Self {
342	Self {
343	flags: ' ' as u32 \| flags::ALIGN_UNKNOWN \| flags::ALWAYS_SET,
344	width: `0`,
345	precision: `0`,
346	}
347	}
348
349	/// Sets or removes the sign (the `+` or the `-` flag).
350	///
351	/// - `+`: This is intended for numeric types and indicates that the sign
352	/// should always be printed. By default only the negative sign of signed
353	/// values is printed, and the sign of positive or unsigned values is
354	/// omitted. This flag indicates that the correct sign (+ or -) should
355	/// always be printed.
356	/// - `-`: Currently not used
357	#[unstable(feature = "formatting_options", issue = "118117")]
358	pub fn sign(&mut self, sign: Option<Sign>) -> &mut Self {
359	let sign = match sign {
360	None => `0`,
361	Some(Sign::Plus) => flags::SIGN_PLUS_FLAG,
362	Some(Sign::Minus) => flags::SIGN_MINUS_FLAG,
363	};
364	self.flags = self.flags & !(flags::SIGN_PLUS_FLAG \| flags::SIGN_MINUS_FLAG) \| sign;
365	self
366	}
367	/// Sets or unsets the `0` flag.
368	///
369	/// 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
370	#[unstable(feature = "formatting_options", issue = "118117")]
371	pub fn sign_aware_zero_pad(&mut self, sign_aware_zero_pad: bool) -> &mut Self {
372	if sign_aware_zero_pad {
373	self.flags \|= flags::SIGN_AWARE_ZERO_PAD_FLAG;
374	} else {
375	self.flags &= !flags::SIGN_AWARE_ZERO_PAD_FLAG;
376	}
377	self
378	}
379	/// Sets or unsets the `#` flag.
380	///
381	/// This flag indicates that the "alternate" form of printing should be
382	/// used. The alternate forms are:
383	/// - [`Debug`] : pretty-print the [`Debug`] formatting (adds linebreaks and indentation)
384	/// - [`LowerHex`] as well as [`UpperHex`] - precedes the argument with a `0x`
385	/// - [`Octal`] - precedes the argument with a `0b`
386	/// - [`Binary`] - precedes the argument with a `0o`
387	#[unstable(feature = "formatting_options", issue = "118117")]
388	pub fn alternate(&mut self, alternate: bool) -> &mut Self {
389	if alternate {
390	self.flags \|= flags::ALTERNATE_FLAG;
391	} else {
392	self.flags &= !flags::ALTERNATE_FLAG;
393	}
394	self
395	}
396	/// Sets the fill character.
397	///
398	/// The optional fill character and alignment is provided normally in
399	/// conjunction with the width parameter. This indicates that if the value
400	/// being formatted is smaller than width some extra characters will be
401	/// printed around it.
402	#[unstable(feature = "formatting_options", issue = "118117")]
403	pub fn fill(&mut self, fill: char) -> &mut Self {
404	self.flags = self.flags & (u32::MAX << `21`) \| fill as u32;
405	self
406	}
407	/// Sets or removes the alignment.
408	///
409	/// The alignment specifies how the value being formatted should be
410	/// positioned if it is smaller than the width of the formatter.
411	#[unstable(feature = "formatting_options", issue = "118117")]
412	pub fn align(&mut self, align: Option<Alignment>) -> &mut Self {
413	let align: u32 = match align {
414	Some(Alignment::Left) => flags::ALIGN_LEFT,
415	Some(Alignment::Right) => flags::ALIGN_RIGHT,
416	Some(Alignment::Center) => flags::ALIGN_CENTER,
417	None => flags::ALIGN_UNKNOWN,
418	};
419	self.flags = self.flags & !flags::ALIGN_BITS \| align;
420	self
421	}
422	/// Sets or removes the width.
423	///
424	/// This is a parameter for the “minimum width” that the format should take
425	/// up. If the value’s string does not fill up this many characters, then
426	/// the padding specified by [`FormattingOptions::fill`]/[`FormattingOptions::align`]
427	/// will be used to take up the required space.
428	#[unstable(feature = "formatting_options", issue = "118117")]
429	pub fn width(&mut self, width: Option<u16>) -> &mut Self {
430	if let Some(width) = width {
431	self.flags \|= flags::WIDTH_FLAG;
432	self.width = width;
433	} else {
434	self.flags &= !flags::WIDTH_FLAG;
435	self.width = `0`;
436	}
437	self
438	}
439	/// Sets or removes the precision.
440	///
441	/// - For non-numeric types, this can be considered a “maximum width”. If
442	/// the resulting string is longer than this width, then it is truncated
443	/// down to this many characters and that truncated value is emitted with
444	/// proper fill, alignment and width if those parameters are set.
445	/// - For integral types, this is ignored.
446	/// - For floating-point types, this indicates how many digits after the
447	/// decimal point should be printed.
448	#[unstable(feature = "formatting_options", issue = "118117")]
449	pub fn precision(&mut self, precision: Option<u16>) -> &mut Self {
450	if let Some(precision) = precision {
451	self.flags \|= flags::PRECISION_FLAG;
452	self.precision = precision;
453	} else {
454	self.flags &= !flags::PRECISION_FLAG;
455	self.precision = `0`;
456	}
457	self
458	}
459	/// Specifies whether the [`Debug`] trait should use lower-/upper-case
460	/// hexadecimal or normal integers
461	#[unstable(feature = "formatting_options", issue = "118117")]
462	pub fn debug_as_hex(&mut self, debug_as_hex: Option<DebugAsHex>) -> &mut Self {
463	let debug_as_hex = match debug_as_hex {
464	None => `0`,
465	Some(DebugAsHex::Lower) => flags::DEBUG_LOWER_HEX_FLAG,
466	Some(DebugAsHex::Upper) => flags::DEBUG_UPPER_HEX_FLAG,
467	};
468	self.flags = self.flags & !(flags::DEBUG_LOWER_HEX_FLAG \| flags::DEBUG_UPPER_HEX_FLAG)
469	\| debug_as_hex;
470	self
471	}
472
473	/// Returns the current sign (the `+` or the `-` flag).
474	#[unstable(feature = "formatting_options", issue = "118117")]
475	pub const fn get_sign(&self) -> Option<Sign> {
476	if self.flags & flags::SIGN_PLUS_FLAG != `0` {
477	Some(Sign::Plus)
478	} else if self.flags & flags::SIGN_MINUS_FLAG != `0` {
479	Some(Sign::Minus)
480	} else {
481	None
482	}
483	}
484	/// Returns the current `0` flag.
485	#[unstable(feature = "formatting_options", issue = "118117")]
486	pub const fn get_sign_aware_zero_pad(&self) -> bool {
487	self.flags & flags::SIGN_AWARE_ZERO_PAD_FLAG != `0`
488	}
489	/// Returns the current `#` flag.
490	#[unstable(feature = "formatting_options", issue = "118117")]
491	pub const fn get_alternate(&self) -> bool {
492	self.flags & flags::ALTERNATE_FLAG != `0`
493	}
494	/// Returns the current fill character.
495	#[unstable(feature = "formatting_options", issue = "118117")]
496	pub const fn get_fill(&self) -> char {
497	// SAFETY: We only ever put a valid `char` in the lower 21 bits of the flags field.
498	unsafe { char::from_u32_unchecked(self.flags & `0x1FFFFF`) }
499	}
500	/// Returns the current alignment.
501	#[unstable(feature = "formatting_options", issue = "118117")]
502	pub const fn get_align(&self) -> Option<Alignment> {
503	match self.flags & flags::ALIGN_BITS {
504	flags::ALIGN_LEFT => Some(Alignment::Left),
505	flags::ALIGN_RIGHT => Some(Alignment::Right),
506	flags::ALIGN_CENTER => Some(Alignment::Center),
507	_ => None,
508	}
509	}
510	/// Returns the current width.
511	#[unstable(feature = "formatting_options", issue = "118117")]
512	pub const fn get_width(&self) -> Option<u16> {
513	if self.flags & flags::WIDTH_FLAG != `0` { Some(self.width) } else { None }
514	}
515	/// Returns the current precision.
516	#[unstable(feature = "formatting_options", issue = "118117")]
517	pub const fn get_precision(&self) -> Option<u16> {
518	if self.flags & flags::PRECISION_FLAG != `0` { Some(self.precision) } else { None }
519	}
520	/// Returns the current precision.
521	#[unstable(feature = "formatting_options", issue = "118117")]
522	pub const fn get_debug_as_hex(&self) -> Option<DebugAsHex> {
523	if self.flags & flags::DEBUG_LOWER_HEX_FLAG != `0` {
524	Some(DebugAsHex::Lower)
525	} else if self.flags & flags::DEBUG_UPPER_HEX_FLAG != `0` {
526	Some(DebugAsHex::Upper)
527	} else {
528	None
529	}
530	}
531
532	/// Creates a [`Formatter`] that writes its output to the given [`Write`] trait.
533	///
534	/// You may alternatively use [`Formatter::new()`].
535	#[unstable(feature = "formatting_options", issue = "118117")]
536	pub fn create_formatter<'a>(self, write: &'a mut (dyn Write + 'a)) -> Formatter<'a> {
537	Formatter { options: self, buf: write }
538	}
539	}
540
541	#[unstable(feature = "formatting_options", issue = "118117")]
542	impl Default for FormattingOptions {
543	/// Same as [`FormattingOptions::new()`].
544	fn default() -> Self {
545	// The `#[derive(Default)]` implementation would set `fill` to `\0` instead of space.
546	Self::new()
547	}
548	}
549
550	/// Configuration for formatting.
551	///
552	/// A `Formatter` represents various options related to formatting. Users do not
553	/// construct `Formatter`s directly; a mutable reference to one is passed to
554	/// the `fmt` method of all formatting traits, like [`Debug`] and [`Display`].
555	///
556	/// To interact with a `Formatter`, you'll call various methods to change the
557	/// various options related to formatting. For examples, please see the
558	/// documentation of the methods defined on `Formatter` below.
559	#[allow(missing_debug_implementations)]
560	#[stable(feature = "rust1", since = "1.0.0")]
561	#[rustc_diagnostic_item = "Formatter"]
562	pub struct Formatter<'a> {
563	options: FormattingOptions,
564
565	buf: &'a mut (dyn Write + 'a),
566	}
567
568	impl<'a> Formatter<'a> {
569	/// Creates a new formatter with given [`FormattingOptions`].
570	///
571	/// If `write` is a reference to a formatter, it is recommended to use
572	/// [`Formatter::with_options`] instead as this can borrow the underlying
573	/// `write`, thereby bypassing one layer of indirection.
574	///
575	/// You may alternatively use [`FormattingOptions::create_formatter()`].
576	#[unstable(feature = "formatting_options", issue = "118117")]
577	pub fn new(write: &'a mut (dyn Write + 'a), options: FormattingOptions) -> Self {
578	Formatter { options, buf: write }
579	}
580
581	/// Creates a new formatter based on this one with given [`FormattingOptions`].
582	#[unstable(feature = "formatting_options", issue = "118117")]
583	pub fn with_options<'b>(&'b mut self, options: FormattingOptions) -> Formatter<'b> {
584	Formatter { options, buf: self.buf }
585	}
586	}
587
588	/// This structure represents a safely precompiled version of a format string
589	/// and its arguments. This cannot be generated at runtime because it cannot
590	/// safely be done, so no constructors are given and the fields are private
591	/// to prevent modification.
592	///
593	/// The [`format_args!`] macro will safely create an instance of this structure.
594	/// The macro validates the format string at compile-time so usage of the
595	/// [`write()`] and [`format()`] functions can be safely performed.
596	///
597	/// You can use the `Arguments<'a>` that [`format_args!`] returns in `Debug`
598	/// and `Display` contexts as seen below. The example also shows that `Debug`
599	/// and `Display` format to the same thing: the interpolated format string
600	/// in `format_args!`.
601	///
602	/// ```rust
603	/// let debug = format!("{:?}", format_args!("{} foo {:?}", `1`, `2`));
604	/// let display = format!("{}", format_args!("{} foo {:?}", `1`, `2`));
605	/// assert_eq!("1 foo 2", display);
606	/// assert_eq!(display, debug);
607	/// ```
608	///
609	/// [`format()`]: ../../std/fmt/fn.format.html
610	#[lang = "format_arguments"]
611	#[stable(feature = "rust1", since = "1.0.0")]
612	#[derive(Copy, Clone)]
613	pub struct Arguments<'a> {
614	// Format string pieces to print.
615	pieces: &'a [&'static str],
616
617	// Placeholder specs, or `None` if all specs are default (as in "{}{}").
618	fmt: Option<&'a [rt::Placeholder]>,
619
620	// Dynamic arguments for interpolation, to be interleaved with string
621	// pieces. (Every argument is preceded by a string piece.)
622	args: &'a [rt::Argument<'a>],
623	}
624
625	#[doc(hidden)]
626	#[unstable(feature = "fmt_internals", issue = "none")]
627	impl<'a> Arguments<'a> {
628	/// Estimates the length of the formatted text.
629	///
630	/// This is intended to be used for setting initial `String` capacity
631	/// when using `format!`. Note: this is neither the lower nor upper bound.
632	#[inline]
633	pub fn estimated_capacity(&self) -> usize {
634	let pieces_length: usize = self.pieces.iter().map(\|x: &&str\| x.len()).sum();
635
636	if self.args.is_empty() {
637	pieces_length
638	} else if !self.pieces.is_empty() && self.pieces[`0`].is_empty() && pieces_length < `16` {
639	// If the format string starts with an argument,
640	// don't preallocate anything, unless length
641	// of pieces is significant.
642	`0`
643	} else {
644	// There are some arguments, so any additional push
645	// will reallocate the string. To avoid that,
646	// we're "pre-doubling" the capacity here.
647	pieces_length.checked_mul(`2`).unwrap_or(default:`0`)
648	}
649	}
650	}
651
652	impl<'a> Arguments<'a> {
653	/// Gets the formatted string, if it has no arguments to be formatted at runtime.
654	///
655	/// This can be used to avoid allocations in some cases.
656	///
657	/// # Guarantees
658	///
659	/// For `format_args!("just a literal")`, this function is guaranteed to
660	/// return `Some("just a literal")`.
661	///
662	/// For most cases with placeholders, this function will return `None`.
663	///
664	/// However, the compiler may perform optimizations that can cause this
665	/// function to return `Some(_)` even if the format string contains
666	/// placeholders. For example, `format_args!("Hello, {}!", "world")` may be
667	/// optimized to `format_args!("Hello, world!")`, such that `as_str()`
668	/// returns `Some("Hello, world!")`.
669	///
670	/// The behavior for anything but the trivial case (without placeholders)
671	/// is not guaranteed, and should not be relied upon for anything other
672	/// than optimization.
673	///
674	/// # Examples
675	///
676	/// ```rust
677	/// use std::fmt::Arguments;
678	///
679	/// fn write_str(_: &str) { / ... / }
680	///
681	/// fn write_fmt(args: &Arguments<'_>) {
682	/// if let Some(s) = args.as_str() {
683	/// write_str(s)
684	/// } else {
685	/// write_str(&args.to_string());
686	/// }
687	/// }
688	/// ```
689	///
690	/// ```rust
691	/// assert_eq!(format_args!("hello").as_str(), Some("hello"));
692	/// assert_eq!(format_args!("").as_str(), Some(""));
693	/// assert_eq!(format_args!("{:?}", std::env::current_dir()).as_str(), None);
694	/// ```
695	#[stable(feature = "fmt_as_str", since = "1.52.0")]
696	#[rustc_const_stable(feature = "const_arguments_as_str", since = "1.84.0")]
697	#[must_use]
698	#[inline]
699	pub const fn as_str(&self) -> Option<&'static str> {
700	match (self.pieces, self.args) {
701	([], []) => Some(""),
702	([s], []) => Some(s),
703	_ => None,
704	}
705	}
706
707	/// Same as [`Arguments::as_str`], but will only return `Some(s)` if it can be determined at compile time.
708	#[unstable(feature = "fmt_internals", reason = "internal to standard library", issue = "none")]
709	#[must_use]
710	#[inline]
711	#[doc(hidden)]
712	pub fn as_statically_known_str(&self) -> Option<&'static str> {
713	let s = self.as_str();
714	if core::intrinsics::is_val_statically_known(s.is_some()) { s } else { None }
715	}
716	}
717
718	// Manually implementing these results in better error messages.
719	#[stable(feature = "rust1", since = "1.0.0")]
720	impl !Send for Arguments<'_> {}
721	#[stable(feature = "rust1", since = "1.0.0")]
722	impl !Sync for Arguments<'_> {}
723
724	#[stable(feature = "rust1", since = "1.0.0")]
725	impl Debug for Arguments<'_> {
726	fn fmt(&self, fmt: &mut Formatter<'_>) -> Result {
727	Display::fmt(self, f:fmt)
728	}
729	}
730
731	#[stable(feature = "rust1", since = "1.0.0")]
732	impl Display for Arguments<'_> {
733	fn fmt(&self, fmt: &mut Formatter<'_>) -> Result {
734	write(output:fmt.buf, *self)
735	}
736	}
737
738	/// `?` formatting.
739	///
740	/// `Debug` should format the output in a programmer-facing, debugging context.
741	///
742	/// Generally speaking, you should just `derive` a `Debug` implementation.
743	///
744	/// When used with the alternate format specifier `#?`, the output is pretty-printed.
745	///
746	/// For more information on formatters, see [the module-level documentation][module].
747	///
748	/// [module]: ../../std/fmt/index.html
749	///
750	/// This trait can be used with `#[derive]` if all fields implement `Debug`. When
751	/// `derive`d for structs, it will use the name of the `struct`, then `{`, then a
752	/// comma-separated list of each field's name and `Debug` value, then `}`. For
753	/// `enum`s, it will use the name of the variant and, if applicable, `(`, then the
754	/// `Debug` values of the fields, then `)`.
755	///
756	/// # Stability
757	///
758	/// Derived `Debug` formats are not stable, and so may change with future Rust
759	/// versions. Additionally, `Debug` implementations of types provided by the
760	/// standard library (`std`, `core`, `alloc`, etc.) are not stable, and
761	/// may also change with future Rust versions.
762	///
763	/// # Examples
764	///
765	/// Deriving an implementation:
766	///
767	/// ```
768	/// #[derive(Debug)]
769	/// struct Point {
770	/// x: i32,
771	/// y: i32,
772	/// }
773	///
774	/// let origin = Point { x: `0`, y: `0` };
775	///
776	/// assert_eq!(
777	/// format!("The origin is: {origin:?}"),
778	/// "The origin is: Point { x: 0, y: 0 }",
779	/// );
780	/// ```
781	///
782	/// Manually implementing:
783	///
784	/// ```
785	/// use std::fmt;
786	///
787	/// struct Point {
788	/// x: i32,
789	/// y: i32,
790	/// }
791	///
792	/// impl fmt::Debug for Point {
793	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
794	/// f.debug_struct("Point")
795	/// .field("x", &self.x)
796	/// .field("y", &self.y)
797	/// .finish()
798	/// }
799	/// }
800	///
801	/// let origin = Point { x: `0`, y: `0` };
802	///
803	/// assert_eq!(
804	/// format!("The origin is: {origin:?}"),
805	/// "The origin is: Point { x: 0, y: 0 }",
806	/// );
807	/// ```
808	///
809	/// There are a number of helper methods on the [`Formatter`] struct to help you with manual
810	/// implementations, such as [`debug_struct`].
811	///
812	/// [`debug_struct`]: Formatter::debug_struct
813	///
814	/// Types that do not wish to use the standard suite of debug representations
815	/// provided by the `Formatter` trait (`debug_struct`, `debug_tuple`,
816	/// `debug_list`, `debug_set`, `debug_map`) can do something totally custom by
817	/// manually writing an arbitrary representation to the `Formatter`.
818	///
819	/// ```
820	/// # use std::fmt;
821	/// # struct Point {
822	/// # x: i32,
823	/// # y: i32,
824	/// # }
825	/// #
826	/// impl fmt::Debug for Point {
827	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
828	/// write!(f, "Point [{} {}]", self.x, self.y)
829	/// }
830	/// }
831	/// ```
832	///
833	/// `Debug` implementations using either `derive` or the debug builder API
834	/// on [`Formatter`] support pretty-printing using the alternate flag: `{:#?}`.
835	///
836	/// Pretty-printing with `#?`:
837	///
838	/// ```
839	/// #[derive(Debug)]
840	/// struct Point {
841	/// x: i32,
842	/// y: i32,
843	/// }
844	///
845	/// let origin = Point { x: `0`, y: `0` };
846	///
847	/// let expected = "The origin is: Point {
848	/// x: 0,
849	/// y: 0,
850	/// }";
851	/// assert_eq!(format!("The origin is: {origin:#?}"), expected);
852	/// ```
853
854	#[stable(feature = "rust1", since = "1.0.0")]
855	#[rustc_on_unimplemented(
856	on(
857	crate_local,
858	label = "`{Self}` cannot be formatted using `{{:?}}`",
859	note = "add `#[derive(Debug)]` to `{Self}` or manually `impl {This} for {Self}`"
860	),
861	message = "`{Self}` doesn't implement `{This}`",
862	label = "`{Self}` cannot be formatted using `{{:?}}` because it doesn't implement `{This}`"
863	)]
864	#[doc(alias = "{:?}")]
865	#[rustc_diagnostic_item = "Debug"]
866	#[rustc_trivial_field_reads]
867	pub trait Debug {
868	#[doc = include_str!("fmt_trait_method_doc.md")]
869	///
870	/// # Examples
871	///
872	/// ```
873	/// use std::fmt;
874	///
875	/// struct Position {
876	/// longitude: f32,
877	/// latitude: f32,
878	/// }
879	///
880	/// impl fmt::Debug for Position {
881	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
882	/// f.debug_tuple("")
883	/// .field(&self.longitude)
884	/// .field(&self.latitude)
885	/// .finish()
886	/// }
887	/// }
888	///
889	/// let position = Position { longitude: `1.987`, latitude: `2.983` };
890	/// assert_eq!(format!("{position:?}"), "(1.987, 2.983)");
891	///
892	/// assert_eq!(format!("{position:#?}"), "(
893	/// 1.987,
894	/// 2.983,
895	/// )");
896	/// ```
897	#[stable(feature = "rust1", since = "1.0.0")]
898	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
899	}
900
901	// Separate module to reexport the macro `Debug` from prelude without the trait `Debug`.
902	pub(crate) mod macros {
903	/// Derive macro generating an impl of the trait `Debug`.
904	#[rustc_builtin_macro]
905	#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
906	#[allow_internal_unstable(core_intrinsics, fmt_helpers_for_derive)]
907	pub macro Debug($item:item) {
908	/ compiler built-in /
909	}
910	}
911	#[stable(feature = "builtin_macro_prelude", since = "1.38.0")]
912	#[doc(inline)]
913	pub use macros::Debug;
914
915	/// Format trait for an empty format, `{}`.
916	///
917	/// Implementing this trait for a type will automatically implement the
918	/// [`ToString`][tostring] trait for the type, allowing the usage
919	/// of the [`.to_string()`][tostring_function] method. Prefer implementing
920	/// the `Display` trait for a type, rather than [`ToString`][tostring].
921	///
922	/// `Display` is similar to [`Debug`], but `Display` is for user-facing
923	/// output, and so cannot be derived.
924	///
925	/// For more information on formatters, see [the module-level documentation][module].
926	///
927	/// [module]: ../../std/fmt/index.html
928	/// [tostring]: ../../std/string/trait.ToString.html
929	/// [tostring_function]: ../../std/string/trait.ToString.html#tymethod.to_string
930	///
931	/// # Completeness and parseability
932	///
933	/// `Display` for a type might not necessarily be a lossless or complete representation of the type.
934	/// It may omit internal state, precision, or other information the type does not consider important
935	/// for user-facing output, as determined by the type. As such, the output of `Display` might not be
936	/// possible to parse, and even if it is, the result of parsing might not exactly match the original
937	/// value.
938	///
939	/// However, if a type has a lossless `Display` implementation whose output is meant to be
940	/// conveniently machine-parseable and not just meant for human consumption, then the type may wish
941	/// to accept the same format in `FromStr`, and document that usage. Having both `Display` and
942	/// `FromStr` implementations where the result of `Display` cannot be parsed with `FromStr` may
943	/// surprise users.
944	///
945	/// # Internationalization
946	///
947	/// Because a type can only have one `Display` implementation, it is often preferable
948	/// to only implement `Display` when there is a single most "obvious" way that
949	/// values can be formatted as text. This could mean formatting according to the
950	/// "invariant" culture and "undefined" locale, or it could mean that the type
951	/// display is designed for a specific culture/locale, such as developer logs.
952	///
953	/// If not all values have a justifiably canonical textual format or if you want
954	/// to support alternative formats not covered by the standard set of possible
955	/// [formatting traits], the most flexible approach is display adapters: methods
956	/// like [`str::escape_default`] or [`Path::display`] which create a wrapper
957	/// implementing `Display` to output the specific display format.
958	///
959	/// [formatting traits]: ../../std/fmt/index.html#formatting-traits
960	/// [`Path::display`]: ../../std/path/struct.Path.html#method.display
961	///
962	/// # Examples
963	///
964	/// Implementing `Display` on a type:
965	///
966	/// ```
967	/// use std::fmt;
968	///
969	/// struct Point {
970	/// x: i32,
971	/// y: i32,
972	/// }
973	///
974	/// impl fmt::Display for Point {
975	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
976	/// write!(f, "({}, {})", self.x, self.y)
977	/// }
978	/// }
979	///
980	/// let origin = Point { x: `0`, y: `0` };
981	///
982	/// assert_eq!(format!("The origin is: {origin}"), "The origin is: (0, 0)");
983	/// ```
984	#[rustc_on_unimplemented(
985	on(
986	any(Self = "std::path::Path", Self = "std::path::PathBuf"),
987	label = "`{Self}` cannot be formatted with the default formatter; call `.display()` on it",
988	note = "call `.display()` or `.to_string_lossy()` to safely print paths, \
989	as they may contain non-Unicode data"
990	),
991	message = "`{Self}` doesn't implement `{This}`",
992	label = "`{Self}` cannot be formatted with the default formatter",
993	note = "in format strings you may be able to use `{{:?}}` (or {{:#?}} for pretty-print) instead"
994	)]
995	#[doc(alias = "{}")]
996	#[rustc_diagnostic_item = "Display"]
997	#[stable(feature = "rust1", since = "1.0.0")]
998	pub trait Display {
999	#[doc = include_str!("fmt_trait_method_doc.md")]
1000	///
1001	/// # Examples
1002	///
1003	/// ```
1004	/// use std::fmt;
1005	///
1006	/// struct Position {
1007	/// longitude: f32,
1008	/// latitude: f32,
1009	/// }
1010	///
1011	/// impl fmt::Display for Position {
1012	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1013	/// write!(f, "({}, {})", self.longitude, self.latitude)
1014	/// }
1015	/// }
1016	///
1017	/// assert_eq!(
1018	/// "(1.987, 2.983)",
1019	/// format!("{}", Position { longitude: `1.987`, latitude: `2.983`, }),
1020	/// );
1021	/// ```
1022	#[stable(feature = "rust1", since = "1.0.0")]
1023	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1024	}
1025
1026	/// `o` formatting.
1027	///
1028	/// The `Octal` trait should format its output as a number in base-8.
1029	///
1030	/// For primitive signed integers (`i8` to `i128`, and `isize`),
1031	/// negative values are formatted as the two’s complement representation.
1032	///
1033	/// The alternate flag, `#`, adds a `0o` in front of the output.
1034	///
1035	/// For more information on formatters, see [the module-level documentation][module].
1036	///
1037	/// [module]: ../../std/fmt/index.html
1038	///
1039	/// # Examples
1040	///
1041	/// Basic usage with `i32`:
1042	///
1043	/// ```
1044	/// let x = `42`; // 42 is '52' in octal
1045	///
1046	/// assert_eq!(format!("{x:o}"), "52");
1047	/// assert_eq!(format!("{x:#o}"), "0o52");
1048	///
1049	/// assert_eq!(format!("{:o}", -`16`), "37777777760");
1050	/// ```
1051	///
1052	/// Implementing `Octal` on a type:
1053	///
1054	/// ```
1055	/// use std::fmt;
1056	///
1057	/// struct Length(i32);
1058	///
1059	/// impl fmt::Octal for Length {
1060	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1061	/// let val = self.0;
1062	///
1063	/// fmt::Octal::fmt(&val, f) // delegate to i32's implementation
1064	/// }
1065	/// }
1066	///
1067	/// let l = Length(`9`);
1068	///
1069	/// assert_eq!(format!("l as octal is: {l:o}"), "l as octal is: 11");
1070	///
1071	/// assert_eq!(format!("l as octal is: {l:#06o}"), "l as octal is: 0o0011");
1072	/// ```
1073	#[stable(feature = "rust1", since = "1.0.0")]
1074	pub trait Octal {
1075	#[doc = include_str!("fmt_trait_method_doc.md")]
1076	#[stable(feature = "rust1", since = "1.0.0")]
1077	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1078	}
1079
1080	/// `b` formatting.
1081	///
1082	/// The `Binary` trait should format its output as a number in binary.
1083	///
1084	/// For primitive signed integers ([`i8`] to [`i128`], and [`isize`]),
1085	/// negative values are formatted as the two’s complement representation.
1086	///
1087	/// The alternate flag, `#`, adds a `0b` in front of the output.
1088	///
1089	/// For more information on formatters, see [the module-level documentation][module].
1090	///
1091	/// [module]: ../../std/fmt/index.html
1092	///
1093	/// # Examples
1094	///
1095	/// Basic usage with [`i32`]:
1096	///
1097	/// ```
1098	/// let x = `42`; // 42 is '101010' in binary
1099	///
1100	/// assert_eq!(format!("{x:b}"), "101010");
1101	/// assert_eq!(format!("{x:#b}"), "0b101010");
1102	///
1103	/// assert_eq!(format!("{:b}", -`16`), "11111111111111111111111111110000");
1104	/// ```
1105	///
1106	/// Implementing `Binary` on a type:
1107	///
1108	/// ```
1109	/// use std::fmt;
1110	///
1111	/// struct Length(i32);
1112	///
1113	/// impl fmt::Binary for Length {
1114	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1115	/// let val = self.0;
1116	///
1117	/// fmt::Binary::fmt(&val, f) // delegate to i32's implementation
1118	/// }
1119	/// }
1120	///
1121	/// let l = Length(`107`);
1122	///
1123	/// assert_eq!(format!("l as binary is: {l:b}"), "l as binary is: 1101011");
1124	///
1125	/// assert_eq!(
1126	/// // Note that the `0b` prefix added by `#` is included in the total width, so we
1127	/// // need to add two to correctly display all 32 bits.
1128	/// format!("l as binary is: {l:#034b}"),
1129	/// "l as binary is: 0b00000000000000000000000001101011"
1130	/// );
1131	/// ```
1132	#[stable(feature = "rust1", since = "1.0.0")]
1133	pub trait Binary {
1134	#[doc = include_str!("fmt_trait_method_doc.md")]
1135	#[stable(feature = "rust1", since = "1.0.0")]
1136	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1137	}
1138
1139	/// `x` formatting.
1140	///
1141	/// The `LowerHex` trait should format its output as a number in hexadecimal, with `a` through `f`
1142	/// in lower case.
1143	///
1144	/// For primitive signed integers (`i8` to `i128`, and `isize`),
1145	/// negative values are formatted as the two’s complement representation.
1146	///
1147	/// The alternate flag, `#`, adds a `0x` in front of the output.
1148	///
1149	/// For more information on formatters, see [the module-level documentation][module].
1150	///
1151	/// [module]: ../../std/fmt/index.html
1152	///
1153	/// # Examples
1154	///
1155	/// Basic usage with `i32`:
1156	///
1157	/// ```
1158	/// let y = `42`; // 42 is '2a' in hex
1159	///
1160	/// assert_eq!(format!("{y:x}"), "2a");
1161	/// assert_eq!(format!("{y:#x}"), "0x2a");
1162	///
1163	/// assert_eq!(format!("{:x}", -`16`), "fffffff0");
1164	/// ```
1165	///
1166	/// Implementing `LowerHex` on a type:
1167	///
1168	/// ```
1169	/// use std::fmt;
1170	///
1171	/// struct Length(i32);
1172	///
1173	/// impl fmt::LowerHex for Length {
1174	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1175	/// let val = self.0;
1176	///
1177	/// fmt::LowerHex::fmt(&val, f) // delegate to i32's implementation
1178	/// }
1179	/// }
1180	///
1181	/// let l = Length(`9`);
1182	///
1183	/// assert_eq!(format!("l as hex is: {l:x}"), "l as hex is: 9");
1184	///
1185	/// assert_eq!(format!("l as hex is: {l:#010x}"), "l as hex is: 0x00000009");
1186	/// ```
1187	#[stable(feature = "rust1", since = "1.0.0")]
1188	pub trait LowerHex {
1189	#[doc = include_str!("fmt_trait_method_doc.md")]
1190	#[stable(feature = "rust1", since = "1.0.0")]
1191	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1192	}
1193
1194	/// `X` formatting.
1195	///
1196	/// The `UpperHex` trait should format its output as a number in hexadecimal, with `A` through `F`
1197	/// in upper case.
1198	///
1199	/// For primitive signed integers (`i8` to `i128`, and `isize`),
1200	/// negative values are formatted as the two’s complement representation.
1201	///
1202	/// The alternate flag, `#`, adds a `0x` in front of the output.
1203	///
1204	/// For more information on formatters, see [the module-level documentation][module].
1205	///
1206	/// [module]: ../../std/fmt/index.html
1207	///
1208	/// # Examples
1209	///
1210	/// Basic usage with `i32`:
1211	///
1212	/// ```
1213	/// let y = `42`; // 42 is '2A' in hex
1214	///
1215	/// assert_eq!(format!("{y:X}"), "2A");
1216	/// assert_eq!(format!("{y:#X}"), "0x2A");
1217	///
1218	/// assert_eq!(format!("{:X}", -`16`), "FFFFFFF0");
1219	/// ```
1220	///
1221	/// Implementing `UpperHex` on a type:
1222	///
1223	/// ```
1224	/// use std::fmt;
1225	///
1226	/// struct Length(i32);
1227	///
1228	/// impl fmt::UpperHex for Length {
1229	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1230	/// let val = self.0;
1231	///
1232	/// fmt::UpperHex::fmt(&val, f) // delegate to i32's implementation
1233	/// }
1234	/// }
1235	///
1236	/// let l = Length(i32::MAX);
1237	///
1238	/// assert_eq!(format!("l as hex is: {l:X}"), "l as hex is: 7FFFFFFF");
1239	///
1240	/// assert_eq!(format!("l as hex is: {l:#010X}"), "l as hex is: 0x7FFFFFFF");
1241	/// ```
1242	#[stable(feature = "rust1", since = "1.0.0")]
1243	pub trait UpperHex {
1244	#[doc = include_str!("fmt_trait_method_doc.md")]
1245	#[stable(feature = "rust1", since = "1.0.0")]
1246	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1247	}
1248
1249	/// `p` formatting.
1250	///
1251	/// The `Pointer` trait should format its output as a memory location. This is commonly presented
1252	/// as hexadecimal. For more information on formatters, see [the module-level documentation][module].
1253	///
1254	/// Printing of pointers is not a reliable way to discover how Rust programs are implemented.
1255	/// The act of reading an address changes the program itself, and may change how the data is represented
1256	/// in memory, and may affect which optimizations are applied to the code.
1257	///
1258	/// The printed pointer values are not guaranteed to be stable nor unique identifiers of objects.
1259	/// Rust allows moving values to different memory locations, and may reuse the same memory locations
1260	/// for different purposes.
1261	///
1262	/// There is no guarantee that the printed value can be converted back to a pointer.
1263	///
1264	/// [module]: ../../std/fmt/index.html
1265	///
1266	/// # Examples
1267	///
1268	/// Basic usage with `&i32`:
1269	///
1270	/// ```
1271	/// let x = &`42`;
1272	///
1273	/// let address = format!("{x:p}"); // this produces something like '0x7f06092ac6d0'
1274	/// ```
1275	///
1276	/// Implementing `Pointer` on a type:
1277	///
1278	/// ```
1279	/// use std::fmt;
1280	///
1281	/// struct Length(i32);
1282	///
1283	/// impl fmt::Pointer for Length {
1284	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1285	/// // use `as` to convert to a `const T`, which implements Pointer, which we can use*
1286	///
1287	/// let ptr = self as *const Self;
1288	/// fmt::Pointer::fmt(&ptr, f)
1289	/// }
1290	/// }
1291	///
1292	/// let l = Length(`42`);
1293	///
1294	/// println!("l is in memory here: {l:p}");
1295	///
1296	/// let l_ptr = format!("{l:018p}");
1297	/// assert_eq!(l_ptr.len(), `18`);
1298	/// assert_eq!(&l_ptr[..`2`], "0x");
1299	/// ```
1300	#[stable(feature = "rust1", since = "1.0.0")]
1301	#[rustc_diagnostic_item = "Pointer"]
1302	pub trait Pointer {
1303	#[doc = include_str!("fmt_trait_method_doc.md")]
1304	#[stable(feature = "rust1", since = "1.0.0")]
1305	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1306	}
1307
1308	/// `e` formatting.
1309	///
1310	/// The `LowerExp` trait should format its output in scientific notation with a lower-case `e`.
1311	///
1312	/// For more information on formatters, see [the module-level documentation][module].
1313	///
1314	/// [module]: ../../std/fmt/index.html
1315	///
1316	/// # Examples
1317	///
1318	/// Basic usage with `f64`:
1319	///
1320	/// ```
1321	/// let x = `42.0`; // 42.0 is '4.2e1' in scientific notation
1322	///
1323	/// assert_eq!(format!("{x:e}"), "4.2e1");
1324	/// ```
1325	///
1326	/// Implementing `LowerExp` on a type:
1327	///
1328	/// ```
1329	/// use std::fmt;
1330	///
1331	/// struct Length(i32);
1332	///
1333	/// impl fmt::LowerExp for Length {
1334	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1335	/// let val = f64::from(self.0);
1336	/// fmt::LowerExp::fmt(&val, f) // delegate to f64's implementation
1337	/// }
1338	/// }
1339	///
1340	/// let l = Length(`100`);
1341	///
1342	/// assert_eq!(
1343	/// format!("l in scientific notation is: {l:e}"),
1344	/// "l in scientific notation is: 1e2"
1345	/// );
1346	///
1347	/// assert_eq!(
1348	/// format!("l in scientific notation is: {l:05e}"),
1349	/// "l in scientific notation is: 001e2"
1350	/// );
1351	/// ```
1352	#[stable(feature = "rust1", since = "1.0.0")]
1353	pub trait LowerExp {
1354	#[doc = include_str!("fmt_trait_method_doc.md")]
1355	#[stable(feature = "rust1", since = "1.0.0")]
1356	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1357	}
1358
1359	/// `E` formatting.
1360	///
1361	/// The `UpperExp` trait should format its output in scientific notation with an upper-case `E`.
1362	///
1363	/// For more information on formatters, see [the module-level documentation][module].
1364	///
1365	/// [module]: ../../std/fmt/index.html
1366	///
1367	/// # Examples
1368	///
1369	/// Basic usage with `f64`:
1370	///
1371	/// ```
1372	/// let x = `42.0`; // 42.0 is '4.2E1' in scientific notation
1373	///
1374	/// assert_eq!(format!("{x:E}"), "4.2E1");
1375	/// ```
1376	///
1377	/// Implementing `UpperExp` on a type:
1378	///
1379	/// ```
1380	/// use std::fmt;
1381	///
1382	/// struct Length(i32);
1383	///
1384	/// impl fmt::UpperExp for Length {
1385	/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1386	/// let val = f64::from(self.0);
1387	/// fmt::UpperExp::fmt(&val, f) // delegate to f64's implementation
1388	/// }
1389	/// }
1390	///
1391	/// let l = Length(`100`);
1392	///
1393	/// assert_eq!(
1394	/// format!("l in scientific notation is: {l:E}"),
1395	/// "l in scientific notation is: 1E2"
1396	/// );
1397	///
1398	/// assert_eq!(
1399	/// format!("l in scientific notation is: {l:05E}"),
1400	/// "l in scientific notation is: 001E2"
1401	/// );
1402	/// ```
1403	#[stable(feature = "rust1", since = "1.0.0")]
1404	pub trait UpperExp {
1405	#[doc = include_str!("fmt_trait_method_doc.md")]
1406	#[stable(feature = "rust1", since = "1.0.0")]
1407	fn fmt(&self, f: &mut Formatter<'_>) -> Result;
1408	}
1409
1410	/// Takes an output stream and an `Arguments` struct that can be precompiled with
1411	/// the `format_args!` macro.
1412	///
1413	/// The arguments will be formatted according to the specified format string
1414	/// into the output stream provided.
1415	///
1416	/// # Examples
1417	///
1418	/// Basic usage:
1419	///
1420	/// ```
1421	/// use std::fmt;
1422	///
1423	/// let mut output = String::new();
1424	/// fmt::write(&mut output, format_args!("Hello {}!", "world"))
1425	/// .expect("Error occurred while trying to write in String");
1426	/// assert_eq!(output, "Hello world!");
1427	/// ```
1428	///
1429	/// Please note that using [`write!`] might be preferable. Example:
1430	///
1431	/// ```
1432	/// use std::fmt::Write;
1433	///
1434	/// let mut output = String::new();
1435	/// write!(&mut output, "Hello {}!", "world")
1436	/// .expect("Error occurred while trying to write in String");
1437	/// assert_eq!(output, "Hello world!");
1438	/// ```
1439	///
1440	/// [`write!`]: crate::write!
1441	#[stable(feature = "rust1", since = "1.0.0")]
1442	pub fn write(output: &mut dyn Write, args: Arguments<'_>) -> Result {
1443	let mut formatter = Formatter::new(output, FormattingOptions::new());
1444	let mut idx = `0`;
1445
1446	match args.fmt {
1447	None => {
1448	// We can use default formatting parameters for all arguments.
1449	for (i, arg) in args.args.iter().enumerate() {
1450	// SAFETY: args.args and args.pieces come from the same Arguments,
1451	// which guarantees the indexes are always within bounds.
1452	let piece = unsafe { args.pieces.get_unchecked(i) };
1453	if !piece.is_empty() {
1454	formatter.buf.write_str(*piece)?;
1455	}
1456
1457	// SAFETY: There are no formatting parameters and hence no
1458	// count arguments.
1459	unsafe {
1460	arg.fmt(&mut formatter)?;
1461	}
1462	idx += `1`;
1463	}
1464	}
1465	Some(fmt) => {
1466	// Every spec has a corresponding argument that is preceded by
1467	// a string piece.
1468	for (i, arg) in fmt.iter().enumerate() {
1469	// SAFETY: fmt and args.pieces come from the same Arguments,
1470	// which guarantees the indexes are always within bounds.
1471	let piece = unsafe { args.pieces.get_unchecked(i) };
1472	if !piece.is_empty() {
1473	formatter.buf.write_str(*piece)?;
1474	}
1475	// SAFETY: arg and args.args come from the same Arguments,
1476	// which guarantees the indexes are always within bounds.
1477	unsafe { run(&mut formatter, arg, args.args) }?;
1478	idx += `1`;
1479	}
1480	}
1481	}
1482
1483	// There can be only one trailing string piece left.
1484	if let Some(piece) = args.pieces.get(idx) {
1485	formatter.buf.write_str(*piece)?;
1486	}
1487
1488	Ok(())
1489	}
1490
1491	unsafe fn run(fmt: &mut Formatter<'_>, arg: &rt::Placeholder, args: &[rt::Argument<'_>]) -> Result {
1492	let (width: u16, precision: u16) =
1493	// SAFETY: arg and args come from the same Arguments,
1494	// which guarantees the indexes are always within bounds.
1495	unsafe { (getcount(args, &arg.width), getcount(args, &arg.precision)) };
1496
1497	let options: FormattingOptions = FormattingOptions { flags: arg.flags, width, precision };
1498
1499	// Extract the correct argument
1500	debug_assert!(arg.position < args.len());
1501	// SAFETY: arg and args come from the same Arguments,
1502	// which guarantees its index is always within bounds.
1503	let value: &Argument<'_> = unsafe { args.get_unchecked(index:arg.position) };
1504
1505	// Set all the formatting options.
1506	fmt.options = options;
1507
1508	// Then actually do some printing
1509	// SAFETY: this is a placeholder argument.
1510	unsafe { value.fmt(fmt) }
1511	}
1512
1513	unsafe fn getcount(args: &[rt::Argument<'_>], cnt: &rt::Count) -> u16 {
1514	match *cnt {
1515	rt::Count::Is(n: u16) => n,
1516	rt::Count::Implied => `0`,
1517	rt::Count::Param(i: usize) => {
1518	debug_assert!(i < args.len());
1519	// SAFETY: cnt and args come from the same Arguments,
1520	// which guarantees this index is always within bounds.
1521	unsafe { args.get_unchecked(index:i).as_u16().unwrap_unchecked() }
1522	}
1523	}
1524	}
1525
1526	/// Padding after the end of something. Returned by `Formatter::padding`.
1527	#[must_use = "don't forget to write the post padding"]
1528	pub(crate) struct PostPadding {
1529	fill: char,
1530	padding: u16,
1531	}
1532
1533	impl PostPadding {
1534	fn new(fill: char, padding: u16) -> PostPadding {
1535	PostPadding { fill, padding }
1536	}
1537
1538	/// Writes this post padding.
1539	pub(crate) fn write(self, f: &mut Formatter<'_>) -> Result {
1540	for _ in `0`..self.padding {
1541	f.buf.write_char(self.fill)?;
1542	}
1543	Ok(())
1544	}
1545	}
1546
1547	impl<'a> Formatter<'a> {
1548	fn wrap_buf<'b, 'c, F>(&'b mut self, wrap: F) -> Formatter<'c>
1549	where
1550	'b: 'c,
1551	F: FnOnce(&'b mut (dyn Write + 'b)) -> &'c mut (dyn Write + 'c),
1552	{
1553	Formatter {
1554	// We want to change this
1555	buf: wrap(self.buf),
1556
1557	// And preserve these
1558	options: self.options,
1559	}
1560	}
1561
1562	// Helper methods used for padding and processing formatting arguments that
1563	// all formatting traits can use.
1564
1565	/// Performs the correct padding for an integer which has already been
1566	/// emitted into a str. The str should not* contain the sign for the*
1567	/// integer, that will be added by this method.
1568	///
1569	/// # Arguments
1570	///
1571	/// is_nonnegative - whether the original integer was either positive or zero.*
1572	/// prefix - if the '#' character (Alternate) is provided, this*
1573	/// is the prefix to put in front of the number.
1574	/// buf - the byte array that the number has been formatted into*
1575	///
1576	/// This function will correctly account for the flags provided as well as
1577	/// the minimum width. It will not take precision into account.
1578	///
1579	/// # Examples
1580	///
1581	/// ```
1582	/// use std::fmt;
1583	///
1584	/// struct Foo { nb: i32 }
1585	///
1586	/// impl Foo {
1587	/// fn new(nb: i32) -> Foo {
1588	/// Foo {
1589	/// nb,
1590	/// }
1591	/// }
1592	/// }
1593	///
1594	/// impl fmt::Display for Foo {
1595	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1596	/// // We need to remove "-" from the number output.
1597	/// let tmp = self.nb.abs().to_string();
1598	///
1599	/// formatter.pad_integral(self.nb >= `0`, "Foo ", &tmp)
1600	/// }
1601	/// }
1602	///
1603	/// assert_eq!(format!("{}", Foo::new(`2`)), "2");
1604	/// assert_eq!(format!("{}", Foo::new(-`1`)), "-1");
1605	/// assert_eq!(format!("{}", Foo::new(`0`)), "0");
1606	/// assert_eq!(format!("{:#}", Foo::new(-`1`)), "-Foo 1");
1607	/// assert_eq!(format!("{:0>#8}", Foo::new(-`1`)), "00-Foo 1");
1608	/// ```
1609	#[stable(feature = "rust1", since = "1.0.0")]
1610	pub fn pad_integral(&mut self, is_nonnegative: bool, prefix: &str, buf: &str) -> Result {
1611	let mut width = buf.len();
1612
1613	let mut sign = None;
1614	if !is_nonnegative {
1615	sign = Some('-');
1616	width += `1`;
1617	} else if self.sign_plus() {
1618	sign = Some('+');
1619	width += `1`;
1620	}
1621
1622	let prefix = if self.alternate() {
1623	width += prefix.chars().count();
1624	Some(prefix)
1625	} else {
1626	None
1627	};
1628
1629	// Writes the sign if it exists, and then the prefix if it was requested
1630	#[inline(never)]
1631	fn write_prefix(f: &mut Formatter<'_>, sign: Option<char>, prefix: Option<&str>) -> Result {
1632	if let Some(c) = sign {
1633	f.buf.write_char(c)?;
1634	}
1635	if let Some(prefix) = prefix { f.buf.write_str(prefix) } else { Ok(()) }
1636	}
1637
1638	// The `width` field is more of a `min-width` parameter at this point.
1639	let min = self.options.width;
1640	if width >= usize::from(min) {
1641	// We're over the minimum width, so then we can just write the bytes.
1642	write_prefix(self, sign, prefix)?;
1643	self.buf.write_str(buf)
1644	} else if self.sign_aware_zero_pad() {
1645	// The sign and prefix goes before the padding if the fill character
1646	// is zero
1647	let old_options = self.options;
1648	self.options.fill('0').align(Some(Alignment::Right));
1649	write_prefix(self, sign, prefix)?;
1650	let post_padding = self.padding(min - width as u16, Alignment::Right)?;
1651	self.buf.write_str(buf)?;
1652	post_padding.write(self)?;
1653	self.options = old_options;
1654	Ok(())
1655	} else {
1656	// Otherwise, the sign and prefix goes after the padding
1657	let post_padding = self.padding(min - width as u16, Alignment::Right)?;
1658	write_prefix(self, sign, prefix)?;
1659	self.buf.write_str(buf)?;
1660	post_padding.write(self)
1661	}
1662	}
1663
1664	/// Takes a string slice and emits it to the internal buffer after applying
1665	/// the relevant formatting flags specified.
1666	///
1667	/// The flags recognized for generic strings are:
1668	///
1669	/// width - the minimum width of what to emit*
1670	/// fill/align - what to emit and where to emit it if the string*
1671	/// provided needs to be padded
1672	/// precision - the maximum length to emit, the string is truncated if it*
1673	/// is longer than this length
1674	///
1675	/// Notably this function ignores the `flag` parameters.
1676	///
1677	/// # Examples
1678	///
1679	/// ```
1680	/// use std::fmt;
1681	///
1682	/// struct Foo;
1683	///
1684	/// impl fmt::Display for Foo {
1685	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1686	/// formatter.pad("Foo")
1687	/// }
1688	/// }
1689	///
1690	/// assert_eq!(format!("{Foo:<4}"), "Foo ");
1691	/// assert_eq!(format!("{Foo:0>4}"), "0Foo");
1692	/// ```
1693	#[stable(feature = "rust1", since = "1.0.0")]
1694	pub fn pad(&mut self, s: &str) -> Result {
1695	// Make sure there's a fast path up front.
1696	if self.options.flags & (flags::WIDTH_FLAG \| flags::PRECISION_FLAG) == `0` {
1697	return self.buf.write_str(s);
1698	}
1699
1700	// The `precision` field can be interpreted as a maximum width for the
1701	// string being formatted.
1702	let (s, char_count) = if let Some(max_char_count) = self.options.get_precision() {
1703	let mut iter = s.char_indices();
1704	let remaining = match iter.advance_by(usize::from(max_char_count)) {
1705	Ok(()) => `0`,
1706	Err(remaining) => remaining.get(),
1707	};
1708	// SAFETY: The offset of `.char_indices()` is guaranteed to be
1709	// in-bounds and between character boundaries.
1710	let truncated = unsafe { s.get_unchecked(..iter.offset()) };
1711	(truncated, usize::from(max_char_count) - remaining)
1712	} else {
1713	// Use the optimized char counting algorithm for the full string.
1714	(s, s.chars().count())
1715	};
1716
1717	// The `width` field is more of a minimum width parameter at this point.
1718	if char_count < usize::from(self.options.width) {
1719	// If we're under the minimum width, then fill up the minimum width
1720	// with the specified string + some alignment.
1721	let post_padding =
1722	self.padding(self.options.width - char_count as u16, Alignment::Left)?;
1723	self.buf.write_str(s)?;
1724	post_padding.write(self)
1725	} else {
1726	// If we're over the minimum width or there is no minimum width, we
1727	// can just emit the string.
1728	self.buf.write_str(s)
1729	}
1730	}
1731
1732	/// Writes the pre-padding and returns the unwritten post-padding.
1733	///
1734	/// Callers are responsible for ensuring post-padding is written after the
1735	/// thing that is being padded.
1736	pub(crate) fn padding(
1737	&mut self,
1738	padding: u16,
1739	default: Alignment,
1740	) -> result::Result<PostPadding, Error> {
1741	let align = self.options.get_align().unwrap_or(default);
1742	let fill = self.options.get_fill();
1743
1744	let padding_left = match align {
1745	Alignment::Left => `0`,
1746	Alignment::Right => padding,
1747	Alignment::Center => padding / `2`,
1748	};
1749
1750	for _ in `0`..padding_left {
1751	self.buf.write_char(fill)?;
1752	}
1753
1754	Ok(PostPadding::new(fill, padding - padding_left))
1755	}
1756
1757	/// Takes the formatted parts and applies the padding.
1758	///
1759	/// Assumes that the caller already has rendered the parts with required precision,
1760	/// so that `self.precision` can be ignored.
1761	///
1762	/// # Safety
1763	///
1764	/// Any `numfmt::Part::Copy` parts in `formatted` must contain valid UTF-8.
1765	unsafe fn pad_formatted_parts(&mut self, formatted: &numfmt::Formatted<'_>) -> Result {
1766	if self.options.width == `0` {
1767	// this is the common case and we take a shortcut
1768	// SAFETY: Per the precondition.
1769	unsafe { self.write_formatted_parts(formatted) }
1770	} else {
1771	// for the sign-aware zero padding, we render the sign first and
1772	// behave as if we had no sign from the beginning.
1773	let mut formatted = formatted.clone();
1774	let mut width = self.options.width;
1775	let old_options = self.options;
1776	if self.sign_aware_zero_pad() {
1777	// a sign always goes first
1778	let sign = formatted.sign;
1779	self.buf.write_str(sign)?;
1780
1781	// remove the sign from the formatted parts
1782	formatted.sign = "";
1783	width = width.saturating_sub(sign.len() as u16);
1784	self.options.fill('0').align(Some(Alignment::Right));
1785	}
1786
1787	// remaining parts go through the ordinary padding process.
1788	let len = formatted.len();
1789	let ret = if usize::from(width) <= len {
1790	// no padding
1791	// SAFETY: Per the precondition.
1792	unsafe { self.write_formatted_parts(&formatted) }
1793	} else {
1794	let post_padding = self.padding(width - len as u16, Alignment::Right)?;
1795	// SAFETY: Per the precondition.
1796	unsafe {
1797	self.write_formatted_parts(&formatted)?;
1798	}
1799	post_padding.write(self)
1800	};
1801	self.options = old_options;
1802	ret
1803	}
1804	}
1805
1806	/// # Safety
1807	///
1808	/// Any `numfmt::Part::Copy` parts in `formatted` must contain valid UTF-8.
1809	unsafe fn write_formatted_parts(&mut self, formatted: &numfmt::Formatted<'_>) -> Result {
1810	unsafe fn write_bytes(buf: &mut dyn Write, s: &[u8]) -> Result {
1811	// SAFETY: This is used for `numfmt::Part::Num` and `numfmt::Part::Copy`.
1812	// It's safe to use for `numfmt::Part::Num` since every char `c` is between
1813	// `b'0'` and `b'9'`, which means `s` is valid UTF-8. It's safe to use for
1814	// `numfmt::Part::Copy` due to this function's precondition.
1815	buf.write_str(unsafe { str::from_utf8_unchecked(s) })
1816	}
1817
1818	if !formatted.sign.is_empty() {
1819	self.buf.write_str(formatted.sign)?;
1820	}
1821	for part in formatted.parts {
1822	match *part {
1823	numfmt::Part::Zero(mut nzeroes) => {
1824	const ZEROES: &str = // 64 zeroes
1825	"0000000000000000000000000000000000000000000000000000000000000000";
1826	while nzeroes > ZEROES.len() {
1827	self.buf.write_str(ZEROES)?;
1828	nzeroes -= ZEROES.len();
1829	}
1830	if nzeroes > `0` {
1831	self.buf.write_str(&ZEROES[..nzeroes])?;
1832	}
1833	}
1834	numfmt::Part::Num(mut v) => {
1835	let mut s = [`0`; `5`];
1836	let len = part.len();
1837	for c in s[..len].iter_mut().rev() {
1838	*c = b'0' + (v % `10`) as u8;
1839	v /= `10`;
1840	}
1841	// SAFETY: Per the precondition.
1842	unsafe {
1843	write_bytes(self.buf, &s[..len])?;
1844	}
1845	}
1846	// SAFETY: Per the precondition.
1847	numfmt::Part::Copy(buf) => unsafe {
1848	write_bytes(self.buf, buf)?;
1849	},
1850	}
1851	}
1852	Ok(())
1853	}
1854
1855	/// Writes some data to the underlying buffer contained within this
1856	/// formatter.
1857	///
1858	/// # Examples
1859	///
1860	/// ```
1861	/// use std::fmt;
1862	///
1863	/// struct Foo;
1864	///
1865	/// impl fmt::Display for Foo {
1866	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1867	/// formatter.write_str("Foo")
1868	/// // This is equivalent to:
1869	/// // write!(formatter, "Foo")
1870	/// }
1871	/// }
1872	///
1873	/// assert_eq!(format!("{Foo}"), "Foo");
1874	/// assert_eq!(format!("{Foo:0>8}"), "Foo");
1875	/// ```
1876	#[stable(feature = "rust1", since = "1.0.0")]
1877	pub fn write_str(&mut self, data: &str) -> Result {
1878	self.buf.write_str(data)
1879	}
1880
1881	/// Glue for usage of the [`write!`] macro with implementors of this trait.
1882	///
1883	/// This method should generally not be invoked manually, but rather through
1884	/// the [`write!`] macro itself.
1885	///
1886	/// Writes some formatted information into this instance.
1887	///
1888	/// # Examples
1889	///
1890	/// ```
1891	/// use std::fmt;
1892	///
1893	/// struct Foo(i32);
1894	///
1895	/// impl fmt::Display for Foo {
1896	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1897	/// formatter.write_fmt(format_args!("Foo {}", self.`0`))
1898	/// }
1899	/// }
1900	///
1901	/// assert_eq!(format!("{}", Foo(-`1`)), "Foo -1");
1902	/// assert_eq!(format!("{:0>8}", Foo(`2`)), "Foo 2");
1903	/// ```
1904	#[stable(feature = "rust1", since = "1.0.0")]
1905	#[inline]
1906	pub fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result {
1907	if let Some(s) = fmt.as_statically_known_str() {
1908	self.buf.write_str(s)
1909	} else {
1910	write(self.buf, fmt)
1911	}
1912	}
1913
1914	/// Returns flags for formatting.
1915	#[must_use]
1916	#[stable(feature = "rust1", since = "1.0.0")]
1917	#[deprecated(
1918	since = "1.24.0",
1919	note = "use the `sign_plus`, `sign_minus`, `alternate`, \
1920	or `sign_aware_zero_pad` methods instead"
1921	)]
1922	pub fn flags(&self) -> u32 {
1923	// Extract the debug upper/lower hex, zero pad, alternate, and plus/minus flags
1924	// to stay compatible with older versions of Rust.
1925	self.options.flags >> `21` & `0x3F`
1926	}
1927
1928	/// Returns the character used as 'fill' whenever there is alignment.
1929	///
1930	/// # Examples
1931	///
1932	/// ```
1933	/// use std::fmt;
1934	///
1935	/// struct Foo;
1936	///
1937	/// impl fmt::Display for Foo {
1938	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1939	/// let c = formatter.fill();
1940	/// if let Some(width) = formatter.width() {
1941	/// for _ in `0`..width {
1942	/// write!(formatter, "{c}")?;
1943	/// }
1944	/// Ok(())
1945	/// } else {
1946	/// write!(formatter, "{c}")
1947	/// }
1948	/// }
1949	/// }
1950	///
1951	/// // We set alignment to the right with ">".
1952	/// assert_eq!(format!("{Foo:G>3}"), "GGG");
1953	/// assert_eq!(format!("{Foo:t>6}"), "tttttt");
1954	/// ```
1955	#[must_use]
1956	#[stable(feature = "fmt_flags", since = "1.5.0")]
1957	pub fn fill(&self) -> char {
1958	self.options.get_fill()
1959	}
1960
1961	/// Returns a flag indicating what form of alignment was requested.
1962	///
1963	/// # Examples
1964	///
1965	/// ```
1966	/// use std::fmt::{self, Alignment};
1967	///
1968	/// struct Foo;
1969	///
1970	/// impl fmt::Display for Foo {
1971	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1972	/// let s = if let Some(s) = formatter.align() {
1973	/// match s {
1974	/// Alignment::Left => "left",
1975	/// Alignment::Right => "right",
1976	/// Alignment::Center => "center",
1977	/// }
1978	/// } else {
1979	/// "into the void"
1980	/// };
1981	/// write!(formatter, "{s}")
1982	/// }
1983	/// }
1984	///
1985	/// assert_eq!(format!("{Foo:<}"), "left");
1986	/// assert_eq!(format!("{Foo:>}"), "right");
1987	/// assert_eq!(format!("{Foo:^}"), "center");
1988	/// assert_eq!(format!("{Foo}"), "into the void");
1989	/// ```
1990	#[must_use]
1991	#[stable(feature = "fmt_flags_align", since = "1.28.0")]
1992	pub fn align(&self) -> Option<Alignment> {
1993	self.options.get_align()
1994	}
1995
1996	/// Returns the optionally specified integer width that the output should be.
1997	///
1998	/// # Examples
1999	///
2000	/// ```
2001	/// use std::fmt;
2002	///
2003	/// struct Foo(i32);
2004	///
2005	/// impl fmt::Display for Foo {
2006	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2007	/// if let Some(width) = formatter.width() {
2008	/// // If we received a width, we use it
2009	/// write!(formatter, "{:width$}", format!("Foo({})", self.`0`), width = width)
2010	/// } else {
2011	/// // Otherwise we do nothing special
2012	/// write!(formatter, "Foo({})", self.`0`)
2013	/// }
2014	/// }
2015	/// }
2016	///
2017	/// assert_eq!(format!("{:10}", Foo(`23`)), "Foo(23) ");
2018	/// assert_eq!(format!("{}", Foo(`23`)), "Foo(23)");
2019	/// ```
2020	#[must_use]
2021	#[stable(feature = "fmt_flags", since = "1.5.0")]
2022	pub fn width(&self) -> Option<usize> {
2023	if self.options.flags & flags::WIDTH_FLAG == `0` {
2024	None
2025	} else {
2026	Some(self.options.width as usize)
2027	}
2028	}
2029
2030	/// Returns the optionally specified precision for numeric types.
2031	/// Alternatively, the maximum width for string types.
2032	///
2033	/// # Examples
2034	///
2035	/// ```
2036	/// use std::fmt;
2037	///
2038	/// struct Foo(f32);
2039	///
2040	/// impl fmt::Display for Foo {
2041	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2042	/// if let Some(precision) = formatter.precision() {
2043	/// // If we received a precision, we use it.
2044	/// write!(formatter, "Foo({1:.})", precision, self*.`0`)
2045	/// } else {
2046	/// // Otherwise we default to 2.
2047	/// write!(formatter, "Foo({:.2})", self.`0`)
2048	/// }
2049	/// }
2050	/// }
2051	///
2052	/// assert_eq!(format!("{:.4}", Foo(`23.2`)), "Foo(23.2000)");
2053	/// assert_eq!(format!("{}", Foo(`23.2`)), "Foo(23.20)");
2054	/// ```
2055	#[must_use]
2056	#[stable(feature = "fmt_flags", since = "1.5.0")]
2057	pub fn precision(&self) -> Option<usize> {
2058	if self.options.flags & flags::PRECISION_FLAG == `0` {
2059	None
2060	} else {
2061	Some(self.options.precision as usize)
2062	}
2063	}
2064
2065	/// Determines if the `+` flag was specified.
2066	///
2067	/// # Examples
2068	///
2069	/// ```
2070	/// use std::fmt;
2071	///
2072	/// struct Foo(i32);
2073	///
2074	/// impl fmt::Display for Foo {
2075	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2076	/// if formatter.sign_plus() {
2077	/// write!(formatter,
2078	/// "Foo({}{})",
2079	/// if self.`0` < `0` { '-' } else { '+' },
2080	/// self.`0`.abs())
2081	/// } else {
2082	/// write!(formatter, "Foo({})", self.`0`)
2083	/// }
2084	/// }
2085	/// }
2086	///
2087	/// assert_eq!(format!("{:+}", Foo(`23`)), "Foo(+23)");
2088	/// assert_eq!(format!("{:+}", Foo(-`23`)), "Foo(-23)");
2089	/// assert_eq!(format!("{}", Foo(`23`)), "Foo(23)");
2090	/// ```
2091	#[must_use]
2092	#[stable(feature = "fmt_flags", since = "1.5.0")]
2093	pub fn sign_plus(&self) -> bool {
2094	self.options.flags & flags::SIGN_PLUS_FLAG != `0`
2095	}
2096
2097	/// Determines if the `-` flag was specified.
2098	///
2099	/// # Examples
2100	///
2101	/// ```
2102	/// use std::fmt;
2103	///
2104	/// struct Foo(i32);
2105	///
2106	/// impl fmt::Display for Foo {
2107	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2108	/// if formatter.sign_minus() {
2109	/// // You want a minus sign? Have one!
2110	/// write!(formatter, "-Foo({})", self.`0`)
2111	/// } else {
2112	/// write!(formatter, "Foo({})", self.`0`)
2113	/// }
2114	/// }
2115	/// }
2116	///
2117	/// assert_eq!(format!("{:-}", Foo(`23`)), "-Foo(23)");
2118	/// assert_eq!(format!("{}", Foo(`23`)), "Foo(23)");
2119	/// ```
2120	#[must_use]
2121	#[stable(feature = "fmt_flags", since = "1.5.0")]
2122	pub fn sign_minus(&self) -> bool {
2123	self.options.flags & flags::SIGN_MINUS_FLAG != `0`
2124	}
2125
2126	/// Determines if the `#` flag was specified.
2127	///
2128	/// # Examples
2129	///
2130	/// ```
2131	/// use std::fmt;
2132	///
2133	/// struct Foo(i32);
2134	///
2135	/// impl fmt::Display for Foo {
2136	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2137	/// if formatter.alternate() {
2138	/// write!(formatter, "Foo({})", self.`0`)
2139	/// } else {
2140	/// write!(formatter, "{}", self.`0`)
2141	/// }
2142	/// }
2143	/// }
2144	///
2145	/// assert_eq!(format!("{:#}", Foo(`23`)), "Foo(23)");
2146	/// assert_eq!(format!("{}", Foo(`23`)), "23");
2147	/// ```
2148	#[must_use]
2149	#[stable(feature = "fmt_flags", since = "1.5.0")]
2150	pub fn alternate(&self) -> bool {
2151	self.options.flags & flags::ALTERNATE_FLAG != `0`
2152	}
2153
2154	/// Determines if the `0` flag was specified.
2155	///
2156	/// # Examples
2157	///
2158	/// ```
2159	/// use std::fmt;
2160	///
2161	/// struct Foo(i32);
2162	///
2163	/// impl fmt::Display for Foo {
2164	/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2165	/// assert!(formatter.sign_aware_zero_pad());
2166	/// assert_eq!(formatter.width(), Some(`4`));
2167	/// // We ignore the formatter's options.
2168	/// write!(formatter, "{}", self.`0`)
2169	/// }
2170	/// }
2171	///
2172	/// assert_eq!(format!("{:04}", Foo(`23`)), "23");
2173	/// ```
2174	#[must_use]
2175	#[stable(feature = "fmt_flags", since = "1.5.0")]
2176	pub fn sign_aware_zero_pad(&self) -> bool {
2177	self.options.flags & flags::SIGN_AWARE_ZERO_PAD_FLAG != `0`
2178	}
2179
2180	// FIXME: Decide what public API we want for these two flags.
2181	// https://github.com/rust-lang/rust/issues/48584
2182	fn debug_lower_hex(&self) -> bool {
2183	self.options.flags & flags::DEBUG_LOWER_HEX_FLAG != `0`
2184	}
2185	fn debug_upper_hex(&self) -> bool {
2186	self.options.flags & flags::DEBUG_UPPER_HEX_FLAG != `0`
2187	}
2188
2189	/// Creates a [`DebugStruct`] builder designed to assist with creation of
2190	/// [`fmt::Debug`] implementations for structs.
2191	///
2192	/// [`fmt::Debug`]: self::Debug
2193	///
2194	/// # Examples
2195	///
2196	/// ```rust
2197	/// use std::fmt;
2198	/// use std::net::Ipv4Addr;
2199	///
2200	/// struct Foo {
2201	/// bar: i32,
2202	/// baz: String,
2203	/// addr: Ipv4Addr,
2204	/// }
2205	///
2206	/// impl fmt::Debug for Foo {
2207	/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
2208	/// fmt.debug_struct("Foo")
2209	/// .field("bar", &self.bar)
2210	/// .field("baz", &self.baz)
2211	/// .field("addr", &format_args!("{}", self.addr))
2212	/// .finish()
2213	/// }
2214	/// }
2215	///
2216	/// assert_eq!(
2217	/// "Foo { bar: 10, baz: `\"`Hello World`\"`, addr: 127.0.0.1 }",
2218	/// format!("{:?}", Foo {
2219	/// bar: `10`,
2220	/// baz: "Hello World".to_string(),
2221	/// addr: Ipv4Addr::new(`127`, `0`, `0`, `1`),
2222	/// })
2223	/// );
2224	/// ```
2225	#[stable(feature = "debug_builders", since = "1.2.0")]
2226	pub fn debug_struct<'b>(&'b mut self, name: &str) -> DebugStruct<'b, 'a> {
2227	builders::debug_struct_new(self, name)
2228	}
2229
2230	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2231	/// binaries. `debug_struct_fields_finish` is more general, but this is
2232	/// faster for 1 field.
2233	#[doc(hidden)]
2234	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2235	pub fn debug_struct_field1_finish<'b>(
2236	&'b mut self,
2237	name: &str,
2238	name1: &str,
2239	value1: &dyn Debug,
2240	) -> Result {
2241	let mut builder = builders::debug_struct_new(self, name);
2242	builder.field(name1, value1);
2243	builder.finish()
2244	}
2245
2246	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2247	/// binaries. `debug_struct_fields_finish` is more general, but this is
2248	/// faster for 2 fields.
2249	#[doc(hidden)]
2250	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2251	pub fn debug_struct_field2_finish<'b>(
2252	&'b mut self,
2253	name: &str,
2254	name1: &str,
2255	value1: &dyn Debug,
2256	name2: &str,
2257	value2: &dyn Debug,
2258	) -> Result {
2259	let mut builder = builders::debug_struct_new(self, name);
2260	builder.field(name1, value1);
2261	builder.field(name2, value2);
2262	builder.finish()
2263	}
2264
2265	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2266	/// binaries. `debug_struct_fields_finish` is more general, but this is
2267	/// faster for 3 fields.
2268	#[doc(hidden)]
2269	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2270	pub fn debug_struct_field3_finish<'b>(
2271	&'b mut self,
2272	name: &str,
2273	name1: &str,
2274	value1: &dyn Debug,
2275	name2: &str,
2276	value2: &dyn Debug,
2277	name3: &str,
2278	value3: &dyn Debug,
2279	) -> Result {
2280	let mut builder = builders::debug_struct_new(self, name);
2281	builder.field(name1, value1);
2282	builder.field(name2, value2);
2283	builder.field(name3, value3);
2284	builder.finish()
2285	}
2286
2287	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2288	/// binaries. `debug_struct_fields_finish` is more general, but this is
2289	/// faster for 4 fields.
2290	#[doc(hidden)]
2291	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2292	pub fn debug_struct_field4_finish<'b>(
2293	&'b mut self,
2294	name: &str,
2295	name1: &str,
2296	value1: &dyn Debug,
2297	name2: &str,
2298	value2: &dyn Debug,
2299	name3: &str,
2300	value3: &dyn Debug,
2301	name4: &str,
2302	value4: &dyn Debug,
2303	) -> Result {
2304	let mut builder = builders::debug_struct_new(self, name);
2305	builder.field(name1, value1);
2306	builder.field(name2, value2);
2307	builder.field(name3, value3);
2308	builder.field(name4, value4);
2309	builder.finish()
2310	}
2311
2312	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2313	/// binaries. `debug_struct_fields_finish` is more general, but this is
2314	/// faster for 5 fields.
2315	#[doc(hidden)]
2316	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2317	pub fn debug_struct_field5_finish<'b>(
2318	&'b mut self,
2319	name: &str,
2320	name1: &str,
2321	value1: &dyn Debug,
2322	name2: &str,
2323	value2: &dyn Debug,
2324	name3: &str,
2325	value3: &dyn Debug,
2326	name4: &str,
2327	value4: &dyn Debug,
2328	name5: &str,
2329	value5: &dyn Debug,
2330	) -> Result {
2331	let mut builder = builders::debug_struct_new(self, name);
2332	builder.field(name1, value1);
2333	builder.field(name2, value2);
2334	builder.field(name3, value3);
2335	builder.field(name4, value4);
2336	builder.field(name5, value5);
2337	builder.finish()
2338	}
2339
2340	/// Shrinks `derive(Debug)` code, for faster compilation and smaller binaries.
2341	/// For the cases not covered by `debug_struct_field[12345]_finish`.
2342	#[doc(hidden)]
2343	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2344	pub fn debug_struct_fields_finish<'b>(
2345	&'b mut self,
2346	name: &str,
2347	names: &[&str],
2348	values: &[&dyn Debug],
2349	) -> Result {
2350	assert_eq!(names.len(), values.len());
2351	let mut builder = builders::debug_struct_new(self, name);
2352	for (name, value) in iter::zip(names, values) {
2353	builder.field(name, value);
2354	}
2355	builder.finish()
2356	}
2357
2358	/// Creates a `DebugTuple` builder designed to assist with creation of
2359	/// `fmt::Debug` implementations for tuple structs.
2360	///
2361	/// # Examples
2362	///
2363	/// ```rust
2364	/// use std::fmt;
2365	/// use std::marker::PhantomData;
2366	///
2367	/// struct Foo<T>(i32, String, PhantomData<T>);
2368	///
2369	/// impl<T> fmt::Debug for Foo<T> {
2370	/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
2371	/// fmt.debug_tuple("Foo")
2372	/// .field(&self.0)
2373	/// .field(&self.1)
2374	/// .field(&format_args!("_"))
2375	/// .finish()
2376	/// }
2377	/// }
2378	///
2379	/// assert_eq!(
2380	/// "Foo(10, `\"`Hello`\"`, _)",
2381	/// format!("{:?}", Foo(`10`, "Hello".to_string(), PhantomData::<u8>))
2382	/// );
2383	/// ```
2384	#[stable(feature = "debug_builders", since = "1.2.0")]
2385	pub fn debug_tuple<'b>(&'b mut self, name: &str) -> DebugTuple<'b, 'a> {
2386	builders::debug_tuple_new(self, name)
2387	}
2388
2389	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2390	/// binaries. `debug_tuple_fields_finish` is more general, but this is faster
2391	/// for 1 field.
2392	#[doc(hidden)]
2393	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2394	pub fn debug_tuple_field1_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug) -> Result {
2395	let mut builder = builders::debug_tuple_new(self, name);
2396	builder.field(value1);
2397	builder.finish()
2398	}
2399
2400	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2401	/// binaries. `debug_tuple_fields_finish` is more general, but this is faster
2402	/// for 2 fields.
2403	#[doc(hidden)]
2404	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2405	pub fn debug_tuple_field2_finish<'b>(
2406	&'b mut self,
2407	name: &str,
2408	value1: &dyn Debug,
2409	value2: &dyn Debug,
2410	) -> Result {
2411	let mut builder = builders::debug_tuple_new(self, name);
2412	builder.field(value1);
2413	builder.field(value2);
2414	builder.finish()
2415	}
2416
2417	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2418	/// binaries. `debug_tuple_fields_finish` is more general, but this is faster
2419	/// for 3 fields.
2420	#[doc(hidden)]
2421	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2422	pub fn debug_tuple_field3_finish<'b>(
2423	&'b mut self,
2424	name: &str,
2425	value1: &dyn Debug,
2426	value2: &dyn Debug,
2427	value3: &dyn Debug,
2428	) -> Result {
2429	let mut builder = builders::debug_tuple_new(self, name);
2430	builder.field(value1);
2431	builder.field(value2);
2432	builder.field(value3);
2433	builder.finish()
2434	}
2435
2436	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2437	/// binaries. `debug_tuple_fields_finish` is more general, but this is faster
2438	/// for 4 fields.
2439	#[doc(hidden)]
2440	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2441	pub fn debug_tuple_field4_finish<'b>(
2442	&'b mut self,
2443	name: &str,
2444	value1: &dyn Debug,
2445	value2: &dyn Debug,
2446	value3: &dyn Debug,
2447	value4: &dyn Debug,
2448	) -> Result {
2449	let mut builder = builders::debug_tuple_new(self, name);
2450	builder.field(value1);
2451	builder.field(value2);
2452	builder.field(value3);
2453	builder.field(value4);
2454	builder.finish()
2455	}
2456
2457	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2458	/// binaries. `debug_tuple_fields_finish` is more general, but this is faster
2459	/// for 5 fields.
2460	#[doc(hidden)]
2461	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2462	pub fn debug_tuple_field5_finish<'b>(
2463	&'b mut self,
2464	name: &str,
2465	value1: &dyn Debug,
2466	value2: &dyn Debug,
2467	value3: &dyn Debug,
2468	value4: &dyn Debug,
2469	value5: &dyn Debug,
2470	) -> Result {
2471	let mut builder = builders::debug_tuple_new(self, name);
2472	builder.field(value1);
2473	builder.field(value2);
2474	builder.field(value3);
2475	builder.field(value4);
2476	builder.field(value5);
2477	builder.finish()
2478	}
2479
2480	/// Shrinks `derive(Debug)` code, for faster compilation and smaller
2481	/// binaries. For the cases not covered by `debug_tuple_field[12345]_finish`.
2482	#[doc(hidden)]
2483	#[unstable(feature = "fmt_helpers_for_derive", issue = "none")]
2484	pub fn debug_tuple_fields_finish<'b>(
2485	&'b mut self,
2486	name: &str,
2487	values: &[&dyn Debug],
2488	) -> Result {
2489	let mut builder = builders::debug_tuple_new(self, name);
2490	for value in values {
2491	builder.field(value);
2492	}
2493	builder.finish()
2494	}
2495
2496	/// Creates a `DebugList` builder designed to assist with creation of
2497	/// `fmt::Debug` implementations for list-like structures.
2498	///
2499	/// # Examples
2500	///
2501	/// ```rust
2502	/// use std::fmt;
2503	///
2504	/// struct Foo(Vec<i32>);
2505	///
2506	/// impl fmt::Debug for Foo {
2507	/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
2508	/// fmt.debug_list().entries(self.0.iter()).finish()
2509	/// }
2510	/// }
2511	///
2512	/// assert_eq!(format!("{:?}", Foo(vec![`10`, `11`])), "[10, 11]");
2513	/// ```
2514	#[stable(feature = "debug_builders", since = "1.2.0")]
2515	pub fn debug_list<'b>(&'b mut self) -> DebugList<'b, 'a> {
2516	builders::debug_list_new(self)
2517	}
2518
2519	/// Creates a `DebugSet` builder designed to assist with creation of
2520	/// `fmt::Debug` implementations for set-like structures.
2521	///
2522	/// # Examples
2523	///
2524	/// ```rust
2525	/// use std::fmt;
2526	///
2527	/// struct Foo(Vec<i32>);
2528	///
2529	/// impl fmt::Debug for Foo {
2530	/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
2531	/// fmt.debug_set().entries(self.0.iter()).finish()
2532	/// }
2533	/// }
2534	///
2535	/// assert_eq!(format!("{:?}", Foo(vec![`10`, `11`])), "{10, 11}");
2536	/// ```
2537	///
2538	/// [`format_args!`]: crate::format_args
2539	///
2540	/// In this more complex example, we use [`format_args!`] and `.debug_set()`
2541	/// to build a list of match arms:
2542	///
2543	/// ```rust
2544	/// use std::fmt;
2545	///
2546	/// struct Arm<'a, L, R>(&'a (L, R));
2547	/// struct Table<'a, K, V>(&'a [(K, V)], V);
2548	///
2549	/// impl<'a, L, R> fmt::Debug for Arm<'a, L, R>
2550	/// where
2551	/// L: 'a + fmt::Debug, R: 'a + fmt::Debug
2552	/// {
2553	/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
2554	/// L::fmt(&(self.0).0, fmt)?;
2555	/// fmt.write_str(" => ")?;
2556	/// R::fmt(&(self.0).1, fmt)
2557	/// }
2558	/// }
2559	///
2560	/// impl<'a, K, V> fmt::Debug for Table<'a, K, V>
2561	/// where
2562	/// K: 'a + fmt::Debug, V: 'a + fmt::Debug
2563	/// {
2564	/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
2565	/// fmt.debug_set()
2566	/// .entries(self.0.iter().map(Arm))
2567	/// .entry(&Arm(&(format_args!("_"), &self.1)))
2568	/// .finish()
2569	/// }
2570	/// }
2571	/// ```
2572	#[stable(feature = "debug_builders", since = "1.2.0")]
2573	pub fn debug_set<'b>(&'b mut self) -> DebugSet<'b, 'a> {
2574	builders::debug_set_new(self)
2575	}
2576
2577	/// Creates a `DebugMap` builder designed to assist with creation of
2578	/// `fmt::Debug` implementations for map-like structures.
2579	///
2580	/// # Examples
2581	///
2582	/// ```rust
2583	/// use std::fmt;
2584	///
2585	/// struct Foo(Vec<(String, i32)>);
2586	///
2587	/// impl fmt::Debug for Foo {
2588	/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
2589	/// fmt.debug_map().entries(self.0.iter().map(\|&(ref k, ref v)\| (k, v))).finish()
2590	/// }
2591	/// }
2592	///
2593	/// assert_eq!(
2594	/// format!("{:?}", Foo(vec![("A".to_string(), `10`), ("B".to_string(), `11`)])),
2595	/// r#"{"A": 10, "B": 11}"#
2596	/// );
2597	/// ```
2598	#[stable(feature = "debug_builders", since = "1.2.0")]
2599	pub fn debug_map<'b>(&'b mut self) -> DebugMap<'b, 'a> {
2600	builders::debug_map_new(self)
2601	}
2602
2603	/// Returns the sign of this formatter (`+` or `-`).
2604	#[unstable(feature = "formatting_options", issue = "118117")]
2605	pub const fn sign(&self) -> Option<Sign> {
2606	self.options.get_sign()
2607	}
2608
2609	/// Returns the formatting options this formatter corresponds to.
2610	#[unstable(feature = "formatting_options", issue = "118117")]
2611	pub const fn options(&self) -> FormattingOptions {
2612	self.options
2613	}
2614	}
2615
2616	#[stable(since = "1.2.0", feature = "formatter_write")]
2617	impl Write for Formatter<'_> {
2618	fn write_str(&mut self, s: &str) -> Result {
2619	self.buf.write_str(s)
2620	}
2621
2622	fn write_char(&mut self, c: char) -> Result {
2623	self.buf.write_char(c)
2624	}
2625
2626	#[inline]
2627	fn write_fmt(&mut self, args: Arguments<'_>) -> Result {
2628	if let Some(s: &'static str) = args.as_statically_known_str() {
2629	self.buf.write_str(s)
2630	} else {
2631	write(self.buf, args)
2632	}
2633	}
2634	}
2635
2636	#[stable(feature = "rust1", since = "1.0.0")]
2637	impl Display for Error {
2638	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2639	Display::fmt(self:"an error occurred when formatting an argument", f)
2640	}
2641	}
2642
2643	// Implementations of the core formatting traits
2644
2645	macro_rules! fmt_refs {
2646	($($tr:ident),*) => {
2647	$(
2648	#[stable(feature = "rust1", since = "1.0.0")]
2649	impl<T: ?Sized + $tr> $tr for &T {
2650	fn fmt(&self, f: &mut Formatter<'_>) -> Result { $tr::fmt(&**self, f) }
2651	}
2652	#[stable(feature = "rust1", since = "1.0.0")]
2653	impl<T: ?Sized + $tr> $tr for &mut T {
2654	fn fmt(&self, f: &mut Formatter<'_>) -> Result { $tr::fmt(&**self, f) }
2655	}
2656	)*
2657	}
2658	}
2659
2660	fmt_refs! { Debug, Display, Octal, Binary, LowerHex, UpperHex, LowerExp, UpperExp }
2661
2662	#[unstable(feature = "never_type", issue = "35121")]
2663	impl Debug for ! {
2664	#[inline]
2665	fn fmt(&self, _: &mut Formatter<'_>) -> Result {
2666	*self
2667	}
2668	}
2669
2670	#[unstable(feature = "never_type", issue = "35121")]
2671	impl Display for ! {
2672	#[inline]
2673	fn fmt(&self, _: &mut Formatter<'_>) -> Result {
2674	*self
2675	}
2676	}
2677
2678	#[stable(feature = "rust1", since = "1.0.0")]
2679	impl Debug for bool {
2680	#[inline]
2681	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2682	Display::fmt(self, f)
2683	}
2684	}
2685
2686	#[stable(feature = "rust1", since = "1.0.0")]
2687	impl Display for bool {
2688	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2689	Display::fmt(self:if self { "true" } else* { "false" }, f)
2690	}
2691	}
2692
2693	#[stable(feature = "rust1", since = "1.0.0")]
2694	impl Debug for str {
2695	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2696	f.write_char('"')?;
2697
2698	// substring we know is printable
2699	let mut printable_range = `0`..`0`;
2700
2701	fn needs_escape(b: u8) -> bool {
2702	b > `0x7E` \|\| b < `0x20` \|\| b == b'`\\`' \|\| b == b'"'
2703	}
2704
2705	// the loop here first skips over runs of printable ASCII as a fast path.
2706	// other chars (unicode, or ASCII that needs escaping) are then handled per-`char`.
2707	let mut rest = self;
2708	while rest.len() > `0` {
2709	let Some(non_printable_start) = rest.as_bytes().iter().position(\|&b\| needs_escape(b))
2710	else {
2711	printable_range.end += rest.len();
2712	break;
2713	};
2714
2715	printable_range.end += non_printable_start;
2716	// SAFETY: the position was derived from an iterator, so is known to be within bounds, and at a char boundary
2717	rest = unsafe { rest.get_unchecked(non_printable_start..) };
2718
2719	let mut chars = rest.chars();
2720	if let Some(c) = chars.next() {
2721	let esc = c.escape_debug_ext(EscapeDebugExtArgs {
2722	escape_grapheme_extended: `true`,
2723	escape_single_quote: `false`,
2724	escape_double_quote: `true`,
2725	});
2726	if esc.len() != `1` {
2727	f.write_str(&self[printable_range.clone()])?;
2728	Display::fmt(&esc, f)?;
2729	printable_range.start = printable_range.end + c.len_utf8();
2730	}
2731	printable_range.end += c.len_utf8();
2732	}
2733	rest = chars.as_str();
2734	}
2735
2736	f.write_str(&self[printable_range])?;
2737
2738	f.write_char('"')
2739	}
2740	}
2741
2742	#[stable(feature = "rust1", since = "1.0.0")]
2743	impl Display for str {
2744	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2745	f.pad(self)
2746	}
2747	}
2748
2749	#[stable(feature = "rust1", since = "1.0.0")]
2750	impl Debug for char {
2751	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2752	f.write_char('`\'`')?;
2753	let esc: EscapeDebug = self.escape_debug_ext(args:EscapeDebugExtArgs {
2754	escape_grapheme_extended: `true`,
2755	escape_single_quote: `true`,
2756	escape_double_quote: `false`,
2757	});
2758	Display::fmt(&esc, f)?;
2759	f.write_char('`\'`')
2760	}
2761	}
2762
2763	#[stable(feature = "rust1", since = "1.0.0")]
2764	impl Display for char {
2765	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2766	if f.options.flags & (flags::WIDTH_FLAG \| flags::PRECISION_FLAG) == `0` {
2767	f.write_char(*self)
2768	} else {
2769	f.pad(self.encode_utf8(&mut [`0`; MAX_LEN_UTF8]))
2770	}
2771	}
2772	}
2773
2774	#[stable(feature = "rust1", since = "1.0.0")]
2775	impl<T: ?Sized> Pointer for *const T {
2776	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2777	if <<T as core::ptr::Pointee>::Metadata as core::unit::IsUnit>::is_unit() {
2778	pointer_fmt_inner(self.expose_provenance(), f)
2779	} else {
2780	f&mut DebugStruct<'_, '_>.debug_struct("Pointer")
2781	.field_with("addr", \|f\| pointer_fmt_inner(self.expose_provenance(), f))
2782	.field(name:"metadata", &core::ptr::metadata(*self))
2783	.finish()
2784	}
2785	}
2786	}
2787
2788	/// Since the formatting will be identical for all pointer types, uses a
2789	/// non-monomorphized implementation for the actual formatting to reduce the
2790	/// amount of codegen work needed.
2791	///
2792	/// This uses `ptr_addr: usize` and not `ptr: const ()` to be able to use this for*
2793	/// `fn(...) -> ...` without using [problematic] "Oxford Casts".
2794	///
2795	/// [problematic]: https://github.com/rust-lang/rust/issues/95489
2796	pub(crate) fn pointer_fmt_inner(ptr_addr: usize, f: &mut Formatter<'_>) -> Result {
2797	let old_options: FormattingOptions = f.options;
2798
2799	// The alternate flag is already treated by LowerHex as being special-
2800	// it denotes whether to prefix with 0x. We use it to work out whether
2801	// or not to zero extend, and then unconditionally set it to get the
2802	// prefix.
2803	if f.options.get_alternate() {
2804	f.options.sign_aware_zero_pad(`true`);
2805
2806	if f.options.get_width().is_none() {
2807	f.options.width(Some((usize::BITS / `4`) as u16 + `2`));
2808	}
2809	}
2810	f.options.alternate(`true`);
2811
2812	let ret: Result<(), Error> = LowerHex::fmt(&ptr_addr, f);
2813
2814	f.options = old_options;
2815
2816	ret
2817	}
2818
2819	#[stable(feature = "rust1", since = "1.0.0")]
2820	impl<T: ?Sized> Pointer for *mut T {
2821	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2822	Pointer::fmt(&(self as const T), f)
2823	}
2824	}
2825
2826	#[stable(feature = "rust1", since = "1.0.0")]
2827	impl<T: ?Sized> Pointer for &T {
2828	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2829	Pointer::fmt(&(self as const T), f)
2830	}
2831	}
2832
2833	#[stable(feature = "rust1", since = "1.0.0")]
2834	impl<T: ?Sized> Pointer for &mut T {
2835	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2836	Pointer::fmt(&(&self as const* T), f)
2837	}
2838	}
2839
2840	// Implementation of Display/Debug for various core types
2841
2842	#[stable(feature = "rust1", since = "1.0.0")]
2843	impl<T: ?Sized> Debug for *const T {
2844	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2845	Pointer::fmt(self, f)
2846	}
2847	}
2848	#[stable(feature = "rust1", since = "1.0.0")]
2849	impl<T: ?Sized> Debug for *mut T {
2850	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2851	Pointer::fmt(self, f)
2852	}
2853	}
2854
2855	macro_rules! peel {
2856	($name:ident, $($other:ident,)) => (tuple! { $($other,) })
2857	}
2858
2859	macro_rules! tuple {
2860	() => ();
2861	( $($name:ident,)+ ) => (
2862	maybe_tuple_doc! {
2863	$($name)+ @
2864	#[stable(feature = "rust1", since = "1.0.0")]
2865	impl<$($name:Debug),+> Debug for ($($name,)+) where last_type!($($name,)+): ?Sized {
2866	#[allow(non_snake_case, unused_assignments)]
2867	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2868	let mut builder = f.debug_tuple("");
2869	let ($(ref $name,)+) = *self;
2870	$(
2871	builder.field(&$name);
2872	)+
2873
2874	builder.finish()
2875	}
2876	}
2877	}
2878	peel! { $($name,)+ }
2879	)
2880	}
2881
2882	macro_rules! maybe_tuple_doc {
2883	($a:ident @ #[$meta:meta] $item:item) => {
2884	#[doc(fake_variadic)]
2885	#[doc = "This trait is implemented for tuples up to twelve items long."]
2886	#[$meta]
2887	$item
2888	};
2889	($a:ident $($rest_a:ident)+ @ #[$meta:meta] $item:item) => {
2890	#[doc(hidden)]
2891	#[$meta]
2892	$item
2893	};
2894	}
2895
2896	macro_rules! last_type {
2897	($a:ident,) => { $a };
2898	($a:ident, $($rest_a:ident,)+) => { last_type!($($rest_a,)+) };
2899	}
2900
2901	tuple! { E, D, C, B, A, Z, Y, X, W, V, U, T, }
2902
2903	#[stable(feature = "rust1", since = "1.0.0")]
2904	impl<T: Debug> Debug for [T] {
2905	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2906	f.debug_list().entries(self.iter()).finish()
2907	}
2908	}
2909
2910	#[stable(feature = "rust1", since = "1.0.0")]
2911	impl Debug for () {
2912	#[inline]
2913	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2914	f.pad("()")
2915	}
2916	}
2917	#[stable(feature = "rust1", since = "1.0.0")]
2918	impl<T: ?Sized> Debug for PhantomData<T> {
2919	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2920	write!(f, "PhantomData<{}>", crate::any::type_name::<T>())
2921	}
2922	}
2923
2924	#[stable(feature = "rust1", since = "1.0.0")]
2925	impl<T: Copy + Debug> Debug for Cell<T> {
2926	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2927	f.debug_struct("Cell").field(name:"value", &self.get()).finish()
2928	}
2929	}
2930
2931	#[stable(feature = "rust1", since = "1.0.0")]
2932	impl<T: ?Sized + Debug> Debug for RefCell<T> {
2933	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2934	let mut d: DebugStruct<'_, '_> = f.debug_struct(name:"RefCell");
2935	match self.try_borrow() {
2936	Ok(borrow: Ref<'_, T>) => d.field(name:"value", &borrow),
2937	Err(_) => d.field(name:"value", &format_args!("<borrowed>")),
2938	};
2939	d.finish()
2940	}
2941	}
2942
2943	#[stable(feature = "rust1", since = "1.0.0")]
2944	impl<T: ?Sized + Debug> Debug for Ref<'_, T> {
2945	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2946	Debug::fmt(&**self, f)
2947	}
2948	}
2949
2950	#[stable(feature = "rust1", since = "1.0.0")]
2951	impl<T: ?Sized + Debug> Debug for RefMut<'_, T> {
2952	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2953	Debug::fmt(&*(self.deref()), f)
2954	}
2955	}
2956
2957	#[stable(feature = "core_impl_debug", since = "1.9.0")]
2958	impl<T: ?Sized> Debug for UnsafeCell<T> {
2959	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2960	f.debug_struct(name:"UnsafeCell").finish_non_exhaustive()
2961	}
2962	}
2963
2964	#[unstable(feature = "sync_unsafe_cell", issue = "95439")]
2965	impl<T: ?Sized> Debug for SyncUnsafeCell<T> {
2966	fn fmt(&self, f: &mut Formatter<'_>) -> Result {
2967	f.debug_struct(name:"SyncUnsafeCell").finish_non_exhaustive()
2968	}
2969	}
2970
2971	// If you expected tests to be here, look instead at coretests/tests/fmt/;
2972	// it's a lot easier than creating all of the rt::Piece structures here.
2973	// There are also tests in alloctests/tests/fmt.rs, for those that need allocations.
2974