Source file src/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  
    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  
    24  	%t	the word true or false
    25  
    26  Integer:
    27  
    28  	%b	base 2
    29  	%c	the character represented by the corresponding Unicode code point
    30  	%d	base 10
    31  	%o	base 8
    32  	%O	base 8 with 0o prefix
    33  	%q	a single-quoted character literal safely escaped with Go syntax.
    34  	%x	base 16, with lower-case letters for a-f
    35  	%X	base 16, with upper-case letters for A-F
    36  	%U	Unicode format: U+1234; same as "U+%04X"
    37  
    38  Floating-point and complex constituents:
    39  
    40  	%b	decimalless scientific notation with exponent a power of two,
    41  		in the manner of strconv.FormatFloat with the 'b' format,
    42  		e.g. -123456p-78
    43  	%e	scientific notation, e.g. -1.234456e+78
    44  	%E	scientific notation, e.g. -1.234456E+78
    45  	%f	decimal point but no exponent, e.g. 123.456
    46  	%F	synonym for %f
    47  	%g	%e for large exponents, %f otherwise. Precision is discussed below.
    48  	%G	%E for large exponents, %F otherwise
    49  	%x	hexadecimal notation (with decimal power of two exponent), e.g. -0x1.23abcp+20
    50  	%X	upper-case hexadecimal notation, e.g. -0X1.23ABCP+20
    51  
    52  String and slice of bytes (treated equivalently with these verbs):
    53  
    54  	%s	the uninterpreted bytes of the string or slice
    55  	%q	a double-quoted string safely escaped with Go syntax
    56  	%x	base 16, lower-case, two characters per byte
    57  	%X	base 16, upper-case, two characters per byte
    58  
    59  Slice:
    60  
    61  	%p	address of 0th element in base 16 notation, with leading 0x
    62  
    63  Pointer:
    64  
    65  	%p	base 16 notation, with leading 0x
    66  	The %b, %d, %o, %x and %X verbs also work with pointers,
    67  	formatting the value exactly as if it were an integer.
    68  
    69  The default format for %v is:
    70  
    71  	bool:                    %t
    72  	int, int8 etc.:          %d
    73  	uint, uint8 etc.:        %d, %#x if printed with %#v
    74  	float32, complex64, etc: %g
    75  	string:                  %s
    76  	chan:                    %p
    77  	pointer:                 %p
    78  
    79  For compound objects, the elements are printed using these rules, recursively,
    80  laid out like this:
    81  
    82  	struct:             {field0 field1 ...}
    83  	array, slice:       [elem0 elem1 ...]
    84  	maps:               map[key1:value1 key2:value2 ...]
    85  	pointer to above:   &{}, &[], &map[]
    86  
    87  Width is specified by an optional decimal number immediately preceding the verb.
    88  If absent, the width is whatever is necessary to represent the value.
    89  Precision is specified after the (optional) width by a period followed by a
    90  decimal number. If no period is present, a default precision is used.
    91  A period with no following number specifies a precision of zero.
    92  Examples:
    93  
    94  	%f     default width, default precision
    95  	%9f    width 9, default precision
    96  	%.2f   default width, precision 2
    97  	%9.2f  width 9, precision 2
    98  	%9.f   width 9, precision 0
    99  
   100  Width and precision are measured in units of Unicode code points,
   101  that is, runes. (This differs from C's printf where the
   102  units are always measured in bytes.) Either or both of the flags
   103  may be replaced with the character '*', causing their values to be
   104  obtained from the next operand (preceding the one to format),
   105  which must be of type int.
   106  
   107  For most values, width is the minimum number of runes to output,
   108  padding the formatted form with spaces if necessary.
   109  
   110  For strings, byte slices and byte arrays, however, precision
   111  limits the length of the input to be formatted (not the size of
   112  the output), truncating if necessary. Normally it is measured in
   113  runes, but for these types when formatted with the %x or %X format
   114  it is measured in bytes.
   115  
   116  For floating-point values, width sets the minimum width of the field and
   117  precision sets the number of places after the decimal, if appropriate,
   118  except that for %g/%G precision sets the maximum number of significant
   119  digits (trailing zeros are removed). For example, given 12.345 the format
   120  %6.3f prints 12.345 while %.3g prints 12.3. The default precision for %e, %f
   121  and %#g is 6; for %g it is the smallest number of digits necessary to identify
   122  the value uniquely.
   123  
   124  For complex numbers, the width and precision apply to the two
   125  components independently and the result is parenthesized, so %f applied
   126  to 1.2+3.4i produces (1.200000+3.400000i).
   127  
   128  When formatting a single integer code point or a rune string (type []rune)
   129  with %q, invalid Unicode code points are changed to the Unicode replacement
   130  character, U+FFFD, as in strconv.QuoteRune.
   131  
   132  Other flags:
   133  
   134  	'+'	always print a sign for numeric values;
   135  		guarantee ASCII-only output for %q (%+q)
   136  	'-'	pad with spaces on the right rather than the left (left-justify the field)
   137  	'#'	alternate format: add leading 0b for binary (%#b), 0 for octal (%#o),
   138  		0x or 0X for hex (%#x or %#X); suppress 0x for %p (%#p);
   139  		for %q, print a raw (backquoted) string if strconv.CanBackquote
   140  		returns true;
   141  		always print a decimal point for %e, %E, %f, %F, %g and %G;
   142  		do not remove trailing zeros for %g and %G;
   143  		write e.g. U+0078 'x' if the character is printable for %U (%#U).
   144  	' '	(space) leave a space for elided sign in numbers (% d);
   145  		put spaces between bytes printing strings or slices in hex (% x, % X)
   146  	'0'	pad with leading zeros rather than spaces;
   147  		for numbers, this moves the padding after the sign;
   148  		ignored for strings, byte slices and byte arrays
   149  
   150  Flags are ignored by verbs that do not expect them.
   151  For example there is no alternate decimal format, so %#d and %d
   152  behave identically.
   153  
   154  For each Printf-like function, there is also a Print function
   155  that takes no format and is equivalent to saying %v for every
   156  operand.  Another variant Println inserts blanks between
   157  operands and appends a newline.
   158  
   159  Regardless of the verb, if an operand is an interface value,
   160  the internal concrete value is used, not the interface itself.
   161  Thus:
   162  
   163  	var i interface{} = 23
   164  	fmt.Printf("%v\n", i)
   165  
   166  will print 23.
   167  
   168  Except when printed using the verbs %T and %p, special
   169  formatting considerations apply for operands that implement
   170  certain interfaces. In order of application:
   171  
   172  1. If the operand is a reflect.Value, the operand is replaced by the
   173  concrete value that it holds, and printing continues with the next rule.
   174  
   175  2. If an operand implements the Formatter interface, it will
   176  be invoked. In this case the interpretation of verbs and flags is
   177  controlled by that implementation.
   178  
   179  3. If the %v verb is used with the # flag (%#v) and the operand
   180  implements the GoStringer interface, that will be invoked.
   181  
   182  If the format (which is implicitly %v for Println etc.) is valid
   183  for a string (%s %q %v %x %X), the following two rules apply:
   184  
   185  4. If an operand implements the error interface, the Error method
   186  will be invoked to convert the object to a string, which will then
   187  be formatted as required by the verb (if any).
   188  
   189  5. If an operand implements method String() string, that method
   190  will be invoked to convert the object to a string, which will then
   191  be formatted as required by the verb (if any).
   192  
   193  For compound operands such as slices and structs, the format
   194  applies to the elements of each operand, recursively, not to the
   195  operand as a whole. Thus %q will quote each element of a slice
   196  of strings, and %6.2f will control formatting for each element
   197  of a floating-point array.
   198  
   199  However, when printing a byte slice with a string-like verb
   200  (%s %q %x %X), it is treated identically to a string, as a single item.
   201  
   202  To avoid recursion in cases such as
   203  
   204  	type X string
   205  	func (x X) String() string { return Sprintf("<%s>", x) }
   206  
   207  convert the value before recurring:
   208  
   209  	func (x X) String() string { return Sprintf("<%s>", string(x)) }
   210  
   211  Infinite recursion can also be triggered by self-referential data
   212  structures, such as a slice that contains itself as an element, if
   213  that type has a String method. Such pathologies are rare, however,
   214  and the package does not protect against them.
   215  
   216  When printing a struct, fmt cannot and therefore does not invoke
   217  formatting methods such as Error or String on unexported fields.
   218  
   219  # Explicit argument indexes
   220  
   221  In Printf, Sprintf, and Fprintf, the default behavior is for each
   222  formatting verb to format successive arguments passed in the call.
   223  However, the notation [n] immediately before the verb indicates that the
   224  nth one-indexed argument is to be formatted instead. The same notation
   225  before a '*' for a width or precision selects the argument index holding
   226  the value. After processing a bracketed expression [n], subsequent verbs
   227  will use arguments n+1, n+2, etc. unless otherwise directed.
   228  
   229  For example,
   230  
   231  	fmt.Sprintf("%[2]d %[1]d\n", 11, 22)
   232  
   233  will yield "22 11", while
   234  
   235  	fmt.Sprintf("%[3]*.[2]*[1]f", 12.0, 2, 6)
   236  
   237  equivalent to
   238  
   239  	fmt.Sprintf("%6.2f", 12.0)
   240  
   241  will yield " 12.00". Because an explicit index affects subsequent verbs,
   242  this notation can be used to print the same values multiple times
   243  by resetting the index for the first argument to be repeated:
   244  
   245  	fmt.Sprintf("%d %d %#[1]x %#x", 16, 17)
   246  
   247  will yield "16 17 0x10 0x11".
   248  
   249  # Format errors
   250  
   251  If an invalid argument is given for a verb, such as providing
   252  a string to %d, the generated string will contain a
   253  description of the problem, as in these examples:
   254  
   255  	Wrong type or unknown verb: %!verb(type=value)
   256  		Printf("%d", "hi"):        %!d(string=hi)
   257  	Too many arguments: %!(EXTRA type=value)
   258  		Printf("hi", "guys"):      hi%!(EXTRA string=guys)
   259  	Too few arguments: %!verb(MISSING)
   260  		Printf("hi%d"):            hi%!d(MISSING)
   261  	Non-int for width or precision: %!(BADWIDTH) or %!(BADPREC)
   262  		Printf("%*s", 4.5, "hi"):  %!(BADWIDTH)hi
   263  		Printf("%.*s", 4.5, "hi"): %!(BADPREC)hi
   264  	Invalid or invalid use of argument index: %!(BADINDEX)
   265  		Printf("%*[2]d", 7):       %!d(BADINDEX)
   266  		Printf("%.[2]d", 7):       %!d(BADINDEX)
   267  
   268  All errors begin with the string "%!" followed sometimes
   269  by a single character (the verb) and end with a parenthesized
   270  description.
   271  
   272  If an Error or String method triggers a panic when called by a
   273  print routine, the fmt package reformats the error message
   274  from the panic, decorating it with an indication that it came
   275  through the fmt package.  For example, if a String method
   276  calls panic("bad"), the resulting formatted message will look
   277  like
   278  
   279  	%!s(PANIC=bad)
   280  
   281  The %!s just shows the print verb in use when the failure
   282  occurred. If the panic is caused by a nil receiver to an Error
   283  or String method, however, the output is the undecorated
   284  string, "<nil>".
   285  
   286  # Scanning
   287  
   288  An analogous set of functions scans formatted text to yield
   289  values.  Scan, Scanf and Scanln read from os.Stdin; Fscan,
   290  Fscanf and Fscanln read from a specified io.Reader; Sscan,
   291  Sscanf and Sscanln read from an argument string.
   292  
   293  Scan, Fscan, Sscan treat newlines in the input as spaces.
   294  
   295  Scanln, Fscanln and Sscanln stop scanning at a newline and
   296  require that the items be followed by a newline or EOF.
   297  
   298  Scanf, Fscanf, and Sscanf parse the arguments according to a
   299  format string, analogous to that of Printf. In the text that
   300  follows, 'space' means any Unicode whitespace character
   301  except newline.
   302  
   303  In the format string, a verb introduced by the % character
   304  consumes and parses input; these verbs are described in more
   305  detail below. A character other than %, space, or newline in
   306  the format consumes exactly that input character, which must
   307  be present. A newline with zero or more spaces before it in
   308  the format string consumes zero or more spaces in the input
   309  followed by a single newline or the end of the input. A space
   310  following a newline in the format string consumes zero or more
   311  spaces in the input. Otherwise, any run of one or more spaces
   312  in the format string consumes as many spaces as possible in
   313  the input. Unless the run of spaces in the format string
   314  appears adjacent to a newline, the run must consume at least
   315  one space from the input or find the end of the input.
   316  
   317  The handling of spaces and newlines differs from that of C's
   318  scanf family: in C, newlines are treated as any other space,
   319  and it is never an error when a run of spaces in the format
   320  string finds no spaces to consume in the input.
   321  
   322  The verbs behave analogously to those of Printf.
   323  For example, %x will scan an integer as a hexadecimal number,
   324  and %v will scan the default representation format for the value.
   325  The Printf verbs %p and %T and the flags # and + are not implemented.
   326  For floating-point and complex values, all valid formatting verbs
   327  (%b %e %E %f %F %g %G %x %X and %v) are equivalent and accept
   328  both decimal and hexadecimal notation (for example: "2.3e+7", "0x4.5p-8")
   329  and digit-separating underscores (for example: "3.14159_26535_89793").
   330  
   331  Input processed by verbs is implicitly space-delimited: the
   332  implementation of every verb except %c starts by discarding
   333  leading spaces from the remaining input, and the %s verb
   334  (and %v reading into a string) stops consuming input at the first
   335  space or newline character.
   336  
   337  The familiar base-setting prefixes 0b (binary), 0o and 0 (octal),
   338  and 0x (hexadecimal) are accepted when scanning integers
   339  without a format or with the %v verb, as are digit-separating
   340  underscores.
   341  
   342  Width is interpreted in the input text but there is no
   343  syntax for scanning with a precision (no %5.2f, just %5f).
   344  If width is provided, it applies after leading spaces are
   345  trimmed and specifies the maximum number of runes to read
   346  to satisfy the verb. For example,
   347  
   348  	Sscanf(" 1234567 ", "%5s%d", &s, &i)
   349  
   350  will set s to "12345" and i to 67 while
   351  
   352  	Sscanf(" 12 34 567 ", "%5s%d", &s, &i)
   353  
   354  will set s to "12" and i to 34.
   355  
   356  In all the scanning functions, a carriage return followed
   357  immediately by a newline is treated as a plain newline
   358  (\r\n means the same as \n).
   359  
   360  In all the scanning functions, if an operand implements method
   361  Scan (that is, it implements the Scanner interface) that
   362  method will be used to scan the text for that operand.  Also,
   363  if the number of arguments scanned is less than the number of
   364  arguments provided, an error is returned.
   365  
   366  All arguments to be scanned must be either pointers to basic
   367  types or implementations of the Scanner interface.
   368  
   369  Like Scanf and Fscanf, Sscanf need not consume its entire input.
   370  There is no way to recover how much of the input string Sscanf used.
   371  
   372  Note: Fscan etc. can read one character (rune) past the input
   373  they return, which means that a loop calling a scan routine
   374  may skip some of the input.  This is usually a problem only
   375  when there is no space between input values.  If the reader
   376  provided to Fscan implements ReadRune, that method will be used
   377  to read characters.  If the reader also implements UnreadRune,
   378  that method will be used to save the character and successive
   379  calls will not lose data.  To attach ReadRune and UnreadRune
   380  methods to a reader without that capability, use
   381  bufio.NewReader.
   382  */
   383  package fmt
   384  

View as plain text