import "fmt"

fmtパッケージは、フォーマットI/Oを実装しており、C言語のprintfおよびscanfと似た関数を持ちます。フォーマットの「書式」はC言語から派生していますが、より単純化されています。

【書式化】

書式:

汎用:

%v	デフォルトフォーマットを適用した値
	構造体を出力する際、+フラグ(%+v)を加えるとフィールド名が表示される
%#v	この値をGo言語の構文で表現する
%T	この値の型をGo言語の構文で表現する

論理値:

%t	単語、trueまたはfalse

整数:

%b	基数2
%c	対応するUnicodeコードポイントによって表される文字
%d	基数10
%o	基数8
%x	基数16、10以上の数には小文字(a-f)を使用
%X	基数16、10以上の数には大文字(A-F)を使用
%U	ユニコードフォーマット: U+1234; "U+%x"と同じ。デフォルトは、4桁

浮動小数と複素数

%e	科学的記数法、例: -1234.456e+78
%E	科学的記数法、例: -1234.456E+78
%f	指数なしの小数、例: 123.456
%g	%e、%fのどちらか出力の短い方
%G	%E、%fのどちらか出力の短い方

文字列とバイト型のスライス

%s	文字列またはスライスそのまま
%q	Go言語の構文に従いダブルクォート形式でエスケープ
%x	各バイトを2文字の16進数文字列として

ポインタ

%p	16進数文字列、先頭に0x

‘u’フラグはありません。整数が符号なしの型であれば、符号なしとして出力されます。同様にオペランド(int8, int64)のサイズを指定する必要はありません。

数値のとき、桁数と精度のフラグを使ってフォーマットの制御を行います。「桁数」にはフィールドの桁数を、「精度」は必要に応じて小数点以降の桁数を設定します。フォーマット%6.2fのとき、123.45と出力されます。このフィールドの桁数は、文字列のUnicodeコードポイントの数です。一方、C言語のprintfでのフィールドの桁数はバイト数です。フラグの片方、もしくは両方を、文字「*」としたときは、これらの値は、次のオペランド(int型でなけれればならない)から取得されます。

その他のフラグ:

+	数値型のとき、常に符号を出力
-	パッドのスペースを左側ではなく右側に出力(フィールドの左寄せ)
#	フォーマットの切替: 8進数(%#o)のとき先頭に0、16進数(%#x)のとき先頭に0x、
	16進数(%#X)のとき先頭に0Xを出力。%p (%#p)のときは0xを出力しない。
        %q (%#q)のとき、出力可能であれば生(シングルクォートされた)文字列を出力
' '	(スペース) 数値で、符号が出力されなかったときに代わりにスペースを出力(% d)、
	文字列またはスライスを16進数で出力したときにバイト間にスペースを出力(% x, % X)
0	パッドとしてスペースの代わりに0を出力

各Printf系の関数には、フォーマットを指定する代わりに、全オペランドに%vを指定したことと等しいPrint関数がそれぞれ用意されています。同様に亜種であるPrintln関数は、オペランド間に空白を挿入し、最後に改行文字を出力します。

書式に関係なく、オペランドがインタフェース値であるときは、インタフェースそのものではなく、その中で実装されている値が使われます。例です:

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

これは23と出力されます。

オペランドがFormatterインタフェースを実装していれば、フォーマットする際に細かい制御を行うことができます。

オペランドがString() stringメソッドを実装しているときは、オブジェクトを文字列に変換するために使われます。その後、必要に応じて書式(指定されていれば)によってフォーマットされます。次のようなケースで、再帰が起こらないよう注意してください。

type X int
func (x X) String() string { return Sprintf("%d", x) }

再帰する前に、キャストしてください。

func (x X) String() string { return Sprintf("%d", int(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は、指定したos.Readerから読み込みます。Sscan、Sscanf、Sscanlnは、引数の文字列から読み込みます。Sscanln、Fscanln、Sscanlnは、改行文字でスキャンを停止するため、項目の後ろには改行文字が必須です。Sscanf、 Fscanf、Sscanfは、フォーマットの改行文字とマッチングさせるため、入力内に改行文字が必要です。それ以外の関数では、改行文字はスペースとして扱われます。

Scanf、Fscanf、Sscanfは、フォーマット文字列に従い、Printfとおなじく引数を解析します。たとえば、%xは、16進数文字列を整数としてスキャンし、%vは、その値のデフォルト表現フォーマットでスキャンします。

このフォーマットは、次の例外をのぞき、Printfのフォーマットと同じように扱われます。:

%pは、実装されていません。%Tは、実装されていません。%e %E %f %F %g %gは、すべて同一で、浮動小数点、または複素数をスキャンします。%s と %vで文字列をスキャンしたときは、トークンはスペースで区切られているとみなします。
桁数は、入力テキストの桁数として解釈されます。たとえば、%5sは、文字列をスキャンするため、最大5つのルーンを入力から読み込むことを意味します。ただし、スキャンの際に精度を指定する文法は用意されていません。(%5.2fとは書けず、%5fと書きます)

フォーマットによるスキャンにおいて、スペース文字が連続したルーン(改行文字を除く)は、フォーマット文字列、入力共に「ひとつのスペース」と等価です。フォーマット文字列内のテキストは、この条件下で、入力からのテキストと一致しなければなりません。一致しないときは、スキャンは停止され、スキャン済みの引数の数を示す値を関数から返します。

すべてのスキャン関数において、オペランドがScanメソッドを実装する(すなわち、Scannerインタフェースを実装する)とき、そのScanメソッドが、オペランドのテキストをスキャンするために使われます。また、指定した引数の数より、スキャンされた数が少ないときは、エラーが返されます。

スキャンに使われる引数はすべて、基本型へのポインタか、もしくはスキャナインタフェースを実装している必要があります。

注:Fscanなどは、入力から一文字(ルーン)余計に読み出すことがあります。これは、ループでスキャンルーチンを呼び出すと、数バイトがスキップされる可能性があることを示しています。これは通常、入力値の間にスペースがないときだけの問題です。ただし、Fscanに与えたreaderがUnreadRuneを実装していれば、このメソッドによって文字が保持され、連続した呼び出しにおいてデータが失われることを防げます。readerの機能を失うことなく、UnreadRuneメソッドを持たせるには、bufio.NewReaderを使ってください。

パッケージファイル

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

定数

const EOF = -1

Errorf関数

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

Errorfは、指定したフォーマットに従いフォーマットし、os.Errorインタフェースを満たすos.ErrorStringへ文字列を変換して返します。

Fprint関数

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

Fprintは、オペランドをデフォルトのフォーマットでフォーマットし、wに書きこみます。オペランドがどちらも文字列でないときは、間にスペースを挿入します。この関数は、書き込んだバイト数と発生した書き込みエラーを返します。

Fprintf関数

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

Fprintfは、指定されたフォーマットに従ってフォーマットを行い、wに書きこみます。この関数は、書き込んだバイト数と発生した書き込みエラーを返します。

Fprintln関数

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

Fprintlnは、オペランドをデフォルトのフォーマットでフォーマットし、wに書きこみます。オペランド間には常にスペースが挿入され、最後に改行文字を出力します。この関数は、書き込んだバイト数と発生した書き込みエラーを返します。

Fscan関数

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

Fscanは、rから読み込んだテキストをスキャンし、スペースで区切られた値として、順に引数に格納します。改行文字はスペースとしてカウントされます。この関数はスキャンに成功した項目数を返します。この数が、引数の数より少ないときは、errにその理由を返します。

Fscanf関数

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

Fscanfは、rから読み込んだテキストをスキャンし、フォーマットに従い、スペースで区切られた値として、順に引数に格納します。この関数はスキャンに成功した項目数を返します。

Fscanln関数

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

Fscanlnは、Fscanと同じですが、改行文字でスキャンを停止します。そのため、最後の項目の後ろは、改行文字かEOFでなければなりません。

Print関数

func Print(a ...interface{}) (n int, errno os.Error)

Printは、オペランドをデフォルトのフォーマットでフォーマットし、標準出力に書きこみます。オペランドがどちらも文字列でないときは、間にスペースを挿入します。この関数は、書き込んだバイト数と発生した書き込みエラーを返します。

Printf関数

func Printf(format string, a ...interface{}) (n int, errno os.Error)

Printf は、指定されたフォーマットに従ってフォーマットを行い、標準出力に書きこみます。この関数は、書き込んだバイト数と発生した書き込みエラーを返します。

Println関数

func Println(a ...interface{}) (n int, errno os.Error)

Printlnは、オペランドをデフォルトのフォーマットでフォーマットし、標準出力に書きこみます。オペランド間には常にスペースが挿入され、最後に改行文字を出力します。この関数は、書き込んだバイト数と発生した書き込みエラーを返します。

Scan関数

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

Scanは、標準入力から読み込んだテキストをスキャンし、スペースで区切られた値として、順に引数に格納します。改行文字はスペースとしてカウントされます。この関数はスキャンに成功した項目数を返します。この数が、引数の数より少ないときは、errにその理由を返します。

Scanf関数

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

Scanfは、標準入力から読み込んだテキストをスキャンし、フォーマットに従い、スペースで区切られた値として、順に引数に格納します。この関数はスキャンに成功した項目数を返します。

Scanln関数

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

Scanlnは、Scanと同じですが、改行文字でスキャンを停止します。そのため、最後の項目の後ろは、改行文字かEOFでなければなりません。

Sprint関数

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

Sprintは、オペランドをデフォルトのフォーマットでフォーマットし、結果を文字列で返します。オペランドがどちらも文字列でないときは、間にスペースを挿入します。

Sprintf関数

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

Sprintfは、指定されたフォーマットに従ってフォーマットを行い、結果を文字列で返します。

Sprintln関数

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

Sprintlnは、オペランドをデフォルトのフォーマットでフォーマットし、結果を文字列で返します。オペランド間には常にスペースが挿入され、最後に改行文字を出力します。

Sscan関数

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

Sscanは、引数の文字列をススキャンし、スペースで区切られた値として、順に引数に格納します。改行文字はスペースとしてカウントされます。この関数はスキャンに成功した項目数を返 します。この数が、引数の数より少ないときは、errにその理由を返します。

Sscanf関数

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

Sscanfは、引数の文字列をスキャンし、フォーマットに従い、スペースで区切られた値として、順に引数に格納します。この関数はスキャンに成功した項目数を返します。

Sscanln関数

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

Sscanlnは、Scanと同じですが、改行文字でスキャンを停止します。そのため、最後の項目の後ろは、改行文字かEOFでなければなりません。

Formatter型

Formatterは、カスタムフォーマッタを持つ値に実装されるインタフェースです。実装したFormatメソッドはSprintfやFprintf(f)などから呼び出され、各々の出力を生成します。

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

GoStringer型

GoStringerは、値のGo言語の構文を規定するGoString()メソッドによって実装されます。GoStringメソッドは、%#vフォーマットへ渡されたオペランドの値を出力するために使われます。

type GoStringer interface {
    GoString() string
}

ScanState型

ScanStateは、カスタムスキャナに渡されるスキャナの状態を表します。スキャナでは、一つのルーンをスキャンをするか、もしくはScanStateに次のスペースで区切られたトークンを見つけるよう依頼します。

type ScanState interface {
    // GetRuneは、入力から次のルーン(Unicodeコードポイント)を読み込みます。
    GetRune() (rune int, err os.Error)
    // UngetRuneは、次回のGetRuneの呼び出しでこのルーンが返されるようにします。
    UngetRune()
    // Widthは、桁数オプションの値と、それが設定されているかを返します。
    // 単位は、Unicodeコードポイントです。
    Width() (wid int, ok bool)
    // Tokenは、入力からスペースで区切り換算で、次のトークンを返します。
    // 桁数が指定されているときは、返されるトークンがその桁数を
    // 超えることはありません。
    Token() (token string, err os.Error)
}

Scanner型

Scanメソッドを持つ値によって実装されるScannerは、入力をスキャンして値を取得し、その結果をレシーバに格納します。そのため、レシーバはポインタでなければなりません。ScanまたはScanln関数への引数が、このScannerインタフェースを実装しているときにScanメソッドが呼び出されます。

type Scanner interface {
    Scan(state ScanState, verb int) os.Error
}

State型

Stateは、カスタムフォーマッタに渡される出力状態を表します。これはio.Writerインタフェースへのアクセスに加え、オペランドのフォーマットで指定されているフラグとオプション情報を提供します。

type State interface {
    // Writeは、フォーマット結果を出力するために呼び出す関数です。
    Write(b []byte) (ret int, err os.Error)
    // Widthは、桁数オプションの値と、それが設定されているかを返します。
    Width() (wid int, ok bool)
    // Precisionは、精度オプションの値と、それが設定されているかを返します。
    Precision() (prec int, ok bool)

    // Flagは、フラグ(文字)がセットされているかどうかを返します。
    Flag(int) bool
}

Stringer型

Stringerは、値の「ネイティブ」フォーマットを規定するString ()メソッドによって実装されます。このStringメソッドは、%s、%vフォーマットまたはPrintのようなフォーマットを伴わない出力メソッドに渡された値を出力するときに使われます。

type Stringer interface {
    String() string
}