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 vec::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: vec::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 `b` 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).
614 // FIXME(huonw's WIP): this is a intermediate state waiting for a
615 // snapshot (at the time of writing we're at 2014-01-20 b6400f9), to
616 // be able to make the `fmt` functions into normal methods and have
617 // `format!()` still work.
618 macro_rules! uniform_fn_call_workaround {
619 ($( $name: ident, $trait_: ident; )*) => {
622 pub fn $name<T: $trait_>(x: &T, fmt: &mut Formatter) -> Result {
628 uniform_fn_call_workaround! {
632 secret_signed, Signed;
633 secret_unsigned, Unsigned;
635 secret_binary, Binary;
636 secret_lower_hex, LowerHex;
637 secret_upper_hex, UpperHex;
638 secret_string, String;
640 secret_pointer, Pointer;
642 secret_lower_exp, LowerExp;
643 secret_upper_exp, UpperExp;
646 /// The `write` function takes an output stream, a precompiled format string,
647 /// and a list of arguments. The arguments will be formatted according to the
648 /// specified format string into the output stream provided.
652 /// * output - the buffer to write output to
653 /// * args - the precompiled arguments generated by `format_args!`
658 /// # #[allow(unused_must_use)];
662 /// let w = &mut io::stdout() as &mut io::Writer;
663 /// format_args!(|args| { fmt::write(w, args); }, "Hello, {}!", "world");
665 pub fn write(output: &mut io::Writer, args: &Arguments) -> Result {
666 unsafe { write_unsafe(output, args.fmt, args.args) }
669 /// The `writeln` function takes the same arguments as `write`, except that it
670 /// will also write a newline (`\n`) character at the end of the format string.
671 pub fn writeln(output: &mut io::Writer, args: &Arguments) -> Result {
672 let first = unsafe { write_unsafe(output, args.fmt, args.args) };
673 first.and_then(|()| output.write(['\n' as u8]))
676 /// The `write_unsafe` function takes an output stream, a precompiled format
677 /// string, and a list of arguments. The arguments will be formatted according
678 /// to the specified format string into the output stream provided.
680 /// See the documentation for `format` for why this function is unsafe and care
681 /// should be taken if calling it manually.
683 /// Thankfully the rust compiler provides macros like `write!` and
684 /// `format_args!` which perform all of this validation at compile-time
685 /// and provide a safe interface for invoking this function.
689 /// * output - the buffer to write output to
690 /// * fmts - the precompiled format string to emit
691 /// * args - the list of arguments to the format string. These are only the
692 /// positional arguments (not named)
694 /// Note that this function assumes that there are enough arguments for the
696 pub unsafe fn write_unsafe(output: &mut io::Writer,
698 args: &[Argument]) -> Result {
699 let mut formatter = Formatter {
704 align: parse::AlignUnknown,
709 for piece in fmt.iter() {
710 try!(formatter.run(piece, None));
715 /// The format function takes a precompiled format string and a list of
716 /// arguments, to return the resulting formatted string.
720 /// * args - a structure of arguments generated via the `format_args!` macro.
721 /// Because this structure can only be safely generated at
722 /// compile-time, this function is safe.
729 /// let s = format_args!(fmt::format, "Hello, {}!", "world");
730 /// assert_eq!(s, ~"Hello, world!");
732 pub fn format(args: &Arguments) -> ~str {
733 unsafe { format_unsafe(args.fmt, args.args) }
736 /// The unsafe version of the formatting function.
738 /// This is currently an unsafe function because the types of all arguments
739 /// aren't verified by immediate callers of this function. This currently does
740 /// not validate that the correct types of arguments are specified for each
741 /// format specifier, nor that each argument itself contains the right function
742 /// for formatting the right type value. Because of this, the function is marked
743 /// as `unsafe` if this is being called manually.
745 /// Thankfully the rust compiler provides the macro `format!` which will perform
746 /// all of this validation at compile-time and provides a safe interface for
747 /// invoking this function.
751 /// * fmts - the precompiled format string to emit.
752 /// * args - the list of arguments to the format string. These are only the
753 /// positional arguments (not named)
755 /// Note that this function assumes that there are enough arguments for the
757 pub unsafe fn format_unsafe(fmt: &[rt::Piece], args: &[Argument]) -> ~str {
758 let mut output = MemWriter::new();
759 write_unsafe(&mut output as &mut io::Writer, fmt, args).unwrap();
760 return str::from_utf8_owned(output.unwrap()).unwrap();
763 impl<'a> Formatter<'a> {
765 // First up is the collection of functions used to execute a format string
766 // at runtime. This consumes all of the compile-time statics generated by
767 // the format! syntax extension.
769 fn run(&mut self, piece: &rt::Piece, cur: Option<&str>) -> Result {
771 rt::String(s) => self.buf.write(s.as_bytes()),
772 rt::CurrentArgument(()) => self.buf.write(cur.unwrap().as_bytes()),
773 rt::Argument(ref arg) => {
774 // Fill in the format parameters into the formatter
775 self.fill = arg.format.fill;
776 self.align = arg.format.align;
777 self.flags = arg.format.flags;
778 self.width = self.getcount(&arg.format.width);
779 self.precision = self.getcount(&arg.format.precision);
781 // Extract the correct argument
782 let value = match arg.position {
783 rt::ArgumentNext => { *self.curarg.next().unwrap() }
784 rt::ArgumentIs(i) => self.args[i],
787 // Then actually do some printing
789 None => (value.formatter)(value.value, self),
790 Some(ref method) => self.execute(*method, value)
796 fn getcount(&mut self, cnt: &rt::Count) -> Option<uint> {
798 rt::CountIs(n) => { Some(n) }
799 rt::CountImplied => { None }
800 rt::CountIsParam(i) => {
801 let v = self.args[i].value;
802 unsafe { Some(*(v as *any::Void as *uint)) }
804 rt::CountIsNextParam => {
805 let v = self.curarg.next().unwrap().value;
806 unsafe { Some(*(v as *any::Void as *uint)) }
811 fn execute(&mut self, method: &rt::Method, arg: Argument) -> Result {
813 // Pluralization is selection upon a numeric value specified as the
815 rt::Plural(offset, ref selectors, ref default) => {
816 // This is validated at compile-time to be a pointer to a
818 let value: &uint = unsafe { cast::transmute(arg.value) };
821 // First, attempt to match against explicit values without the
823 for s in selectors.iter() {
825 rt::Literal(val) if value == val => {
826 return self.runplural(value, s.result);
832 // Next, offset the value and attempt to match against the
833 // keyword selectors.
834 let value = value - match offset { Some(i) => i, None => 0 };
835 for s in selectors.iter() {
836 let run = match s.selector {
837 rt::Keyword(parse::Zero) => value == 0,
838 rt::Keyword(parse::One) => value == 1,
839 rt::Keyword(parse::Two) => value == 2,
841 // FIXME: Few/Many should have a user-specified boundary
842 // One possible option would be in the function
843 // pointer of the 'arg: Argument' struct.
844 rt::Keyword(parse::Few) => value < 8,
845 rt::Keyword(parse::Many) => value >= 8,
847 rt::Literal(..) => false
850 return self.runplural(value, s.result);
854 self.runplural(value, *default)
857 // Select is just a matching against the string specified.
858 rt::Select(ref selectors, ref default) => {
859 // This is validated at compile-time to be a pointer to a
861 let value: & &str = unsafe { cast::transmute(arg.value) };
864 for s in selectors.iter() {
865 if s.selector == value {
866 for piece in s.result.iter() {
867 try!(self.run(piece, Some(value)));
872 for piece in default.iter() {
873 try!(self.run(piece, Some(value)));
880 fn runplural(&mut self, value: uint, pieces: &[rt::Piece]) -> Result {
881 ::uint::to_str_bytes(value, 10, |buf| {
882 let valuestr = str::from_utf8(buf).unwrap();
883 for piece in pieces.iter() {
884 try!(self.run(piece, Some(valuestr)));
890 // Helper methods used for padding and processing formatting arguments that
891 // all formatting traits can use.
893 /// Performs the correct padding for an integer which has already been
894 /// emitted into a byte-array. The byte-array should *not* contain the sign
895 /// for the integer, that will be added by this method.
899 /// * is_positive - whether the original integer was positive or not.
900 /// * prefix - if the '#' character (FlagAlternate) is provided, this
901 /// is the prefix to put in front of the number.
902 /// * buf - the byte array that the number has been formatted into
904 /// This function will correctly account for the flags provided as well as
905 /// the minimum width. It will not take precision into account.
906 pub fn pad_integral(&mut self, is_positive: bool, prefix: &str, buf: &[u8]) -> Result {
907 use fmt::parse::{FlagAlternate, FlagSignPlus, FlagSignAwareZeroPad};
909 let mut width = buf.len();
913 sign = Some('-'); width += 1;
914 } else if self.flags & (1 << (FlagSignPlus as uint)) != 0 {
915 sign = Some('+'); width += 1;
918 let mut prefixed = false;
919 if self.flags & (1 << (FlagAlternate as uint)) != 0 {
920 prefixed = true; width += prefix.len();
923 // Writes the sign if it exists, and then the prefix if it was requested
924 let write_prefix = |f: &mut Formatter| {
925 for c in sign.move_iter() { try!(f.buf.write_char(c)); }
926 if prefixed { f.buf.write_str(prefix) }
930 // The `width` field is more of a `min-width` parameter at this point.
932 // If there's no minimum length requirements then we can just
935 try!(write_prefix(self)); self.buf.write(buf)
937 // Check if we're over the minimum width, if so then we can also
938 // just write the bytes.
939 Some(min) if width >= min => {
940 try!(write_prefix(self)); self.buf.write(buf)
942 // The sign and prefix goes before the padding if the fill character
944 Some(min) if self.flags & (1 << (FlagSignAwareZeroPad as uint)) != 0 => {
946 try!(write_prefix(self));
947 self.with_padding(min - width, parse::AlignRight, |f| f.buf.write(buf))
949 // Otherwise, the sign and prefix goes after the padding
951 self.with_padding(min - width, parse::AlignRight, |f| {
952 try!(write_prefix(f)); f.buf.write(buf)
958 /// This function takes a string slice and emits it to the internal buffer
959 /// after applying the relevant formatting flags specified. The flags
960 /// recognized for generic strings are:
962 /// * width - the minimum width of what to emit
963 /// * fill/align - what to emit and where to emit it if the string
964 /// provided needs to be padded
965 /// * precision - the maximum length to emit, the string is truncated if it
966 /// is longer than this length
968 /// Notably this function ignored the `flag` parameters
969 pub fn pad(&mut self, s: &str) -> Result {
970 // Make sure there's a fast path up front
971 if self.width.is_none() && self.precision.is_none() {
972 return self.buf.write(s.as_bytes());
974 // The `precision` field can be interpreted as a `max-width` for the
975 // string being formatted
976 match self.precision {
978 // If there's a maximum width and our string is longer than
979 // that, then we must always have truncation. This is the only
980 // case where the maximum length will matter.
981 let char_len = s.char_len();
983 let nchars = ::cmp::min(max, char_len);
984 return self.buf.write(s.slice_chars(0, nchars).as_bytes());
989 // The `width` field is more of a `min-width` parameter at this point.
991 // If we're under the maximum length, and there's no minimum length
992 // requirements, then we can just emit the string
993 None => self.buf.write(s.as_bytes()),
994 // If we're under the maximum width, check if we're over the minimum
995 // width, if so it's as easy as just emitting the string.
996 Some(width) if s.char_len() >= width => {
997 self.buf.write(s.as_bytes())
999 // If we're under both the maximum and the minimum width, then fill
1000 // up the minimum width with the specified string + some alignment.
1002 self.with_padding(width - s.len(), parse::AlignLeft, |me| {
1003 me.buf.write(s.as_bytes())
1009 /// Runs a callback, emitting the correct padding either before or
1010 /// afterwards depending on whether right or left alingment is requested.
1011 fn with_padding(&mut self,
1013 default: parse::Alignment,
1014 f: |&mut Formatter| -> Result) -> Result {
1015 let align = match self.align {
1016 parse::AlignUnknown => default,
1017 parse::AlignLeft | parse::AlignRight => self.align
1019 if align == parse::AlignLeft {
1022 let mut fill = [0u8, ..4];
1023 let len = self.fill.encode_utf8(fill);
1024 for _ in range(0, padding) {
1025 try!(self.buf.write(fill.slice_to(len)));
1027 if align == parse::AlignRight {
1034 /// This is a function which calls are emitted to by the compiler itself to
1035 /// create the Argument structures that are passed into the `format` function.
1036 #[doc(hidden)] #[inline]
1037 pub fn argument<'a, T>(f: extern "Rust" fn(&T, &mut Formatter) -> Result,
1038 t: &'a T) -> Argument<'a> {
1041 formatter: cast::transmute(f),
1042 value: cast::transmute(t)
1047 /// When the compiler determines that the type of an argument *must* be a string
1048 /// (such as for select), then it invokes this method.
1049 #[doc(hidden)] #[inline]
1050 pub fn argumentstr<'a>(s: &'a &str) -> Argument<'a> {
1051 argument(secret_string, s)
1054 /// When the compiler determines that the type of an argument *must* be a uint
1055 /// (such as for plural), then it invokes this method.
1056 #[doc(hidden)] #[inline]
1057 pub fn argumentuint<'a>(s: &'a uint) -> Argument<'a> {
1058 argument(secret_unsigned, s)
1061 // Implementations of the core formatting traits
1063 impl Bool for bool {
1064 fn fmt(&self, f: &mut Formatter) -> Result {
1065 secret_string(&(if *self {"true"} else {"false"}), f)
1069 impl<'a, T: str::Str> String for T {
1070 fn fmt(&self, f: &mut Formatter) -> Result {
1071 f.pad(self.as_slice())
1075 impl Char for char {
1076 fn fmt(&self, f: &mut Formatter) -> Result {
1077 let mut utf8 = [0u8, ..4];
1078 let amt = self.encode_utf8(utf8);
1079 let s: &str = unsafe { cast::transmute(utf8.slice_to(amt)) };
1080 secret_string(&s, f)
1084 macro_rules! floating(($ty:ident) => {
1085 impl Float for $ty {
1086 fn fmt(&self, fmt: &mut Formatter) -> Result {
1087 // FIXME: this shouldn't perform an allocation
1088 let s = match fmt.precision {
1089 Some(i) => ::$ty::to_str_exact(self.abs(), i),
1090 None => ::$ty::to_str_digits(self.abs(), 6)
1092 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1096 impl LowerExp for $ty {
1097 fn fmt(&self, fmt: &mut Formatter) -> Result {
1098 // FIXME: this shouldn't perform an allocation
1099 let s = match fmt.precision {
1100 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, false),
1101 None => ::$ty::to_str_exp_digits(self.abs(), 6, false)
1103 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1107 impl UpperExp for $ty {
1108 fn fmt(&self, fmt: &mut Formatter) -> Result {
1109 // FIXME: this shouldn't perform an allocation
1110 let s = match fmt.precision {
1111 Some(i) => ::$ty::to_str_exp_exact(self.abs(), i, true),
1112 None => ::$ty::to_str_exp_digits(self.abs(), 6, true)
1114 fmt.pad_integral(*self >= 0.0, "", s.as_bytes())
1121 impl<T> Poly for T {
1122 fn fmt(&self, f: &mut Formatter) -> Result {
1123 match (f.width, f.precision) {
1125 repr::write_repr(f.buf, self)
1128 // If we have a specified width for formatting, then we have to make
1129 // this allocation of a new string
1131 let s = repr::repr_to_str(self);
1138 impl<T> Pointer for *T {
1139 fn fmt(&self, f: &mut Formatter) -> Result {
1140 f.flags |= 1 << (parse::FlagAlternate as uint);
1141 secret_lower_hex::<uint>(&(*self as uint), f)
1144 impl<T> Pointer for *mut T {
1145 fn fmt(&self, f: &mut Formatter) -> Result {
1146 secret_pointer::<*T>(&(*self as *T), f)
1149 impl<'a, T> Pointer for &'a T {
1150 fn fmt(&self, f: &mut Formatter) -> Result {
1151 secret_pointer::<*T>(&(&**self as *T), f)
1154 impl<'a, T> Pointer for &'a mut T {
1155 fn fmt(&self, f: &mut Formatter) -> Result {
1156 secret_pointer::<*T>(&(&**self as *T), f)
1160 // Implementation of Show for various core types
1162 macro_rules! delegate(($ty:ty to $other:ident) => {
1163 impl<'a> Show for $ty {
1164 fn fmt(&self, f: &mut Formatter) -> Result {
1165 (concat_idents!(secret_, $other)(self, f))
1169 delegate!(~str to string)
1170 delegate!(&'a str to string)
1171 delegate!(bool to bool)
1172 delegate!(char to char)
1173 delegate!(f32 to float)
1174 delegate!(f64 to float)
1176 impl<T> Show for *T {
1177 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1179 impl<T> Show for *mut T {
1180 fn fmt(&self, f: &mut Formatter) -> Result { secret_pointer(self, f) }
1183 // If you expected tests to be here, look instead at the run-pass/ifmt.rs test,
1184 // it's a lot easier than creating all of the rt::Piece structures here.