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".to_owned()
38 format!("Hello, {:s}!", "world"); // => "Hello, world!".to_owned()
39 format!("The number is {:d}", 1); // => "The number is 1".to_owned()
40 format!("{:?}", ~[3, 4]); // => "~[3, 4]".to_owned()
41 format!("{value}", value=4); // => "4".to_owned()
42 format!("{} {}", 1, 2); // => "1 2".to_owned()
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".to_owned()
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".to_owned()
93 format!("{name} {}", 1, name = 2); // => "2 1".to_owned()
94 format!("{a:s} {c:d} {b:?}", a="a", b=(), c=3); // => "a 3 ()".to_owned()
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".to_owned()
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 `"\\{"`.
490 use container::Container;
491 use intrinsics::TypeId;
494 use iter::{Iterator, range};
499 use option::{Option, Some, None};
502 use result::{Ok, Err, ResultUnwrap};
503 use slice::{Vector, ImmutableVector};
505 use str::{StrSlice, StrAllocating, UTF16Item, ScalarValue, LoneSurrogate};
509 pub use self::num::radix;
510 pub use self::num::Radix;
511 pub use self::num::RadixFmt;
516 pub type Result = io::IoResult<()>;
518 /// A struct to represent both where to emit formatting strings to and how they
519 /// should be formatted. A mutable version of this is passed to all formatting
521 pub struct Formatter<'a> {
522 /// Flags for formatting (packed version of rt::Flag)
524 /// Character used as 'fill' whenever there is alignment
526 /// Boolean indication of whether the output should be left-aligned
527 pub align: rt::Alignment,
528 /// Optionally specified integer width that the output should be
529 pub width: Option<uint>,
530 /// Optionally specified precision for numeric types
531 pub precision: Option<uint>,
534 pub buf: &'a mut io::Writer,
535 curarg: slice::Items<'a, Argument<'a>>,
536 args: &'a [Argument<'a>],
539 /// This struct represents the generic "argument" which is taken by the Xprintf
540 /// family of functions. It contains a function to format the given value. At
541 /// compile time it is ensured that the function and the value have the correct
542 /// types, and then this struct is used to canonicalize arguments to one type.
543 pub struct Argument<'a> {
544 formatter: extern "Rust" fn(&any::Void, &mut Formatter) -> Result,
545 value: &'a any::Void,
548 impl<'a> Arguments<'a> {
549 /// When using the format_args!() macro, this function is used to generate the
550 /// Arguments structure. The compiler inserts an `unsafe` block to call this,
551 /// which is valid because the compiler performs all necessary validation to
552 /// ensure that the resulting call to format/write would be safe.
553 #[doc(hidden)] #[inline]
554 pub unsafe fn new<'a>(fmt: &'static [rt::Piece<'static>],
555 args: &'a [Argument<'a>]) -> Arguments<'a> {
556 Arguments{ fmt: mem::transmute(fmt), args: args }
560 /// This structure represents a safely precompiled version of a format string
561 /// and its arguments. This cannot be generated at runtime because it cannot
562 /// safely be done so, so no constructors are given and the fields are private
563 /// to prevent modification.
565 /// The `format_args!` macro will safely create an instance of this structure
566 /// and pass it to a user-supplied function. The macro validates the format
567 /// string at compile-time so usage of the `write` and `format` functions can
568 /// be safely performed.
569 pub struct Arguments<'a> {
570 fmt: &'a [rt::Piece<'a>],
571 args: &'a [Argument<'a>],
574 impl<'a> Show for Arguments<'a> {
575 fn fmt(&self, fmt: &mut Formatter) -> Result {
580 /// When a format is not otherwise specified, types are formatted by ascribing
581 /// to this trait. There is not an explicit way of selecting this trait to be
582 /// used for formatting, it is only if no other format is specified.
584 /// Formats the value using the given formatter.
585 fn fmt(&self, &mut Formatter) -> Result;
588 /// Format trait for the `b` character
590 /// Formats the value using the given formatter.
591 fn fmt(&self, &mut Formatter) -> Result;
594 /// Format trait for the `c` character
596 /// Formats the value using the given formatter.
597 fn fmt(&self, &mut Formatter) -> Result;
600 /// Format trait for the `i` and `d` characters
602 /// Formats the value using the given formatter.
603 fn fmt(&self, &mut Formatter) -> Result;
606 /// Format trait for the `u` character
608 /// Formats the value using the given formatter.
609 fn fmt(&self, &mut Formatter) -> Result;
612 /// Format trait for the `o` character
614 /// Formats the value using the given formatter.
615 fn fmt(&self, &mut Formatter) -> Result;
618 /// Format trait for the `t` character
620 /// Formats the value using the given formatter.
621 fn fmt(&self, &mut Formatter) -> Result;
624 /// Format trait for the `x` character
626 /// Formats the value using the given formatter.
627 fn fmt(&self, &mut Formatter) -> Result;
630 /// Format trait for the `X` character
632 /// Formats the value using the given formatter.
633 fn fmt(&self, &mut Formatter) -> Result;
636 /// Format trait for the `s` character
638 /// Formats the value using the given formatter.
639 fn fmt(&self, &mut Formatter) -> Result;
642 /// Format trait for the `?` character
644 /// Formats the value using the given formatter.
645 fn fmt(&self, &mut Formatter) -> Result;
648 /// Format trait for the `p` character
650 /// Formats the value using the given formatter.
651 fn fmt(&self, &mut Formatter) -> Result;
654 /// Format trait for the `f` character
656 /// Formats the value using the given formatter.
657 fn fmt(&self, &mut Formatter) -> Result;
660 /// Format trait for the `e` character
662 /// Formats the value using the given formatter.
663 fn fmt(&self, &mut Formatter) -> Result;
666 /// Format trait for the `E` character
668 /// Formats the value using the given formatter.
669 fn fmt(&self, &mut Formatter) -> Result;
672 // FIXME #11938 - UFCS would make us able call the above methods
673 // directly Show::show(x, fmt).
674 macro_rules! uniform_fn_call_workaround {
675 ($( $name: ident, $trait_: ident; )*) => {
678 pub fn $name<T: $trait_>(x: &T, fmt: &mut Formatter) -> Result {
684 uniform_fn_call_workaround! {
688 secret_signed, Signed;
689 secret_unsigned, Unsigned;
691 secret_binary, Binary;
692 secret_lower_hex, LowerHex;
693 secret_upper_hex, UpperHex;
694 secret_string, String;
696 secret_pointer, Pointer;
698 secret_lower_exp, LowerExp;
699 secret_upper_exp, UpperExp;
702 /// The `write` function takes an output stream, a precompiled format string,
703 /// and a list of arguments. The arguments will be formatted according to the
704 /// specified format string into the output stream provided.
708 /// * output - the buffer to write output to
709 /// * args - the precompiled arguments generated by `format_args!`
714 /// # #![allow(unused_must_use)]
718 /// let mut w = io::stdout();
719 /// format_args!(|args| { fmt::write(&mut w, args); }, "Hello, {}!", "world");
721 pub fn write(output: &mut io::Writer, args: &Arguments) -> Result {
722 unsafe { write_unsafe(output, args.fmt, args.args) }
725 /// The `writeln` function takes the same arguments as `write`, except that it
726 /// will also write a newline (`\n`) character at the end of the format string.
727 pub fn writeln(output: &mut io::Writer, args: &Arguments) -> Result {
728 let first = unsafe { write_unsafe(output, args.fmt, args.args) };
729 first.and_then(|()| output.write(['\n' as u8]))
732 /// The `write_unsafe` function takes an output stream, a precompiled format
733 /// string, and a list of arguments. The arguments will be formatted according
734 /// to the specified format string into the output stream provided.
736 /// See the documentation for `format` for why this function is unsafe and care
737 /// should be taken if calling it manually.
739 /// Thankfully the rust compiler provides macros like `write!` and
740 /// `format_args!` which perform all of this validation at compile-time
741 /// and provide a safe interface for invoking this function.
745 /// * output - the buffer to write output to
746 /// * fmts - the precompiled format string to emit
747 /// * args - the list of arguments to the format string. These are only the
748 /// positional arguments (not named)
750 /// Note that this function assumes that there are enough arguments for the
752 pub unsafe fn write_unsafe(output: &mut io::Writer,
754 args: &[Argument]) -> Result {
755 let mut formatter = Formatter {
760 align: rt::AlignUnknown,
765 for piece in fmt.iter() {
766 try!(formatter.run(piece, None));
771 /// The format function takes a precompiled format string and a list of
772 /// arguments, to return the resulting formatted string.
776 /// * args - a structure of arguments generated via the `format_args!` macro.
777 /// Because this structure can only be safely generated at
778 /// compile-time, this function is safe.
785 /// let s = format_args!(fmt::format, "Hello, {}!", "world");
786 /// assert_eq!(s, "Hello, world!".to_owned());
788 pub fn format(args: &Arguments) -> ~str {
789 unsafe { format_unsafe(args.fmt, args.args) }
792 /// Temporary transitionary thing.
793 pub fn format_strbuf(args: &Arguments) -> StrBuf {
794 unsafe { format_unsafe_strbuf(args.fmt, args.args) }
797 /// The unsafe version of the formatting function.
799 /// This is currently an unsafe function because the types of all arguments
800 /// aren't verified by immediate callers of this function. This currently does
801 /// not validate that the correct types of arguments are specified for each
802 /// format specifier, nor that each argument itself contains the right function
803 /// for formatting the right type value. Because of this, the function is marked
804 /// as `unsafe` if this is being called manually.
806 /// Thankfully the rust compiler provides the macro `format!` which will perform
807 /// all of this validation at compile-time and provides a safe interface for
808 /// invoking this function.
812 /// * fmts - the precompiled format string to emit.
813 /// * args - the list of arguments to the format string. These are only the
814 /// positional arguments (not named)
816 /// Note that this function assumes that there are enough arguments for the
818 pub unsafe fn format_unsafe(fmt: &[rt::Piece], args: &[Argument]) -> ~str {
819 let mut output = MemWriter::new();
820 write_unsafe(&mut output as &mut io::Writer, fmt, args).unwrap();
821 return str::from_utf8(output.unwrap().as_slice()).unwrap().to_owned();
824 /// Temporary transitionary thing.
825 pub unsafe fn format_unsafe_strbuf(fmt: &[rt::Piece], args: &[Argument])
827 let mut output = MemWriter::new();
828 write_unsafe(&mut output as &mut io::Writer, fmt, args).unwrap();
829 return str::from_utf8(output.unwrap().as_slice()).unwrap().into_strbuf();
832 impl<'a> Formatter<'a> {
834 // First up is the collection of functions used to execute a format string
835 // at runtime. This consumes all of the compile-time statics generated by
836 // the format! syntax extension.
838 fn run(&mut self, piece: &rt::Piece, cur: Option<&str>) -> Result {
840 rt::String(s) => self.buf.write(s.as_bytes()),
841 rt::CurrentArgument(()) => self.buf.write(cur.unwrap().as_bytes()),
842 rt::Argument(ref arg) => {
843 // Fill in the format parameters into the formatter
844 self.fill = arg.format.fill;
845 self.align = arg.format.align;
846 self.flags = arg.format.flags;
847 self.width = self.getcount(&arg.format.width);
848 self.precision = self.getcount(&arg.format.precision);
850 // Extract the correct argument
851 let value = match arg.position {
852 rt::ArgumentNext => { *self.curarg.next().unwrap() }
853 rt::ArgumentIs(i) => self.args[i],
856 // Then actually do some printing
858 None => (value.formatter)(value.value, self),
859 Some(ref method) => self.execute(*method, value)
865 fn getcount(&mut self, cnt: &rt::Count) -> Option<uint> {
867 rt::CountIs(n) => { Some(n) }
868 rt::CountImplied => { None }
869 rt::CountIsParam(i) => {
870 let v = self.args[i].value;
871 unsafe { Some(*(v as *any::Void as *uint)) }
873 rt::CountIsNextParam => {
874 let v = self.curarg.next().unwrap().value;
875 unsafe { Some(*(v as *any::Void as *uint)) }
880 fn execute(&mut self, method: &rt::Method, arg: Argument) -> Result {
882 // Pluralization is selection upon a numeric value specified as the
884 rt::Plural(offset, ref selectors, ref default) => {
885 // This is validated at compile-time to be a pointer to a
887 let value: &uint = unsafe { mem::transmute(arg.value) };
890 // First, attempt to match against explicit values without the
892 for s in selectors.iter() {
894 rt::Literal(val) if value == val => {
895 return self.runplural(value, s.result);
901 // Next, offset the value and attempt to match against the
902 // keyword selectors.
903 let value = value - match offset { Some(i) => i, None => 0 };
904 for s in selectors.iter() {
905 let run = match s.selector {
906 rt::Keyword(rt::Zero) => value == 0,
907 rt::Keyword(rt::One) => value == 1,
908 rt::Keyword(rt::Two) => value == 2,
910 // FIXME: Few/Many should have a user-specified boundary
911 // One possible option would be in the function
912 // pointer of the 'arg: Argument' struct.
913 rt::Keyword(rt::Few) => value < 8,
914 rt::Keyword(rt::Many) => value >= 8,
916 rt::Literal(..) => false
919 return self.runplural(value, s.result);
923 self.runplural(value, *default)
926 // Select is just a matching against the string specified.
927 rt::Select(ref selectors, ref default) => {
928 // This is validated at compile-time to be a pointer to a
930 let value: & &str = unsafe { mem::transmute(arg.value) };
933 for s in selectors.iter() {
934 if s.selector == value {
935 for piece in s.result.iter() {
936 try!(self.run(piece, Some(value)));
941 for piece in default.iter() {
942 try!(self.run(piece, Some(value)));
949 fn runplural(&mut self, value: uint, pieces: &[rt::Piece]) -> Result {
950 ::uint::to_str_bytes(value, 10, |buf| {
951 let valuestr = str::from_utf8(buf).unwrap();
952 for piece in pieces.iter() {
953 try!(self.run(piece, Some(valuestr)));
959 // Helper methods used for padding and processing formatting arguments that
960 // all formatting traits can use.
962 /// Performs the correct padding for an integer which has already been
963 /// emitted into a byte-array. The byte-array should *not* contain the sign
964 /// for the integer, that will be added by this method.
968 /// * is_positive - whether the original integer was positive or not.
969 /// * prefix - if the '#' character (FlagAlternate) is provided, this
970 /// is the prefix to put in front of the number.
971 /// * buf - the byte array that the number has been formatted into
973 /// This function will correctly account for the flags provided as well as
974 /// the minimum width. It will not take precision into account.
975 pub fn pad_integral(&mut self, is_positive: bool, prefix: &str, buf: &[u8]) -> Result {
976 use fmt::rt::{FlagAlternate, FlagSignPlus, FlagSignAwareZeroPad};
978 let mut width = buf.len();
982 sign = Some('-'); width += 1;
983 } else if self.flags & (1 << (FlagSignPlus as uint)) != 0 {
984 sign = Some('+'); width += 1;
987 let mut prefixed = false;
988 if self.flags & (1 << (FlagAlternate as uint)) != 0 {
989 prefixed = true; width += prefix.len();
992 // Writes the sign if it exists, and then the prefix if it was requested
993 let write_prefix = |f: &mut Formatter| {
994 for c in sign.move_iter() { try!(f.buf.write_char(c)); }
995 if prefixed { f.buf.write_str(prefix) }
999 // The `width` field is more of a `min-width` parameter at this point.
1001 // If there's no minimum length requirements then we can just
1004 try!(write_prefix(self)); self.buf.write(buf)
1006 // Check if we're over the minimum width, if so then we can also
1007 // just write the bytes.
1008 Some(min) if width >= min => {
1009 try!(write_prefix(self)); self.buf.write(buf)
1011 // The sign and prefix goes before the padding if the fill character
1013 Some(min) if self.flags & (1 << (FlagSignAwareZeroPad as uint)) != 0 => {
1015 try!(write_prefix(self));
1016 self.with_padding(min - width, rt::AlignRight, |f| f.buf.write(buf))
1018 // Otherwise, the sign and prefix goes after the padding
1020 self.with_padding(min - width, rt::AlignRight, |f| {
1021 try!(write_prefix(f)); f.buf.write(buf)
1027 /// This function takes a string slice and emits it to the internal buffer
1028 /// after applying the relevant formatting flags specified. The flags
1029 /// recognized for generic strings are:
1031 /// * width - the minimum width of what to emit
1032 /// * fill/align - what to emit and where to emit it if the string
1033 /// provided needs to be padded
1034 /// * precision - the maximum length to emit, the string is truncated if it
1035 /// is longer than this length
1037 /// Notably this function ignored the `flag` parameters
1038 pub fn pad(&mut self, s: &str) -> Result {
1039 // Make sure there's a fast path up front
1040 if self.width.is_none() && self.precision.is_none() {
1041 return self.buf.write(s.as_bytes());
1043 // The `precision` field can be interpreted as a `max-width` for the
1044 // string being formatted
1045 match self.precision {
1047 // If there's a maximum width and our string is longer than
1048 // that, then we must always have truncation. This is the only
1049 // case where the maximum length will matter.
1050 let char_len = s.char_len();
1051 if char_len >= max {
1052 let nchars = ::cmp::min(max, char_len);
1053 return self.buf.write(s.slice_chars(0, nchars).as_bytes());
1058 // The `width` field is more of a `min-width` parameter at this point.
1060 // If we're under the maximum length, and there's no minimum length
1061 // requirements, then we can just emit the string
1062 None => self.buf.write(s.as_bytes()),
1063 // If we're under the maximum width, check if we're over the minimum
1064 // width, if so it's as easy as just emitting the string.
1065 Some(width) if s.char_len() >= width => {
1066 self.buf.write(s.as_bytes())
1068 // If we're under both the maximum and the minimum width, then fill
1069 // up the minimum width with the specified string + some alignment.
1071 self.with_padding(width - s.len(), rt::AlignLeft, |me| {
1072 me.buf.write(s.as_bytes())
1078 /// Runs a callback, emitting the correct padding either before or
1079 /// afterwards depending on whether right or left alingment is requested.
1080 fn with_padding(&mut self,
1082 default: rt::Alignment,
1083 f: |&mut Formatter| -> Result) -> Result {
1084 let align = match self.align {
1085 rt::AlignUnknown => default,
1086 rt::AlignLeft | rt::AlignRight => self.align
1088 if align == rt::AlignLeft {
1091 let mut fill = [0u8, ..4];
1092 let len = self.fill.encode_utf8(fill);
1093 for _ in range(0, padding) {
1094 try!(self.buf.write(fill.slice_to(len)));
1096 if align == rt::AlignRight {
1103 /// This is a function which calls are emitted to by the compiler itself to
1104 /// create the Argument structures that are passed into the `format` function.
1105 #[doc(hidden)] #[inline]
1106 pub fn argument<'a, T>(f: extern "Rust" fn(&T, &mut Formatter) -> Result,
1107 t: &'a T) -> Argument<'a> {
1110 formatter: mem::transmute(f),
1111 value: mem::transmute(t)
1116 /// When the compiler determines that the type of an argument *must* be a string
1117 /// (such as for select), then it invokes this method.
1118 #[doc(hidden)] #[inline]
1119 pub fn argumentstr<'a>(s: &'a &str) -> Argument<'a> {
1120 argument(secret_string, s)
1123 /// When the compiler determines that the type of an argument *must* be a uint
1124 /// (such as for plural), then it invokes this method.
1125 #[doc(hidden)] #[inline]
1126 pub fn argumentuint<'a>(s: &'a uint) -> Argument<'a> {
1127 argument(secret_unsigned, s)
1130 // Implementations of the core formatting traits
1132 impl<T: Show> Show for @T {
1133 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(&**self, f) }
1135 impl<T: Show> Show for Box<T> {
1136 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(&**self, f) }
1138 impl<'a, T: Show> Show for &'a T {
1139 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(*self, f) }
1141 impl<'a, T: Show> Show for &'a mut T {
1142 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(*self, f) }
1145 impl Bool for bool {
1146 fn fmt(&self, f: &mut Formatter) -> Result {
1147 secret_string(&(if *self {"true"} else {"false"}), f)
1151 impl<'a, T: str::Str> String for T {
1152 fn fmt(&self, f: &mut Formatter) -> Result {
1153 f.pad(self.as_slice())
1157 impl Char for char {
1158 fn fmt(&self, f: &mut Formatter) -> Result {
1159 let mut utf8 = [0u8, ..4];
1160 let amt = self.encode_utf8(utf8);
1161 let s: &str = unsafe { mem::transmute(utf8.slice_to(amt)) };
1162 secret_string(&s, f)
1166 macro_rules! floating(($ty:ident) => {
1167 impl Float for $ty {
1168 fn fmt(&self, fmt: &mut Formatter) -> Result {
1169 // FIXME: this shouldn't perform an allocation
1170 let s = match fmt.precision {
1171 Some(i) => ::$ty::to_str_exact(self.abs(), i),
1172 None => ::$ty::to_str_digits(self.abs(), 6)
1174 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1178 impl LowerExp for $ty {
1179 fn fmt(&self, fmt: &mut Formatter) -> Result {
1180 // FIXME: this shouldn't perform an allocation
1181 let s = match fmt.precision {
1182 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, false),
1183 None => ::$ty::to_str_exp_digits(self.abs(), 6, false)
1185 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1189 impl UpperExp for $ty {
1190 fn fmt(&self, fmt: &mut Formatter) -> Result {
1191 // FIXME: this shouldn't perform an allocation
1192 let s = match fmt.precision {
1193 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, true),
1194 None => ::$ty::to_str_exp_digits(self.abs(), 6, true)
1196 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1203 impl<T> Poly for T {
1204 fn fmt(&self, f: &mut Formatter) -> Result {
1205 match (f.width, f.precision) {
1207 repr::write_repr(f.buf, self)
1210 // If we have a specified width for formatting, then we have to make
1211 // this allocation of a new string
1213 let s = repr::repr_to_str(self);
1220 impl<T> Pointer for *T {
1221 fn fmt(&self, f: &mut Formatter) -> Result {
1222 f.flags |= 1 << (rt::FlagAlternate as uint);
1223 secret_lower_hex::<uint>(&(*self as uint), f)
1226 impl<T> Pointer for *mut T {
1227 fn fmt(&self, f: &mut Formatter) -> Result {
1228 secret_pointer::<*T>(&(*self as *T), f)
1231 impl<'a, T> Pointer for &'a T {
1232 fn fmt(&self, f: &mut Formatter) -> Result {
1233 secret_pointer::<*T>(&(&**self as *T), f)
1236 impl<'a, T> Pointer for &'a mut T {
1237 fn fmt(&self, f: &mut Formatter) -> Result {
1238 secret_pointer::<*T>(&(&**self as *T), f)
1242 // Implementation of Show for various core types
1244 macro_rules! delegate(($ty:ty to $other:ident) => {
1245 impl<'a> Show for $ty {
1246 fn fmt(&self, f: &mut Formatter) -> Result {
1247 (concat_idents!(secret_, $other)(self, f))
1251 delegate!(~str to string)
1252 delegate!(&'a str to string)
1253 delegate!(bool to bool)
1254 delegate!(char to char)
1255 delegate!(f32 to float)
1256 delegate!(f64 to float)
1258 impl<T> Show for *T {
1259 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1261 impl<T> Show for *mut T {
1262 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1265 macro_rules! peel(($name:ident, $($other:ident,)*) => (tuple!($($other,)*)))
1267 macro_rules! tuple (
1269 ( $($name:ident,)+ ) => (
1270 impl<$($name:Show),*> Show for ($($name,)*) {
1271 #[allow(uppercase_variables, dead_assignment)]
1272 fn fmt(&self, f: &mut Formatter) -> Result {
1273 try!(write!(f.buf, "("));
1274 let ($(ref $name,)*) = *self;
1278 try!(write!(f.buf, ", "));
1280 try!(write!(f.buf, "{}", *$name));
1284 try!(write!(f.buf, ","));
1293 tuple! { T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, }
1295 impl Show for Box<any::Any> {
1296 fn fmt(&self, f: &mut Formatter) -> Result { f.pad("Box<Any>") }
1299 impl<'a> Show for &'a any::Any {
1300 fn fmt(&self, f: &mut Formatter) -> Result { f.pad("&Any") }
1303 impl<T: Show> Show for Option<T> {
1304 fn fmt(&self, f: &mut Formatter) -> Result {
1306 Some(ref t) => write!(f.buf, "Some({})", *t),
1307 None => write!(f.buf, "None"),
1312 impl<T: Show, U: Show> Show for ::result::Result<T, U> {
1313 fn fmt(&self, f: &mut Formatter) -> Result {
1315 Ok(ref t) => write!(f.buf, "Ok({})", *t),
1316 Err(ref t) => write!(f.buf, "Err({})", *t),
1321 impl<'a, T: Show> Show for &'a [T] {
1322 fn fmt(&self, f: &mut Formatter) -> Result {
1323 if f.flags & (1 << (rt::FlagAlternate as uint)) == 0 {
1324 try!(write!(f.buf, "["));
1326 let mut is_first = true;
1327 for x in self.iter() {
1331 try!(write!(f.buf, ", "));
1333 try!(write!(f.buf, "{}", *x))
1335 if f.flags & (1 << (rt::FlagAlternate as uint)) == 0 {
1336 try!(write!(f.buf, "]"));
1342 impl<'a, T: Show> Show for &'a mut [T] {
1343 fn fmt(&self, f: &mut Formatter) -> Result {
1344 secret_show(&self.as_slice(), f)
1348 impl<T: Show> Show for ~[T] {
1349 fn fmt(&self, f: &mut Formatter) -> Result {
1350 secret_show(&self.as_slice(), f)
1355 fn fmt(&self, f: &mut Formatter) -> Result {
1360 impl Show for TypeId {
1361 fn fmt(&self, f: &mut Formatter) -> Result {
1362 write!(f.buf, "TypeId \\{ {} \\}", self.hash())
1366 impl<T: Show> Show for iter::MinMaxResult<T> {
1367 fn fmt(&self, f: &mut Formatter) -> Result {
1370 write!(f.buf, "NoElements"),
1371 iter::OneElement(ref t) =>
1372 write!(f.buf, "OneElement({})", *t),
1373 iter::MinMax(ref t1, ref t2) =>
1374 write!(f.buf, "MinMax({}, {})", *t1, *t2),
1379 impl Show for cmp::Ordering {
1380 fn fmt(&self, f: &mut Formatter) -> Result {
1382 cmp::Less => write!(f.buf, "Less"),
1383 cmp::Greater => write!(f.buf, "Greater"),
1384 cmp::Equal => write!(f.buf, "Equal"),
1389 impl<T: Copy + Show> Show for Cell<T> {
1390 fn fmt(&self, f: &mut Formatter) -> Result {
1391 write!(f.buf, r"Cell \{ value: {} \}", self.get())
1395 impl Show for UTF16Item {
1396 fn fmt(&self, f: &mut Formatter) -> Result {
1398 ScalarValue(c) => write!(f.buf, "ScalarValue({})", c),
1399 LoneSurrogate(u) => write!(f.buf, "LoneSurrogate({})", u),
1404 // If you expected tests to be here, look instead at the run-pass/ifmt.rs test,
1405 // it's a lot easier than creating all of the rt::Piece structures here.