...
Run Format

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

View as plain text