Some examples of the `format!` extension are:
```rust
-format!("Hello"); // => ~"Hello"
-format!("Hello, {:s}!", "world"); // => ~"Hello, world!"
-format!("The number is {:d}", 1); // => ~"The number is 1"
-format!("{:?}", ~[3, 4]); // => ~"~[3, 4]"
-format!("{value}", value=4); // => ~"4"
-format!("{} {}", 1, 2); // => ~"1 2"
+format!("Hello"); // => "Hello".to_owned()
+format!("Hello, {:s}!", "world"); // => "Hello, world!".to_owned()
+format!("The number is {:d}", 1); // => "The number is 1".to_owned()
+format!("{:?}", ~[3, 4]); // => "~[3, 4]".to_owned()
+format!("{value}", value=4); // => "4".to_owned()
+format!("{} {}", 1, 2); // => "1 2".to_owned()
```
From these, you can see that the first argument is a format string. It is
iterator advances. This leads to behavior like this:
```rust
-format!("{1} {} {0} {}", 1, 2); // => ~"2 1 1 2"
+format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2".to_owned()
```
The internal iterator over the argument has not been advanced by the time the
For example, the following `format!` expressions all use named argument:
```rust
-format!("{argument}", argument = "test"); // => ~"test"
-format!("{name} {}", 1, name = 2); // => ~"2 1"
-format!("{a:s} {c:d} {b:?}", a="a", b=(), c=3); // => ~"a 3 ()"
+format!("{argument}", argument = "test"); // => "test".to_owned()
+format!("{name} {}", 1, name = 2); // => "2 1".to_owned()
+format!("{a:s} {c:d} {b:?}", a="a", b=(), c=3); // => "a 3 ()".to_owned()
```
It is illegal to put positional parameters (those without names) after arguments
actually invoking the `write` function defined in this module. Example usage is:
```rust
-# #[allow(unused_must_use)];
+# #![allow(unused_must_use)]
use std::io;
let mut w = io::MemWriter::new();
the related macros are implemented in terms of this. First
off, some example usage is:
-```ignore
+```
use std::fmt;
+use std::io;
-# fn lol<T>() -> T { fail!() }
-# let my_writer: &mut ::std::io::Writer = lol();
-# let my_fn: fn(&fmt::Arguments) = lol();
-
+# #[allow(unused_must_use)]
+# fn main() {
format_args!(fmt::format, "this returns {}", "~str");
-format_args!(|args| { fmt::write(my_writer, args) }, "some {}", "args");
-format_args!(my_fn, "format {}", "string");
+
+let some_writer: &mut io::Writer = &mut io::stdout();
+format_args!(|args| { fmt::write(some_writer, args) }, "print with a {}", "closure");
+
+fn my_fmt_fn(args: &fmt::Arguments) {
+ fmt::write(&mut io::stdout(), args);
+}
+format_args!(my_fmt_fn, "or a {} too", "function");
+# }
```
The first argument of the `format_args!` macro is a function (or closure) which
example:
```rust
-format!("{0, select, other{#}}", "hello"); // => ~"hello"
+format!("{0, select, other{#}}", "hello"); // => "hello".to_owned()
```
This example is the equivalent of `{0:s}` essentially.
use result::{Ok, Err};
use str::StrSlice;
use str;
-use slice::ImmutableVector;
+use slice::{Vector, ImmutableVector};
use slice;
pub use self::num::radix;
/// traits.
pub struct Formatter<'a> {
/// Flags for formatting (packed version of rt::Flag)
- flags: uint,
+ pub flags: uint,
/// Character used as 'fill' whenever there is alignment
- fill: char,
+ pub fill: char,
/// Boolean indication of whether the output should be left-aligned
- align: parse::Alignment,
+ pub align: parse::Alignment,
/// Optionally specified integer width that the output should be
- width: Option<uint>,
+ pub width: Option<uint>,
/// Optionally specified precision for numeric types
- precision: Option<uint>,
+ pub precision: Option<uint>,
/// Output buffer.
- buf: &'a mut io::Writer,
- priv curarg: slice::Items<'a, Argument<'a>>,
- priv args: &'a [Argument<'a>],
+ pub buf: &'a mut io::Writer,
+ curarg: slice::Items<'a, Argument<'a>>,
+ args: &'a [Argument<'a>],
}
/// This struct represents the generic "argument" which is taken by the Xprintf
/// compile time it is ensured that the function and the value have the correct
/// types, and then this struct is used to canonicalize arguments to one type.
pub struct Argument<'a> {
- priv formatter: extern "Rust" fn(&any::Void, &mut Formatter) -> Result,
- priv value: &'a any::Void,
+ formatter: extern "Rust" fn(&any::Void, &mut Formatter) -> Result,
+ value: &'a any::Void,
}
impl<'a> Arguments<'a> {
/// string at compile-time so usage of the `write` and `format` functions can
/// be safely performed.
pub struct Arguments<'a> {
- priv fmt: &'a [rt::Piece<'a>],
- priv args: &'a [Argument<'a>],
+ fmt: &'a [rt::Piece<'a>],
+ args: &'a [Argument<'a>],
}
/// When a format is not otherwise specified, types are formatted by ascribing
/// # Example
///
/// ```rust
-/// # #[allow(unused_must_use)];
+/// # #![allow(unused_must_use)]
/// use std::fmt;
/// use std::io;
///
/// use std::fmt;
///
/// let s = format_args!(fmt::format, "Hello, {}!", "world");
-/// assert_eq!(s, ~"Hello, world!");
+/// assert_eq!(s, "Hello, world!".to_owned());
/// ```
pub fn format(args: &Arguments) -> ~str {
unsafe { format_unsafe(args.fmt, args.args) }
pub unsafe fn format_unsafe(fmt: &[rt::Piece], args: &[Argument]) -> ~str {
let mut output = MemWriter::new();
write_unsafe(&mut output as &mut io::Writer, fmt, args).unwrap();
- return str::from_utf8_owned(output.unwrap()).unwrap();
+ return str::from_utf8(output.unwrap().as_slice()).unwrap().to_owned();
}
impl<'a> Formatter<'a> {