Skip to content

Commit f727f8a

Browse files
RalfJungRalfJung
committed
move Formatting Traits down
1 parent a14601e commit f727f8a

File tree

1 file changed

+182
-182
lines changed

1 file changed

+182
-182
lines changed

‎src/liballoc/fmt.rs

+182-182
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,187 @@
9797
//! actual object being formatted, and the number of characters must have the
9898
//! type [`usize`].
9999
//!
100-
//! ## Formatting traits
100+
//! # Formatting Parameters
101+
//!
102+
//! Each argument being formatted can be transformed by a number of formatting
103+
//! parameters (corresponding to `format_spec` in the syntax above). These
104+
//! parameters affect the string representation of what's being formatted.
105+
//!
106+
//! ## Fill/Alignment
107+
//!
108+
//! The fill character is provided normally in conjunction with the
109+
//! [`width`](#width)
110+
//! parameter. This indicates that if the value being formatted is smaller than
111+
//! `width` some extra characters will be printed around it. The extra
112+
//! characters are specified by `fill`, and the alignment can be one of the
113+
//! following options:
114+
//!
115+
//! * `<` - the argument is left-aligned in `width` columns
116+
//! * `^` - the argument is center-aligned in `width` columns
117+
//! * `>` - the argument is right-aligned in `width` columns
118+
//!
119+
//! Note that alignment may not be implemented by some types. In particular, it
120+
//! is not generally implemented for the `Debug` trait. A good way to ensure
121+
//! padding is applied is to format your input, then use this resulting string
122+
//! to pad your output.
123+
//!
124+
//! ## Sign/`#`/`0`
125+
//!
126+
//! These can all be interpreted as flags for a particular formatter.
127+
//!
128+
//! * `+` - This is intended for numeric types and indicates that the sign
129+
//! should always be printed. Positive signs are never printed by
130+
//! default, and the negative sign is only printed by default for the
131+
//! `Signed` trait. This flag indicates that the correct sign (`+` or `-`)
132+
//! should always be printed.
133+
//! * `-` - Currently not used
134+
//! * `#` - This flag is indicates that the "alternate" form of printing should
135+
//! be used. The alternate forms are:
136+
//! * `#?` - pretty-print the [`Debug`] formatting
137+
//! * `#x` - precedes the argument with a `0x`
138+
//! * `#X` - precedes the argument with a `0x`
139+
//! * `#b` - precedes the argument with a `0b`
140+
//! * `#o` - precedes the argument with a `0o`
141+
//! * `0` - This is used to indicate for integer formats that the padding should
142+
//! both be done with a `0` character as well as be sign-aware. A format
143+
//! like `{:08}` would yield `00000001` for the integer `1`, while the
144+
//! same format would yield `-0000001` for the integer `-1`. Notice that
145+
//! the negative version has one fewer zero than the positive version.
146+
//! Note that padding zeroes are always placed after the sign (if any)
147+
//! and before the digits. When used together with the `#` flag, a similar
148+
//! rule applies: padding zeroes are inserted after the prefix but before
149+
//! the digits.
150+
//!
151+
//! ## Width
152+
//!
153+
//! This is a parameter for the "minimum width" that the format should take up.
154+
//! If the value's string does not fill up this many characters, then the
155+
//! padding specified by fill/alignment will be used to take up the required
156+
//! space.
157+
//!
158+
//! The default [fill/alignment](#fillalignment) for non-numerics is a space and
159+
//! left-aligned. The
160+
//! defaults for numeric formatters is also a space but with right-alignment. If
161+
//! the `0` flag is specified for numerics, then the implicit fill character is
162+
//! `0`.
163+
//!
164+
//! The value for the width can also be provided as a [`usize`] in the list of
165+
//! parameters by using the dollar syntax indicating that the second argument is
166+
//! a [`usize`] specifying the width, for example:
167+
//!
168+
//! ```
169+
//! // All of these print "Hello x !"
170+
//! println!("Hello {:5}!", "x");
171+
//! println!("Hello {:1$}!", "x", 5);
172+
//! println!("Hello {1:0$}!", 5, "x");
173+
//! println!("Hello {:width$}!", "x", width = 5);
174+
//! ```
175+
//!
176+
//! Referring to an argument with the dollar syntax does not affect the "next
177+
//! argument" counter, so it's usually a good idea to refer to arguments by
178+
//! position, or use named arguments.
179+
//!
180+
//! ## Precision
181+
//!
182+
//! For non-numeric types, this can be considered a "maximum width". If the resulting string is
183+
//! longer than this width, then it is truncated down to this many characters and that truncated
184+
//! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set.
185+
//!
186+
//! For integral types, this is ignored.
187+
//!
188+
//! For floating-point types, this indicates how many digits after the decimal point should be
189+
//! printed.
190+
//!
191+
//! There are three possible ways to specify the desired `precision`:
192+
//!
193+
//! 1. An integer `.N`:
194+
//!
195+
//! the integer `N` itself is the precision.
196+
//!
197+
//! 2. An integer or name followed by dollar sign `.N$`:
198+
//!
199+
//! use format *argument* `N` (which must be a `usize`) as the precision.
200+
//!
201+
//! 3. An asterisk `.*`:
202+
//!
203+
//! `.*` means that this `{...}` is associated with *two* format inputs rather than one: the
204+
//! first input holds the `usize` precision, and the second holds the value to print. Note that
205+
//! in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part refers
206+
//! to the *value* to print, and the `precision` must come in the input preceding `<arg>`.
207+
//!
208+
//! For example, the following calls all print the same thing `Hello x is 0.01000`:
209+
//!
210+
//! ```
211+
//! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)}
212+
//! println!("Hello {0} is {1:.5}", "x", 0.01);
213+
//!
214+
//! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)}
215+
//! println!("Hello {1} is {2:.0$}", 5, "x", 0.01);
216+
//!
217+
//! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)}
218+
//! println!("Hello {0} is {2:.1$}", "x", 5, 0.01);
219+
//!
220+
//! // Hello {next arg ("x")} is {second of next two args (0.01) with precision
221+
//! // specified in first of next two args (5)}
222+
//! println!("Hello {} is {:.*}", "x", 5, 0.01);
223+
//!
224+
//! // Hello {next arg ("x")} is {arg 2 (0.01) with precision
225+
//! // specified in its predecessor (5)}
226+
//! println!("Hello {} is {2:.*}", "x", 5, 0.01);
227+
//!
228+
//! // Hello {next arg ("x")} is {arg "number" (0.01) with precision specified
229+
//! // in arg "prec" (5)}
230+
//! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01);
231+
//! ```
232+
//!
233+
//! While these:
234+
//!
235+
//! ```
236+
//! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56);
237+
//! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56");
238+
//! println!("{}, `{name:>8.*}` has 3 right-aligned characters", "Hello", 3, name="1234.56");
239+
//! ```
240+
//!
241+
//! print two significantly different things:
242+
//!
243+
//! ```text
244+
//! Hello, `1234.560` has 3 fractional digits
245+
//! Hello, `123` has 3 characters
246+
//! Hello, ` 123` has 3 right-aligned characters
247+
//! ```
248+
//!
249+
//! # Escaping
250+
//!
251+
//! The literal characters `{` and `}` may be included in a string by preceding
252+
//! them with the same character. For example, the `{` character is escaped with
253+
//! `{{` and the `}` character is escaped with `}}`.
254+
//!
255+
//! # Syntax
256+
//!
257+
//! To summarize, you can find the full grammar of format strings.
258+
//! The syntax for the formatting language used is drawn from other languages,
259+
//! so it should not be too alien. Arguments are formatted with Python-like
260+
//! syntax, meaning that arguments are surrounded by `{}` instead of the C-like
261+
//! `%`. The actual grammar for the formatting syntax is:
262+
//!
263+
//! ```text
264+
//! format_string := <text> [ maybe-format <text> ] *
265+
//! maybe-format := '{' '{' | '}' '}' | <format>
266+
//! format := '{' [ argument ] [ ':' format_spec ] '}'
267+
//! argument := integer | identifier
268+
//!
269+
//! format_spec := [[fill]align][sign]['#']['0'][width]['.' precision][type]
270+
//! fill := character
271+
//! align := '<' | '^' | '>'
272+
//! sign := '+' | '-'
273+
//! width := count
274+
//! precision := count | '*'
275+
//! type := identifier | '?' | ''
276+
//! count := parameter | integer
277+
//! parameter := argument '$'
278+
//! ```
279+
//!
280+
//! # Formatting traits
101281
//!
102282
//! When requesting that an argument be formatted with a particular type, you
103283
//! are actually requesting that an argument ascribes to a particular trait.
@@ -220,7 +400,7 @@
220400
//! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");
221401
//! ```
222402
//!
223-
//! ## Related macros
403+
//! # Related macros
224404
//!
225405
//! There are a number of related macros in the [`format!`] family. The ones that
226406
//! are currently implemented are:
@@ -300,186 +480,6 @@
300480
//! it would internally pass around this structure until it has been determined
301481
//! where output should go to.
302482
//!
303-
//! # Formatting Parameters
304-
//!
305-
//! Each argument being formatted can be transformed by a number of formatting
306-
//! parameters (corresponding to `format_spec` in the syntax above). These
307-
//! parameters affect the string representation of what's being formatted.
308-
//!
309-
//! ## Fill/Alignment
310-
//!
311-
//! The fill character is provided normally in conjunction with the
312-
//! [`width`](#width)
313-
//! parameter. This indicates that if the value being formatted is smaller than
314-
//! `width` some extra characters will be printed around it. The extra
315-
//! characters are specified by `fill`, and the alignment can be one of the
316-
//! following options:
317-
//!
318-
//! * `<` - the argument is left-aligned in `width` columns
319-
//! * `^` - the argument is center-aligned in `width` columns
320-
//! * `>` - the argument is right-aligned in `width` columns
321-
//!
322-
//! Note that alignment may not be implemented by some types. In particular, it
323-
//! is not generally implemented for the `Debug` trait. A good way to ensure
324-
//! padding is applied is to format your input, then use this resulting string
325-
//! to pad your output.
326-
//!
327-
//! ## Sign/`#`/`0`
328-
//!
329-
//! These can all be interpreted as flags for a particular formatter.
330-
//!
331-
//! * `+` - This is intended for numeric types and indicates that the sign
332-
//! should always be printed. Positive signs are never printed by
333-
//! default, and the negative sign is only printed by default for the
334-
//! `Signed` trait. This flag indicates that the correct sign (`+` or `-`)
335-
//! should always be printed.
336-
//! * `-` - Currently not used
337-
//! * `#` - This flag is indicates that the "alternate" form of printing should
338-
//! be used. The alternate forms are:
339-
//! * `#?` - pretty-print the [`Debug`] formatting
340-
//! * `#x` - precedes the argument with a `0x`
341-
//! * `#X` - precedes the argument with a `0x`
342-
//! * `#b` - precedes the argument with a `0b`
343-
//! * `#o` - precedes the argument with a `0o`
344-
//! * `0` - This is used to indicate for integer formats that the padding should
345-
//! both be done with a `0` character as well as be sign-aware. A format
346-
//! like `{:08}` would yield `00000001` for the integer `1`, while the
347-
//! same format would yield `-0000001` for the integer `-1`. Notice that
348-
//! the negative version has one fewer zero than the positive version.
349-
//! Note that padding zeroes are always placed after the sign (if any)
350-
//! and before the digits. When used together with the `#` flag, a similar
351-
//! rule applies: padding zeroes are inserted after the prefix but before
352-
//! the digits.
353-
//!
354-
//! ## Width
355-
//!
356-
//! This is a parameter for the "minimum width" that the format should take up.
357-
//! If the value's string does not fill up this many characters, then the
358-
//! padding specified by fill/alignment will be used to take up the required
359-
//! space.
360-
//!
361-
//! The default [fill/alignment](#fillalignment) for non-numerics is a space and
362-
//! left-aligned. The
363-
//! defaults for numeric formatters is also a space but with right-alignment. If
364-
//! the `0` flag is specified for numerics, then the implicit fill character is
365-
//! `0`.
366-
//!
367-
//! The value for the width can also be provided as a [`usize`] in the list of
368-
//! parameters by using the dollar syntax indicating that the second argument is
369-
//! a [`usize`] specifying the width, for example:
370-
//!
371-
//! ```
372-
//! // All of these print "Hello x !"
373-
//! println!("Hello {:5}!", "x");
374-
//! println!("Hello {:1$}!", "x", 5);
375-
//! println!("Hello {1:0$}!", 5, "x");
376-
//! println!("Hello {:width$}!", "x", width = 5);
377-
//! ```
378-
//!
379-
//! Referring to an argument with the dollar syntax does not affect the "next
380-
//! argument" counter, so it's usually a good idea to refer to arguments by
381-
//! position, or use named arguments.
382-
//!
383-
//! ## Precision
384-
//!
385-
//! For non-numeric types, this can be considered a "maximum width". If the resulting string is
386-
//! longer than this width, then it is truncated down to this many characters and that truncated
387-
//! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set.
388-
//!
389-
//! For integral types, this is ignored.
390-
//!
391-
//! For floating-point types, this indicates how many digits after the decimal point should be
392-
//! printed.
393-
//!
394-
//! There are three possible ways to specify the desired `precision`:
395-
//!
396-
//! 1. An integer `.N`:
397-
//!
398-
//! the integer `N` itself is the precision.
399-
//!
400-
//! 2. An integer or name followed by dollar sign `.N$`:
401-
//!
402-
//! use format *argument* `N` (which must be a `usize`) as the precision.
403-
//!
404-
//! 3. An asterisk `.*`:
405-
//!
406-
//! `.*` means that this `{...}` is associated with *two* format inputs rather than one: the
407-
//! first input holds the `usize` precision, and the second holds the value to print. Note that
408-
//! in this case, if one uses the format string `{<arg>:<spec>.*}`, then the `<arg>` part refers
409-
//! to the *value* to print, and the `precision` must come in the input preceding `<arg>`.
410-
//!
411-
//! For example, the following calls all print the same thing `Hello x is 0.01000`:
412-
//!
413-
//! ```
414-
//! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)}
415-
//! println!("Hello {0} is {1:.5}", "x", 0.01);
416-
//!
417-
//! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)}
418-
//! println!("Hello {1} is {2:.0$}", 5, "x", 0.01);
419-
//!
420-
//! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)}
421-
//! println!("Hello {0} is {2:.1$}", "x", 5, 0.01);
422-
//!
423-
//! // Hello {next arg ("x")} is {second of next two args (0.01) with precision
424-
//! // specified in first of next two args (5)}
425-
//! println!("Hello {} is {:.*}", "x", 5, 0.01);
426-
//!
427-
//! // Hello {next arg ("x")} is {arg 2 (0.01) with precision
428-
//! // specified in its predecessor (5)}
429-
//! println!("Hello {} is {2:.*}", "x", 5, 0.01);
430-
//!
431-
//! // Hello {next arg ("x")} is {arg "number" (0.01) with precision specified
432-
//! // in arg "prec" (5)}
433-
//! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01);
434-
//! ```
435-
//!
436-
//! While these:
437-
//!
438-
//! ```
439-
//! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56);
440-
//! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56");
441-
//! println!("{}, `{name:>8.*}` has 3 right-aligned characters", "Hello", 3, name="1234.56");
442-
//! ```
443-
//!
444-
//! print two significantly different things:
445-
//!
446-
//! ```text
447-
//! Hello, `1234.560` has 3 fractional digits
448-
//! Hello, `123` has 3 characters
449-
//! Hello, ` 123` has 3 right-aligned characters
450-
//! ```
451-
//!
452-
//! # Escaping
453-
//!
454-
//! The literal characters `{` and `}` may be included in a string by preceding
455-
//! them with the same character. For example, the `{` character is escaped with
456-
//! `{{` and the `}` character is escaped with `}}`.
457-
//!
458-
//! # Syntax
459-
//!
460-
//! Below, you can find the full grammar of format strings.
461-
//! The syntax for the formatting language used is drawn from other languages,
462-
//! so it should not be too alien. Arguments are formatted with Python-like
463-
//! syntax, meaning that arguments are surrounded by `{}` instead of the C-like
464-
//! `%`. The actual grammar for the formatting syntax is:
465-
//!
466-
//! ```text
467-
//! format_string := <text> [ maybe-format <text> ] *
468-
//! maybe-format := '{' '{' | '}' '}' | <format>
469-
//! format := '{' [ argument ] [ ':' format_spec ] '}'
470-
//! argument := integer | identifier
471-
//!
472-
//! format_spec := [[fill]align][sign]['#']['0'][width]['.' precision][type]
473-
//! fill := character
474-
//! align := '<' | '^' | '>'
475-
//! sign := '+' | '-'
476-
//! width := count
477-
//! precision := count | '*'
478-
//! type := identifier | '?' | ''
479-
//! count := parameter | integer
480-
//! parameter := argument '$'
481-
//! ```
482-
//!
483483
//! [`usize`]: ../../std/primitive.usize.html
484484
//! [`isize`]: ../../std/primitive.isize.html
485485
//! [`i8`]: ../../std/primitive.i8.html

0 commit comments

Comments
 (0)