Golang Printf und Sprintf: Spickzettel der fmt-Format-Verben

Das Paket fmt hat drei Familien von Ausgabefunktionen, und jede Familie hat dieselben drei Varianten:

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 setzt Leerzeichen zwischen die Operanden und einen Zeilenumbruch ans Ende. Printf fügt nichts hinzu: Du schreibst \n selbst. Print setzt Leerzeichen nur zwischen Operanden, die beide keine Strings sind. Das überrascht genug, dass der meiste Code Println oder Printf nutzt.

Format-Verben

Allgemein

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 ist das Verb der Wahl beim Debuggen. Ein Pointer auf ein Struct erscheint als &{...} statt als Adresse. Maps werden mit sortierten Schlüsseln ausgegeben, die Ausgabe ist also stabil, obwohl die Iterationsreihenfolge von Maps zufällig ist.

Ganzzahlen

Floats

%.2f rundet den exakten Binärwert des Floats, also ist fmt.Sprintf("%.2f", 2.675) gleich 2.67: Der float64, der 2.675 am nächsten liegt, ist etwas kleiner. Formatiere Geld nie aus einem Float; speichere Cent in einer Ganzzahl.

Strings und Bytes

%s auf einem []byte gibt es als Text aus; %v gibt die Zahlen aus ([104 105]).

Andere Typen

Breite, Genauigkeit und Padding

Zwischen % und das Verb kannst du Flags, eine Breite und eine Genauigkeit setzen:

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

Beachte: %.0f von 2.5 ergibt 2, denn Go rundet hier auf die gerade Zahl. Bei Strings zählt die Breite Runes, keine Anzeigespalten, also können CJK-Zeichen und Emoji eine Tabelle trotzdem verschieben. Für ausgerichtete Spalten mit variablem Text übernimmt text/tabwriter das Messen für dich.

Argumentindizes

%[n] wählt ein Argument nach Position, damit kannst du eins wiederverwenden:

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

Errorf und %w

fmt.Errorf baut einen error aus einem Format-String. Mit %w wrappt es zusätzlich einen anderen Fehler, sodass Aufrufer das Original noch erkennen können:

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

Nimm %w, wenn Aufrufer die Ursache prüfen müssen könnten, und %v, wenn du sie bewusst verbirgst. Seit Go 1.20 darf ein Errorf-Aufruf mehrere %w-Verben enthalten. Die Seite zur Fehlerbehandlung erklärt das Wrapping im Detail.

Eigene Formatierung mit String()

Jeder Typ mit einer Methode String() string bestimmt, wie %v, %s und Println ihn anzeigen:

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 umgeht String() und gibt die zugrunde liegende Zahl aus. Bei Fehlertypen ist die entsprechende Methode Error() string, die Vorrang vor String() hat.

Wenn das Verb falsch ist

fmt löst bei einem falschen Format nie eine Panic aus. Es gibt das Problem direkt in der Ausgabe aus:

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)

Solche Ausgaben landen gern in Produktion, weil sie nichts zum Absturz bringen. go vet findet alle drei beim Build:

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

Hinweise zur Performance

fmt nimmt jedes Argument als any und untersucht seinen Typ zur Laufzeit (bei Structs, Slices und Maps per Reflection). Für Logging und Ausgaben ist das in Ordnung, in engen Schleifen aber messbar. Um eine einzelne Zahl zu konvertieren, sind strconv.Itoa und strconv.FormatFloat schneller als Sprintf. Um in einer Schleife einen langen String zu bauen, schreib mit fmt.Fprintf(&b, ...) in einen strings.Builder, statt Ergebnisse von Sprintf zu verketten.