Printf y Sprintf en Golang: chuleta de verbos de formato de fmt

El paquete fmt tiene tres familias de funciones de impresión, y cada familia tiene las mismas tres 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 añade espacios entre operandos y un salto de línea al final. Printf no añade nada: el \n lo escribes tú. Print añade espacios solo entre operandos que no son strings, lo cual sorprende lo suficiente como para que la mayor parte del código use Println o Printf.

Verbos de formato

Generales

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 es el que conviene usar al depurar. Un puntero a un struct se imprime como &{...} en lugar de como una dirección. Los maps se imprimen con las claves ordenadas, así que la salida es estable aunque el orden de iteración de un map sea aleatorio.

Enteros

Flotantes

%.2f redondea el valor binario exacto del float, así que fmt.Sprintf("%.2f", 2.675) da 2.67: el float64 más cercano a 2.675 está un poco por debajo. Nunca formatees dinero a partir de un float; guarda los céntimos en un entero.

Strings y bytes

%s sobre un []byte lo imprime como texto; %v imprime los números ([104 105]).

Otros tipos

Ancho, precisión y relleno

Entre % y el verbo puedes poner flags, un ancho y una precisión:

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

Ojo: %.0f de 2.5 imprime 2, porque aquí Go redondea al par más cercano. En los strings, el ancho cuenta runes, no columnas en pantalla, así que los caracteres CJK y los emoji todavía pueden desalinear una tabla. Para columnas alineadas de texto variable, text/tabwriter hace la medición por ti.

Índices de argumentos

%[n] elige un argumento por posición, lo que te permite reutilizarlo:

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

Errorf y %w

fmt.Errorf construye un error a partir de una cadena de formato. Con %w además envuelve otro error, para que quien llama pueda seguir detectando el 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))
}

Usa %w cuando quien llama pueda necesitar comprobar la causa, y %v cuando quieras ocultarla a propósito. Desde Go 1.20 una llamada a Errorf puede contener varios verbos %w. La página de manejo de errores trata el envoltorio de errores a fondo.

Formato propio con String()

Cualquier tipo con un método String() string controla cómo lo muestran %v, %s y 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 se salta String() e imprime el número subyacente. Para los tipos de error el método equivalente es Error() string, que tiene prioridad sobre String().

Cuando el verbo es incorrecto

fmt nunca provoca un panic por un formato incorrecto. Imprime el problema en la propia salida:

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)

Esa salida suele llegar a producción porque no hace caer nada. go vet detecta los tres casos al compilar:

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

fmt recibe cada argumento como any e inspecciona su tipo en tiempo de ejecución (recurriendo a reflexión para structs, slices y maps), lo cual está bien para logs y salida, pero se nota en bucles ajustados. Para convertir un solo número, strconv.Itoa y strconv.FormatFloat son más rápidos que Sprintf. Para construir un string largo en un bucle, escribe en un strings.Builder con fmt.Fprintf(&b, ...) en lugar de concatenar resultados de Sprintf.