Go fmt包 翻譯

Fmt包

import "fmt"

簡介▾

Package fmt包含有格式化I/O函數，類似於C語言的printf和scanf。格式字串的規則來源於C但更簡單一些。

輸出

格式：

一般：

%v   基本格式的值。當輸出結構體時，擴充標誌(%+v)新增成員的名字。the value in a default format.

     when printing structs, the plus flag (%+v) adds field names

%#v  值的Go文法表示。

%T   值的類型的Go文法表示。

%%   百分比符號。

布爾型：

%t   值的true或false

整型：

%b   二進位表示

%c   數值對應的Unicode編碼字元

%d   十進位表示

%o   八進位表示

%q   單引號

%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格式（以獲得更簡潔的輸出）

%G   根據實際情況採用%E或%f格式（以獲得更簡潔的輸出）

字串和byte切片類型：

%s   直接輸出字串或者[]byte

%q   雙引號括起來的字串

%x   每個位元組用兩字元十六進位數表示（使用小寫a-f）

%X   每個位元組用兩字元十六進位數表示（使用大寫A-F）

指標：

%p   0x開頭的十六進位數表示

木有'u'標誌。如果是無類型整數，自然會列印無類型格式。類似的，沒有必要去區分運算元的大小(int8, int64)。

寬度和精度格式化控制是指的Unicode編碼字元的數量（不同於C的printf，它的這兩個因子指的是位元組的數量。）兩者均可以使用'*'號取代（任一個或兩個都），此時它們的值將被緊接著的參數控制，這個運算元必須是整型。

對於數字，寬度設定總長度，精度設定小數部分長度。例如，格式%6.2f 輸出123.45。

對於字串，寬度是輸出字元數目的最低數量，如果不足會用空格填充。精度是輸出字元數目的最大數量，超過則會截斷。

其它符號：

+    總是輸出數值的加號或減號；對%q(%+q)將保證純ASCII碼輸出

-    用空格在右側填充空缺而不是預設的左側。

#    切換格式：在八進位前加0(%#o)，十六進位前加0x(%#x)或0X(%#X)；廢除指標的0x(%#p)；

     對%q (%#q)如果可能的話輸出一個無修飾的字串；

     對%U(%#U)如果對應數值是可列印字元輸出該字元。

' '  對數字(% d)空格會留一個空格在數字前並忽略數位加號或減號；

     對切片和字串(% x, % X)會以16進位輸出。

0    用前置0代替空格填補空缺。

每一個類似Printf的函數，都會有一個同樣的Print函數，此函數不需要format字串，等價於對每一個參數設定為%v。另一個變體Println會在參數之間加上空格並在輸出結束後換行。

如果參數是一個介面值，將使用內在的具體實現的值，而不是介面本身，%v參數不會被使用。如下：

var i interface{} = 23

fmt.Printf("%v\n", i)

將輸出23。

如果參數實現了Formatter介面，該介面可用來更好的控制格式化。

如果格式（標誌對Println等是隱含的%v）是專用於字串的(%s %q %v %x %X)，還提供了如下兩個規則：

1. 如果一個參數實現了error介面，Error方法會用來將目標轉化為字串，隨後將被按給出的要求格式化。

2. 如果參數提供了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)

使用非整數提供寬度和精度: %!(BADWIDTH) or %!(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, and Sscanf根據格式字串解析資料，類似於Printf。例如，%x將讀取一個十六進位數，%v將讀取值的預設表示。

格式行為類似於Printf，但有如下例外：

%p沒有提供

%T沒有提供

%e %E %f %F %g %G是等價的，都可以讀取任何浮點數或者複合數（非複數，指科學計數法表示的帶指數的數）

%s 和 %v字串使用這兩個格式讀取時會因為空白格而結束

不設格式或者使用%v讀取整數時，如果首碼為0(八進位)或0x(十六進位)，將按對應進位讀取。

寬度在輸入中被解釋（%5s意思是最多從輸入讀取5個字元賦值給一個字串），但輸入系列函數沒有解釋精度的文法(木有%5.2f，只有%5f)。

輸入系列函數中的格式字串，所有非空的空白字元（除了分行符號之外），無論在輸入裡還是格式字串裡，都等價於1個空白字元。格式字串必須匹配輸入的文本，如果不匹配將停止讀取資料並返回函數已經賦值的參數的數量。

所有的scan系列函數，如果參數包含Scan方法（或者說實現了Scanner介面），該參數將使用該方法讀取文本。另外，如果被填寫的參數的數量少於提供的參數的數量，將返回一個錯誤。

所有要被輸入的參數都應該是基礎類型或者實現了Scanner介面的資料類型的指標。

注意：Fscan等函數可以從輸入略過一些字元讀取需要的字元並返回，這就意味著一個迴圈的讀取程式可能會跳過輸入的部分資料。當資料間沒有空白時就會導致出現問題。如果讀取這提供給Fscan系列函數ReadRune 方法，這個方法可以用來讀取字元。如果讀取者還提供了UnreadRune 方法，該方法將被用來儲存字元以使成功的調用不會遺失資料。為了給一個沒有這些功能的讀取者添加這倆方法，使用bufio.NewReader。

目錄

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

type Formatter

type GoStringer

type ScanState

type Scanner

type State

type Stringer

Package files

doc.go format.go print.go scan.go

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讀取文本，根據格式字串順序將資料存入參數中。它返回成功解析並存入的參數的數量。

func Fscanln

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

Fscanln類似Fscanf，但會在分行符號中止，並且存入最後一條後時讀取位置必須有換行或者結束符。

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從標準輸入讀取文本，根據格式字串順序將資料存入參數中。它返回成功解析並存入的參數的數量。

func Scanln

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

Scanln類似Scan，但會在分行符號中止，並且存入最後一條後時讀取位置必須有換行或者結束符。

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從字串讀取文本，將空白分割的連續資料順序存入參數裡。換行視同空白。它返回成功讀取的參數的數量。如果少於提供的參數的數量，傳回值err將報告原因。

func Sscanf

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

Scanf從字串讀取文本，根據格式字串順序將資料存入參數中。它返回成功解析並存入的參數的數量。

func Sscanln

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

Sscanln類似Sscan，但會在分行符號中止，並且存入最後一條後時讀取位置必須有換行或者結束符。

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函數從輸入讀取下一個Unicode符號。如果在Scanln，Fscanln或Sscanln中調用，本函數會在讀取到第一個'\n'或達到最大寬度時返回EOF。

    ReadRune() (r rune, size int, err error)

    // UnreadRune會讓ReadRune的下一次調用返回同一個字元。

    UnreadRune() error

    // SkipSpace跳過輸入的空白。換行被視為空白（Scanln，Fscanln和Sscanln例外，這三個函數裡分行符號視為EOF）。

    SkipSpace()

    // Token方法會在skipSpace為真時跳過輸入中的空白，並返回一個滿足f(c)的Unicode字元。如果f是nil，則使用!unicode.IsSpace(c)（即返回第一個非空格Unicode字元）；

    // 即是說，本函數只對非Null 字元起效。分行符號視為空白字元（Scanln，Fscanln和Sscanln例外，這三個函數裡分行符號視為EOF）。

    // 返回的切片類型指向共用的資料，該資料可以被下一次Token的調用（使用ScanState介面作為輸入調用Scan函數）中或者調用返回的Scan方法時重寫。

    Token(skipSpace bool, f func(rune) bool) (token []byte, err error)

    // Width返回width選項的值以及其是否被設定。

    Width() (wid int, ok bool)

    // 因為ReadRune用介面實現，Read方法應該永遠不被scan程式調用，一個好使的ScanState實現應該保證總是從Read返回錯誤。

    Read(buf []byte) (n int, err error)

}

ScanState是一個交給使用者定製的Scanner介面的參數的介面。Scanner介面可能會進行一次一個字元的掃描或者要求ScanState去探測下一個空白分隔的token。

type Scanner

type Scanner interface {

    Scan(state ScanState, verb rune) error

}

任何實現了Scan方法的對象都實現了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返回符號（加號或減號……）的值是否被設定。

    Flag(c int) bool

}

State是一個提供給Formatter介面的輸出參數的介面。它提供對io.Writer介面的、使用提供的資料對參數格式化後的訪問。

type Stringer

type Stringer interface {

    String() string

}

Stringer介面被任何實現了String方法的類型自動實現，該方法定義了該類型的“原生”格式。String方法用來輸出參數，當使用%s或%v格式時，或者被Print等不使用格式字串的函數輸出時。