Printf i Sprintf w Go (Golang): ściągawka formatowania fmt

Pakiet fmt ma trzy rodziny funkcji wypisujących, a każda rodzina ma te same trzy warianty:

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 dodaje spacje między argumentami i nową linię na końcu. Printf nic nie dodaje: \n dopisujesz samodzielnie. Print dodaje spacje tylko między argumentami, z których żaden nie jest stringiem, co jest na tyle zaskakujące, że większość kodu używa Println lub Printf.

Czasowniki formatujące

Ogólne

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 to czasownik, po który warto sięgać przy debugowaniu. Wskaźnik na strukturę wypisuje się jako &{...}, a nie jako adres. Mapy wypisują się z posortowanymi kluczami, więc wynik jest stabilny, choć kolejność iteracji po mapie jest losowa.

Liczby całkowite

Liczby zmiennoprzecinkowe

%.2f zaokrągla dokładną binarną wartość liczby, więc fmt.Sprintf("%.2f", 2.675) daje 2.67: najbliższy float64 dla 2.675 jest odrobinę mniejszy. Nigdy nie formatuj kwot pieniężnych z floata; trzymaj grosze w liczbie całkowitej.

Stringi i bajty

%s na []byte wypisuje go jako tekst; %v wypisuje liczby ([104 105]).

Inne typy

Szerokość, precyzja i dopełnianie

Między % a czasownikiem możesz wstawić flagi, szerokość i precyzję:

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)
	}
}

Uwaga: %.0f dla 2.5 wypisuje 2: Go zaokrągla tu połówki do parzystej. Dla stringów szerokość liczy runy, a nie kolumny na ekranie, więc znaki CJK i emoji mogą nadal rozjechać tabelę. Do wyrównanych kolumn ze zmiennym tekstem użyj text/tabwriter, który zmierzy wszystko za ciebie.

Indeksy argumentów

%[n] wybiera argument według pozycji, co pozwala użyć go ponownie:

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

Errorf i %w

fmt.Errorf buduje error ze stringa formatującego. Z %w dodatkowo opakowuje inny błąd, więc wywołujący nadal mogą wykryć oryginał:

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))
}

Używaj %w, gdy wywołujący mogą potrzebować sprawdzić przyczynę, a %v, gdy celowo ją ukrywasz. Od Go 1.20 jedno wywołanie Errorf może zawierać kilka czasowników %w. Opakowywanie szczegółowo omawia strona o obsłudze błędów.

Własne formatowanie przez String()

Każdy typ z metodą String() string decyduje, jak pokazują go %v, %s i 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 omija String() i wypisuje liczbę bazową. Dla typów błędów odpowiednikiem jest metoda Error() string, która ma pierwszeństwo przed String().

Gdy czasownik jest zły

fmt nigdy nie wywołuje panic przy złym formacie. Wypisuje problem w miejscu:

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)

Taki wynik często trafia na produkcję, bo niczego nie wywraca. go vet wyłapuje wszystkie trzy przypadki podczas budowania:

./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

Uwagi o wydajności

fmt przyjmuje każdy argument jako any i sprawdza jego typ w czasie działania (dla struktur, slice'ów i map korzystając z refleksji), co jest w porządku przy logowaniu i wypisywaniu, ale mierzalne w ciasnych pętlach. Do konwersji pojedynczej liczby strconv.Itoa i strconv.FormatFloat są szybsze niż Sprintf. Do budowania długiego stringa w pętli zapisuj do strings.Builder przez fmt.Fprintf(&b, ...) zamiast łączyć wyniki Sprintf.