src/doc/rust-by-example/src/hello/print.md

   1 # Formatted print
   2
   3 Printing is handled by a series of [`macros`][macros] defined in [`std::fmt`][fmt]
   4 some of which include:
   5
   6 * `format!`: write formatted text to [`String`][string]
   7 * `print!`: same as `format!` but the text is printed to the console (io::stdout).
   8 * `println!`: same as `print!` but a newline is appended.
   9 * `eprint!`: same as `format!` but the text is printed to the standard error (io::stderr).
  10 * `eprintln!`: sames as `eprint!`but a newline is appended.
  11
  12 All parse text in the same fashion. A plus is that the formatting correctness will
  13 be checked at compile time.
  14
  15 ```rust,editable,ignore,mdbook-runnable
  16 fn main() {
  17     // In general, the `{}` will be automatically replaced with any
  18     // arguments. These will be stringified.
  19     println!("{} days", 31);
  20
  21     // Without a suffix, 31 becomes an i32. You can change what type 31 is,
  22     // with a suffix.
  23
  24     // There are various optional patterns this works with. Positional
  25     // arguments can be used.
  26     println!("{0}, this is {1}. {1}, this is {0}", "Alice", "Bob");
  27
  28     // As can named arguments.
  29     println!("{subject} {verb} {object}",
  30              object="the lazy dog",
  31              subject="the quick brown fox",
  32              verb="jumps over");
  33
  34     // Special formatting can be specified after a `:`.
  35     println!("{} of {:b} people know binary, the other half doesn't", 1, 2);
  36
  37     // You can right-align text with a specified width. This will output
  38     // "     1". 5 white spaces and a "1".
  39     println!("{number:>width$}", number=1, width=6);
  40
  41     // You can pad numbers with extra zeroes. This will output "000001".
  42     println!("{number:>0width$}", number=1, width=6);
  43
  44     // It will even check to make sure the correct number of arguments are
  45     // used.
  46     println!("My name is {0}, {1} {0}", "Bond");
  47     // FIXME ^ Add the missing argument: "James"
  48
  49     // Create a structure which contains an `i32`. Name it `Structure`.
  50     #[allow(dead_code)]
  51     struct Structure(i32);
  52
  53     // However, custom types such as this structure require more complicated
  54     // handling. This will not work.
  55     println!("This struct `{}` won't print...", Structure(3));
  56     // FIXME ^ Comment out this line.
  57 }
  58 ```
  59
  60 [`std::fmt`][fmt] contains many [`traits`][traits] which govern the display
  61 of text. The base form of two important ones are listed below:
  62
  63 * `fmt::Debug`: Uses the `{:?}` marker. Format text for debugging purposes.
  64 * `fmt::Display`: Uses the `{}` marker. Format text in a more elegant, user
  65 friendly fashion.
  66
  67 Here, `fmt::Display` was used because the std library provides implementations
  68 for these types. To print text for custom types, more steps are required.
  69
  70 ### Activities
  71
  72  * Fix the two issues in the above code (see FIXME) so that it runs without
  73    error.
  74  * Add a `println!` macro that prints: `Pi is roughly 3.142` by controlling
  75    the number of decimal places shown. For the purposes of this exercise,
  76    use `let pi = 3.141592` as an estimate for Pi. (Hint: you may need to
  77    check the [`std::fmt`][fmt] documentation for setting the number of
  78    decimals to display)
  79
  80 ### See also
  81
  82 [`std::fmt`][fmt], [`macros`][macros], [`struct`][structs],
  83 and [`traits`][traits]
  84
  85 [fmt]: https://doc.rust-lang.org/std/fmt/
  86 [macros]: macros.html
  87 [string]: std/str.html
  88 [structs]: custom_types/structs.html
  89 [traits]: trait.html