Printf et Sprintf en Golang : aide-mémoire des verbes de format fmt

Le package fmt a trois familles de fonctions d'affichage, et chaque famille a les trois mêmes variantes :

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 ajoute des espaces entre les opérandes et un retour à la ligne à la fin. Printf n'ajoute rien : vous écrivez \n vous-même. Print n'ajoute des espaces qu'entre deux opérandes qui ne sont ni l'un ni l'autre des chaînes, ce qui surprend assez pour que la plupart du code utilise Println ou Printf.

Verbes de format

Généraux

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 est celui à utiliser pour déboguer. Un pointeur vers une struct s'affiche &{...} plutôt qu'une adresse. Les maps s'affichent avec les clés triées, donc la sortie est stable même si l'ordre d'itération des maps est aléatoire.

Entiers

Flottants

%.2f arrondit la valeur binaire exacte du flottant, donc fmt.Sprintf("%.2f", 2.675) donne 2.67 : le float64 le plus proche de 2,675 est légèrement en dessous. Ne formatez jamais de l'argent à partir d'un flottant ; gardez les centimes dans un entier.

Chaînes et octets

%s sur un []byte l'affiche comme du texte ; %v affiche les nombres ([104 105]).

Autres types

Largeur, précision et remplissage

Entre % et le verbe, vous pouvez placer des flags, une largeur et une précision :

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

Notez que %.0f de 2.5 affiche 2 : Go arrondit ici au pair le plus proche. Pour les chaînes, la largeur compte les runes, pas les colonnes affichées, donc les caractères CJK et les emojis peuvent encore désaligner un tableau. Pour des colonnes alignées de texte variable, text/tabwriter fait la mesure à votre place.

Indices d'arguments

%[n] choisit un argument par sa position, ce qui permet d'en réutiliser un :

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

Errorf et %w

fmt.Errorf construit une error à partir d'une chaîne de format. Avec %w, elle enveloppe aussi une autre erreur, pour que les appelants puissent encore détecter l'originale :

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

Utilisez %w quand les appelants peuvent avoir besoin de vérifier la cause, et %v quand vous la masquez volontairement. Depuis Go 1.20, un appel à Errorf peut contenir plusieurs verbes %w. La page sur la gestion des erreurs traite l'enveloppement en détail.

Formatage personnalisé avec String()

Tout type doté d'une méthode String() string contrôle la façon dont %v, %s et Println l'affichent :

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 contourne String() et affiche le nombre sous-jacent. Pour les types d'erreur, la méthode équivalente est Error() string, qui a priorité sur String().

Quand le verbe est faux

fmt ne provoque jamais de panic sur un format invalide. Il affiche le problème en ligne :

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)

Cette sortie a tendance à arriver en production parce qu'elle ne fait rien planter. go vet détecte les trois à la compilation :

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

Notes de performance

fmt prend chaque argument comme un any et inspecte son type à l'exécution (en passant par la réflexion pour les structs, slices et maps), ce qui convient pour les logs et l'affichage mais se mesure dans les boucles serrées. Pour convertir un seul nombre, strconv.Itoa et strconv.FormatFloat sont plus rapides que Sprintf. Pour construire une longue chaîne dans une boucle, écrivez dans un strings.Builder avec fmt.Fprintf(&b, ...) au lieu de concaténer des résultats de Sprintf.