Printf и Sprintf в Golang: шпаргалка по глаголам формата fmt

В пакете fmt три семейства функций печати, и в каждом одни и те же три варианта:

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 округляет точное двоичное значение float, поэтому fmt.Sprintf("%.2f", 2.675) даёт 2.67: ближайший к 2.675 float64 чуть меньше этого числа. Никогда не форматируйте деньги из float; храните копейки в целом числе.

Строки и байты

%s для []byte печатает его как текст; %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)
	}
}

Заметьте: %.0f для 2.5 печатает 2, здесь Go округляет половину к чётному. Для строк ширина считается в рунах, а не в экранных колонках, поэтому иероглифы и эмодзи всё равно могут сбить выравнивание таблицы. Для ровных колонок с текстом переменной длины измерения за вас сделает 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 один вызов 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 никогда не паникует из-за неправильного формата. Он печатает проблему прямо в выводе:

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 ловит все три случая при сборке:

./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 и проверяет его тип во время выполнения (для структур, слайсов и мап используя рефлексию). Для логов и вывода это нормально, но в плотных циклах заметно. Чтобы преобразовать одно число, strconv.Itoa и strconv.FormatFloat быстрее, чем Sprintf. Чтобы собрать длинную строку в цикле, пишите в strings.Builder через fmt.Fprintf(&b, ...), а не склеивайте результаты Sprintf.