1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
13 Utilities for formatting and printing strings
15 This module contains the runtime support for the `format!` syntax extension.
16 This macro is implemented in the compiler to emit calls to this module in order
17 to format arguments at runtime into strings and streams.
19 The functions contained in this module should not normally be used in everyday
20 use cases of `format!`. The assumptions made by these functions are unsafe for
21 all inputs, and the compiler performs a large amount of validation on the
22 arguments to `format!` in order to ensure safety at runtime. While it is
23 possible to call these functions directly, it is not recommended to do so in the
28 The `format!` macro is intended to be familiar to those coming from C's
29 printf/fprintf functions or Python's `str.format` function. In its current
30 revision, the `format!` macro returns a `~str` type which is the result of the
31 formatting. In the future it will also be able to pass in a stream to format
32 arguments directly while performing minimal allocations.
34 Some examples of the `format!` extension are:
37 format!("Hello"); // => ~"Hello"
38 format!("Hello, {:s}!", "world"); // => ~"Hello, world!"
39 format!("The number is {:d}", 1); // => ~"The number is 1"
40 format!("{:?}", ~[3, 4]); // => ~"~[3, 4]"
41 format!("{value}", value=4); // => ~"4"
42 format!("{} {}", 1, 2); // => ~"1 2"
45 From these, you can see that the first argument is a format string. It is
46 required by the compiler for this to be a string literal; it cannot be a
47 variable passed in (in order to perform validity checking). The compiler will
48 then parse the format string and determine if the list of arguments provided is
49 suitable to pass to this format string.
51 ### Positional parameters
53 Each formatting argument is allowed to specify which value argument it's
54 referencing, and if omitted it is assumed to be "the next argument". For
55 example, the format string `{} {} {}` would take three parameters, and they
56 would be formatted in the same order as they're given. The format string
57 `{2} {1} {0}`, however, would format arguments in reverse order.
59 Things can get a little tricky once you start intermingling the two types of
60 positional specifiers. The "next argument" specifier can be thought of as an
61 iterator over the argument. Each time a "next argument" specifier is seen, the
62 iterator advances. This leads to behavior like this:
65 format!("{1} {} {0} {}", 1, 2); // => ~"2 1 1 2"
68 The internal iterator over the argument has not been advanced by the time the
69 first `{}` is seen, so it prints the first argument. Then upon reaching the
70 second `{}`, the iterator has advanced forward to the second argument.
71 Essentially, parameters which explicitly name their argument do not affect
72 parameters which do not name an argument in terms of positional specifiers.
74 A format string is required to use all of its arguments, otherwise it is a
75 compile-time error. You may refer to the same argument more than once in the
76 format string, although it must always be referred to with the same type.
80 Rust itself does not have a Python-like equivalent of named parameters to a
81 function, but the `format!` macro is a syntax extension which allows it to
82 leverage named parameters. Named parameters are listed at the end of the
83 argument list and have the syntax:
86 identifier '=' expression
89 For example, the following `format!` expressions all use named argument:
92 format!("{argument}", argument = "test"); // => ~"test"
93 format!("{name} {}", 1, name = 2); // => ~"2 1"
94 format!("{a:s} {c:d} {b:?}", a="a", b=(), c=3); // => ~"a 3 ()"
97 It is illegal to put positional parameters (those without names) after arguments
98 which have names. Like positional parameters, it is illegal to provided named
99 parameters that are unused by the format string.
103 Each argument's type is dictated by the format string. It is a requirement that
104 every argument is only ever referred to by one type. When specifying the format
105 of an argument, however, a string like `{}` indicates no type. This is allowed,
106 and if all references to one argument do not provide a type, then the format `?`
107 is used (the type's rust-representation is printed). For example, this is an
108 invalid format string:
114 Because the first argument is both referred to as an integer as well as a
117 Because formatting is done via traits, there is no requirement that the
118 `d` format actually takes an `int`, but rather it simply requires a type which
119 ascribes to the `Signed` formatting trait. There are various parameters which do
120 require a particular type, however. Namely if the syntax `{:.*s}` is used, then
121 the number of characters to print from the string precedes the actual string and
122 must have the type `uint`. Although a `uint` can be printed with `{:u}`, it is
123 illegal to reference an argument as such. For example, this is another invalid
130 ### Formatting traits
132 When requesting that an argument be formatted with a particular type, you are
133 actually requesting that an argument ascribes to a particular trait. This allows
134 multiple actual types to be formatted via `{:d}` (like `i8` as well as `int`).
135 The current mapping of types to traits is:
154 What this means is that any type of argument which implements the
155 `std::fmt::Binary` trait can then be formatted with `{:t}`. Implementations are
156 provided for these traits for a number of primitive types by the standard
157 library as well. If no format is specified (as in `{}` or `{:6}`), then the
158 format trait used is the `Show` trait. This is one of the more commonly
159 implemented traits when formatting a custom type.
161 When implementing a format trait for your own type, you will have to implement a
162 method of the signature:
166 # mod fmt { pub type Result = (); }
168 # trait SomeName<T> {
169 fn fmt(&self, f: &mut std::fmt::Formatter) -> fmt::Result;
173 Your type will be passed as `self` by-reference, and then the function should
174 emit output into the `f.buf` stream. It is up to each format trait
175 implementation to correctly adhere to the requested formatting parameters. The
176 values of these parameters will be listed in the fields of the `Formatter`
177 struct. In order to help with this, the `Formatter` struct also provides some
180 Additionally, the return value of this function is `fmt::Result` which is a
181 typedef to `Result<(), IoError>` (also known as `IoError<()>`). Formatting
182 implementations should ensure that they return errors from `write!` correctly
183 (propagating errors upward).
185 An example of implementing the formatting traits would look
197 impl fmt::Show for Vector2D {
198 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
199 // The `f.buf` value is of the type `&mut io::Writer`, which is what the
200 // write! macro is expecting. Note that this formatting ignores the
201 // various flags provided to format strings.
202 write!(f.buf, "({}, {})", self.x, self.y)
206 // Different traits allow different forms of output of a type. The meaning of
207 // this format is to print the magnitude of a vector.
208 impl fmt::Binary for Vector2D {
209 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
210 let magnitude = (self.x * self.x + self.y * self.y) as f64;
211 let magnitude = magnitude.sqrt();
213 // Respect the formatting flags by using the helper method
214 // `pad_integral` on the Formatter object. See the method documentation
215 // for details, and the function `pad` can be used to pad strings.
216 let decimals = f.precision.unwrap_or(3);
217 let string = f64::to_str_exact(magnitude, decimals);
218 f.pad_integral(true, "", string.as_bytes())
223 let myvector = Vector2D { x: 3, y: 4 };
225 println!("{}", myvector); // => "(3, 4)"
226 println!("{:10.3t}", myvector); // => " 5.000"
232 There are a number of related macros in the `format!` family. The ones that are
233 currently implemented are:
236 format! // described above
237 write! // first argument is a &mut io::Writer, the destination
238 writeln! // same as write but appends a newline
239 print! // the format string is printed to the standard output
240 println! // same as print but appends a newline
241 format_args! // described below.
247 This and `writeln` are two macros which are used to emit the format string to a
248 specified stream. This is used to prevent intermediate allocations of format
249 strings and instead directly write the output. Under the hood, this function is
250 actually invoking the `write` function defined in this module. Example usage is:
253 # #![allow(unused_must_use)]
256 let mut w = io::MemWriter::new();
257 write!(&mut w as &mut io::Writer, "Hello {}!", "world");
262 This and `println` emit their output to stdout. Similarly to the `write!` macro,
263 the goal of these macros is to avoid intermediate allocations when printing
264 output. Example usage is:
267 print!("Hello {}!", "world");
268 println!("I have a newline {}", "character at the end");
272 This is a curious macro which is used to safely pass around
273 an opaque object describing the format string. This object
274 does not require any heap allocations to create, and it only
275 references information on the stack. Under the hood, all of
276 the related macros are implemented in terms of this. First
277 off, some example usage is:
283 # #[allow(unused_must_use)]
285 format_args!(fmt::format, "this returns {}", "~str");
287 let some_writer: &mut io::Writer = &mut io::stdout();
288 format_args!(|args| { fmt::write(some_writer, args) }, "print with a {}", "closure");
290 fn my_fmt_fn(args: &fmt::Arguments) {
291 fmt::write(&mut io::stdout(), args);
293 format_args!(my_fmt_fn, "or a {} too", "function");
297 The first argument of the `format_args!` macro is a function (or closure) which
298 takes one argument of type `&fmt::Arguments`. This structure can then be
299 passed to the `write` and `format` functions inside this module in order to
300 process the format string. The goal of this macro is to even further prevent
301 intermediate allocations when dealing formatting strings.
303 For example, a logging library could use the standard formatting syntax, but it
304 would internally pass around this structure until it has been determined where
307 It is unsafe to programmatically create an instance of `fmt::Arguments` because
308 the operations performed when executing a format string require the compile-time
309 checks provided by the compiler. The `format_args!` macro is the only method of
310 safely creating these structures, but they can be unsafely created with the
311 constructor provided.
313 ## Internationalization
315 The formatting syntax supported by the `format!` extension supports
316 internationalization by providing "methods" which execute various different
317 outputs depending on the input. The syntax and methods provided are similar to
318 other internationalization systems, so again nothing should seem alien.
319 Currently two methods are supported by this extension: "select" and "plural".
321 Each method will execute one of a number of clauses, and then the value of the
322 clause will become what's the result of the argument's format. Inside of the
323 cases, nested argument strings may be provided, but all formatting arguments
324 must not be done through implicit positional means. All arguments inside of each
325 case of a method must be explicitly selected by their name or their integer
328 Furthermore, whenever a case is running, the special character `#` can be used
329 to reference the string value of the argument which was selected upon. As an
333 format!("{0, select, other{#}}", "hello"); // => ~"hello"
336 This example is the equivalent of `{0:s}` essentially.
340 The select method is a switch over a `&str` parameter, and the parameter *must*
341 be of the type `&str`. An example of the syntax is:
344 {0, select, male{...} female{...} other{...}}
347 Breaking this down, the `0`-th argument is selected upon with the `select`
348 method, and then a number of cases follow. Each case is preceded by an
349 identifier which is the match-clause to execute the given arm. In this case,
350 there are two explicit cases, `male` and `female`. The case will be executed if
351 the string argument provided is an exact match to the case selected.
353 The `other` case is also a required case for all `select` methods. This arm will
354 be executed if none of the other arms matched the word being selected over.
358 The plural method is a switch statement over a `uint` parameter, and the
359 parameter *must* be a `uint`. A plural method in its full glory can be specified
363 {0, plural, offset=1 =1{...} two{...} many{...} other{...}}
366 To break this down, the first `0` indicates that this method is selecting over
367 the value of the first positional parameter to the format string. Next, the
368 `plural` method is being executed. An optionally-supplied `offset` is then given
369 which indicates a number to subtract from argument `0` when matching. This is
370 then followed by a list of cases.
372 Each case is allowed to supply a specific value to match upon with the syntax
373 `=N`. This case is executed if the value at argument `0` matches N exactly,
374 without taking the offset into account. A case may also be specified by one of
375 five keywords: `zero`, `one`, `two`, `few`, and `many`. These cases are matched
376 on after argument `0` has the offset taken into account. Currently the
377 definitions of `many` and `few` are hardcoded, but they are in theory defined by
380 Finally, all `plural` methods must have an `other` case supplied which will be
381 executed if none of the other cases match.
385 The syntax for the formatting language used is drawn from other languages, so it
386 should not be too alien. Arguments are formatted with python-like syntax,
387 meaning that arguments are surrounded by `{}` instead of the C-like `%`. The
388 actual grammar for the formatting syntax is:
391 format_string := <text> [ format <text> ] *
392 format := '{' [ argument ] [ ':' format_spec ] [ ',' function_spec ] '}'
393 argument := integer | identifier
395 format_spec := [[fill]align][sign]['#'][0][width]['.' precision][type]
400 precision := count | '*'
401 type := identifier | ''
402 count := parameter | integer
403 parameter := integer '$'
405 function_spec := plural | select
406 select := 'select' ',' ( identifier arm ) *
407 plural := 'plural' ',' [ 'offset:' integer ] ( selector arm ) *
408 selector := '=' integer | keyword
409 keyword := 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'
410 arm := '{' format_string '}'
413 ## Formatting Parameters
415 Each argument being formatted can be transformed by a number of formatting
416 parameters (corresponding to `format_spec` in the syntax above). These
417 parameters affect the string representation of what's being formatted. This
418 syntax draws heavily from Python's, so it may seem a bit familiar.
422 The fill character is provided normally in conjunction with the `width`
423 parameter. This indicates that if the value being formatted is smaller than
424 `width` some extra characters will be printed around it. The extra characters
425 are specified by `fill`, and the alignment can be one of two options:
427 * `<` - the argument is left-aligned in `width` columns
428 * `>` - the argument is right-aligned in `width` columns
432 These can all be interpreted as flags for a particular formatter.
434 * '+' - This is intended for numeric types and indicates that the sign should
435 always be printed. Positive signs are never printed by default, and the
436 negative sign is only printed by default for the `Signed` trait. This
437 flag indicates that the correct sign (+ or -) should always be printed.
438 * '-' - Currently not used
439 * '#' - This flag is indicates that the "alternate" form of printing should be
440 used. By default, this only applies to the integer formatting traits and
442 * `x` - precedes the argument with a "0x"
443 * `X` - precedes the argument with a "0x"
444 * `t` - precedes the argument with a "0b"
445 * `o` - precedes the argument with a "0o"
446 * '0' - This is used to indicate for integer formats that the padding should
447 both be done with a `0` character as well as be sign-aware. A format
448 like `{:08d}` would yield `00000001` for the integer `1`, while the same
449 format would yield `-0000001` for the integer `-1`. Notice that the
450 negative version has one fewer zero than the positive version.
454 This is a parameter for the "minimum width" that the format should take up. If
455 the value's string does not fill up this many characters, then the padding
456 specified by fill/alignment will be used to take up the required space.
458 The default fill/alignment for non-numerics is a space and left-aligned. The
459 defaults for numeric formatters is also a space but with right-alignment. If the
460 '0' flag is specified for numerics, then the implicit fill character is '0'.
462 The value for the width can also be provided as a `uint` in the list of
463 parameters by using the `2$` syntax indicating that the second argument is a
464 `uint` specifying the width.
468 For non-numeric types, this can be considered a "maximum width". If the
469 resulting string is longer than this width, then it is truncated down to this
470 many characters and only those are emitted.
472 For integral types, this has no meaning currently.
474 For floating-point types, this indicates how many digits after the decimal point
479 The literal characters `{`, `}`, or `#` may be included in a string by
480 preceding them with the `\` character. Since `\` is already an
481 escape character in Rust strings, a string literal using this escape
482 will look like `"\\{"`.
489 use container::Container;
492 use iter::{Iterator, range};
494 use option::{Option,Some,None};
496 use result::{Ok, Err};
499 use slice::{Vector, ImmutableVector};
502 pub use self::num::radix;
503 pub use self::num::Radix;
504 pub use self::num::RadixFmt;
510 pub type Result = io::IoResult<()>;
512 /// A struct to represent both where to emit formatting strings to and how they
513 /// should be formatted. A mutable version of this is passed to all formatting
515 pub struct Formatter<'a> {
516 /// Flags for formatting (packed version of rt::Flag)
518 /// Character used as 'fill' whenever there is alignment
520 /// Boolean indication of whether the output should be left-aligned
521 pub align: parse::Alignment,
522 /// Optionally specified integer width that the output should be
523 pub width: Option<uint>,
524 /// Optionally specified precision for numeric types
525 pub precision: Option<uint>,
528 pub buf: &'a mut io::Writer,
529 curarg: slice::Items<'a, Argument<'a>>,
530 args: &'a [Argument<'a>],
533 /// This struct represents the generic "argument" which is taken by the Xprintf
534 /// family of functions. It contains a function to format the given value. At
535 /// compile time it is ensured that the function and the value have the correct
536 /// types, and then this struct is used to canonicalize arguments to one type.
537 pub struct Argument<'a> {
538 formatter: extern "Rust" fn(&any::Void, &mut Formatter) -> Result,
539 value: &'a any::Void,
542 impl<'a> Arguments<'a> {
543 /// When using the format_args!() macro, this function is used to generate the
544 /// Arguments structure. The compiler inserts an `unsafe` block to call this,
545 /// which is valid because the compiler performs all necessary validation to
546 /// ensure that the resulting call to format/write would be safe.
547 #[doc(hidden)] #[inline]
548 pub unsafe fn new<'a>(fmt: &'static [rt::Piece<'static>],
549 args: &'a [Argument<'a>]) -> Arguments<'a> {
550 Arguments{ fmt: cast::transmute(fmt), args: args }
554 /// This structure represents a safely precompiled version of a format string
555 /// and its arguments. This cannot be generated at runtime because it cannot
556 /// safely be done so, so no constructors are given and the fields are private
557 /// to prevent modification.
559 /// The `format_args!` macro will safely create an instance of this structure
560 /// and pass it to a user-supplied function. The macro validates the format
561 /// string at compile-time so usage of the `write` and `format` functions can
562 /// be safely performed.
563 pub struct Arguments<'a> {
564 fmt: &'a [rt::Piece<'a>],
565 args: &'a [Argument<'a>],
568 /// When a format is not otherwise specified, types are formatted by ascribing
569 /// to this trait. There is not an explicit way of selecting this trait to be
570 /// used for formatting, it is only if no other format is specified.
572 /// Formats the value using the given formatter.
573 fn fmt(&self, &mut Formatter) -> Result;
576 /// Format trait for the `b` character
578 /// Formats the value using the given formatter.
579 fn fmt(&self, &mut Formatter) -> Result;
582 /// Format trait for the `c` character
584 /// Formats the value using the given formatter.
585 fn fmt(&self, &mut Formatter) -> Result;
588 /// Format trait for the `i` and `d` characters
590 /// Formats the value using the given formatter.
591 fn fmt(&self, &mut Formatter) -> Result;
594 /// Format trait for the `u` character
596 /// Formats the value using the given formatter.
597 fn fmt(&self, &mut Formatter) -> Result;
600 /// Format trait for the `o` character
602 /// Formats the value using the given formatter.
603 fn fmt(&self, &mut Formatter) -> Result;
606 /// Format trait for the `t` character
608 /// Formats the value using the given formatter.
609 fn fmt(&self, &mut Formatter) -> Result;
612 /// Format trait for the `x` character
614 /// Formats the value using the given formatter.
615 fn fmt(&self, &mut Formatter) -> Result;
618 /// Format trait for the `X` character
620 /// Formats the value using the given formatter.
621 fn fmt(&self, &mut Formatter) -> Result;
624 /// Format trait for the `s` character
626 /// Formats the value using the given formatter.
627 fn fmt(&self, &mut Formatter) -> Result;
630 /// Format trait for the `?` character
632 /// Formats the value using the given formatter.
633 fn fmt(&self, &mut Formatter) -> Result;
636 /// Format trait for the `p` character
638 /// Formats the value using the given formatter.
639 fn fmt(&self, &mut Formatter) -> Result;
642 /// Format trait for the `f` character
644 /// Formats the value using the given formatter.
645 fn fmt(&self, &mut Formatter) -> Result;
648 /// Format trait for the `e` character
650 /// Formats the value using the given formatter.
651 fn fmt(&self, &mut Formatter) -> Result;
654 /// Format trait for the `E` character
656 /// Formats the value using the given formatter.
657 fn fmt(&self, &mut Formatter) -> Result;
660 // FIXME #11938 - UFCS would make us able call the above methods
661 // directly Show::show(x, fmt).
662 macro_rules! uniform_fn_call_workaround {
663 ($( $name: ident, $trait_: ident; )*) => {
666 pub fn $name<T: $trait_>(x: &T, fmt: &mut Formatter) -> Result {
672 uniform_fn_call_workaround! {
676 secret_signed, Signed;
677 secret_unsigned, Unsigned;
679 secret_binary, Binary;
680 secret_lower_hex, LowerHex;
681 secret_upper_hex, UpperHex;
682 secret_string, String;
684 secret_pointer, Pointer;
686 secret_lower_exp, LowerExp;
687 secret_upper_exp, UpperExp;
690 /// The `write` function takes an output stream, a precompiled format string,
691 /// and a list of arguments. The arguments will be formatted according to the
692 /// specified format string into the output stream provided.
696 /// * output - the buffer to write output to
697 /// * args - the precompiled arguments generated by `format_args!`
702 /// # #![allow(unused_must_use)]
706 /// let mut w = io::stdout();
707 /// format_args!(|args| { fmt::write(&mut w, args); }, "Hello, {}!", "world");
709 pub fn write(output: &mut io::Writer, args: &Arguments) -> Result {
710 unsafe { write_unsafe(output, args.fmt, args.args) }
713 /// The `writeln` function takes the same arguments as `write`, except that it
714 /// will also write a newline (`\n`) character at the end of the format string.
715 pub fn writeln(output: &mut io::Writer, args: &Arguments) -> Result {
716 let first = unsafe { write_unsafe(output, args.fmt, args.args) };
717 first.and_then(|()| output.write(['\n' as u8]))
720 /// The `write_unsafe` function takes an output stream, a precompiled format
721 /// string, and a list of arguments. The arguments will be formatted according
722 /// to the specified format string into the output stream provided.
724 /// See the documentation for `format` for why this function is unsafe and care
725 /// should be taken if calling it manually.
727 /// Thankfully the rust compiler provides macros like `write!` and
728 /// `format_args!` which perform all of this validation at compile-time
729 /// and provide a safe interface for invoking this function.
733 /// * output - the buffer to write output to
734 /// * fmts - the precompiled format string to emit
735 /// * args - the list of arguments to the format string. These are only the
736 /// positional arguments (not named)
738 /// Note that this function assumes that there are enough arguments for the
740 pub unsafe fn write_unsafe(output: &mut io::Writer,
742 args: &[Argument]) -> Result {
743 let mut formatter = Formatter {
748 align: parse::AlignUnknown,
753 for piece in fmt.iter() {
754 try!(formatter.run(piece, None));
759 /// The format function takes a precompiled format string and a list of
760 /// arguments, to return the resulting formatted string.
764 /// * args - a structure of arguments generated via the `format_args!` macro.
765 /// Because this structure can only be safely generated at
766 /// compile-time, this function is safe.
773 /// let s = format_args!(fmt::format, "Hello, {}!", "world");
774 /// assert_eq!(s, ~"Hello, world!");
776 pub fn format(args: &Arguments) -> ~str {
777 unsafe { format_unsafe(args.fmt, args.args) }
780 /// The unsafe version of the formatting function.
782 /// This is currently an unsafe function because the types of all arguments
783 /// aren't verified by immediate callers of this function. This currently does
784 /// not validate that the correct types of arguments are specified for each
785 /// format specifier, nor that each argument itself contains the right function
786 /// for formatting the right type value. Because of this, the function is marked
787 /// as `unsafe` if this is being called manually.
789 /// Thankfully the rust compiler provides the macro `format!` which will perform
790 /// all of this validation at compile-time and provides a safe interface for
791 /// invoking this function.
795 /// * fmts - the precompiled format string to emit.
796 /// * args - the list of arguments to the format string. These are only the
797 /// positional arguments (not named)
799 /// Note that this function assumes that there are enough arguments for the
801 pub unsafe fn format_unsafe(fmt: &[rt::Piece], args: &[Argument]) -> ~str {
802 let mut output = MemWriter::new();
803 write_unsafe(&mut output as &mut io::Writer, fmt, args).unwrap();
804 return str::from_utf8(output.unwrap().as_slice()).unwrap().to_owned();
807 impl<'a> Formatter<'a> {
809 // First up is the collection of functions used to execute a format string
810 // at runtime. This consumes all of the compile-time statics generated by
811 // the format! syntax extension.
813 fn run(&mut self, piece: &rt::Piece, cur: Option<&str>) -> Result {
815 rt::String(s) => self.buf.write(s.as_bytes()),
816 rt::CurrentArgument(()) => self.buf.write(cur.unwrap().as_bytes()),
817 rt::Argument(ref arg) => {
818 // Fill in the format parameters into the formatter
819 self.fill = arg.format.fill;
820 self.align = arg.format.align;
821 self.flags = arg.format.flags;
822 self.width = self.getcount(&arg.format.width);
823 self.precision = self.getcount(&arg.format.precision);
825 // Extract the correct argument
826 let value = match arg.position {
827 rt::ArgumentNext => { *self.curarg.next().unwrap() }
828 rt::ArgumentIs(i) => self.args[i],
831 // Then actually do some printing
833 None => (value.formatter)(value.value, self),
834 Some(ref method) => self.execute(*method, value)
840 fn getcount(&mut self, cnt: &rt::Count) -> Option<uint> {
842 rt::CountIs(n) => { Some(n) }
843 rt::CountImplied => { None }
844 rt::CountIsParam(i) => {
845 let v = self.args[i].value;
846 unsafe { Some(*(v as *any::Void as *uint)) }
848 rt::CountIsNextParam => {
849 let v = self.curarg.next().unwrap().value;
850 unsafe { Some(*(v as *any::Void as *uint)) }
855 fn execute(&mut self, method: &rt::Method, arg: Argument) -> Result {
857 // Pluralization is selection upon a numeric value specified as the
859 rt::Plural(offset, ref selectors, ref default) => {
860 // This is validated at compile-time to be a pointer to a
862 let value: &uint = unsafe { cast::transmute(arg.value) };
865 // First, attempt to match against explicit values without the
867 for s in selectors.iter() {
869 rt::Literal(val) if value == val => {
870 return self.runplural(value, s.result);
876 // Next, offset the value and attempt to match against the
877 // keyword selectors.
878 let value = value - match offset { Some(i) => i, None => 0 };
879 for s in selectors.iter() {
880 let run = match s.selector {
881 rt::Keyword(parse::Zero) => value == 0,
882 rt::Keyword(parse::One) => value == 1,
883 rt::Keyword(parse::Two) => value == 2,
885 // FIXME: Few/Many should have a user-specified boundary
886 // One possible option would be in the function
887 // pointer of the 'arg: Argument' struct.
888 rt::Keyword(parse::Few) => value < 8,
889 rt::Keyword(parse::Many) => value >= 8,
891 rt::Literal(..) => false
894 return self.runplural(value, s.result);
898 self.runplural(value, *default)
901 // Select is just a matching against the string specified.
902 rt::Select(ref selectors, ref default) => {
903 // This is validated at compile-time to be a pointer to a
905 let value: & &str = unsafe { cast::transmute(arg.value) };
908 for s in selectors.iter() {
909 if s.selector == value {
910 for piece in s.result.iter() {
911 try!(self.run(piece, Some(value)));
916 for piece in default.iter() {
917 try!(self.run(piece, Some(value)));
924 fn runplural(&mut self, value: uint, pieces: &[rt::Piece]) -> Result {
925 ::uint::to_str_bytes(value, 10, |buf| {
926 let valuestr = str::from_utf8(buf).unwrap();
927 for piece in pieces.iter() {
928 try!(self.run(piece, Some(valuestr)));
934 // Helper methods used for padding and processing formatting arguments that
935 // all formatting traits can use.
937 /// Performs the correct padding for an integer which has already been
938 /// emitted into a byte-array. The byte-array should *not* contain the sign
939 /// for the integer, that will be added by this method.
943 /// * is_positive - whether the original integer was positive or not.
944 /// * prefix - if the '#' character (FlagAlternate) is provided, this
945 /// is the prefix to put in front of the number.
946 /// * buf - the byte array that the number has been formatted into
948 /// This function will correctly account for the flags provided as well as
949 /// the minimum width. It will not take precision into account.
950 pub fn pad_integral(&mut self, is_positive: bool, prefix: &str, buf: &[u8]) -> Result {
951 use fmt::parse::{FlagAlternate, FlagSignPlus, FlagSignAwareZeroPad};
953 let mut width = buf.len();
957 sign = Some('-'); width += 1;
958 } else if self.flags & (1 << (FlagSignPlus as uint)) != 0 {
959 sign = Some('+'); width += 1;
962 let mut prefixed = false;
963 if self.flags & (1 << (FlagAlternate as uint)) != 0 {
964 prefixed = true; width += prefix.len();
967 // Writes the sign if it exists, and then the prefix if it was requested
968 let write_prefix = |f: &mut Formatter| {
969 for c in sign.move_iter() { try!(f.buf.write_char(c)); }
970 if prefixed { f.buf.write_str(prefix) }
974 // The `width` field is more of a `min-width` parameter at this point.
976 // If there's no minimum length requirements then we can just
979 try!(write_prefix(self)); self.buf.write(buf)
981 // Check if we're over the minimum width, if so then we can also
982 // just write the bytes.
983 Some(min) if width >= min => {
984 try!(write_prefix(self)); self.buf.write(buf)
986 // The sign and prefix goes before the padding if the fill character
988 Some(min) if self.flags & (1 << (FlagSignAwareZeroPad as uint)) != 0 => {
990 try!(write_prefix(self));
991 self.with_padding(min - width, parse::AlignRight, |f| f.buf.write(buf))
993 // Otherwise, the sign and prefix goes after the padding
995 self.with_padding(min - width, parse::AlignRight, |f| {
996 try!(write_prefix(f)); f.buf.write(buf)
1002 /// This function takes a string slice and emits it to the internal buffer
1003 /// after applying the relevant formatting flags specified. The flags
1004 /// recognized for generic strings are:
1006 /// * width - the minimum width of what to emit
1007 /// * fill/align - what to emit and where to emit it if the string
1008 /// provided needs to be padded
1009 /// * precision - the maximum length to emit, the string is truncated if it
1010 /// is longer than this length
1012 /// Notably this function ignored the `flag` parameters
1013 pub fn pad(&mut self, s: &str) -> Result {
1014 // Make sure there's a fast path up front
1015 if self.width.is_none() && self.precision.is_none() {
1016 return self.buf.write(s.as_bytes());
1018 // The `precision` field can be interpreted as a `max-width` for the
1019 // string being formatted
1020 match self.precision {
1022 // If there's a maximum width and our string is longer than
1023 // that, then we must always have truncation. This is the only
1024 // case where the maximum length will matter.
1025 let char_len = s.char_len();
1026 if char_len >= max {
1027 let nchars = ::cmp::min(max, char_len);
1028 return self.buf.write(s.slice_chars(0, nchars).as_bytes());
1033 // The `width` field is more of a `min-width` parameter at this point.
1035 // If we're under the maximum length, and there's no minimum length
1036 // requirements, then we can just emit the string
1037 None => self.buf.write(s.as_bytes()),
1038 // If we're under the maximum width, check if we're over the minimum
1039 // width, if so it's as easy as just emitting the string.
1040 Some(width) if s.char_len() >= width => {
1041 self.buf.write(s.as_bytes())
1043 // If we're under both the maximum and the minimum width, then fill
1044 // up the minimum width with the specified string + some alignment.
1046 self.with_padding(width - s.len(), parse::AlignLeft, |me| {
1047 me.buf.write(s.as_bytes())
1053 /// Runs a callback, emitting the correct padding either before or
1054 /// afterwards depending on whether right or left alingment is requested.
1055 fn with_padding(&mut self,
1057 default: parse::Alignment,
1058 f: |&mut Formatter| -> Result) -> Result {
1059 let align = match self.align {
1060 parse::AlignUnknown => default,
1061 parse::AlignLeft | parse::AlignRight => self.align
1063 if align == parse::AlignLeft {
1066 let mut fill = [0u8, ..4];
1067 let len = self.fill.encode_utf8(fill);
1068 for _ in range(0, padding) {
1069 try!(self.buf.write(fill.slice_to(len)));
1071 if align == parse::AlignRight {
1078 /// This is a function which calls are emitted to by the compiler itself to
1079 /// create the Argument structures that are passed into the `format` function.
1080 #[doc(hidden)] #[inline]
1081 pub fn argument<'a, T>(f: extern "Rust" fn(&T, &mut Formatter) -> Result,
1082 t: &'a T) -> Argument<'a> {
1085 formatter: cast::transmute(f),
1086 value: cast::transmute(t)
1091 /// When the compiler determines that the type of an argument *must* be a string
1092 /// (such as for select), then it invokes this method.
1093 #[doc(hidden)] #[inline]
1094 pub fn argumentstr<'a>(s: &'a &str) -> Argument<'a> {
1095 argument(secret_string, s)
1098 /// When the compiler determines that the type of an argument *must* be a uint
1099 /// (such as for plural), then it invokes this method.
1100 #[doc(hidden)] #[inline]
1101 pub fn argumentuint<'a>(s: &'a uint) -> Argument<'a> {
1102 argument(secret_unsigned, s)
1105 // Implementations of the core formatting traits
1107 impl<T: Show> Show for @T {
1108 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(&**self, f) }
1110 impl<T: Show> Show for ~T {
1111 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(&**self, f) }
1113 impl<'a, T: Show> Show for &'a T {
1114 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(*self, f) }
1117 impl Bool for bool {
1118 fn fmt(&self, f: &mut Formatter) -> Result {
1119 secret_string(&(if *self {"true"} else {"false"}), f)
1123 impl<'a, T: str::Str> String for T {
1124 fn fmt(&self, f: &mut Formatter) -> Result {
1125 f.pad(self.as_slice())
1129 impl Char for char {
1130 fn fmt(&self, f: &mut Formatter) -> Result {
1131 let mut utf8 = [0u8, ..4];
1132 let amt = self.encode_utf8(utf8);
1133 let s: &str = unsafe { cast::transmute(utf8.slice_to(amt)) };
1134 secret_string(&s, f)
1138 macro_rules! floating(($ty:ident) => {
1139 impl Float for $ty {
1140 fn fmt(&self, fmt: &mut Formatter) -> Result {
1141 // FIXME: this shouldn't perform an allocation
1142 let s = match fmt.precision {
1143 Some(i) => ::$ty::to_str_exact(self.abs(), i),
1144 None => ::$ty::to_str_digits(self.abs(), 6)
1146 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1150 impl LowerExp for $ty {
1151 fn fmt(&self, fmt: &mut Formatter) -> Result {
1152 // FIXME: this shouldn't perform an allocation
1153 let s = match fmt.precision {
1154 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, false),
1155 None => ::$ty::to_str_exp_digits(self.abs(), 6, false)
1157 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1161 impl UpperExp for $ty {
1162 fn fmt(&self, fmt: &mut Formatter) -> Result {
1163 // FIXME: this shouldn't perform an allocation
1164 let s = match fmt.precision {
1165 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, true),
1166 None => ::$ty::to_str_exp_digits(self.abs(), 6, true)
1168 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1175 impl<T> Poly for T {
1176 fn fmt(&self, f: &mut Formatter) -> Result {
1177 match (f.width, f.precision) {
1179 repr::write_repr(f.buf, self)
1182 // If we have a specified width for formatting, then we have to make
1183 // this allocation of a new string
1185 let s = repr::repr_to_str(self);
1192 impl<T> Pointer for *T {
1193 fn fmt(&self, f: &mut Formatter) -> Result {
1194 f.flags |= 1 << (parse::FlagAlternate as uint);
1195 secret_lower_hex::<uint>(&(*self as uint), f)
1198 impl<T> Pointer for *mut T {
1199 fn fmt(&self, f: &mut Formatter) -> Result {
1200 secret_pointer::<*T>(&(*self as *T), f)
1203 impl<'a, T> Pointer for &'a T {
1204 fn fmt(&self, f: &mut Formatter) -> Result {
1205 secret_pointer::<*T>(&(&**self as *T), f)
1208 impl<'a, T> Pointer for &'a mut T {
1209 fn fmt(&self, f: &mut Formatter) -> Result {
1210 secret_pointer::<*T>(&(&**self as *T), f)
1214 // Implementation of Show for various core types
1216 macro_rules! delegate(($ty:ty to $other:ident) => {
1217 impl<'a> Show for $ty {
1218 fn fmt(&self, f: &mut Formatter) -> Result {
1219 (concat_idents!(secret_, $other)(self, f))
1223 delegate!(~str to string)
1224 delegate!(&'a str to string)
1225 delegate!(bool to bool)
1226 delegate!(char to char)
1227 delegate!(f32 to float)
1228 delegate!(f64 to float)
1230 impl<T> Show for *T {
1231 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1233 impl<T> Show for *mut T {
1234 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1237 // If you expected tests to be here, look instead at the run-pass/ifmt.rs test,
1238 // it's a lot easier than creating all of the rt::Piece structures here.