Printf e Sprintf em Golang: guia dos verbos de formato do fmt

O pacote fmt tem três famílias de funções de impressão, e cada família tem as mesmas três 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 coloca espaços entre os operandos e uma quebra de linha no final. Printf não acrescenta nada: você mesmo escreve o \n. Print só coloca espaço entre operandos que não são strings, o que surpreende o bastante para a maior parte do código usar Println ou Printf.

Verbos de formato

Gerais

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 é o verbo para usar na depuração. Um ponteiro para struct é impresso como &{...} em vez de um endereço. Maps são impressos com as chaves ordenadas, então a saída é estável mesmo com a ordem de iteração dos maps sendo aleatória.

Inteiros

Floats

%.2f arredonda o valor binário exato do float, então fmt.Sprintf("%.2f", 2.675) dá 2.67: o float64 mais próximo de 2.675 fica um pouco abaixo dele. Nunca formate dinheiro a partir de um float; guarde centavos em um inteiro.

Strings e bytes

%s em um []byte imprime como texto; %v imprime os números ([104 105]).

Outros tipos

Largura, precisão e preenchimento

Entre o % e o verbo você pode colocar flags, uma largura e uma precisão:

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

Repare que %.0f de 2.5 imprime 2: aqui o Go arredonda a metade para o par. Em strings, a largura conta runes, não colunas na tela, então caracteres CJK e emoji ainda podem desalinhar uma tabela. Para colunas alinhadas de texto variável, o text/tabwriter faz a medição por você.

Índices de argumentos

%[n] escolhe um argumento pela posição, o que permite reutilizá-lo:

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

Errorf e %w

fmt.Errorf monta um error a partir de uma string de formato. Com %w ele também empacota outro erro, então quem chama ainda consegue detectar o original:

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

Use %w quando quem chama pode precisar verificar a causa, e %v quando você quer escondê-la de propósito. Desde o Go 1.20 uma chamada de Errorf pode ter vários verbos %w. A página de tratamento de erros aprofunda o empacotamento.

Formatação personalizada com String()

Qualquer tipo com um método String() string controla como %v, %s e Println o exibem:

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 ignora o String() e imprime o número subjacente. Para tipos de erro, o método equivalente é Error() string, que tem prioridade sobre String().

Quando o verbo está errado

O fmt nunca causa panic por um formato ruim. Ele imprime o problema no meio da saída:

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)

Essa saída costuma chegar à produção porque não derruba nada. O go vet pega os três na hora do 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

Notas de desempenho

O fmt recebe todo argumento como any e inspeciona o tipo em tempo de execução (recorrendo a reflection para structs, slices e maps), o que não é problema para logs e saída, mas pesa em laços apertados. Para converter um único número, strconv.Itoa e strconv.FormatFloat são mais rápidos que Sprintf. Para montar uma string longa em um laço, escreva em um strings.Builder com fmt.Fprintf(&b, ...) em vez de concatenar resultados de Sprintf.