diff options
Diffstat (limited to 'src/fmt/doc.go')
| -rw-r--r-- | src/fmt/doc.go | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/src/fmt/doc.go b/src/fmt/doc.go new file mode 100644 index 0000000..9785ed9 --- /dev/null +++ b/src/fmt/doc.go @@ -0,0 +1,383 @@ +// Copyright 2009 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +/* +Package fmt implements formatted I/O with functions analogous +to C's printf and scanf. The format 'verbs' are derived from C's but +are simpler. + +# Printing + +The verbs: + +General: + + %v the value in a default format + when printing structs, the plus flag (%+v) adds field names + %#v a Go-syntax representation of the value + %T a Go-syntax representation of the type of the value + %% a literal percent sign; consumes no value + +Boolean: + + %t the word true or false + +Integer: + + %b base 2 + %c the character represented by the corresponding Unicode code point + %d base 10 + %o base 8 + %O base 8 with 0o prefix + %q a single-quoted character literal safely escaped with Go syntax. + %x base 16, with lower-case letters for a-f + %X base 16, with upper-case letters for A-F + %U Unicode format: U+1234; same as "U+%04X" + +Floating-point and complex constituents: + + %b decimalless scientific notation with exponent a power of two, + in the manner of strconv.FormatFloat with the 'b' format, + e.g. -123456p-78 + %e scientific notation, e.g. -1.234456e+78 + %E scientific notation, e.g. -1.234456E+78 + %f decimal point but no exponent, e.g. 123.456 + %F synonym for %f + %g %e for large exponents, %f otherwise. Precision is discussed below. + %G %E for large exponents, %F otherwise + %x hexadecimal notation (with decimal power of two exponent), e.g. -0x1.23abcp+20 + %X upper-case hexadecimal notation, e.g. -0X1.23ABCP+20 + +String and slice of bytes (treated equivalently with these verbs): + + %s the uninterpreted bytes of the string or slice + %q a double-quoted string safely escaped with Go syntax + %x base 16, lower-case, two characters per byte + %X base 16, upper-case, two characters per byte + +Slice: + + %p address of 0th element in base 16 notation, with leading 0x + +Pointer: + + %p base 16 notation, with leading 0x + The %b, %d, %o, %x and %X verbs also work with pointers, + formatting the value exactly as if it were an integer. + +The default format for %v is: + + bool: %t + int, int8 etc.: %d + uint, uint8 etc.: %d, %#x if printed with %#v + float32, complex64, etc: %g + string: %s + chan: %p + pointer: %p + +For compound objects, the elements are printed using these rules, recursively, +laid out like this: + + struct: {field0 field1 ...} + array, slice: [elem0 elem1 ...] + maps: map[key1:value1 key2:value2 ...] + pointer to above: &{}, &[], &map[] + +Width is specified by an optional decimal number immediately preceding the verb. +If absent, the width is whatever is necessary to represent the value. +Precision is specified after the (optional) width by a period followed by a +decimal number. If no period is present, a default precision is used. +A period with no following number specifies a precision of zero. +Examples: + + %f default width, default precision + %9f width 9, default precision + %.2f default width, precision 2 + %9.2f width 9, precision 2 + %9.f width 9, precision 0 + +Width and precision are measured in units of Unicode code points, +that is, runes. (This differs from C's printf where the +units are always measured in bytes.) Either or both of the flags +may be replaced with the character '*', causing their values to be +obtained from the next operand (preceding the one to format), +which must be of type int. + +For most values, width is the minimum number of runes to output, +padding the formatted form with spaces if necessary. + +For strings, byte slices and byte arrays, however, precision +limits the length of the input to be formatted (not the size of +the output), truncating if necessary. Normally it is measured in +runes, but for these types when formatted with the %x or %X format +it is measured in bytes. + +For floating-point values, width sets the minimum width of the field and +precision sets the number of places after the decimal, if appropriate, +except that for %g/%G precision sets the maximum number of significant +digits (trailing zeros are removed). For example, given 12.345 the format +%6.3f prints 12.345 while %.3g prints 12.3. The default precision for %e, %f +and %#g is 6; for %g it is the smallest number of digits necessary to identify +the value uniquely. + +For complex numbers, the width and precision apply to the two +components independently and the result is parenthesized, so %f applied +to 1.2+3.4i produces (1.200000+3.400000i). + +When formatting a single integer code point or a rune string (type []rune) +with %q, invalid Unicode code points are changed to the Unicode replacement +character, U+FFFD, as in strconv.QuoteRune. + +Other flags: + + '+' always print a sign for numeric values; + guarantee ASCII-only output for %q (%+q) + '-' pad with spaces on the right rather than the left (left-justify the field) + '#' alternate format: add leading 0b for binary (%#b), 0 for octal (%#o), + 0x or 0X for hex (%#x or %#X); suppress 0x for %p (%#p); + for %q, print a raw (backquoted) string if strconv.CanBackquote + returns true; + always print a decimal point for %e, %E, %f, %F, %g and %G; + do not remove trailing zeros for %g and %G; + write e.g. U+0078 'x' if the character is printable for %U (%#U). + ' ' (space) leave a space for elided sign in numbers (% d); + put spaces between bytes printing strings or slices in hex (% x, % X) + '0' pad with leading zeros rather than spaces; + for numbers, this moves the padding after the sign; + ignored for strings, byte slices and byte arrays + +Flags are ignored by verbs that do not expect them. +For example there is no alternate decimal format, so %#d and %d +behave identically. + +For each Printf-like function, there is also a Print function +that takes no format and is equivalent to saying %v for every +operand. Another variant Println inserts blanks between +operands and appends a newline. + +Regardless of the verb, if an operand is an interface value, +the internal concrete value is used, not the interface itself. +Thus: + + var i interface{} = 23 + fmt.Printf("%v\n", i) + +will print 23. + +Except when printed using the verbs %T and %p, special +formatting considerations apply for operands that implement +certain interfaces. In order of application: + +1. If the operand is a reflect.Value, the operand is replaced by the +concrete value that it holds, and printing continues with the next rule. + +2. If an operand implements the Formatter interface, it will +be invoked. In this case the interpretation of verbs and flags is +controlled by that implementation. + +3. If the %v verb is used with the # flag (%#v) and the operand +implements the GoStringer interface, that will be invoked. + +If the format (which is implicitly %v for Println etc.) is valid +for a string (%s %q %v %x %X), the following two rules apply: + +4. If an operand implements the error interface, the Error method +will be invoked to convert the object to a string, which will then +be formatted as required by the verb (if any). + +5. If an operand implements method String() string, that method +will be invoked to convert the object to a string, which will then +be formatted as required by the verb (if any). + +For compound operands such as slices and structs, the format +applies to the elements of each operand, recursively, not to the +operand as a whole. Thus %q will quote each element of a slice +of strings, and %6.2f will control formatting for each element +of a floating-point array. + +However, when printing a byte slice with a string-like verb +(%s %q %x %X), it is treated identically to a string, as a single item. + +To avoid recursion in cases such as + + type X string + func (x X) String() string { return Sprintf("<%s>", x) } + +convert the value before recurring: + + func (x X) String() string { return Sprintf("<%s>", string(x)) } + +Infinite recursion can also be triggered by self-referential data +structures, such as a slice that contains itself as an element, if +that type has a String method. Such pathologies are rare, however, +and the package does not protect against them. + +When printing a struct, fmt cannot and therefore does not invoke +formatting methods such as Error or String on unexported fields. + +# Explicit argument indexes + +In Printf, Sprintf, and Fprintf, the default behavior is for each +formatting verb to format successive arguments passed in the call. +However, the notation [n] immediately before the verb indicates that the +nth one-indexed argument is to be formatted instead. The same notation +before a '*' for a width or precision selects the argument index holding +the value. After processing a bracketed expression [n], subsequent verbs +will use arguments n+1, n+2, etc. unless otherwise directed. + +For example, + + fmt.Sprintf("%[2]d %[1]d\n", 11, 22) + +will yield "22 11", while + + fmt.Sprintf("%[3]*.[2]*[1]f", 12.0, 2, 6) + +equivalent to + + fmt.Sprintf("%6.2f", 12.0) + +will yield " 12.00". Because an explicit index affects subsequent verbs, +this notation can be used to print the same values multiple times +by resetting the index for the first argument to be repeated: + + fmt.Sprintf("%d %d %#[1]x %#x", 16, 17) + +will yield "16 17 0x10 0x11". + +# Format errors + +If an invalid argument is given for a verb, such as providing +a string to %d, the generated string will contain a +description of the problem, as in these examples: + + Wrong type or unknown verb: %!verb(type=value) + Printf("%d", "hi"): %!d(string=hi) + Too many arguments: %!(EXTRA type=value) + Printf("hi", "guys"): hi%!(EXTRA string=guys) + Too few arguments: %!verb(MISSING) + Printf("hi%d"): hi%!d(MISSING) + Non-int for width or precision: %!(BADWIDTH) or %!(BADPREC) + Printf("%*s", 4.5, "hi"): %!(BADWIDTH)hi + Printf("%.*s", 4.5, "hi"): %!(BADPREC)hi + Invalid or invalid use of argument index: %!(BADINDEX) + Printf("%*[2]d", 7): %!d(BADINDEX) + Printf("%.[2]d", 7): %!d(BADINDEX) + +All errors begin with the string "%!" followed sometimes +by a single character (the verb) and end with a parenthesized +description. + +If an Error or String method triggers a panic when called by a +print routine, the fmt package reformats the error message +from the panic, decorating it with an indication that it came +through the fmt package. For example, if a String method +calls panic("bad"), the resulting formatted message will look +like + + %!s(PANIC=bad) + +The %!s just shows the print verb in use when the failure +occurred. If the panic is caused by a nil receiver to an Error +or String method, however, the output is the undecorated +string, "<nil>". + +# Scanning + +An analogous set of functions scans formatted text to yield +values. Scan, Scanf and Scanln read from os.Stdin; Fscan, +Fscanf and Fscanln read from a specified io.Reader; Sscan, +Sscanf and Sscanln read from an argument string. + +Scan, Fscan, Sscan treat newlines in the input as spaces. + +Scanln, Fscanln and Sscanln stop scanning at a newline and +require that the items be followed by a newline or EOF. + +Scanf, Fscanf, and Sscanf parse the arguments according to a +format string, analogous to that of Printf. In the text that +follows, 'space' means any Unicode whitespace character +except newline. + +In the format string, a verb introduced by the % character +consumes and parses input; these verbs are described in more +detail below. A character other than %, space, or newline in +the format consumes exactly that input character, which must +be present. A newline with zero or more spaces before it in +the format string consumes zero or more spaces in the input +followed by a single newline or the end of the input. A space +following a newline in the format string consumes zero or more +spaces in the input. Otherwise, any run of one or more spaces +in the format string consumes as many spaces as possible in +the input. Unless the run of spaces in the format string +appears adjacent to a newline, the run must consume at least +one space from the input or find the end of the input. + +The handling of spaces and newlines differs from that of C's +scanf family: in C, newlines are treated as any other space, +and it is never an error when a run of spaces in the format +string finds no spaces to consume in the input. + +The verbs behave analogously to those of Printf. +For example, %x will scan an integer as a hexadecimal number, +and %v will scan the default representation format for the value. +The Printf verbs %p and %T and the flags # and + are not implemented. +For floating-point and complex values, all valid formatting verbs +(%b %e %E %f %F %g %G %x %X and %v) are equivalent and accept +both decimal and hexadecimal notation (for example: "2.3e+7", "0x4.5p-8") +and digit-separating underscores (for example: "3.14159_26535_89793"). + +Input processed by verbs is implicitly space-delimited: the +implementation of every verb except %c starts by discarding +leading spaces from the remaining input, and the %s verb +(and %v reading into a string) stops consuming input at the first +space or newline character. + +The familiar base-setting prefixes 0b (binary), 0o and 0 (octal), +and 0x (hexadecimal) are accepted when scanning integers +without a format or with the %v verb, as are digit-separating +underscores. + +Width is interpreted in the input text but there is no +syntax for scanning with a precision (no %5.2f, just %5f). +If width is provided, it applies after leading spaces are +trimmed and specifies the maximum number of runes to read +to satisfy the verb. For example, + + Sscanf(" 1234567 ", "%5s%d", &s, &i) + +will set s to "12345" and i to 67 while + + Sscanf(" 12 34 567 ", "%5s%d", &s, &i) + +will set s to "12" and i to 34. + +In all the scanning functions, a carriage return followed +immediately by a newline is treated as a plain newline +(\r\n means the same as \n). + +In all the scanning functions, if an operand implements method +Scan (that is, it implements the Scanner interface) that +method will be used to scan the text for that operand. Also, +if the number of arguments scanned is less than the number of +arguments provided, an error is returned. + +All arguments to be scanned must be either pointers to basic +types or implementations of the Scanner interface. + +Like Scanf and Fscanf, Sscanf need not consume its entire input. +There is no way to recover how much of the input string Sscanf used. + +Note: Fscan etc. can read one character (rune) past the input +they return, which means that a loop calling a scan routine +may skip some of the input. This is usually a problem only +when there is no space between input values. If the reader +provided to Fscan implements ReadRune, that method will be used +to read characters. If the reader also implements UnreadRune, +that method will be used to save the character and successive +calls will not lose data. To attach ReadRune and UnreadRune +methods to a reader without that capability, use +bufio.NewReader. +*/ +package fmt |