Go言語のPrintfとSprintf：fmtの書式指定子チートシート

fmt パッケージには表示関数のファミリーが3つあり、どのファミリーにも同じ3つの種類があります。

package main

import (
	"fmt"
	"os"
)

func main() {
	name, score := "Ana", 92.456

	fmt.Println("Player", name, "scored", score)
	fmt.Printf("Player %s scored %.1f\n", name, score)

	msg := fmt.Sprintf("%s: %.0f points", name, score)
	fmt.Println(msg, len(msg))

	fmt.Fprintf(os.Stdout, "%-6s|%6.2f|\n", name, score)

	err := fmt.Errorf("player %q not found", "Ben")
	fmt.Println(err)
}

Println はオペランドの間に空白を入れ、最後に改行を付けます。Printf は何も付けないので、\n を自分で書きます。Print は、両側とも文字列でないオペランドの間にだけ空白を入れます。これはかなり意外な挙動なので、ほとんどのコードは Println か Printf を使います。

書式指定子

汎用

package main

import "fmt"

type User struct {
	Name string
	Age  int
	Tags []string
}

func main() {
	u := User{Name: "Ana", Age: 31, Tags: []string{"admin"}}

	fmt.Printf("%v\n", u)
	fmt.Printf("%+v\n", u)
	fmt.Printf("%#v\n", u)
	fmt.Printf("%T\n", u)
	fmt.Printf("%v\n", &u)

	m := map[string]int{"b": 2, "a": 1}
	fmt.Printf("%v %#v\n", m, m)
}

デバッグのときに使うのは %+v です。構造体へのポインタはアドレスではなく &{...} として表示されます。マップはキーをソートして表示するので、マップの反復順がランダムでも出力は安定します。

整数

浮動小数点数

%.2f は浮動小数点数の正確な2進数の値を丸めるので、fmt.Sprintf("%.2f", 2.675) は 2.67 になります。2.675に最も近いfloat64は2.675よりわずかに小さいからです。お金を浮動小数点数から整形してはいけません。セントを整数で持ちます。

文字列とバイト

[]byte に %s を使うとテキストとして表示し、%v を使うと数値（[104 105]）を表示します。

その他の型

幅、精度、パディング

% と指定子の間に、フラグ、幅、精度を置けます。

package main

import "fmt"

func main() {
	fmt.Printf("|%5d|%-5d|%05d|\n", 42, 42, 42)
	fmt.Printf("|%8.2f|%-8.2f|%.0f|\n", 3.14159, 3.14159, 2.5)
	fmt.Printf("|%10s|%-10s|%.3s|\n", "gopher", "gopher", "gopher")
	fmt.Printf("|%+d|%+d|\n", 5, -5)
	fmt.Printf("|%*d|\n", 7, 42) // width from an argument

	fmt.Println()
	items := []struct {
		name  string
		price float64
	}{{"Keyboard", 49.9}, {"Mouse", 19.5}, {"Monitor", 229}}
	for _, it := range items {
		fmt.Printf("%-10s %8.2f\n", it.name, it.price)
	}
}

2.5 を %.0f で整形すると 2 になることに注意してください。ここでは0.5を偶数方向に丸めます。文字列の幅は表示上の桁数ではなくルーン数で数えるので、日本語などのCJK文字や絵文字では表の列がずれることがあります。可変長のテキストの列をそろえるなら、text/tabwriter が幅を測ってくれます。

引数のインデックス

%[n] は位置で引数を選ぶので、同じ引数を再利用できます。

fmt.Printf("%[2]s %[1]s\n", "world", "hello") // hello world
fmt.Printf("%d %[1]x %[1]b\n", 10)             // 10 a 1010

Errorfと%w

fmt.Errorf は書式文字列から error を作ります。%w を使うと別のエラーもラップするので、呼び出し側は元のエラーを検出できます。

package main

import (
	"errors"
	"fmt"
	"os"
)

func loadConfig(path string) error {
	_, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("load config %s: %w", path, err)
	}
	return nil
}

func main() {
	err := loadConfig("/no/such/file.yaml")
	fmt.Println(err)
	fmt.Println("not exist?", errors.Is(err, os.ErrNotExist))

	// %v formats the same text but does not wrap
	flat := fmt.Errorf("load config: %v", os.ErrNotExist)
	fmt.Println("wrapped?", errors.Is(flat, os.ErrNotExist))
}

呼び出し側が原因をチェックする必要がありそうなら %w を、意図的に隠すなら %v を使います。Go 1.20以降は、1つの Errorf 呼び出しに複数の %w を含められます。ラップについてはエラー処理のページで詳しく扱っています。

String()による独自の書式

String() string メソッドを持つ型は、%v、%s、Println での表示方法を自分で決められます。

package main

import "fmt"

type Money int64 // cents

func (m Money) String() string {
	return fmt.Sprintf("$%d.%02d", m/100, m%100)
}

func main() {
	price := Money(129950)
	fmt.Println(price)
	fmt.Printf("%v | %s | %d\n", price, price, price)
}

%d は String() を通らず、基底の数値を表示します。エラー型での同等のメソッドは Error() string で、String() より優先されます。

指定子が間違っているとき

fmt は書式が間違っていてもpanicしません。問題をその場に表示します。

fmt.Printf("%d\n", "oops")
fmt.Printf("%d %d\n", 1)
fmt.Printf("%d\n", 1, 2)

%!d(string=oops)
1 %!d(MISSING)
1
%!(EXTRA int=2)

何もクラッシュさせないので、この出力は本番環境まで届きがちです。go vet はビルド時に3つとも検出します。

./main.go:8:2: fmt.Printf format %d has arg "oops" of wrong type string
./main.go:9:2: fmt.Printf format %d reads arg #2, but call has 1 arg
./main.go:10:2: fmt.Printf call needs 1 arg but has 2 args

パフォーマンスについて

fmt はすべての引数を any として受け取り、実行時に型を調べます（構造体、スライス、マップではリフレクションを使います）。ログや出力には問題ありませんが、タイトなループでは差が出ます。数値を1つ変換するだけなら、strconv.Itoa や strconv.FormatFloat のほうが Sprintf より高速です。ループで長い文字列を組み立てるなら、Sprintf の結果を連結するのではなく、fmt.Fprintf(&b, ...) で strings.Builder に書き込みます。