diff options
Diffstat (limited to 'src/pkg/fmt/doc.go')
| -rw-r--r-- | src/pkg/fmt/doc.go | 272 |
1 files changed, 0 insertions, 272 deletions
diff --git a/src/pkg/fmt/doc.go b/src/pkg/fmt/doc.go deleted file mode 100644 index 02642d6ae..000000000 --- a/src/pkg/fmt/doc.go +++ /dev/null @@ -1,272 +0,0 @@ -// 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 - %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. -1234.456e+78 - %E scientific notation, e.g. -1234.456E+78 - %f decimal point but no exponent, e.g. 123.456 - %F synonym for %f - %g whichever of %e or %f produces more compact output - %G whichever of %E or %f produces more compact output - String and slice of bytes: - %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 - Pointer: - %p base 16 notation, with leading 0x - - There is no 'u' flag. Integers are printed unsigned if they have unsigned type. - Similarly, there is no need to specify the size of the operand (int8, int64). - - Width is specified by an optional decimal number immediately following 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. - (This differs from C's printf where the units are numbers - of bytes.) Either or both of the flags may be replaced with the - character '*', causing their values to be obtained from the next - operand, which must be of type int. - - For most values, width is the minimum number of characters to output, - padding the formatted form with spaces if necessary. - For strings, precision is the maximum number of characters to output, - truncating if necessary. - - 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 it sets the total number of digits. For example, - given 123.45 the format %6.2f prints 123.45 while %.4g prints 123.5. - The default precision for %e and %f 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). - - 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 0 for octal (%#o), 0x for hex (%#x); - 0X for hex (%#X); suppress 0x for %p (%#p); - for %q, print a raw (backquoted) string if strconv.CanBackquote - returns true; - 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 - - 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 an operand implements the Formatter interface, it will - be invoked. Formatter provides fine control of formatting. - - 2. 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: - - 3. 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). - - 4. 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. - - 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)) } - - 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], arguments n+1, - n+2, etc. will be processed 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. - - 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. Scanln, - Fscanln and Sscanln stop scanning at a newline and require that - the items be followed by one; Scanf, Fscanf and Sscanf require - newlines in the input to match newlines in the format; the other - routines treat newlines as spaces. - - Scanf, Fscanf, and Sscanf parse the arguments according to a - format string, analogous to that 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 formats behave analogously to those of Printf with the - following exceptions: - - %p is not implemented - %T is not implemented - %e %E %f %F %g %G are all equivalent and scan any floating point or complex value - %s and %v on strings scan a space-delimited token - Flags # and + are not implemented. - - The familiar base-setting prefixes 0 (octal) and 0x - (hexadecimal) are accepted when scanning integers without a - format or with the %v verb. - - Width is interpreted in the input text (%5s means at most - five runes of input will be read to scan a string) but there - is no syntax for scanning with a precision (no %5.2f, just - %5f). - - When scanning with a format, all non-empty runs of space - characters (except newline) are equivalent to a single - space in both the format and the input. With that proviso, - text in the format string must match the input text; scanning - stops if it does not, with the return value of the function - indicating the number of arguments scanned. - - 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. - - 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 |