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:
282 # fn lol<T>() -> T { fail!() }
283 # let my_writer: &mut ::std::io::Writer = lol();
284 # let my_fn: fn(&fmt::Arguments) = lol();
286 format_args!(fmt::format, "this returns {}", "~str");
287 format_args!(|args| { fmt::write(my_writer, args) }, "some {}", "args");
288 format_args!(my_fn, "format {}", "string");
291 The first argument of the `format_args!` macro is a function (or closure) which
292 takes one argument of type `&fmt::Arguments`. This structure can then be
293 passed to the `write` and `format` functions inside this module in order to
294 process the format string. The goal of this macro is to even further prevent
295 intermediate allocations when dealing formatting strings.
297 For example, a logging library could use the standard formatting syntax, but it
298 would internally pass around this structure until it has been determined where
301 It is unsafe to programmatically create an instance of `fmt::Arguments` because
302 the operations performed when executing a format string require the compile-time
303 checks provided by the compiler. The `format_args!` macro is the only method of
304 safely creating these structures, but they can be unsafely created with the
305 constructor provided.
307 ## Internationalization
309 The formatting syntax supported by the `format!` extension supports
310 internationalization by providing "methods" which execute various different
311 outputs depending on the input. The syntax and methods provided are similar to
312 other internationalization systems, so again nothing should seem alien.
313 Currently two methods are supported by this extension: "select" and "plural".
315 Each method will execute one of a number of clauses, and then the value of the
316 clause will become what's the result of the argument's format. Inside of the
317 cases, nested argument strings may be provided, but all formatting arguments
318 must not be done through implicit positional means. All arguments inside of each
319 case of a method must be explicitly selected by their name or their integer
322 Furthermore, whenever a case is running, the special character `#` can be used
323 to reference the string value of the argument which was selected upon. As an
327 format!("{0, select, other{#}}", "hello"); // => ~"hello"
330 This example is the equivalent of `{0:s}` essentially.
334 The select method is a switch over a `&str` parameter, and the parameter *must*
335 be of the type `&str`. An example of the syntax is:
338 {0, select, male{...} female{...} other{...}}
341 Breaking this down, the `0`-th argument is selected upon with the `select`
342 method, and then a number of cases follow. Each case is preceded by an
343 identifier which is the match-clause to execute the given arm. In this case,
344 there are two explicit cases, `male` and `female`. The case will be executed if
345 the string argument provided is an exact match to the case selected.
347 The `other` case is also a required case for all `select` methods. This arm will
348 be executed if none of the other arms matched the word being selected over.
352 The plural method is a switch statement over a `uint` parameter, and the
353 parameter *must* be a `uint`. A plural method in its full glory can be specified
357 {0, plural, offset=1 =1{...} two{...} many{...} other{...}}
360 To break this down, the first `0` indicates that this method is selecting over
361 the value of the first positional parameter to the format string. Next, the
362 `plural` method is being executed. An optionally-supplied `offset` is then given
363 which indicates a number to subtract from argument `0` when matching. This is
364 then followed by a list of cases.
366 Each case is allowed to supply a specific value to match upon with the syntax
367 `=N`. This case is executed if the value at argument `0` matches N exactly,
368 without taking the offset into account. A case may also be specified by one of
369 five keywords: `zero`, `one`, `two`, `few`, and `many`. These cases are matched
370 on after argument `0` has the offset taken into account. Currently the
371 definitions of `many` and `few` are hardcoded, but they are in theory defined by
374 Finally, all `plural` methods must have an `other` case supplied which will be
375 executed if none of the other cases match.
379 The syntax for the formatting language used is drawn from other languages, so it
380 should not be too alien. Arguments are formatted with python-like syntax,
381 meaning that arguments are surrounded by `{}` instead of the C-like `%`. The
382 actual grammar for the formatting syntax is:
385 format_string := <text> [ format <text> ] *
386 format := '{' [ argument ] [ ':' format_spec ] [ ',' function_spec ] '}'
387 argument := integer | identifier
389 format_spec := [[fill]align][sign]['#'][0][width]['.' precision][type]
394 precision := count | '*'
395 type := identifier | ''
396 count := parameter | integer
397 parameter := integer '$'
399 function_spec := plural | select
400 select := 'select' ',' ( identifier arm ) *
401 plural := 'plural' ',' [ 'offset:' integer ] ( selector arm ) *
402 selector := '=' integer | keyword
403 keyword := 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'
404 arm := '{' format_string '}'
407 ## Formatting Parameters
409 Each argument being formatted can be transformed by a number of formatting
410 parameters (corresponding to `format_spec` in the syntax above). These
411 parameters affect the string representation of what's being formatted. This
412 syntax draws heavily from Python's, so it may seem a bit familiar.
416 The fill character is provided normally in conjunction with the `width`
417 parameter. This indicates that if the value being formatted is smaller than
418 `width` some extra characters will be printed around it. The extra characters
419 are specified by `fill`, and the alignment can be one of two options:
421 * `<` - the argument is left-aligned in `width` columns
422 * `>` - the argument is right-aligned in `width` columns
426 These can all be interpreted as flags for a particular formatter.
428 * '+' - This is intended for numeric types and indicates that the sign should
429 always be printed. Positive signs are never printed by default, and the
430 negative sign is only printed by default for the `Signed` trait. This
431 flag indicates that the correct sign (+ or -) should always be printed.
432 * '-' - Currently not used
433 * '#' - This flag is indicates that the "alternate" form of printing should be
434 used. By default, this only applies to the integer formatting traits and
436 * `x` - precedes the argument with a "0x"
437 * `X` - precedes the argument with a "0x"
438 * `t` - precedes the argument with a "0b"
439 * `o` - precedes the argument with a "0o"
440 * '0' - This is used to indicate for integer formats that the padding should
441 both be done with a `0` character as well as be sign-aware. A format
442 like `{:08d}` would yield `00000001` for the integer `1`, while the same
443 format would yield `-0000001` for the integer `-1`. Notice that the
444 negative version has one fewer zero than the positive version.
448 This is a parameter for the "minimum width" that the format should take up. If
449 the value's string does not fill up this many characters, then the padding
450 specified by fill/alignment will be used to take up the required space.
452 The default fill/alignment for non-numerics is a space and left-aligned. The
453 defaults for numeric formatters is also a space but with right-alignment. If the
454 '0' flag is specified for numerics, then the implicit fill character is '0'.
456 The value for the width can also be provided as a `uint` in the list of
457 parameters by using the `2$` syntax indicating that the second argument is a
458 `uint` specifying the width.
462 For non-numeric types, this can be considered a "maximum width". If the
463 resulting string is longer than this width, then it is truncated down to this
464 many characters and only those are emitted.
466 For integral types, this has no meaning currently.
468 For floating-point types, this indicates how many digits after the decimal point
473 The literal characters `{`, `}`, or `#` may be included in a string by
474 preceding them with the `\` character. Since `\` is already an
475 escape character in Rust strings, a string literal using this escape
476 will look like `"\\{"`.
483 use container::Container;
486 use iter::{Iterator, range};
488 use option::{Option,Some,None};
490 use result::{Ok, Err};
493 use slice::ImmutableVector;
496 pub use self::num::radix;
497 pub use self::num::Radix;
498 pub use self::num::RadixFmt;
504 pub type Result = io::IoResult<()>;
506 /// A struct to represent both where to emit formatting strings to and how they
507 /// should be formatted. A mutable version of this is passed to all formatting
509 pub struct Formatter<'a> {
510 /// Flags for formatting (packed version of rt::Flag)
512 /// Character used as 'fill' whenever there is alignment
514 /// Boolean indication of whether the output should be left-aligned
515 align: parse::Alignment,
516 /// Optionally specified integer width that the output should be
518 /// Optionally specified precision for numeric types
519 precision: Option<uint>,
522 buf: &'a mut io::Writer,
523 priv curarg: slice::Items<'a, Argument<'a>>,
524 priv args: &'a [Argument<'a>],
527 /// This struct represents the generic "argument" which is taken by the Xprintf
528 /// family of functions. It contains a function to format the given value. At
529 /// compile time it is ensured that the function and the value have the correct
530 /// types, and then this struct is used to canonicalize arguments to one type.
531 pub struct Argument<'a> {
532 priv formatter: extern "Rust" fn(&any::Void, &mut Formatter) -> Result,
533 priv value: &'a any::Void,
536 impl<'a> Arguments<'a> {
537 /// When using the format_args!() macro, this function is used to generate the
538 /// Arguments structure. The compiler inserts an `unsafe` block to call this,
539 /// which is valid because the compiler performs all necessary validation to
540 /// ensure that the resulting call to format/write would be safe.
541 #[doc(hidden)] #[inline]
542 pub unsafe fn new<'a>(fmt: &'static [rt::Piece<'static>],
543 args: &'a [Argument<'a>]) -> Arguments<'a> {
544 Arguments{ fmt: cast::transmute(fmt), args: args }
548 /// This structure represents a safely precompiled version of a format string
549 /// and its arguments. This cannot be generated at runtime because it cannot
550 /// safely be done so, so no constructors are given and the fields are private
551 /// to prevent modification.
553 /// The `format_args!` macro will safely create an instance of this structure
554 /// and pass it to a user-supplied function. The macro validates the format
555 /// string at compile-time so usage of the `write` and `format` functions can
556 /// be safely performed.
557 pub struct Arguments<'a> {
558 priv fmt: &'a [rt::Piece<'a>],
559 priv args: &'a [Argument<'a>],
562 /// When a format is not otherwise specified, types are formatted by ascribing
563 /// to this trait. There is not an explicit way of selecting this trait to be
564 /// used for formatting, it is only if no other format is specified.
565 #[allow(missing_doc)]
566 pub trait Show { fn fmt(&self, &mut Formatter) -> Result; }
568 /// Format trait for the `b` character
569 #[allow(missing_doc)]
570 pub trait Bool { fn fmt(&self, &mut Formatter) -> Result; }
571 /// Format trait for the `c` character
572 #[allow(missing_doc)]
573 pub trait Char { fn fmt(&self, &mut Formatter) -> Result; }
574 /// Format trait for the `i` and `d` characters
575 #[allow(missing_doc)]
576 pub trait Signed { fn fmt(&self, &mut Formatter) -> Result; }
577 /// Format trait for the `u` character
578 #[allow(missing_doc)]
579 pub trait Unsigned { fn fmt(&self, &mut Formatter) -> Result; }
580 /// Format trait for the `o` character
581 #[allow(missing_doc)]
582 pub trait Octal { fn fmt(&self, &mut Formatter) -> Result; }
583 /// Format trait for the `t` character
584 #[allow(missing_doc)]
585 pub trait Binary { fn fmt(&self, &mut Formatter) -> Result; }
586 /// Format trait for the `x` character
587 #[allow(missing_doc)]
588 pub trait LowerHex { fn fmt(&self, &mut Formatter) -> Result; }
589 /// Format trait for the `X` character
590 #[allow(missing_doc)]
591 pub trait UpperHex { fn fmt(&self, &mut Formatter) -> Result; }
592 /// Format trait for the `s` character
593 #[allow(missing_doc)]
594 pub trait String { fn fmt(&self, &mut Formatter) -> Result; }
595 /// Format trait for the `?` character
596 #[allow(missing_doc)]
597 pub trait Poly { fn fmt(&self, &mut Formatter) -> Result; }
598 /// Format trait for the `p` character
599 #[allow(missing_doc)]
600 pub trait Pointer { fn fmt(&self, &mut Formatter) -> Result; }
601 /// Format trait for the `f` character
602 #[allow(missing_doc)]
603 pub trait Float { fn fmt(&self, &mut Formatter) -> Result; }
604 /// Format trait for the `e` character
605 #[allow(missing_doc)]
606 pub trait LowerExp { fn fmt(&self, &mut Formatter) -> Result; }
607 /// Format trait for the `E` character
608 #[allow(missing_doc)]
609 pub trait UpperExp { fn fmt(&self, &mut Formatter) -> Result; }
611 // FIXME #11938 - UFCS would make us able call the above methods
612 // directly Show::show(x, fmt).
613 macro_rules! uniform_fn_call_workaround {
614 ($( $name: ident, $trait_: ident; )*) => {
617 pub fn $name<T: $trait_>(x: &T, fmt: &mut Formatter) -> Result {
623 uniform_fn_call_workaround! {
627 secret_signed, Signed;
628 secret_unsigned, Unsigned;
630 secret_binary, Binary;
631 secret_lower_hex, LowerHex;
632 secret_upper_hex, UpperHex;
633 secret_string, String;
635 secret_pointer, Pointer;
637 secret_lower_exp, LowerExp;
638 secret_upper_exp, UpperExp;
641 /// The `write` function takes an output stream, a precompiled format string,
642 /// and a list of arguments. The arguments will be formatted according to the
643 /// specified format string into the output stream provided.
647 /// * output - the buffer to write output to
648 /// * args - the precompiled arguments generated by `format_args!`
653 /// # #[allow(unused_must_use)];
657 /// let mut w = io::stdout();
658 /// format_args!(|args| { fmt::write(&mut w, args); }, "Hello, {}!", "world");
660 pub fn write(output: &mut io::Writer, args: &Arguments) -> Result {
661 unsafe { write_unsafe(output, args.fmt, args.args) }
664 /// The `writeln` function takes the same arguments as `write`, except that it
665 /// will also write a newline (`\n`) character at the end of the format string.
666 pub fn writeln(output: &mut io::Writer, args: &Arguments) -> Result {
667 let first = unsafe { write_unsafe(output, args.fmt, args.args) };
668 first.and_then(|()| output.write(['\n' as u8]))
671 /// The `write_unsafe` function takes an output stream, a precompiled format
672 /// string, and a list of arguments. The arguments will be formatted according
673 /// to the specified format string into the output stream provided.
675 /// See the documentation for `format` for why this function is unsafe and care
676 /// should be taken if calling it manually.
678 /// Thankfully the rust compiler provides macros like `write!` and
679 /// `format_args!` which perform all of this validation at compile-time
680 /// and provide a safe interface for invoking this function.
684 /// * output - the buffer to write output to
685 /// * fmts - the precompiled format string to emit
686 /// * args - the list of arguments to the format string. These are only the
687 /// positional arguments (not named)
689 /// Note that this function assumes that there are enough arguments for the
691 pub unsafe fn write_unsafe(output: &mut io::Writer,
693 args: &[Argument]) -> Result {
694 let mut formatter = Formatter {
699 align: parse::AlignUnknown,
704 for piece in fmt.iter() {
705 try!(formatter.run(piece, None));
710 /// The format function takes a precompiled format string and a list of
711 /// arguments, to return the resulting formatted string.
715 /// * args - a structure of arguments generated via the `format_args!` macro.
716 /// Because this structure can only be safely generated at
717 /// compile-time, this function is safe.
724 /// let s = format_args!(fmt::format, "Hello, {}!", "world");
725 /// assert_eq!(s, ~"Hello, world!");
727 pub fn format(args: &Arguments) -> ~str {
728 unsafe { format_unsafe(args.fmt, args.args) }
731 /// The unsafe version of the formatting function.
733 /// This is currently an unsafe function because the types of all arguments
734 /// aren't verified by immediate callers of this function. This currently does
735 /// not validate that the correct types of arguments are specified for each
736 /// format specifier, nor that each argument itself contains the right function
737 /// for formatting the right type value. Because of this, the function is marked
738 /// as `unsafe` if this is being called manually.
740 /// Thankfully the rust compiler provides the macro `format!` which will perform
741 /// all of this validation at compile-time and provides a safe interface for
742 /// invoking this function.
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 format_unsafe(fmt: &[rt::Piece], args: &[Argument]) -> ~str {
753 let mut output = MemWriter::new();
754 write_unsafe(&mut output as &mut io::Writer, fmt, args).unwrap();
755 return str::from_utf8_owned(output.unwrap()).unwrap();
758 impl<'a> Formatter<'a> {
760 // First up is the collection of functions used to execute a format string
761 // at runtime. This consumes all of the compile-time statics generated by
762 // the format! syntax extension.
764 fn run(&mut self, piece: &rt::Piece, cur: Option<&str>) -> Result {
766 rt::String(s) => self.buf.write(s.as_bytes()),
767 rt::CurrentArgument(()) => self.buf.write(cur.unwrap().as_bytes()),
768 rt::Argument(ref arg) => {
769 // Fill in the format parameters into the formatter
770 self.fill = arg.format.fill;
771 self.align = arg.format.align;
772 self.flags = arg.format.flags;
773 self.width = self.getcount(&arg.format.width);
774 self.precision = self.getcount(&arg.format.precision);
776 // Extract the correct argument
777 let value = match arg.position {
778 rt::ArgumentNext => { *self.curarg.next().unwrap() }
779 rt::ArgumentIs(i) => self.args[i],
782 // Then actually do some printing
784 None => (value.formatter)(value.value, self),
785 Some(ref method) => self.execute(*method, value)
791 fn getcount(&mut self, cnt: &rt::Count) -> Option<uint> {
793 rt::CountIs(n) => { Some(n) }
794 rt::CountImplied => { None }
795 rt::CountIsParam(i) => {
796 let v = self.args[i].value;
797 unsafe { Some(*(v as *any::Void as *uint)) }
799 rt::CountIsNextParam => {
800 let v = self.curarg.next().unwrap().value;
801 unsafe { Some(*(v as *any::Void as *uint)) }
806 fn execute(&mut self, method: &rt::Method, arg: Argument) -> Result {
808 // Pluralization is selection upon a numeric value specified as the
810 rt::Plural(offset, ref selectors, ref default) => {
811 // This is validated at compile-time to be a pointer to a
813 let value: &uint = unsafe { cast::transmute(arg.value) };
816 // First, attempt to match against explicit values without the
818 for s in selectors.iter() {
820 rt::Literal(val) if value == val => {
821 return self.runplural(value, s.result);
827 // Next, offset the value and attempt to match against the
828 // keyword selectors.
829 let value = value - match offset { Some(i) => i, None => 0 };
830 for s in selectors.iter() {
831 let run = match s.selector {
832 rt::Keyword(parse::Zero) => value == 0,
833 rt::Keyword(parse::One) => value == 1,
834 rt::Keyword(parse::Two) => value == 2,
836 // FIXME: Few/Many should have a user-specified boundary
837 // One possible option would be in the function
838 // pointer of the 'arg: Argument' struct.
839 rt::Keyword(parse::Few) => value < 8,
840 rt::Keyword(parse::Many) => value >= 8,
842 rt::Literal(..) => false
845 return self.runplural(value, s.result);
849 self.runplural(value, *default)
852 // Select is just a matching against the string specified.
853 rt::Select(ref selectors, ref default) => {
854 // This is validated at compile-time to be a pointer to a
856 let value: & &str = unsafe { cast::transmute(arg.value) };
859 for s in selectors.iter() {
860 if s.selector == value {
861 for piece in s.result.iter() {
862 try!(self.run(piece, Some(value)));
867 for piece in default.iter() {
868 try!(self.run(piece, Some(value)));
875 fn runplural(&mut self, value: uint, pieces: &[rt::Piece]) -> Result {
876 ::uint::to_str_bytes(value, 10, |buf| {
877 let valuestr = str::from_utf8(buf).unwrap();
878 for piece in pieces.iter() {
879 try!(self.run(piece, Some(valuestr)));
885 // Helper methods used for padding and processing formatting arguments that
886 // all formatting traits can use.
888 /// Performs the correct padding for an integer which has already been
889 /// emitted into a byte-array. The byte-array should *not* contain the sign
890 /// for the integer, that will be added by this method.
894 /// * is_positive - whether the original integer was positive or not.
895 /// * prefix - if the '#' character (FlagAlternate) is provided, this
896 /// is the prefix to put in front of the number.
897 /// * buf - the byte array that the number has been formatted into
899 /// This function will correctly account for the flags provided as well as
900 /// the minimum width. It will not take precision into account.
901 pub fn pad_integral(&mut self, is_positive: bool, prefix: &str, buf: &[u8]) -> Result {
902 use fmt::parse::{FlagAlternate, FlagSignPlus, FlagSignAwareZeroPad};
904 let mut width = buf.len();
908 sign = Some('-'); width += 1;
909 } else if self.flags & (1 << (FlagSignPlus as uint)) != 0 {
910 sign = Some('+'); width += 1;
913 let mut prefixed = false;
914 if self.flags & (1 << (FlagAlternate as uint)) != 0 {
915 prefixed = true; width += prefix.len();
918 // Writes the sign if it exists, and then the prefix if it was requested
919 let write_prefix = |f: &mut Formatter| {
920 for c in sign.move_iter() { try!(f.buf.write_char(c)); }
921 if prefixed { f.buf.write_str(prefix) }
925 // The `width` field is more of a `min-width` parameter at this point.
927 // If there's no minimum length requirements then we can just
930 try!(write_prefix(self)); self.buf.write(buf)
932 // Check if we're over the minimum width, if so then we can also
933 // just write the bytes.
934 Some(min) if width >= min => {
935 try!(write_prefix(self)); self.buf.write(buf)
937 // The sign and prefix goes before the padding if the fill character
939 Some(min) if self.flags & (1 << (FlagSignAwareZeroPad as uint)) != 0 => {
941 try!(write_prefix(self));
942 self.with_padding(min - width, parse::AlignRight, |f| f.buf.write(buf))
944 // Otherwise, the sign and prefix goes after the padding
946 self.with_padding(min - width, parse::AlignRight, |f| {
947 try!(write_prefix(f)); f.buf.write(buf)
953 /// This function takes a string slice and emits it to the internal buffer
954 /// after applying the relevant formatting flags specified. The flags
955 /// recognized for generic strings are:
957 /// * width - the minimum width of what to emit
958 /// * fill/align - what to emit and where to emit it if the string
959 /// provided needs to be padded
960 /// * precision - the maximum length to emit, the string is truncated if it
961 /// is longer than this length
963 /// Notably this function ignored the `flag` parameters
964 pub fn pad(&mut self, s: &str) -> Result {
965 // Make sure there's a fast path up front
966 if self.width.is_none() && self.precision.is_none() {
967 return self.buf.write(s.as_bytes());
969 // The `precision` field can be interpreted as a `max-width` for the
970 // string being formatted
971 match self.precision {
973 // If there's a maximum width and our string is longer than
974 // that, then we must always have truncation. This is the only
975 // case where the maximum length will matter.
976 let char_len = s.char_len();
978 let nchars = ::cmp::min(max, char_len);
979 return self.buf.write(s.slice_chars(0, nchars).as_bytes());
984 // The `width` field is more of a `min-width` parameter at this point.
986 // If we're under the maximum length, and there's no minimum length
987 // requirements, then we can just emit the string
988 None => self.buf.write(s.as_bytes()),
989 // If we're under the maximum width, check if we're over the minimum
990 // width, if so it's as easy as just emitting the string.
991 Some(width) if s.char_len() >= width => {
992 self.buf.write(s.as_bytes())
994 // If we're under both the maximum and the minimum width, then fill
995 // up the minimum width with the specified string + some alignment.
997 self.with_padding(width - s.len(), parse::AlignLeft, |me| {
998 me.buf.write(s.as_bytes())
1004 /// Runs a callback, emitting the correct padding either before or
1005 /// afterwards depending on whether right or left alingment is requested.
1006 fn with_padding(&mut self,
1008 default: parse::Alignment,
1009 f: |&mut Formatter| -> Result) -> Result {
1010 let align = match self.align {
1011 parse::AlignUnknown => default,
1012 parse::AlignLeft | parse::AlignRight => self.align
1014 if align == parse::AlignLeft {
1017 let mut fill = [0u8, ..4];
1018 let len = self.fill.encode_utf8(fill);
1019 for _ in range(0, padding) {
1020 try!(self.buf.write(fill.slice_to(len)));
1022 if align == parse::AlignRight {
1029 /// This is a function which calls are emitted to by the compiler itself to
1030 /// create the Argument structures that are passed into the `format` function.
1031 #[doc(hidden)] #[inline]
1032 pub fn argument<'a, T>(f: extern "Rust" fn(&T, &mut Formatter) -> Result,
1033 t: &'a T) -> Argument<'a> {
1036 formatter: cast::transmute(f),
1037 value: cast::transmute(t)
1042 /// When the compiler determines that the type of an argument *must* be a string
1043 /// (such as for select), then it invokes this method.
1044 #[doc(hidden)] #[inline]
1045 pub fn argumentstr<'a>(s: &'a &str) -> Argument<'a> {
1046 argument(secret_string, s)
1049 /// When the compiler determines that the type of an argument *must* be a uint
1050 /// (such as for plural), then it invokes this method.
1051 #[doc(hidden)] #[inline]
1052 pub fn argumentuint<'a>(s: &'a uint) -> Argument<'a> {
1053 argument(secret_unsigned, s)
1056 // Implementations of the core formatting traits
1058 impl<T: Show> Show for @T {
1059 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(&**self, f) }
1061 impl<T: Show> Show for ~T {
1062 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(&**self, f) }
1064 impl<'a, T: Show> Show for &'a T {
1065 fn fmt(&self, f: &mut Formatter) -> Result { secret_show(*self, f) }
1068 impl Bool for bool {
1069 fn fmt(&self, f: &mut Formatter) -> Result {
1070 secret_string(&(if *self {"true"} else {"false"}), f)
1074 impl<'a, T: str::Str> String for T {
1075 fn fmt(&self, f: &mut Formatter) -> Result {
1076 f.pad(self.as_slice())
1080 impl Char for char {
1081 fn fmt(&self, f: &mut Formatter) -> Result {
1082 let mut utf8 = [0u8, ..4];
1083 let amt = self.encode_utf8(utf8);
1084 let s: &str = unsafe { cast::transmute(utf8.slice_to(amt)) };
1085 secret_string(&s, f)
1089 macro_rules! floating(($ty:ident) => {
1090 impl Float for $ty {
1091 fn fmt(&self, fmt: &mut Formatter) -> Result {
1092 // FIXME: this shouldn't perform an allocation
1093 let s = match fmt.precision {
1094 Some(i) => ::$ty::to_str_exact(self.abs(), i),
1095 None => ::$ty::to_str_digits(self.abs(), 6)
1097 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1101 impl LowerExp for $ty {
1102 fn fmt(&self, fmt: &mut Formatter) -> Result {
1103 // FIXME: this shouldn't perform an allocation
1104 let s = match fmt.precision {
1105 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, false),
1106 None => ::$ty::to_str_exp_digits(self.abs(), 6, false)
1108 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1112 impl UpperExp for $ty {
1113 fn fmt(&self, fmt: &mut Formatter) -> Result {
1114 // FIXME: this shouldn't perform an allocation
1115 let s = match fmt.precision {
1116 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, true),
1117 None => ::$ty::to_str_exp_digits(self.abs(), 6, true)
1119 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1126 impl<T> Poly for T {
1127 fn fmt(&self, f: &mut Formatter) -> Result {
1128 match (f.width, f.precision) {
1130 repr::write_repr(f.buf, self)
1133 // If we have a specified width for formatting, then we have to make
1134 // this allocation of a new string
1136 let s = repr::repr_to_str(self);
1143 impl<T> Pointer for *T {
1144 fn fmt(&self, f: &mut Formatter) -> Result {
1145 f.flags |= 1 << (parse::FlagAlternate as uint);
1146 secret_lower_hex::<uint>(&(*self as uint), f)
1149 impl<T> Pointer for *mut T {
1150 fn fmt(&self, f: &mut Formatter) -> Result {
1151 secret_pointer::<*T>(&(*self as *T), f)
1154 impl<'a, T> Pointer for &'a T {
1155 fn fmt(&self, f: &mut Formatter) -> Result {
1156 secret_pointer::<*T>(&(&**self as *T), f)
1159 impl<'a, T> Pointer for &'a mut T {
1160 fn fmt(&self, f: &mut Formatter) -> Result {
1161 secret_pointer::<*T>(&(&**self as *T), f)
1165 // Implementation of Show for various core types
1167 macro_rules! delegate(($ty:ty to $other:ident) => {
1168 impl<'a> Show for $ty {
1169 fn fmt(&self, f: &mut Formatter) -> Result {
1170 (concat_idents!(secret_, $other)(self, f))
1174 delegate!(~str to string)
1175 delegate!(&'a str to string)
1176 delegate!(bool to bool)
1177 delegate!(char to char)
1178 delegate!(f32 to float)
1179 delegate!(f64 to float)
1181 impl<T> Show for *T {
1182 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1184 impl<T> Show for *mut T {
1185 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1188 // If you expected tests to be here, look instead at the run-pass/ifmt.rs test,
1189 // it's a lot easier than creating all of the rt::Piece structures here.