src/libcore/fmt/mod.rs

   1 // Copyright 2013-2015 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.
   4 //
   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.
  10
  11 //! Utilities for formatting and printing strings
  12
  13 #![stable(feature = "rust1", since = "1.0.0")]
  14
  15 use prelude::*;
  16
  17 use cell::{Cell, RefCell, Ref, RefMut, BorrowState};
  18 use marker::PhantomData;
  19 use mem;
  20 use num::flt2dec;
  21 use ops::Deref;
  22 use result;
  23 use slice;
  24 use str;
  25 use self::rt::v1::Alignment;
  26
  27 pub use self::num::radix;
  28 pub use self::num::Radix;
  29 pub use self::num::RadixFmt;
  30
  31 pub use self::builders::{DebugStruct, DebugTuple, DebugSet, DebugList, DebugMap};
  32
  33 mod num;
  34 mod builders;
  35
  36 #[unstable(feature = "fmt_internals", reason = "internal to format_args!")]
  37 #[doc(hidden)]
  38 pub mod rt {
  39     pub mod v1;
  40 }
  41
  42 #[stable(feature = "rust1", since = "1.0.0")]
  43 /// The type returned by formatter methods.
  44 pub type Result = result::Result<(), Error>;
  45
  46 /// The error type which is returned from formatting a message into a stream.
  47 ///
  48 /// This type does not support transmission of an error other than that an error
  49 /// occurred. Any extra information must be arranged to be transmitted through
  50 /// some other means.
  51 #[stable(feature = "rust1", since = "1.0.0")]
  52 #[derive(Copy, Clone, Debug)]
  53 pub struct Error;
  54
  55 /// A collection of methods that are required to format a message into a stream.
  56 ///
  57 /// This trait is the type which this modules requires when formatting
  58 /// information. This is similar to the standard library's `io::Write` trait,
  59 /// but it is only intended for use in libcore.
  60 ///
  61 /// This trait should generally not be implemented by consumers of the standard
  62 /// library. The `write!` macro accepts an instance of `io::Write`, and the
  63 /// `io::Write` trait is favored over implementing this trait.
  64 #[stable(feature = "rust1", since = "1.0.0")]
  65 pub trait Write {
  66     /// Writes a slice of bytes into this writer, returning whether the write
  67     /// succeeded.
  68     ///
  69     /// This method can only succeed if the entire byte slice was successfully
  70     /// written, and this method will not return until all data has been
  71     /// written or an error occurs.
  72     ///
  73     /// # Errors
  74     ///
  75     /// This function will return an instance of `Error` on error.
  76     #[stable(feature = "rust1", since = "1.0.0")]
  77     fn write_str(&mut self, s: &str) -> Result;
  78
  79     /// Writes a `char` into this writer, returning whether the write succeeded.
  80     ///
  81     /// A single `char` may be encoded as more than one byte.
  82     /// This method can only succeed if the entire byte sequence was successfully
  83     /// written, and this method will not return until all data has been
  84     /// written or an error occurs.
  85     ///
  86     /// # Errors
  87     ///
  88     /// This function will return an instance of `Error` on error.
  89     #[stable(feature = "fmt_write_char", since = "1.1.0")]
  90     fn write_char(&mut self, c: char) -> Result {
  91         let mut utf_8 = [0u8; 4];
  92         let bytes_written = c.encode_utf8(&mut utf_8).unwrap_or(0);
  93         self.write_str(unsafe { mem::transmute(&utf_8[..bytes_written]) })
  94     }
  95
  96     /// Glue for usage of the `write!` macro with implementers of this trait.
  97     ///
  98     /// This method should generally not be invoked manually, but rather through
  99     /// the `write!` macro itself.
 100     #[stable(feature = "rust1", since = "1.0.0")]
 101     fn write_fmt(&mut self, args: Arguments) -> Result {
 102         // This Adapter is needed to allow `self` (of type `&mut
 103         // Self`) to be cast to a Write (below) without
 104         // requiring a `Sized` bound.
 105         struct Adapter<'a,T: ?Sized +'a>(&'a mut T);
 106
 107         impl<'a, T: ?Sized> Write for Adapter<'a, T>
 108             where T: Write
 109         {
 110             fn write_str(&mut self, s: &str) -> Result {
 111                 self.0.write_str(s)
 112             }
 113
 114             fn write_fmt(&mut self, args: Arguments) -> Result {
 115                 self.0.write_fmt(args)
 116             }
 117         }
 118
 119         write(&mut Adapter(self), args)
 120     }
 121 }
 122
 123 /// A struct to represent both where to emit formatting strings to and how they
 124 /// should be formatted. A mutable version of this is passed to all formatting
 125 /// traits.
 126 #[stable(feature = "rust1", since = "1.0.0")]
 127 pub struct Formatter<'a> {
 128     flags: u32,
 129     fill: char,
 130     align: rt::v1::Alignment,
 131     width: Option<usize>,
 132     precision: Option<usize>,
 133
 134     buf: &'a mut (Write+'a),
 135     curarg: slice::Iter<'a, ArgumentV1<'a>>,
 136     args: &'a [ArgumentV1<'a>],
 137 }
 138
 139 // NB. Argument is essentially an optimized partially applied formatting function,
 140 // equivalent to `exists T.(&T, fn(&T, &mut Formatter) -> Result`.
 141
 142 enum Void {}
 143
 144 /// This struct represents the generic "argument" which is taken by the Xprintf
 145 /// family of functions. It contains a function to format the given value. At
 146 /// compile time it is ensured that the function and the value have the correct
 147 /// types, and then this struct is used to canonicalize arguments to one type.
 148 #[derive(Copy)]
 149 #[unstable(feature = "fmt_internals", reason = "internal to format_args!")]
 150 #[doc(hidden)]
 151 pub struct ArgumentV1<'a> {
 152     value: &'a Void,
 153     formatter: fn(&Void, &mut Formatter) -> Result,
 154 }
 155
 156 impl<'a> Clone for ArgumentV1<'a> {
 157     fn clone(&self) -> ArgumentV1<'a> {
 158         *self
 159     }
 160 }
 161
 162 impl<'a> ArgumentV1<'a> {
 163     #[inline(never)]
 164     fn show_usize(x: &usize, f: &mut Formatter) -> Result {
 165         Display::fmt(x, f)
 166     }
 167
 168     #[doc(hidden)]
 169     #[unstable(feature = "fmt_internals", reason = "internal to format_args!")]
 170     pub fn new<'b, T>(x: &'b T,
 171                       f: fn(&T, &mut Formatter) -> Result) -> ArgumentV1<'b> {
 172         unsafe {
 173             ArgumentV1 {
 174                 formatter: mem::transmute(f),
 175                 value: mem::transmute(x)
 176             }
 177         }
 178     }
 179
 180     #[doc(hidden)]
 181     #[unstable(feature = "fmt_internals", reason = "internal to format_args!")]
 182     pub fn from_usize(x: &usize) -> ArgumentV1 {
 183         ArgumentV1::new(x, ArgumentV1::show_usize)
 184     }
 185
 186     fn as_usize(&self) -> Option<usize> {
 187         if self.formatter as usize == ArgumentV1::show_usize as usize {
 188             Some(unsafe { *(self.value as *const _ as *const usize) })
 189         } else {
 190             None
 191         }
 192     }
 193 }
 194
 195 // flags available in the v1 format of format_args
 196 #[derive(Copy, Clone)]
 197 #[allow(dead_code)] // SignMinus isn't currently used
 198 enum FlagV1 { SignPlus, SignMinus, Alternate, SignAwareZeroPad, }
 199
 200 impl<'a> Arguments<'a> {
 201     /// When using the format_args!() macro, this function is used to generate the
 202     /// Arguments structure.
 203     #[doc(hidden)] #[inline]
 204     #[unstable(feature = "fmt_internals", reason = "internal to format_args!")]
 205     pub fn new_v1(pieces: &'a [&'a str],
 206                   args: &'a [ArgumentV1<'a>]) -> Arguments<'a> {
 207         Arguments {
 208             pieces: pieces,
 209             fmt: None,
 210             args: args
 211         }
 212     }
 213
 214     /// This function is used to specify nonstandard formatting parameters.
 215     /// The `pieces` array must be at least as long as `fmt` to construct
 216     /// a valid Arguments structure. Also, any `Count` within `fmt` that is
 217     /// `CountIsParam` or `CountIsNextParam` has to point to an argument
 218     /// created with `argumentusize`. However, failing to do so doesn't cause
 219     /// unsafety, but will ignore invalid .
 220     #[doc(hidden)] #[inline]
 221     #[unstable(feature = "fmt_internals", reason = "internal to format_args!")]
 222     pub fn new_v1_formatted(pieces: &'a [&'a str],
 223                             args: &'a [ArgumentV1<'a>],
 224                             fmt: &'a [rt::v1::Argument]) -> Arguments<'a> {
 225         Arguments {
 226             pieces: pieces,
 227             fmt: Some(fmt),
 228             args: args
 229         }
 230     }
 231 }
 232
 233 /// This structure represents a safely precompiled version of a format string
 234 /// and its arguments. This cannot be generated at runtime because it cannot
 235 /// safely be done so, so no constructors are given and the fields are private
 236 /// to prevent modification.
 237 ///
 238 /// The `format_args!` macro will safely create an instance of this structure
 239 /// and pass it to a function or closure, passed as the first argument. The
 240 /// macro validates the format string at compile-time so usage of the `write`
 241 /// and `format` functions can be safely performed.
 242 #[stable(feature = "rust1", since = "1.0.0")]
 243 #[derive(Copy, Clone)]
 244 pub struct Arguments<'a> {
 245     // Format string pieces to print.
 246     pieces: &'a [&'a str],
 247
 248     // Placeholder specs, or `None` if all specs are default (as in "{}{}").
 249     fmt: Option<&'a [rt::v1::Argument]>,
 250
 251     // Dynamic arguments for interpolation, to be interleaved with string
 252     // pieces. (Every argument is preceded by a string piece.)
 253     args: &'a [ArgumentV1<'a>],
 254 }
 255
 256 #[stable(feature = "rust1", since = "1.0.0")]
 257 impl<'a> Debug for Arguments<'a> {
 258     fn fmt(&self, fmt: &mut Formatter) -> Result {
 259         Display::fmt(self, fmt)
 260     }
 261 }
 262
 263 #[stable(feature = "rust1", since = "1.0.0")]
 264 impl<'a> Display for Arguments<'a> {
 265     fn fmt(&self, fmt: &mut Formatter) -> Result {
 266         write(fmt.buf, *self)
 267     }
 268 }
 269
 270 /// Format trait for the `?` character. Useful for debugging, all types
 271 /// should implement this.
 272 ///
 273 /// Generally speaking, you should just `derive` a `Debug` implementation.
 274 ///
 275 /// # Examples
 276 ///
 277 /// Deriving an implementation:
 278 ///
 279 /// ```
 280 /// #[derive(Debug)]
 281 /// struct Point {
 282 ///     x: i32,
 283 ///     y: i32,
 284 /// }
 285 ///
 286 /// let origin = Point { x: 0, y: 0 };
 287 ///
 288 /// println!("The origin is: {:?}", origin);
 289 /// ```
 290 ///
 291 /// Manually implementing:
 292 ///
 293 /// ```
 294 /// use std::fmt;
 295 ///
 296 /// struct Point {
 297 ///     x: i32,
 298 ///     y: i32,
 299 /// }
 300 ///
 301 /// impl fmt::Debug for Point {
 302 ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 303 ///         write!(f, "({}, {})", self.x, self.y)
 304 ///     }
 305 /// }
 306 ///
 307 /// let origin = Point { x: 0, y: 0 };
 308 ///
 309 /// println!("The origin is: {:?}", origin);
 310 /// ```
 311 ///
 312 /// There are a number of `debug_*` methods on `Formatter` to help you with manual
 313 /// implementations, such as [`debug_struct`][debug_struct].
 314 ///
 315 /// `Debug` implementations using either `derive` or the debug builder API
 316 /// on `Formatter` support pretty printing using the alternate flag: `{:#?}`.
 317 ///
 318 /// [debug_struct]: ../std/fmt/struct.Formatter.html#method.debug_struct
 319 #[stable(feature = "rust1", since = "1.0.0")]
 320 #[rustc_on_unimplemented = "`{Self}` cannot be formatted using `:?`; if it is \
 321                             defined in your crate, add `#[derive(Debug)]` or \
 322                             manually implement it"]
 323 #[lang = "debug_trait"]
 324 pub trait Debug {
 325     /// Formats the value using the given formatter.
 326     #[stable(feature = "rust1", since = "1.0.0")]
 327     fn fmt(&self, &mut Formatter) -> Result;
 328 }
 329
 330 /// When a value can be semantically expressed as a String, this trait may be
 331 /// used. It corresponds to the default format, `{}`.
 332 #[rustc_on_unimplemented = "`{Self}` cannot be formatted with the default \
 333                             formatter; try using `:?` instead if you are using \
 334                             a format string"]
 335 #[stable(feature = "rust1", since = "1.0.0")]
 336 pub trait Display {
 337     /// Formats the value using the given formatter.
 338     #[stable(feature = "rust1", since = "1.0.0")]
 339     fn fmt(&self, &mut Formatter) -> Result;
 340 }
 341
 342 /// Format trait for the `o` character
 343 #[stable(feature = "rust1", since = "1.0.0")]
 344 pub trait Octal {
 345     /// Formats the value using the given formatter.
 346     #[stable(feature = "rust1", since = "1.0.0")]
 347     fn fmt(&self, &mut Formatter) -> Result;
 348 }
 349
 350 /// Format trait for the `b` character
 351 #[stable(feature = "rust1", since = "1.0.0")]
 352 pub trait Binary {
 353     /// Formats the value using the given formatter.
 354     #[stable(feature = "rust1", since = "1.0.0")]
 355     fn fmt(&self, &mut Formatter) -> Result;
 356 }
 357
 358 /// Format trait for the `x` character
 359 #[stable(feature = "rust1", since = "1.0.0")]
 360 pub trait LowerHex {
 361     /// Formats the value using the given formatter.
 362     #[stable(feature = "rust1", since = "1.0.0")]
 363     fn fmt(&self, &mut Formatter) -> Result;
 364 }
 365
 366 /// Format trait for the `X` character
 367 #[stable(feature = "rust1", since = "1.0.0")]
 368 pub trait UpperHex {
 369     /// Formats the value using the given formatter.
 370     #[stable(feature = "rust1", since = "1.0.0")]
 371     fn fmt(&self, &mut Formatter) -> Result;
 372 }
 373
 374 /// Format trait for the `p` character
 375 #[stable(feature = "rust1", since = "1.0.0")]
 376 pub trait Pointer {
 377     /// Formats the value using the given formatter.
 378     #[stable(feature = "rust1", since = "1.0.0")]
 379     fn fmt(&self, &mut Formatter) -> Result;
 380 }
 381
 382 /// Format trait for the `e` character
 383 #[stable(feature = "rust1", since = "1.0.0")]
 384 pub trait LowerExp {
 385     /// Formats the value using the given formatter.
 386     #[stable(feature = "rust1", since = "1.0.0")]
 387     fn fmt(&self, &mut Formatter) -> Result;
 388 }
 389
 390 /// Format trait for the `E` character
 391 #[stable(feature = "rust1", since = "1.0.0")]
 392 pub trait UpperExp {
 393     /// Formats the value using the given formatter.
 394     #[stable(feature = "rust1", since = "1.0.0")]
 395     fn fmt(&self, &mut Formatter) -> Result;
 396 }
 397
 398 /// The `write` function takes an output stream, a precompiled format string,
 399 /// and a list of arguments. The arguments will be formatted according to the
 400 /// specified format string into the output stream provided.
 401 ///
 402 /// # Arguments
 403 ///
 404 ///   * output - the buffer to write output to
 405 ///   * args - the precompiled arguments generated by `format_args!`
 406 #[stable(feature = "rust1", since = "1.0.0")]
 407 pub fn write(output: &mut Write, args: Arguments) -> Result {
 408     let mut formatter = Formatter {
 409         flags: 0,
 410         width: None,
 411         precision: None,
 412         buf: output,
 413         align: Alignment::Unknown,
 414         fill: ' ',
 415         args: args.args,
 416         curarg: args.args.iter(),
 417     };
 418
 419     let mut pieces = args.pieces.iter();
 420
 421     match args.fmt {
 422         None => {
 423             // We can use default formatting parameters for all arguments.
 424             for (arg, piece) in args.args.iter().zip(pieces.by_ref()) {
 425                 try!(formatter.buf.write_str(*piece));
 426                 try!((arg.formatter)(arg.value, &mut formatter));
 427             }
 428         }
 429         Some(fmt) => {
 430             // Every spec has a corresponding argument that is preceded by
 431             // a string piece.
 432             for (arg, piece) in fmt.iter().zip(pieces.by_ref()) {
 433                 try!(formatter.buf.write_str(*piece));
 434                 try!(formatter.run(arg));
 435             }
 436         }
 437     }
 438
 439     // There can be only one trailing string piece left.
 440     match pieces.next() {
 441         Some(piece) => {
 442             try!(formatter.buf.write_str(*piece));
 443         }
 444         None => {}
 445     }
 446
 447     Ok(())
 448 }
 449
 450 impl<'a> Formatter<'a> {
 451
 452     // First up is the collection of functions used to execute a format string
 453     // at runtime. This consumes all of the compile-time statics generated by
 454     // the format! syntax extension.
 455     fn run(&mut self, arg: &rt::v1::Argument) -> Result {
 456         // Fill in the format parameters into the formatter
 457         self.fill = arg.format.fill;
 458         self.align = arg.format.align;
 459         self.flags = arg.format.flags;
 460         self.width = self.getcount(&arg.format.width);
 461         self.precision = self.getcount(&arg.format.precision);
 462
 463         // Extract the correct argument
 464         let value = match arg.position {
 465             rt::v1::Position::Next => { *self.curarg.next().unwrap() }
 466             rt::v1::Position::At(i) => self.args[i],
 467         };
 468
 469         // Then actually do some printing
 470         (value.formatter)(value.value, self)
 471     }
 472
 473     fn getcount(&mut self, cnt: &rt::v1::Count) -> Option<usize> {
 474         match *cnt {
 475             rt::v1::Count::Is(n) => Some(n),
 476             rt::v1::Count::Implied => None,
 477             rt::v1::Count::Param(i) => {
 478                 self.args[i].as_usize()
 479             }
 480             rt::v1::Count::NextParam => {
 481                 self.curarg.next().and_then(|arg| arg.as_usize())
 482             }
 483         }
 484     }
 485
 486     // Helper methods used for padding and processing formatting arguments that
 487     // all formatting traits can use.
 488
 489     /// Performs the correct padding for an integer which has already been
 490     /// emitted into a str. The str should *not* contain the sign for the
 491     /// integer, that will be added by this method.
 492     ///
 493     /// # Arguments
 494     ///
 495     /// * is_positive - whether the original integer was positive or not.
 496     /// * prefix - if the '#' character (Alternate) is provided, this
 497     ///   is the prefix to put in front of the number.
 498     /// * buf - the byte array that the number has been formatted into
 499     ///
 500     /// This function will correctly account for the flags provided as well as
 501     /// the minimum width. It will not take precision into account.
 502     #[stable(feature = "rust1", since = "1.0.0")]
 503     pub fn pad_integral(&mut self,
 504                         is_positive: bool,
 505                         prefix: &str,
 506                         buf: &str)
 507                         -> Result {
 508         use char::CharExt;
 509
 510         let mut width = buf.len();
 511
 512         let mut sign = None;
 513         if !is_positive {
 514             sign = Some('-'); width += 1;
 515         } else if self.flags & (1 << (FlagV1::SignPlus as u32)) != 0 {
 516             sign = Some('+'); width += 1;
 517         }
 518
 519         let mut prefixed = false;
 520         if self.flags & (1 << (FlagV1::Alternate as u32)) != 0 {
 521             prefixed = true; width += prefix.char_len();
 522         }
 523
 524         // Writes the sign if it exists, and then the prefix if it was requested
 525         let write_prefix = |f: &mut Formatter| {
 526             if let Some(c) = sign {
 527                 let mut b = [0; 4];
 528                 let n = c.encode_utf8(&mut b).unwrap_or(0);
 529                 let b = unsafe { str::from_utf8_unchecked(&b[..n]) };
 530                 try!(f.buf.write_str(b));
 531             }
 532             if prefixed { f.buf.write_str(prefix) }
 533             else { Ok(()) }
 534         };
 535
 536         // The `width` field is more of a `min-width` parameter at this point.
 537         match self.width {
 538             // If there's no minimum length requirements then we can just
 539             // write the bytes.
 540             None => {
 541                 try!(write_prefix(self)); self.buf.write_str(buf)
 542             }
 543             // Check if we're over the minimum width, if so then we can also
 544             // just write the bytes.
 545             Some(min) if width >= min => {
 546                 try!(write_prefix(self)); self.buf.write_str(buf)
 547             }
 548             // The sign and prefix goes before the padding if the fill character
 549             // is zero
 550             Some(min) if self.flags & (1 << (FlagV1::SignAwareZeroPad as u32)) != 0 => {
 551                 self.fill = '0';
 552                 try!(write_prefix(self));
 553                 self.with_padding(min - width, Alignment::Right, |f| {
 554                     f.buf.write_str(buf)
 555                 })
 556             }
 557             // Otherwise, the sign and prefix goes after the padding
 558             Some(min) => {
 559                 self.with_padding(min - width, Alignment::Right, |f| {
 560                     try!(write_prefix(f)); f.buf.write_str(buf)
 561                 })
 562             }
 563         }
 564     }
 565
 566     /// This function takes a string slice and emits it to the internal buffer
 567     /// after applying the relevant formatting flags specified. The flags
 568     /// recognized for generic strings are:
 569     ///
 570     /// * width - the minimum width of what to emit
 571     /// * fill/align - what to emit and where to emit it if the string
 572     ///                provided needs to be padded
 573     /// * precision - the maximum length to emit, the string is truncated if it
 574     ///               is longer than this length
 575     ///
 576     /// Notably this function ignored the `flag` parameters
 577     #[stable(feature = "rust1", since = "1.0.0")]
 578     pub fn pad(&mut self, s: &str) -> Result {
 579         // Make sure there's a fast path up front
 580         if self.width.is_none() && self.precision.is_none() {
 581             return self.buf.write_str(s);
 582         }
 583         // The `precision` field can be interpreted as a `max-width` for the
 584         // string being formatted
 585         match self.precision {
 586             Some(max) => {
 587                 // If there's a maximum width and our string is longer than
 588                 // that, then we must always have truncation. This is the only
 589                 // case where the maximum length will matter.
 590                 let char_len = s.char_len();
 591                 if char_len >= max {
 592                     let nchars = ::cmp::min(max, char_len);
 593                     return self.buf.write_str(s.slice_chars(0, nchars));
 594                 }
 595             }
 596             None => {}
 597         }
 598         // The `width` field is more of a `min-width` parameter at this point.
 599         match self.width {
 600             // If we're under the maximum length, and there's no minimum length
 601             // requirements, then we can just emit the string
 602             None => self.buf.write_str(s),
 603             // If we're under the maximum width, check if we're over the minimum
 604             // width, if so it's as easy as just emitting the string.
 605             Some(width) if s.char_len() >= width => {
 606                 self.buf.write_str(s)
 607             }
 608             // If we're under both the maximum and the minimum width, then fill
 609             // up the minimum width with the specified string + some alignment.
 610             Some(width) => {
 611                 self.with_padding(width - s.char_len(), Alignment::Left, |me| {
 612                     me.buf.write_str(s)
 613                 })
 614             }
 615         }
 616     }
 617
 618     /// Runs a callback, emitting the correct padding either before or
 619     /// afterwards depending on whether right or left alignment is requested.
 620     fn with_padding<F>(&mut self, padding: usize, default: Alignment,
 621                        f: F) -> Result
 622         where F: FnOnce(&mut Formatter) -> Result,
 623     {
 624         use char::CharExt;
 625         let align = match self.align {
 626             Alignment::Unknown => default,
 627             _ => self.align
 628         };
 629
 630         let (pre_pad, post_pad) = match align {
 631             Alignment::Left => (0, padding),
 632             Alignment::Right | Alignment::Unknown => (padding, 0),
 633             Alignment::Center => (padding / 2, (padding + 1) / 2),
 634         };
 635
 636         let mut fill = [0; 4];
 637         let len = self.fill.encode_utf8(&mut fill).unwrap_or(0);
 638         let fill = unsafe { str::from_utf8_unchecked(&fill[..len]) };
 639
 640         for _ in 0..pre_pad {
 641             try!(self.buf.write_str(fill));
 642         }
 643
 644         try!(f(self));
 645
 646         for _ in 0..post_pad {
 647             try!(self.buf.write_str(fill));
 648         }
 649
 650         Ok(())
 651     }
 652
 653     /// Takes the formatted parts and applies the padding.
 654     /// Assumes that the caller already has rendered the parts with required precision,
 655     /// so that `self.precision` can be ignored.
 656     fn pad_formatted_parts(&mut self, formatted: &flt2dec::Formatted) -> Result {
 657         if let Some(mut width) = self.width {
 658             // for the sign-aware zero padding, we render the sign first and
 659             // behave as if we had no sign from the beginning.
 660             let mut formatted = formatted.clone();
 661             let mut align = self.align;
 662             let old_fill = self.fill;
 663             if self.flags & (1 << (FlagV1::SignAwareZeroPad as u32)) != 0 {
 664                 // a sign always goes first
 665                 let sign = unsafe { str::from_utf8_unchecked(formatted.sign) };
 666                 try!(self.buf.write_str(sign));
 667
 668                 // remove the sign from the formatted parts
 669                 formatted.sign = b"";
 670                 width = if width < sign.len() { 0 } else { width - sign.len() };
 671                 align = Alignment::Right;
 672                 self.fill = '0';
 673             }
 674
 675             // remaining parts go through the ordinary padding process.
 676             let len = formatted.len();
 677             let ret = if width <= len { // no padding
 678                 self.write_formatted_parts(&formatted)
 679             } else {
 680                 self.with_padding(width - len, align, |f| {
 681                     f.write_formatted_parts(&formatted)
 682                 })
 683             };
 684             self.fill = old_fill;
 685             ret
 686         } else {
 687             // this is the common case and we take a shortcut
 688             self.write_formatted_parts(formatted)
 689         }
 690     }
 691
 692     fn write_formatted_parts(&mut self, formatted: &flt2dec::Formatted) -> Result {
 693         fn write_bytes(buf: &mut Write, s: &[u8]) -> Result {
 694             buf.write_str(unsafe { str::from_utf8_unchecked(s) })
 695         }
 696
 697         if !formatted.sign.is_empty() {
 698             try!(write_bytes(self.buf, formatted.sign));
 699         }
 700         for part in formatted.parts {
 701             match *part {
 702                 flt2dec::Part::Zero(mut nzeroes) => {
 703                     const ZEROES: &'static str = // 64 zeroes
 704                         "0000000000000000000000000000000000000000000000000000000000000000";
 705                     while nzeroes > ZEROES.len() {
 706                         try!(self.buf.write_str(ZEROES));
 707                         nzeroes -= ZEROES.len();
 708                     }
 709                     if nzeroes > 0 {
 710                         try!(self.buf.write_str(&ZEROES[..nzeroes]));
 711                     }
 712                 }
 713                 flt2dec::Part::Num(mut v) => {
 714                     let mut s = [0; 5];
 715                     let len = part.len();
 716                     for c in s[..len].iter_mut().rev() {
 717                         *c = b'0' + (v % 10) as u8;
 718                         v /= 10;
 719                     }
 720                     try!(write_bytes(self.buf, &s[..len]));
 721                 }
 722                 flt2dec::Part::Copy(buf) => {
 723                     try!(write_bytes(self.buf, buf));
 724                 }
 725             }
 726         }
 727         Ok(())
 728     }
 729
 730     /// Writes some data to the underlying buffer contained within this
 731     /// formatter.
 732     #[stable(feature = "rust1", since = "1.0.0")]
 733     pub fn write_str(&mut self, data: &str) -> Result {
 734         self.buf.write_str(data)
 735     }
 736
 737     /// Writes some formatted information into this instance
 738     #[stable(feature = "rust1", since = "1.0.0")]
 739     pub fn write_fmt(&mut self, fmt: Arguments) -> Result {
 740         write(self.buf, fmt)
 741     }
 742
 743     /// Flags for formatting (packed version of rt::Flag)
 744     #[stable(feature = "rust1", since = "1.0.0")]
 745     pub fn flags(&self) -> u32 { self.flags }
 746
 747     /// Character used as 'fill' whenever there is alignment
 748     #[unstable(feature = "fmt_flags", reason = "method was just created")]
 749     pub fn fill(&self) -> char { self.fill }
 750
 751     /// Flag indicating what form of alignment was requested
 752     #[unstable(feature = "fmt_flags", reason = "method was just created")]
 753     pub fn align(&self) -> Alignment { self.align }
 754
 755     /// Optionally specified integer width that the output should be
 756     #[unstable(feature = "fmt_flags", reason = "method was just created")]
 757     pub fn width(&self) -> Option<usize> { self.width }
 758
 759     /// Optionally specified precision for numeric types
 760     #[unstable(feature = "fmt_flags", reason = "method was just created")]
 761     pub fn precision(&self) -> Option<usize> { self.precision }
 762
 763     /// Creates a `DebugStruct` builder designed to assist with creation of
 764     /// `fmt::Debug` implementations for structs.
 765     ///
 766     /// # Examples
 767     ///
 768     /// ```rust
 769     /// use std::fmt;
 770     ///
 771     /// struct Foo {
 772     ///     bar: i32,
 773     ///     baz: String,
 774     /// }
 775     ///
 776     /// impl fmt::Debug for Foo {
 777     ///     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 778     ///         fmt.debug_struct("Foo")
 779     ///             .field("bar", &self.bar)
 780     ///             .field("baz", &self.baz)
 781     ///             .finish()
 782     ///     }
 783     /// }
 784     ///
 785     /// // prints "Foo { bar: 10, baz: "Hello World" }"
 786     /// println!("{:?}", Foo { bar: 10, baz: "Hello World".to_string() });
 787     /// ```
 788     #[stable(feature = "debug_builders", since = "1.2.0")]
 789     #[inline]
 790     pub fn debug_struct<'b>(&'b mut self, name: &str) -> DebugStruct<'b, 'a> {
 791         builders::debug_struct_new(self, name)
 792     }
 793
 794     /// Creates a `DebugTuple` builder designed to assist with creation of
 795     /// `fmt::Debug` implementations for tuple structs.
 796     ///
 797     /// # Examples
 798     ///
 799     /// ```rust
 800     /// use std::fmt;
 801     ///
 802     /// struct Foo(i32, String);
 803     ///
 804     /// impl fmt::Debug for Foo {
 805     ///     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 806     ///         fmt.debug_tuple("Foo")
 807     ///             .field(&self.0)
 808     ///             .field(&self.1)
 809     ///             .finish()
 810     ///     }
 811     /// }
 812     ///
 813     /// // prints "Foo(10, "Hello World")"
 814     /// println!("{:?}", Foo(10, "Hello World".to_string()));
 815     /// ```
 816     #[stable(feature = "debug_builders", since = "1.2.0")]
 817     #[inline]
 818     pub fn debug_tuple<'b>(&'b mut self, name: &str) -> DebugTuple<'b, 'a> {
 819         builders::debug_tuple_new(self, name)
 820     }
 821
 822     /// Creates a `DebugList` builder designed to assist with creation of
 823     /// `fmt::Debug` implementations for list-like structures.
 824     ///
 825     /// # Examples
 826     ///
 827     /// ```rust
 828     /// use std::fmt;
 829     ///
 830     /// struct Foo(Vec<i32>);
 831     ///
 832     /// impl fmt::Debug for Foo {
 833     ///     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 834     ///         fmt.debug_list().entries(self.0.iter()).finish()
 835     ///     }
 836     /// }
 837     ///
 838     /// // prints "[10, 11]"
 839     /// println!("{:?}", Foo(vec![10, 11]));
 840     /// ```
 841     #[stable(feature = "debug_builders", since = "1.2.0")]
 842     #[inline]
 843     pub fn debug_list<'b>(&'b mut self) -> DebugList<'b, 'a> {
 844         builders::debug_list_new(self)
 845     }
 846
 847     /// Creates a `DebugSet` builder designed to assist with creation of
 848     /// `fmt::Debug` implementations for set-like structures.
 849     ///
 850     /// # Examples
 851     ///
 852     /// ```rust
 853     /// use std::fmt;
 854     ///
 855     /// struct Foo(Vec<i32>);
 856     ///
 857     /// impl fmt::Debug for Foo {
 858     ///     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 859     ///         fmt.debug_set().entries(self.0.iter()).finish()
 860     ///     }
 861     /// }
 862     ///
 863     /// // prints "{10, 11}"
 864     /// println!("{:?}", Foo(vec![10, 11]));
 865     /// ```
 866     #[stable(feature = "debug_builders", since = "1.2.0")]
 867     #[inline]
 868     pub fn debug_set<'b>(&'b mut self) -> DebugSet<'b, 'a> {
 869         builders::debug_set_new(self)
 870     }
 871
 872     /// Creates a `DebugMap` builder designed to assist with creation of
 873     /// `fmt::Debug` implementations for map-like structures.
 874     ///
 875     /// # Examples
 876     ///
 877     /// ```rust
 878     /// use std::fmt;
 879     ///
 880     /// struct Foo(Vec<(String, i32)>);
 881     ///
 882     /// impl fmt::Debug for Foo {
 883     ///     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 884     ///         fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish()
 885     ///     }
 886     /// }
 887     ///
 888     /// // prints "{"A": 10, "B": 11}"
 889     /// println!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)]));
 890     /// ```
 891     #[stable(feature = "debug_builders", since = "1.2.0")]
 892     #[inline]
 893     pub fn debug_map<'b>(&'b mut self) -> DebugMap<'b, 'a> {
 894         builders::debug_map_new(self)
 895     }
 896 }
 897
 898 #[stable(since = "1.2.0", feature = "formatter_write")]
 899 impl<'a> Write for Formatter<'a> {
 900     fn write_str(&mut self, s: &str) -> Result {
 901         self.buf.write_str(s)
 902     }
 903
 904     fn write_char(&mut self, c: char) -> Result {
 905         self.buf.write_char(c)
 906     }
 907
 908     fn write_fmt(&mut self, args: Arguments) -> Result {
 909         write(self.buf, args)
 910     }
 911 }
 912
 913 #[stable(feature = "rust1", since = "1.0.0")]
 914 impl Display for Error {
 915     fn fmt(&self, f: &mut Formatter) -> Result {
 916         Display::fmt("an error occurred when formatting an argument", f)
 917     }
 918 }
 919
 920 // Implementations of the core formatting traits
 921
 922 macro_rules! fmt_refs {
 923     ($($tr:ident),*) => {
 924         $(
 925         #[stable(feature = "rust1", since = "1.0.0")]
 926         impl<'a, T: ?Sized + $tr> $tr for &'a T {
 927             fn fmt(&self, f: &mut Formatter) -> Result { $tr::fmt(&**self, f) }
 928         }
 929         #[stable(feature = "rust1", since = "1.0.0")]
 930         impl<'a, T: ?Sized + $tr> $tr for &'a mut T {
 931             fn fmt(&self, f: &mut Formatter) -> Result { $tr::fmt(&**self, f) }
 932         }
 933         )*
 934     }
 935 }
 936
 937 fmt_refs! { Debug, Display, Octal, Binary, LowerHex, UpperHex, LowerExp, UpperExp }
 938
 939 #[stable(feature = "rust1", since = "1.0.0")]
 940 impl Debug for bool {
 941     fn fmt(&self, f: &mut Formatter) -> Result {
 942         Display::fmt(self, f)
 943     }
 944 }
 945
 946 #[stable(feature = "rust1", since = "1.0.0")]
 947 impl Display for bool {
 948     fn fmt(&self, f: &mut Formatter) -> Result {
 949         Display::fmt(if *self { "true" } else { "false" }, f)
 950     }
 951 }
 952
 953 #[stable(feature = "rust1", since = "1.0.0")]
 954 impl Debug for str {
 955     fn fmt(&self, f: &mut Formatter) -> Result {
 956         try!(write!(f, "\""));
 957         for c in self.chars().flat_map(|c| c.escape_default()) {
 958             try!(write!(f, "{}", c));
 959         }
 960         write!(f, "\"")
 961     }
 962 }
 963
 964 #[stable(feature = "rust1", since = "1.0.0")]
 965 impl Display for str {
 966     fn fmt(&self, f: &mut Formatter) -> Result {
 967         f.pad(self)
 968     }
 969 }
 970
 971 #[stable(feature = "rust1", since = "1.0.0")]
 972 impl Debug for char {
 973     fn fmt(&self, f: &mut Formatter) -> Result {
 974         use char::CharExt;
 975         try!(write!(f, "'"));
 976         for c in self.escape_default() {
 977             try!(write!(f, "{}", c));
 978         }
 979         write!(f, "'")
 980     }
 981 }
 982
 983 #[stable(feature = "rust1", since = "1.0.0")]
 984 impl Display for char {
 985     fn fmt(&self, f: &mut Formatter) -> Result {
 986         if f.width.is_none() && f.precision.is_none() {
 987             f.write_char(*self)
 988         } else {
 989             let mut utf8 = [0; 4];
 990             let amt = self.encode_utf8(&mut utf8).unwrap_or(0);
 991             let s: &str = unsafe { mem::transmute(&utf8[..amt]) };
 992             f.pad(s)
 993         }
 994     }
 995 }
 996
 997 #[stable(feature = "rust1", since = "1.0.0")]
 998 impl<T> Pointer for *const T {
 999     fn fmt(&self, f: &mut Formatter) -> Result {
1000         let old_width = f.width;
1001         let old_flags = f.flags;
1002
1003         // The alternate flag is already treated by LowerHex as being special-
1004         // it denotes whether to prefix with 0x. We use it to work out whether
1005         // or not to zero extend, and then unconditionally set it to get the
1006         // prefix.
1007         if f.flags & 1 << (FlagV1::Alternate as u32) > 0 {
1008             f.flags |= 1 << (FlagV1::SignAwareZeroPad as u32);
1009
1010             if let None = f.width {
1011                 // The formats need two extra bytes, for the 0x
1012                 if cfg!(target_pointer_width = "32") {
1013                     f.width = Some(10);
1014                 } else {
1015                     f.width = Some(18);
1016                 }
1017             }
1018         }
1019         f.flags |= 1 << (FlagV1::Alternate as u32);
1020
1021         let ret = LowerHex::fmt(&(*self as usize), f);
1022
1023         f.width = old_width;
1024         f.flags = old_flags;
1025
1026         ret
1027     }
1028 }
1029
1030 #[stable(feature = "rust1", since = "1.0.0")]
1031 impl<T> Pointer for *mut T {
1032     fn fmt(&self, f: &mut Formatter) -> Result {
1033         // FIXME(#23542) Replace with type ascription.
1034         #![allow(trivial_casts)]
1035         Pointer::fmt(&(*self as *const T), f)
1036     }
1037 }
1038
1039 #[stable(feature = "rust1", since = "1.0.0")]
1040 impl<'a, T> Pointer for &'a T {
1041     fn fmt(&self, f: &mut Formatter) -> Result {
1042         // FIXME(#23542) Replace with type ascription.
1043         #![allow(trivial_casts)]
1044         Pointer::fmt(&(*self as *const T), f)
1045     }
1046 }
1047
1048 #[stable(feature = "rust1", since = "1.0.0")]
1049 impl<'a, T> Pointer for &'a mut T {
1050     fn fmt(&self, f: &mut Formatter) -> Result {
1051         // FIXME(#23542) Replace with type ascription.
1052         #![allow(trivial_casts)]
1053         Pointer::fmt(&(&**self as *const T), f)
1054     }
1055 }
1056
1057 // Common code of floating point Debug and Display.
1058 fn float_to_decimal_common<T>(fmt: &mut Formatter, num: &T, negative_zero: bool) -> Result
1059     where T: flt2dec::DecodableFloat
1060 {
1061     let force_sign = fmt.flags & (1 << (FlagV1::SignPlus as u32)) != 0;
1062     let sign = match (force_sign, negative_zero) {
1063         (false, false) => flt2dec::Sign::Minus,
1064         (false, true)  => flt2dec::Sign::MinusRaw,
1065         (true,  false) => flt2dec::Sign::MinusPlus,
1066         (true,  true)  => flt2dec::Sign::MinusPlusRaw,
1067     };
1068
1069     let mut buf = [0; 1024]; // enough for f32 and f64
1070     let mut parts = [flt2dec::Part::Zero(0); 16];
1071     let formatted = if let Some(precision) = fmt.precision {
1072         flt2dec::to_exact_fixed_str(flt2dec::strategy::grisu::format_exact, *num, sign,
1073                                     precision, false, &mut buf, &mut parts)
1074     } else {
1075         flt2dec::to_shortest_str(flt2dec::strategy::grisu::format_shortest, *num, sign,
1076                                  0, false, &mut buf, &mut parts)
1077     };
1078     fmt.pad_formatted_parts(&formatted)
1079 }
1080
1081 // Common code of floating point LowerExp and UpperExp.
1082 fn float_to_exponential_common<T>(fmt: &mut Formatter, num: &T, upper: bool) -> Result
1083     where T: flt2dec::DecodableFloat
1084 {
1085     let force_sign = fmt.flags & (1 << (FlagV1::SignPlus as u32)) != 0;
1086     let sign = match force_sign {
1087         false => flt2dec::Sign::Minus,
1088         true  => flt2dec::Sign::MinusPlus,
1089     };
1090
1091     let mut buf = [0; 1024]; // enough for f32 and f64
1092     let mut parts = [flt2dec::Part::Zero(0); 16];
1093     let formatted = if let Some(precision) = fmt.precision {
1094         // 1 integral digit + `precision` fractional digits = `precision + 1` total digits
1095         flt2dec::to_exact_exp_str(flt2dec::strategy::grisu::format_exact, *num, sign,
1096                                   precision + 1, upper, &mut buf, &mut parts)
1097     } else {
1098         flt2dec::to_shortest_exp_str(flt2dec::strategy::grisu::format_shortest, *num, sign,
1099                                      (0, 0), upper, &mut buf, &mut parts)
1100     };
1101     fmt.pad_formatted_parts(&formatted)
1102 }
1103
1104 macro_rules! floating { ($ty:ident) => {
1105
1106     #[stable(feature = "rust1", since = "1.0.0")]
1107     impl Debug for $ty {
1108         fn fmt(&self, fmt: &mut Formatter) -> Result {
1109             float_to_decimal_common(fmt, self, true)
1110         }
1111     }
1112
1113     #[stable(feature = "rust1", since = "1.0.0")]
1114     impl Display for $ty {
1115         fn fmt(&self, fmt: &mut Formatter) -> Result {
1116             float_to_decimal_common(fmt, self, false)
1117         }
1118     }
1119
1120     #[stable(feature = "rust1", since = "1.0.0")]
1121     impl LowerExp for $ty {
1122         fn fmt(&self, fmt: &mut Formatter) -> Result {
1123             float_to_exponential_common(fmt, self, false)
1124         }
1125     }
1126
1127     #[stable(feature = "rust1", since = "1.0.0")]
1128     impl UpperExp for $ty {
1129         fn fmt(&self, fmt: &mut Formatter) -> Result {
1130             float_to_exponential_common(fmt, self, true)
1131         }
1132     }
1133 } }
1134 floating! { f32 }
1135 floating! { f64 }
1136
1137 // Implementation of Display/Debug for various core types
1138
1139 #[stable(feature = "rust1", since = "1.0.0")]
1140 impl<T> Debug for *const T {
1141     fn fmt(&self, f: &mut Formatter) -> Result { Pointer::fmt(self, f) }
1142 }
1143 #[stable(feature = "rust1", since = "1.0.0")]
1144 impl<T> Debug for *mut T {
1145     fn fmt(&self, f: &mut Formatter) -> Result { Pointer::fmt(self, f) }
1146 }
1147
1148 macro_rules! peel {
1149     ($name:ident, $($other:ident,)*) => (tuple! { $($other,)* })
1150 }
1151
1152 macro_rules! tuple {
1153     () => ();
1154     ( $($name:ident,)+ ) => (
1155         #[stable(feature = "rust1", since = "1.0.0")]
1156         impl<$($name:Debug),*> Debug for ($($name,)*) {
1157             #[allow(non_snake_case, unused_assignments)]
1158             fn fmt(&self, f: &mut Formatter) -> Result {
1159                 try!(write!(f, "("));
1160                 let ($(ref $name,)*) = *self;
1161                 let mut n = 0;
1162                 $(
1163                     if n > 0 {
1164                         try!(write!(f, ", "));
1165                     }
1166                     try!(write!(f, "{:?}", *$name));
1167                     n += 1;
1168                 )*
1169                 if n == 1 {
1170                     try!(write!(f, ","));
1171                 }
1172                 write!(f, ")")
1173             }
1174         }
1175         peel! { $($name,)* }
1176     )
1177 }
1178
1179 tuple! { T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, }
1180
1181 #[stable(feature = "rust1", since = "1.0.0")]
1182 impl<T: Debug> Debug for [T] {
1183     fn fmt(&self, f: &mut Formatter) -> Result {
1184         f.debug_list().entries(self.iter()).finish()
1185     }
1186 }
1187
1188 #[stable(feature = "rust1", since = "1.0.0")]
1189 impl Debug for () {
1190     fn fmt(&self, f: &mut Formatter) -> Result {
1191         f.pad("()")
1192     }
1193 }
1194 impl<T> Debug for PhantomData<T> {
1195     fn fmt(&self, f: &mut Formatter) -> Result {
1196         f.pad("PhantomData")
1197     }
1198 }
1199
1200 #[stable(feature = "rust1", since = "1.0.0")]
1201 impl<T: Copy + Debug> Debug for Cell<T> {
1202     fn fmt(&self, f: &mut Formatter) -> Result {
1203         write!(f, "Cell {{ value: {:?} }}", self.get())
1204     }
1205 }
1206
1207 #[stable(feature = "rust1", since = "1.0.0")]
1208 impl<T: ?Sized + Debug> Debug for RefCell<T> {
1209     fn fmt(&self, f: &mut Formatter) -> Result {
1210         match self.borrow_state() {
1211             BorrowState::Unused | BorrowState::Reading => {
1212                 write!(f, "RefCell {{ value: {:?} }}", self.borrow())
1213             }
1214             BorrowState::Writing => write!(f, "RefCell {{ <borrowed> }}"),
1215         }
1216     }
1217 }
1218
1219 #[stable(feature = "rust1", since = "1.0.0")]
1220 impl<'b, T: ?Sized + Debug> Debug for Ref<'b, T> {
1221     fn fmt(&self, f: &mut Formatter) -> Result {
1222         Debug::fmt(&**self, f)
1223     }
1224 }
1225
1226 #[stable(feature = "rust1", since = "1.0.0")]
1227 impl<'b, T: ?Sized + Debug> Debug for RefMut<'b, T> {
1228     fn fmt(&self, f: &mut Formatter) -> Result {
1229         Debug::fmt(&*(self.deref()), f)
1230     }
1231 }
1232
1233 // If you expected tests to be here, look instead at the run-pass/ifmt.rs test,
1234 // it's a lot easier than creating all of the rt::Piece structures here.