...

Package fmt

import "fmt"
概览
索引

概览 ▾

fmt 包实现了格式化I/O函数,类似于C的 printf 和 scanf. 格式“占位符”衍生自C,但比C更简单。

打印

占位符:

一般:

%v	相应值的默认格式。在打印结构体时,“加号”标记(%+v)会添加字段名
%#v	相应值的Go语法表示
%T	相应值的类型的Go语法表示
%%	字面上的百分号,并非值的占位符

布尔:

%t	单词 true 或 false。

整数:

%b	二进制表示
%c	相应Unicode码点所表示的字符
%d	十进制表示
%o	八进制表示
%q	单引号围绕的字符字面值,由Go语法安全地转义
%x	十六进制表示,字母形式为小写 a-f
%X	十六进制表示,字母形式为大写 A-F
%U	Unicode格式:U+1234,等同于 "U+%04X"

浮点数及其复合构成:

%b	无小数部分的,指数为二的幂的科学计数法,与 strconv.FormatFloat
	的 'b' 转换格式一致。例如 -123456p-78
%e	科学计数法,例如 -1234.456e+78
%E	科学计数法,例如 -1234.456E+78
%f	有小数点而无指数,例如 123.456
%g	根据情况选择 %e 或 %f 以产生更紧凑的(无末尾的0)输出
%G	根据情况选择 %E 或 %f 以产生更紧凑的(无末尾的0)输出

字符串与字节切片:

%s	字符串或切片的无解译字节
%q	双引号围绕的字符串,由Go语法安全地转义
%x	十六进制,小写字母,每字节两个字符
%X	十六进制,大写字母,每字节两个字符

指针:

%p	十六进制表示,前缀 0x

这里没有 'u' 标记。若整数为无符号类型,他们就会被打印成无符号的。类似地, 这里也不需要指定操作数的大小(int8,int64)。

宽度与精度的控制格式以Unicode码点为单位。(这点与C的 printf 不同, 它以字节数为单位。)二者或其中之一均可用字符 '*' 表示, 此时它们的值会从下一个操作数中获取,该操作数的类型必须为 int。

对数值而言,宽度为该数值占用区域的最小宽度;精度为小数点之后的位数。 但对于 %g/%G 而言,精度为所有数字的总数。例如,对于123.45,格式 %6.2f 会打印123.45,而 %.4g 会打印123.5。%e 和 %f 的默认精度为6;但对于 %g 而言, 它的默认精度为确定该值所必须的最小位数。

对大多数值而言,宽度为输出的最小字符数,如果必要的话会为已格式化的形式填充空格。 对字符串而言,精度为输出的最大字符数,如果必要的话会直接截断。

其它标记:

+	总打印数值的正负号;对于%q(%+q)保证只输出ASCII编码的字符。
-	在右侧而非左侧填充空格(左对齐该区域)
#	备用格式:为八进制添加前导 0(%#o),为十六进制添加前导 0x(%#x)或
	0X(%#X),为 %p(%#p)去掉前导 0x;对于 %q,若 strconv.CanBackquote
	返回 true,就会打印原始(即反引号围绕的)字符串;如果是可打印字符,
	%U(%#U)会写出该字符的Unicode编码形式(如字符 x 会被打印成 U+0078 'x')。
' '	(空格)为数值中省略的正负号留出空白(% d);
	以十六进制(% x, % X)打印字符串或切片时,在字节之间用空格隔开
0	填充前导的0而非空格;
	对于数字,这会将填充移到正负号之后

标记有事会被占位符忽略,所以不要指望它们。例如十进制没有备用格式,因此 %#d 与 %d 的行为相同。

对于每一个 Printf 类的函数,都有一个 Print 函数,该函数不接受任何格式化, 它等价于对每一个操作数都应用 %v。另一个变参函数 Println 会在操作数之间插入空白, 并在末尾追加一个换行符。

不考虑占位符的话,如果操作数是接口值,就会使用其内部的具体值,而非接口本身。 因此:

var i interface{} = 23
fmt.Printf("%v\n", i)

会打印 23。

若一个操作数实现了 Formatter 接口,该接口就能更好地用于控制格式化。

若其格式(它对于 Println 等函数是隐式的 %v)对于字符串是有效的 (%s %q %v %x %X),以下两条规则也适用:

1. 若一个操作数实现了 error 接口,Error 方法就能将该对象转换为字符串, 随后会根据占位符的需要进行格式化。

2. 若一个操作数实现了 String() string 方法,该方法能将该对象转换为字符串, 随后会根据占位符的需要进行格式化。

为避免以下这类递归的情况:

type X string
func (x X) String() string { return Sprintf("<%s>", x) }

需要在递归前转换该值:

func (x X) String() string { return Sprintf("<%s>", string(x)) }

格式化错误:

如果给占位符提供了无效的实参(例如将一个字符串提供给 %d), 所生成的字符串会包含该问题的描述,如下例所示:

类型错误或占位符未知:%!verb(type=value)
	Printf("%d", hi):          %!d(string=hi)
实参太多:%!(EXTRA type=value)
	Printf("hi", "guys"):      hi%!(EXTRA string=guys)
实参太少: %!verb(MISSING)
	Printf("hi%d"):            hi %!d(MISSING)
宽度或精度不是int类型: %!(BADWIDTH) 或 %!(BADPREC)
	Printf("%*s", 4.5, "hi"):  %!(BADWIDTH)hi
	Printf("%.*s", 4.5, "hi"): %!(BADPREC)hi

所有错误都始于“%!”,有时紧跟着单个字符(占位符),并以小括号括住的描述结尾。

扫描

一组类似的函数通过扫描已格式化的文本来产生值。Scan、Scanf 和 Scanln 从 os.Stdin 中读取;Fscan、Fscanf 和 Fscanln 从指定的 io.Reader 中读取; Sscan、Sscanf 和 Sscanln 从实参字符串中读取。Scanln、Fscanln 和 Sscanln 在换行符处停止扫描,且需要条目紧随换行符之后;Scanf、Fscanf 和 Sscanf 需要输入换行符来匹配格式中的换行符;其它函数则将换行符视为空格。

Scanf、Fscanf 和 Sscanf 根据格式字符串解析实参,类似于 Printf。例如,%x 会将一个整数扫描为十六进制数,而 %v 则会扫描该值的默认表现格式。

格式化行为类似于 Printf,但也有如下例外:

%p 没有实现
%T 没有实现
%e %E %f %F %g %G 都完全等价,且可扫描任何浮点数或复合数值
%s 和 %v 在扫描字符串时会将其中的空格作为分隔符
标记 # 和 + 没有实现

在或使用 %v 占位符扫描整数时,可接受友好的进制前缀0(八进制)和0x(十六进制)。

宽度被解释为输入的文本(%5s 意为最多从输入中读取5个符文来扫描成字符串), 而扫描函数则没有精度的语法(没有 %5.2f,只有 %5f)。

当以某种格式进行扫描时,无论在格式中还是在输入中,所有非空的连续空白字符 (除换行符外)都等价于单个空格。由于这种限制,格式字符串文本必须匹配输入的文本, 如果不匹配,扫描过程就会停止,并返回已扫描的实参数。

在所有的扫描参数中,若一个操作数实现了 Scan 方法(即它实现了 Scanner 接口), 该操作数将使用该方法扫描其文本。此外,若已扫描的实参数少于所提供的实参数, 就会返回一个错误。

所有需要被扫描的实参都必须是基本类型或 Scanner 接口的实现。

注意:Fscan 等函数会从输入中多读取一个字符(符文),因此,如果循环调用扫描函数, 可能会跳过输入中的某些数据。一般只有在输入的数据中没有空白符时该问题才会出现。 若提供给 Fscan 的读取器实现了 ReadRune,就会用该方法读取字符。若此读取器还实现了 UnreadRune 方法,就会用该方法保存字符,而连续的调用将不会丢失数据。若要为没有 ReadRune 和 UnreadRune 方法的读取器加上这些功能,需使用 bufio.NewReader。

func Errorf

func Errorf(format string, a ...interface{}) error

Errorf 根据于格式说明符进行格式化并将字符串作为满足 error 的值返回。

func Fprint

func Fprint(w io.Writer, a ...interface{}) (n int, err error)

Fprint 使用其操作数的默认格式进行格式化并写入到 w。 当两个连续的操作数均不为字符串时,它们之间就会添加空格。 它返回写入的字节数以及任何遇到的错误。

func Fprintf

func Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)

Fprintf 根据于格式说明符进行格式化并写入到 w。 它返回写入的字节数以及任何遇到的写入错误。

func Fprintln

func Fprintln(w io.Writer, a ...interface{}) (n int, err error)

Fprintln 使用其操作数的默认格式进行格式化并写入到 w。 其操作数之间总是添加空格,且总在最后追加一个换行符。 它返回写入的字节数以及任何遇到的错误。

func Fscan

func Fscan(r io.Reader, a ...interface{}) (n int, err error)

Fscan 扫描从 r 中读取的文本,并将连续由空格分隔的值存储为连续的实参。 换行符计为空格。它返回成功扫描的条目数。若它少于实参数,err 就会报告原因。

func Fscanf

func Fscanf(r io.Reader, format string, a ...interface{}) (n int, err error)

Fscanf 扫描从 r 中读取的文本,并将连续由空格分隔的值存储为连续的实参, 其格式由 format 决定。它返回成功解析的条目数。

func Fscanln

func Fscanln(r io.Reader, a ...interface{}) (n int, err error)

Fscanln 类似于 Sscan,但它在换行符处停止扫描,且最后的条目之后必须为换行符或 EOF。

func Print

func Print(a ...interface{}) (n int, err error)

Print 使用其操作数的默认格式进行格式化并写入到标准输出。 当两个连续的操作数均不为字符串时,它们之间就会添加空格。 它返回写入的字节数以及任何遇到的错误。

func Printf

func Printf(format string, a ...interface{}) (n int, err error)

Printf 根据于格式说明符进行格式化并写入到标准输出。 它返回写入的字节数以及任何遇到的写入错误。

func Println

func Println(a ...interface{}) (n int, err error)

Println 使用其操作数的默认格式进行格式化并写入到标准输出。 其操作数之间总是添加空格,且总在最后追加一个换行符。 它返回写入的字节数以及任何遇到的错误。

func Scan

func Scan(a ...interface{}) (n int, err error)

Scan 扫描从标准输入中读取的文本,并将连续由空格分隔的值存储为连续的实参。 换行符计为空格。它返回成功扫描的条目数。若它少于实参数,err 就会报告原因。

func Scanf

func Scanf(format string, a ...interface{}) (n int, err error)

Scanf 扫描从标准输入中读取的文本,并将连续由空格分隔的值存储为连续的实参, 其格式由 format 决定。它返回成功扫描的条目数。若返回的条目数小于实参数, 则会报告错误原因 err。

func Scanln

func Scanln(a ...interface{}) (n int, err error)

Scanln 类似于 Scan,但它在换行符处停止扫描,且最后的条目之后必须为换行符或 EOF。

func Sprint

func Sprint(a ...interface{}) string

Sprint 使用其操作数的默认格式进行格式化并返回其结果字符串。 当两个连续的操作数均不为字符串时,它们之间就会添加空格。

func Sprintf

func Sprintf(format string, a ...interface{}) string

Sprintf 根据于格式说明符进行格式化并返回其结果字符串。

func Sprintln

func Sprintln(a ...interface{}) string

Sprintln 使用其操作数的默认格式进行格式化并写返回其结果字符串。 其操作数之间总是添加空格,且总在最后追加一个换行符。

func Sscan

func Sscan(str string, a ...interface{}) (n int, err error)

Sscan 扫描实参 string,并将连续由空格分隔的值存储为连续的实参。 换行符计为空格。它返回成功扫描的条目数。若它少于实参数,err 就会报告原因。

func Sscanf

func Sscanf(str string, format string, a ...interface{}) (n int, err error)

Scanf 扫描实参 string,并将连续由空格分隔的值存储为连续的实参, 其格式由 format 决定。它返回成功解析的条目数。

func Sscanln

func Sscanln(str string, a ...interface{}) (n int, err error)

Sscanln 类似于 Sscan,但它在换行符处停止扫描,且最后的条目之后必须为换行符或 EOF。

type Formatter

type Formatter interface {
    Format(f State, c rune)
}

Formatter 接口由带有定制的格式化器的值所实现。 Format 的实现可调用 Sprintf 或 Fprintf(f) 等函数来生成其输出。

type GoStringer

type GoStringer interface {
    GoString() string
}

GoStringer 接口由任何拥有 GoString 方法的值所实现,该方法定义了该值的Go语法格式。 GoString 方法用于打印作为操作数传至 %#v 进行格式化的值。

type ScanState

type ScanState interface {
    // ReadRune reads the next rune (Unicode code point) from the input.
    // If invoked during Scanln, Fscanln, or Sscanln, ReadRune() will
    // return EOF after returning the first '\n' or when reading beyond
    // the specified width.
    //
    // ReadRune 从输入中读取下一个符文(Unicode码点)。若它在 Scanln、Fscanln 或
    // Sscanln 中被调用,ReadRune() 就会在返回第一个“\n”或读取至指定宽度后返回 EOF。
    ReadRune() (r rune, size int, err error)
    // UnreadRune causes the next call to ReadRune to return the same rune.
    // UnreadRune 会使 ReadRune 的下一次调用返回相同的符文。
    UnreadRune() error
    // SkipSpace skips space in the input. Newlines are treated as space
    // unless the scan operation is Scanln, Fscanln or Sscanln, in which case
    // a newline is treated as EOF.
    //
    // SkipSpace 跳过输入中的空格。换行符会被视作空格,除非该扫描操作为 Scanln、
    // Fscanln 或 Sscanln,在这种情况下,换行符会被视作 EOF。
    SkipSpace()
    // Token skips space in the input if skipSpace is true, then returns the
    // run of Unicode code points c satisfying f(c).  If f is nil,
    // !unicode.IsSpace(c) is used; that is, the token will hold non-space
    // characters.  Newlines are treated as space unless the scan operation
    // is Scanln, Fscanln or Sscanln, in which case a newline is treated as
    // EOF.  The returned slice points to shared data that may be overwritten
    // by the next call to Token, a call to a Scan function using the ScanState
    // as input, or when the calling Scan method returns.
    //
    // Token 会在 skipSpace 为 true 时从输入中跳过空格,然后返回一系列满足 f(c)
    // 的Unicode码点 c。若 f 为 nil,就会使用 !unicode.IsSpace(c);
    // 即,该标记会保留非空格字符。换行符会被视作空格,除非该扫描操作为 Scanln、
    // Fscanln 或 Sscanln,否则在这种情况下,换行符会被视作 EOF。
    // 所返回的指向共享数据的切片可能会在下次调用 Token 时被覆盖,Scan 函数的调用
    // 会将 ScanState 用作输入,或当调用 Scan 方法返回时也会。
    Token(skipSpace bool, f func(rune) bool) (token []byte, err error)
    // Width returns the value of the width option and whether it has been set.
    // The unit is Unicode code points.
    // Width 返回宽度选项的值,并判断它是否被设置。其单元为Unicode码点。
    Width() (wid int, ok bool)
    // Because ReadRune is implemented by the interface, Read should never be
    // called by the scanning routines and a valid implementation of
    // ScanState may choose always to return an error from Read.
    //
    // 由于 ReadRune 被此接口实现,因此 Read 不应当被扫描功能调用,而 ScanState
    // 的有效实现可选择总是从 Read 中返回错误。
    Read(buf []byte) (n int, err error)
}

ScanState 表示传递给定制扫描器的扫描状态。扫瞄器可一次扫描一个附文或请求 ScanState 发现下一个以空格分隔的标记。

type Scanner

type Scanner interface {
    Scan(state ScanState, verb rune) error
}

Scanner 由任何拥有 Scan 方法的值实现,它将输入扫描成值的表示,并将其结果存储到接收者中, 该接收者必须为可用的指针。Scan 方法会被 Scan、Scanf 或 Scanln 的任何实现了它的实参所调用。

type State

type State interface {

    // Write 函数用于打印出已格式化的输出。
    Write(b []byte) (ret int, err error)

    // Width 返回宽度选项的值以及它是否已被设置。
    Width() (wid int, ok bool)

    // Precision 返回精度选项的值以及它是否已被设置。
    Precision() (prec int, ok bool)

    // Flag 返回标记 c(一个字符)是否已被设置。
    Flag(c int) bool
}

State 表示传递给格式化器的打印器的状态。 它提供了访问 io.Writer 接口及关于标记的信息,以及操作数的格式说明符选项。

type Stringer

type Stringer interface {
    String() string
}

Stringer 接口由任何拥有 String 方法的值所实现,该方法定义了该值的“原生”格式。 String 方法用于打印值,该值可作为操作数传至任何接受字符串的格式,或像 Print 这样的未格式化打印器。