libgo/go/fmt/doc.go

   1 // Copyright 2009 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 /*
   6         Package fmt implements formatted I/O with functions analogous
   7         to C's printf and scanf.  The format 'verbs' are derived from C's but
   8         are simpler.
   9
  10
  11         Printing
  12
  13         The verbs:
  14
  15         General:
  16                 %v      the value in a default format.
  17                         when printing structs, the plus flag (%+v) adds field names
  18                 %#v     a Go-syntax representation of the value
  19                 %T      a Go-syntax representation of the type of the value
  20                 %%      a literal percent sign; consumes no value
  21
  22         Boolean:
  23                 %t      the word true or false
  24         Integer:
  25                 %b      base 2
  26                 %c      the character represented by the corresponding Unicode code point
  27                 %d      base 10
  28                 %o      base 8
  29                 %q      a single-quoted character literal safely escaped with Go syntax.
  30                 %x      base 16, with lower-case letters for a-f
  31                 %X      base 16, with upper-case letters for A-F
  32                 %U      Unicode format: U+1234; same as "U+%04X"
  33         Floating-point and complex constituents:
  34                 %b      decimalless scientific notation with exponent a power of two,
  35                         in the manner of strconv.FormatFloat with the 'b' format,
  36                         e.g. -123456p-78
  37                 %e      scientific notation, e.g. -1234.456e+78
  38                 %E      scientific notation, e.g. -1234.456E+78
  39                 %f      decimal point but no exponent, e.g. 123.456
  40                 %g      whichever of %e or %f produces more compact output
  41                 %G      whichever of %E or %f produces more compact output
  42         String and slice of bytes:
  43                 %s      the uninterpreted bytes of the string or slice
  44                 %q      a double-quoted string safely escaped with Go syntax
  45                 %x      base 16, lower-case, two characters per byte
  46                 %X      base 16, upper-case, two characters per byte
  47         Pointer:
  48                 %p      base 16 notation, with leading 0x
  49
  50         There is no 'u' flag.  Integers are printed unsigned if they have unsigned type.
  51         Similarly, there is no need to specify the size of the operand (int8, int64).
  52
  53         The width and precision control formatting and are in units of Unicode
  54         code points.  (This differs from C's printf where the units are numbers
  55         of bytes.) Either or both of the flags may be replaced with the
  56         character '*', causing their values to be obtained from the next
  57         operand, which must be of type int.
  58
  59         For numeric values, width sets the minimum width of the field and
  60         precision sets the number of places after the decimal, if appropriate,
  61         except that for %g/%G it sets the total number of digits. For example,
  62         given 123.45 the format %6.2f prints 123.45 while %.4g prints 123.5.
  63         The default precision for %e and %f is 6; for %g it is the smallest
  64         number of digits necessary to identify the value uniquely.
  65
  66         For most values, width is the minimum number of characters to output,
  67         padding the formatted form with spaces if necessary.
  68         For strings, precision is the maximum number of characters to output,
  69         truncating if necessary.
  70
  71         Other flags:
  72                 +       always print a sign for numeric values;
  73                         guarantee ASCII-only output for %q (%+q)
  74                 -       pad with spaces on the right rather than the left (left-justify the field)
  75                 #       alternate format: add leading 0 for octal (%#o), 0x for hex (%#x);
  76                         0X for hex (%#X); suppress 0x for %p (%#p);
  77                         for %q, print a raw (backquoted) string if strconv.CanBackquote
  78                         returns true;
  79                         write e.g. U+0078 'x' if the character is printable for %U (%#U).
  80                 ' '     (space) leave a space for elided sign in numbers (% d);
  81                         put spaces between bytes printing strings or slices in hex (% x, % X)
  82                 0       pad with leading zeros rather than spaces;
  83                         for numbers, this moves the padding after the sign
  84
  85         Flags are ignored by verbs that do not expect them.
  86         For example there is no alternate decimal format, so %#d and %d
  87         behave identically.
  88
  89         For each Printf-like function, there is also a Print function
  90         that takes no format and is equivalent to saying %v for every
  91         operand.  Another variant Println inserts blanks between
  92         operands and appends a newline.
  93
  94         Regardless of the verb, if an operand is an interface value,
  95         the internal concrete value is used, not the interface itself.
  96         Thus:
  97                 var i interface{} = 23
  98                 fmt.Printf("%v\n", i)
  99         will print 23.
 100
 101         If an operand implements interface Formatter, that interface
 102         can be used for fine control of formatting.
 103
 104         If the format (which is implicitly %v for Println etc.) is valid
 105         for a string (%s %q %v %x %X), the following two rules also apply:
 106
 107         1. If an operand implements the error interface, the Error method
 108         will be used to convert the object to a string, which will then
 109         be formatted as required by the verb (if any).
 110
 111         2. If an operand implements method String() string, that method
 112         will be used to convert the object to a string, which will then
 113         be formatted as required by the verb (if any).
 114
 115         To avoid recursion in cases such as
 116                 type X string
 117                 func (x X) String() string { return Sprintf("<%s>", x) }
 118         convert the value before recurring:
 119                 func (x X) String() string { return Sprintf("<%s>", string(x)) }
 120
 121         Explicit argument indexes:
 122
 123         In Printf, Sprintf, and Fprintf, the default behavior is for each
 124         formatting verb to format successive arguments passed in the call.
 125         However, the notation [n] immediately before the verb indicates that the
 126         nth one-indexed argument is to be formatted instead. The same notation
 127         before a '*' for a width or precision selects the argument index holding
 128         the value. After processing a bracketed expression [n], arguments n+1,
 129         n+2, etc. will be processed unless otherwise directed.
 130
 131         For example,
 132                 fmt.Sprintf("%[2]d %[1]d\n", 11, 22)
 133         will yield "22, 11", while
 134                 fmt.Sprintf("%[3]*.[2]*[1]f", 12.0, 2, 6),
 135         equivalent to
 136                 fmt.Sprintf("%6.2f", 12.0),
 137         will yield " 12.00". Because an explicit index affects subsequent verbs,
 138         this notation can be used to print the same values multiple times
 139         by resetting the index for the first argument to be repeated:
 140                 fmt.Sprintf("%d %d %#[1]x %#x", 16, 17)
 141         will yield "16 17 0x10 0x11".
 142
 143         Format errors:
 144
 145         If an invalid argument is given for a verb, such as providing
 146         a string to %d, the generated string will contain a
 147         description of the problem, as in these examples:
 148
 149                 Wrong type or unknown verb: %!verb(type=value)
 150                         Printf("%d", hi):          %!d(string=hi)
 151                 Too many arguments: %!(EXTRA type=value)
 152                         Printf("hi", "guys"):      hi%!(EXTRA string=guys)
 153                 Too few arguments: %!verb(MISSING)
 154                         Printf("hi%d"):            hi %!d(MISSING)
 155                 Non-int for width or precision: %!(BADWIDTH) or %!(BADPREC)
 156                         Printf("%*s", 4.5, "hi"):  %!(BADWIDTH)hi
 157                         Printf("%.*s", 4.5, "hi"): %!(BADPREC)hi
 158                 Invalid or invalid use of argument index: %!(BADINDEX)
 159                         Printf("%*[2]d", 7):       %!d(BADINDEX)
 160                         Printf("%.[2]d", 7):       %!d(BADINDEX)
 161
 162         All errors begin with the string "%!" followed sometimes
 163         by a single character (the verb) and end with a parenthesized
 164         description.
 165
 166         If an Error or String method triggers a panic when called by a
 167         print routine, the fmt package reformats the error message
 168         from the panic, decorating it with an indication that it came
 169         through the fmt package.  For example, if a String method
 170         calls panic("bad"), the resulting formatted message will look
 171         like
 172                 %!s(PANIC=bad)
 173
 174         The %!s just shows the print verb in use when the failure
 175         occurred.
 176
 177         Scanning
 178
 179         An analogous set of functions scans formatted text to yield
 180         values.  Scan, Scanf and Scanln read from os.Stdin; Fscan,
 181         Fscanf and Fscanln read from a specified io.Reader; Sscan,
 182         Sscanf and Sscanln read from an argument string.  Scanln,
 183         Fscanln and Sscanln stop scanning at a newline and require that
 184         the items be followed by one; Scanf, Fscanf and Sscanf require
 185         newlines in the input to match newlines in the format; the other
 186         routines treat newlines as spaces.
 187
 188         Scanf, Fscanf, and Sscanf parse the arguments according to a
 189         format string, analogous to that of Printf.  For example, %x
 190         will scan an integer as a hexadecimal number, and %v will scan
 191         the default representation format for the value.
 192
 193         The formats behave analogously to those of Printf with the
 194         following exceptions:
 195
 196                 %p is not implemented
 197                 %T is not implemented
 198                 %e %E %f %F %g %G are all equivalent and scan any floating point or complex value
 199                 %s and %v on strings scan a space-delimited token
 200                 Flags # and + are not implemented.
 201
 202         The familiar base-setting prefixes 0 (octal) and 0x
 203         (hexadecimal) are accepted when scanning integers without a
 204         format or with the %v verb.
 205
 206         Width is interpreted in the input text (%5s means at most
 207         five runes of input will be read to scan a string) but there
 208         is no syntax for scanning with a precision (no %5.2f, just
 209         %5f).
 210
 211         When scanning with a format, all non-empty runs of space
 212         characters (except newline) are equivalent to a single
 213         space in both the format and the input.  With that proviso,
 214         text in the format string must match the input text; scanning
 215         stops if it does not, with the return value of the function
 216         indicating the number of arguments scanned.
 217
 218         In all the scanning functions, a carriage return followed
 219         immediately by a newline is treated as a plain newline
 220         (\r\n means the same as \n).
 221
 222         In all the scanning functions, if an operand implements method
 223         Scan (that is, it implements the Scanner interface) that
 224         method will be used to scan the text for that operand.  Also,
 225         if the number of arguments scanned is less than the number of
 226         arguments provided, an error is returned.
 227
 228         All arguments to be scanned must be either pointers to basic
 229         types or implementations of the Scanner interface.
 230
 231         Note: Fscan etc. can read one character (rune) past the input
 232         they return, which means that a loop calling a scan routine
 233         may skip some of the input.  This is usually a problem only
 234         when there is no space between input values.  If the reader
 235         provided to Fscan implements ReadRune, that method will be used
 236         to read characters.  If the reader also implements UnreadRune,
 237         that method will be used to save the character and successive
 238         calls will not lose data.  To attach ReadRune and UnreadRune
 239         methods to a reader without that capability, use
 240         bufio.NewReader.
 241 */
 242 package fmt