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         Printing:
  11
  12         The verbs:
  13
  14         General:
  15                 %v      the value in a default format.
  16                         when printing structs, the plus flag (%+v) adds field names
  17                 %#v     a Go-syntax representation of the value
  18                 %T      a Go-syntax representation of the type of the value
  19
  20         Boolean:
  21                 %t      the word true or false
  22         Integer:
  23                 %b      base 2
  24                 %c      the character represented by the corresponding Unicode code point
  25                 %d      base 10
  26                 %o      base 8
  27                 %x      base 16, with lower-case letters for a-f
  28                 %X      base 16, with upper-case letters for A-F
  29         Floating-point and complex constituents:
  30                 %e      scientific notation, e.g. -1234.456e+78
  31                 %E      scientific notation, e.g. -1234.456E+78
  32                 %f      decimal point but no exponent, e.g. 123.456
  33                 %g      whichever of %e or %f produces more compact output
  34                 %G      whichever of %E or %f produces more compact output
  35         String and slice of bytes:
  36                 %s      the uninterpreted bytes of the string or slice
  37                 %q      a double-quoted string safely escaped with Go syntax
  38                 %x      base 16 notation with two characters per byte
  39         Pointer:
  40                 %p      base 16 notation, with leading 0x
  41
  42         There is no 'u' flag.  Integers are printed unsigned if they have unsigned type.
  43         Similarly, there is no need to specify the size of the operand (int8, int64).
  44
  45         For numeric values, the width and precision flags control
  46         formatting; width sets the width of the field, precision the
  47         number of places after the decimal, if appropriate.  The
  48         format %6.2f prints 123.45. The width of a field is the number
  49         of Unicode code points in the string. This differs from C's printf where
  50         the field width is the number of bytes.  Either or both of the
  51         flags may be replaced with the character '*', causing their values
  52         to be obtained from the next operand, which must be of type int.
  53
  54         Other flags:
  55                 +       always print a sign for numeric values
  56                 -       pad with spaces on the right rather than the left (left-justify the field)
  57                 #       alternate format: add leading 0 for octal (%#o), 0x for hex (%#x);
  58                         0X for hex (%#X); suppress 0x for %p (%#p);
  59                         print a raw (backquoted) string if possible for %q (%#q)
  60                 ' '     (space) leave a space for elided sign in numbers (% d);
  61                         put spaces between bytes printing strings or slices in hex (% x)
  62                 0       pad with leading zeros rather than spaces
  63
  64         For each Printf-like function, there is also a Print function
  65         that takes no format and is equivalent to saying %v for every
  66         operand.  Another variant Println inserts blanks between
  67         operands and appends a newline.
  68
  69         Regardless of the verb, if an operand is an interface value,
  70         the internal concrete value is used, not the interface itself.
  71         Thus:
  72                 var i interface{} = 23
  73                 fmt.Printf("%v\n", i)
  74         will print 23.
  75
  76         If an operand implements interface Formatter, that interface
  77         can be used for fine control of formatting.
  78
  79         If an operand implements method String() string that method
  80         will be used to convert the object to a string, which will then
  81         be formatted as required by the verb (if any). To avoid
  82         recursion in cases such as
  83                 type X int
  84                 func (x X) String() string { return Sprintf("%d", x) }
  85         cast the value before recurring:
  86                 func (x X) String() string { return Sprintf("%d", int(x)) }
  87
  88         Format errors:
  89
  90         If an invalid argument is given for a verb, such as providing
  91         a string to %d, the generated string will contain a
  92         description of the problem, as in these examples:
  93
  94                 Wrong type or unknown verb: %!verb(type=value)
  95                         Printf("%d", hi):          %!d(string=hi)
  96                 Too many arguments: %!(EXTRA type=value)
  97                         Printf("hi", "guys"):      hi%!(EXTRA string=guys)
  98                 Too few arguments: %!verb(MISSING)
  99                         Printf("hi%d"):            hi %!d(MISSING)
 100                 Non-int for width or precision: %!(BADWIDTH) or %!(BADPREC)
 101                         Printf("%*s", 4.5, "hi"):  %!(BADWIDTH)hi
 102                         Printf("%.*s", 4.5, "hi"): %!(BADPREC)hi
 103
 104         All errors begin with the string "%!" followed sometimes
 105         by a single character (the verb) and end with a parenthesized
 106         description.
 107
 108         Scanning:
 109
 110         An analogous set of functions scans formatted text to yield
 111         values.  Scan, Scanf and Scanln read from os.Stdin; Fscan,
 112         Fscanf and Fscanln read from a specified os.Reader; Sscan,
 113         Sscanf and Sscanln read from an argument string.  Sscanln,
 114         Fscanln and Sscanln stop scanning at a newline and require that
 115         the items be followed by one; Sscanf, Fscanf and Sscanf require
 116         newlines in the input to match newlines in the format; the other
 117         routines treat newlines as spaces.
 118
 119         Scanf, Fscanf, and Sscanf parse the arguments according to a
 120         format string, analogous to that of Printf.  For example, %x
 121         will scan an integer as a hexadecimal number, and %v will scan
 122         the default representation format for the value.
 123
 124         The formats behave analogously to those of Printf with the
 125         following exceptions:
 126
 127         %p is not implemented
 128         %T is not implemented
 129         %e %E %f %F %g %g are all equivalent and scan any floating
 130                 point or complex value
 131         %s and %v on strings scan a space-delimited token
 132
 133         Width is interpreted in the input text (%5s means at most
 134         five runes of input will be read to scan a string) but there
 135         is no syntax for scanning with a precision (no %5.2f, just
 136         %5f).
 137
 138         When scanning with a format, all non-empty runs of space
 139         characters (except newline) are equivalent to a single
 140         space in both the format and the input.  With that proviso,
 141         text in the format string must match the input text; scanning
 142         stops if it does not, with the return value of the function
 143         indicating the number of arguments scanned.
 144
 145         In all the scanning functions, if an operand implements method
 146         Scan (that is, it implements the Scanner interface) that
 147         method will be used to scan the text for that operand.  Also,
 148         if the number of arguments scanned is less than the number of
 149         arguments provided, an error is returned.
 150
 151         All arguments to be scanned must be either pointers to basic
 152         types or implementations of the Scanner interface.
 153
 154         Note: Fscan etc. can read one character (rune) past the
 155         input they return, which means that a loop calling a scan
 156         routine may skip some of the input.  This is usually a
 157         problem only when there is no space between input values.
 158         However, if the reader provided to Fscan implements UnreadRune,
 159         that method will be used to save the character and successive
 160         calls will not lose data.  To attach an UnreadRune method
 161         to a reader without that capability, use bufio.NewReader.
 162 */
 163 package fmt