1212
1313# The Formatting Module
1414
15- This module contains the runtime support for the `ifmt !` syntax extension. This
15+ This module contains the runtime support for the `format !` syntax extension. This
1616macro is implemented in the compiler to emit calls to this module in order to
1717format arguments at runtime into strings and streams.
1818
1919The functions contained in this module should not normally be used in everyday
20- use cases of `ifmt !`. The assumptions made by these functions are unsafe for all
20+ use cases of `format !`. The assumptions made by these functions are unsafe for all
2121inputs, and the compiler performs a large amount of validation on the arguments
22- to `ifmt !` in order to ensure safety at runtime. While it is possible to call
22+ to `format !` in order to ensure safety at runtime. While it is possible to call
2323these functions directly, it is not recommended to do so in the general case.
2424
2525## Usage
2626
27- The `ifmt !` macro is intended to be familiar to those coming from C's
28- printf/sprintf functions or Python's `str.format` function. In its current
29- revision, the `ifmt !` macro returns a `~str` type which is the result of the
27+ The `format !` macro is intended to be familiar to those coming from C's
28+ printf/fprintf functions or Python's `str.format` function. In its current
29+ revision, the `format !` macro returns a `~str` type which is the result of the
3030formatting. In the future it will also be able to pass in a stream to format
3131arguments directly while performing minimal allocations.
3232
33- Some examples of the `ifmt !` extension are:
33+ Some examples of the `format !` extension are:
3434
3535~~~{.rust}
36- ifmt !("Hello") // => ~"Hello"
37- ifmt !("Hello, {:s}!", "world") // => ~"Hello, world!"
38- ifmt !("The number is {:d}", 1) // => ~"The number is 1"
39- ifmt !("{}", ~[3, 4]) // => ~"~[3, 4]"
40- ifmt !("{value}", value=4) // => ~"4"
41- ifmt !("{} {}", 1, 2) // => ~"1 2"
36+ format !("Hello") // => ~"Hello"
37+ format !("Hello, {:s}!", "world") // => ~"Hello, world!"
38+ format !("The number is {:d}", 1) // => ~"The number is 1"
39+ format !("{}", ~[3, 4]) // => ~"~[3, 4]"
40+ format !("{value}", value=4) // => ~"4"
41+ format !("{} {}", 1, 2) // => ~"1 2"
4242~~~
4343
4444From these, you can see that the first argument is a format string. It is
@@ -62,7 +62,7 @@ format string, although it must always be referred to with the same type.
6262### Named parameters
6363
6464Rust itself does not have a Python-like equivalent of named parameters to a
65- function, but the `ifmt !` macro is a syntax extension which allows it to
65+ function, but the `format !` macro is a syntax extension which allows it to
6666leverage named parameters. Named parameters are listed at the end of the
6767argument list and have the syntax:
6868
@@ -146,7 +146,7 @@ helper methods.
146146
147147## Internationalization
148148
149- The formatting syntax supported by the `ifmt !` extension supports
149+ The formatting syntax supported by the `format !` extension supports
150150internationalization by providing "methods" which execute various different
151151outputs depending on the input. The syntax and methods provided are similar to
152152other internationalization systems, so again nothing should seem alien.
@@ -164,7 +164,7 @@ to reference the string value of the argument which was selected upon. As an
164164example:
165165
166166~~~
167- ifmt !("{0, select, other{#}}", "hello") // => ~"hello"
167+ format !("{0, select, other{#}}", "hello") // => ~"hello"
168168~~~
169169
170170This example is the equivalent of `{0:s}` essentially.
@@ -399,7 +399,44 @@ pub trait Pointer { fn fmt(&Self, &mut Formatter); }
399399#[ allow( missing_doc) ]
400400pub trait Float { fn fmt ( & Self , & mut Formatter ) ; }
401401
402- /// The sprintf function takes a precompiled format string and a list of
402+ /// The `write` function takes an output stream, a precompiled format string,
403+ /// and a list of arguments. The arguments will be formatted according to the
404+ /// specified format string into the output stream provided.
405+ ///
406+ /// See the documentation for `format` for why this function is unsafe and care
407+ /// should be taken if calling it manually.
408+ ///
409+ /// Thankfully the rust compiler provides the macro `fmtf!` which will perform
410+ /// all of this validation at compile-time and provides a safe interface for
411+ /// invoking this function.
412+ ///
413+ /// # Arguments
414+ ///
415+ /// * output - the buffer to write output to
416+ /// * fmts - the precompiled format string to emit
417+ /// * args - the list of arguments to the format string. These are only the
418+ /// positional arguments (not named)
419+ ///
420+ /// Note that this function assumes that there are enough arguments for the
421+ /// format string.
422+ pub unsafe fn write ( output : & mut io:: Writer ,
423+ fmt : & [ rt:: Piece ] , args : & [ Argument ] ) {
424+ let mut formatter = Formatter {
425+ flags : 0 ,
426+ width : None ,
427+ precision : None ,
428+ buf : output,
429+ align : parse:: AlignUnknown ,
430+ fill : ' ' ,
431+ args : args,
432+ curarg : args. iter ( ) ,
433+ } ;
434+ for piece in fmt. iter ( ) {
435+ formatter. run ( piece, None ) ;
436+ }
437+ }
438+
439+ /// The format function takes a precompiled format string and a list of
403440/// arguments, to return the resulting formatted string.
404441///
405442/// This is currently an unsafe function because the types of all arguments
@@ -409,7 +446,7 @@ pub trait Float { fn fmt(&Self, &mut Formatter); }
409446/// for formatting the right type value. Because of this, the function is marked
410447/// as `unsafe` if this is being called manually.
411448///
412- /// Thankfully the rust compiler provides the macro `ifmt !` which will perform
449+ /// Thankfully the rust compiler provides the macro `format !` which will perform
413450/// all of this validation at compile-time and provides a safe interface for
414451/// invoking this function.
415452///
@@ -421,32 +458,17 @@ pub trait Float { fn fmt(&Self, &mut Formatter); }
421458///
422459/// Note that this function assumes that there are enough arguments for the
423460/// format string.
424- pub unsafe fn sprintf ( fmt : & [ rt:: Piece ] , args : & [ Argument ] ) -> ~str {
425- let output = MemWriter :: new ( ) ;
426- {
427- let mut formatter = Formatter {
428- flags : 0 ,
429- width : None ,
430- precision : None ,
431- // FIXME(#8248): shouldn't need a transmute
432- buf : cast:: transmute ( & output as & io:: Writer ) ,
433- align : parse:: AlignUnknown ,
434- fill : ' ' ,
435- args : args,
436- curarg : args. iter ( ) ,
437- } ;
438- for piece in fmt. iter ( ) {
439- formatter. run ( piece, None ) ;
440- }
441- }
461+ pub unsafe fn format ( fmt : & [ rt:: Piece ] , args : & [ Argument ] ) -> ~str {
462+ let mut output = MemWriter :: new ( ) ;
463+ write ( & mut output as & mut io:: Writer , fmt, args) ;
442464 return str:: from_bytes_owned ( output. inner ( ) ) ;
443465}
444466
445467impl < ' self > Formatter < ' self > {
446468
447469 // First up is the collection of functions used to execute a format string
448470 // at runtime. This consumes all of the compile-time statics generated by
449- // the ifmt ! syntax extension.
471+ // the format ! syntax extension.
450472
451473 fn run ( & mut self , piece : & rt:: Piece , cur : Option < & str > ) {
452474 let setcount = |slot : & mut Option < uint > , cnt : & parse:: Count | {
@@ -710,7 +732,7 @@ impl<'self> Formatter<'self> {
710732}
711733
712734/// This is a function which calls are emitted to by the compiler itself to
713- /// create the Argument structures that are passed into the `sprintf ` function.
735+ /// create the Argument structures that are passed into the `format ` function.
714736#[ doc( hidden) ]
715737pub fn argument < ' a , T > ( f : extern "Rust" fn ( & T , & mut Formatter ) ,
716738 t : & ' a T ) -> Argument < ' a > {
0 commit comments