Go fmt — Specification¶

Source: https://pkg.go.dev/fmt Section: Package documentation (verb table, interfaces)

1. Spec Reference¶

2. Definition¶

The fmt package implements formatted I/O with functions analogous to C's printf and scanf. Verbs derive from C but include Go-specific extensions (struct formatting, %w for error wrapping, %T for types).

The package exposes the printer family (Print/Sprint/Fprint ± ln/f), Errorf, the scanner family (Scan/Sscan/Fscan ± ln/f), and three customisation interfaces (Stringer, GoStringer, Formatter).

3. Core Function Signatures¶

// Print to stdout
func Print(a ...any) (n int, err error)
func Println(a ...any) (n int, err error)
func Printf(format string, a ...any) (n int, err error)

// Build a string
func Sprint(a ...any) string
func Sprintln(a ...any) string
func Sprintf(format string, a ...any) string

// Write to any io.Writer
func Fprint(w io.Writer, a ...any) (n int, err error)
func Fprintln(w io.Writer, a ...any) (n int, err error)
func Fprintf(w io.Writer, format string, a ...any) (n int, err error)

// Build an error
func Errorf(format string, a ...any) error

// Read input
func Scan(a ...any) (n int, err error)
func Scanln(a ...any) (n int, err error)
func Scanf(format string, a ...any) (n int, err error)
func Sscan(s string, a ...any) (n int, err error)
func Sscanln(s string, a ...any) (n int, err error)
func Sscanf(s, format string, a ...any) (n int, err error)
func Fscan(r io.Reader, a ...any) (n int, err error)
func Fscanln(r io.Reader, a ...any) (n int, err error)
func Fscanf(r io.Reader, format string, a ...any) (n int, err error)

// Append (Go 1.19+)
func Append(b []byte, a ...any) []byte
func Appendln(b []byte, a ...any) []byte
func Appendf(b []byte, format string, a ...any) []byte

4. The Verb Table¶

4.1 General¶

4.2 Boolean¶

4.3 Integer¶

4.4 Floating-Point and Complex¶

4.5 String and Slice of Byte¶

4.6 Pointer¶

4.7 Error Wrapping¶

5. Width and Precision¶

% [flags] [width] [.precision] [argument index] verb

Flags:

Examples¶

fmt.Printf("%5d\n", 42)     //    42
fmt.Printf("%-5d|\n", 42)   // 42   |
fmt.Printf("%05d\n", 42)    // 00042
fmt.Printf("%+d\n", 42)     // +42
fmt.Printf("%.3f\n", 3.14)  // 3.140
fmt.Printf("%6.2f\n", 3.14) //   3.14
fmt.Printf("%.3s\n", "hello") // hel
fmt.Printf("%[2]d %[1]d\n", 1, 2) // 2 1
fmt.Printf("%*d\n", 5, 42)  //    42

6. The Stringer Interface¶

type Stringer interface { String() string }

Called by %s, %v, and the unformatted Print* family when the type implements it. Bypassed by %T, %#v (when GoStringer exists), and %p.

7. The GoStringer Interface¶

type GoStringer interface { GoString() string }

Called by %#v only. Should return text that compiles back to the value in Go syntax.

8. The Formatter Interface¶

type Formatter interface { Format(f State, verb rune) }

type State interface {
    Write(b []byte) (n int, err error)
    Width()     (wid int, ok bool)
    Precision() (prec int, ok bool)
    Flag(c int) bool
}

A type implementing Formatter overrides all default verb handling, including String() and Error(). f State embeds io.Writer plus Width()/Precision()/Flag(c). verb rune is the verb character.

9. Errorf and the %w Verb¶

func Errorf(format string, a ...any) error

If the format contains a %w verb, the corresponding argument must be an error. The returned error implements Unwrap() error (single %w) or Unwrap() []error (multiple %w, Go 1.20+).

Outside Errorf, %w is treated as a malformed verb and produces %!w(...).

Errorf("...: %w", nil) panics in Go 1.20+:

panic: %w error operand cannot be nil

Errors Helpers (errors package)¶

func errors.Is(err, target error) bool
func errors.As(err error, target any) bool
func errors.Unwrap(err error) error
func errors.Join(errs ...error) error

These walk the chain produced by %w.

10. Default Format Rules¶

For each Go kind, the default %v representation:

For %+v of structs: {Name:value Age:value ...}. For %#v: Go-syntax form.

11. Print Family Spacing Rules¶

fmt.Print:

• Adds a space between two adjacent operands when neither is a string.
• No leading or trailing newline.

fmt.Println:

• Always adds a space between adjacent operands.
• Adds a trailing newline.

fmt.Printf:

• Inserts no spaces or newlines automatically; the format string is authoritative.

12. Scan Family¶

func Scan(a ...any) (n int, err error)
func Scanf(format string, a ...any) (n int, err error)
func Sscan(s string, a ...any) (n int, err error)
func Sscanf(s, format string, a ...any) (n int, err error)
func Fscan(r io.Reader, a ...any) (n int, err error)
func Fscanf(r io.Reader, format string, a ...any) (n int, err error)

• Whitespace separates tokens.
• Newlines: Scan treats them as whitespace; Scanln requires a newline at end.
• Verbs: %d, %s, %f, etc., similar to Printf.
• %w is not valid in scanning.

Returns the number of successfully scanned items.

13. Append Family (Go 1.19+)¶

func Append(b []byte, a ...any) []byte
func Appendln(b []byte, a ...any) []byte
func Appendf(b []byte, format string, a ...any) []byte

Same semantics as Print*/Sprint* but writes into a caller- provided byte slice, returning the resulting slice. Useful for zero-allocation formatting in hot paths.

14. Edge Cases¶

14.1 nil interface¶

var i any = nil
fmt.Printf("%v\n", i) // <nil>
fmt.Printf("%T\n", i) // <nil>

14.2 typed nil¶

var p *T = nil
var i any = p
fmt.Printf("%v\n", i) // <nil>  (actually calls String() if defined)
fmt.Printf("%T\n", i) // *main.T
i == nil               // false  (interface is non-nil)

14.3 Recursion¶

A String() that calls fmt.Sprintf("%v", t) on its own type infinitely recurses. The runtime detects stack overflow and crashes. There is no automatic protection.

14.4 Wrong Verb For Type¶

fmt substitutes a runtime placeholder:

%!verb(type=value)   // e.g. %!d(string=hello)
%!(EXTRA type=value) // unconsumed argument
%!d(MISSING)         // missing argument

go vet catches these at compile time when the format is a literal.

14.5 Format String Parsing Failure¶

If the format string ends mid-verb (e.g. "%5"), fmt emits %!(NOVERB) and stops scanning verbs.

15. Related Specifications¶

errors¶

• errors.New(text string) error
• errors.Is(err, target error) bool
• errors.As(err error, target any) bool
• errors.Unwrap(err error) error
• errors.Join(errs ...error) error

reflect¶

fmt's default formatting uses reflect.Value for composite types. The Kind enumeration determines which fast path or recursion is used.

strconv¶

For pure value-to-string conversions, strconv is the zero-allocation alternative: - strconv.Itoa(n int) string - strconv.FormatFloat(f float64, fmt byte, prec, bitSize int) string - strconv.AppendInt(dst []byte, n int64, base int) []byte

io¶

Fprint* accepts any io.Writer. Fscan* accepts any io.Reader.

16. Version History¶

17. Implementation Notes¶

File map¶

src/fmt/
  doc.go         Verb table documentation.
  print.go       Print/Sprint/Fprint, pp state, dispatch.
  format.go      Per-type byte writers (fmtInteger, fmtFloat, ...).
  scan.go        Scan/Sscan/Fscan, ss state.
  errors.go      Errorf, wrapError, wrapErrors.

pp State¶

// (simplified)
type pp struct {
    buf         buffer       // []byte the formatted bytes go into
    arg         any          // current argument
    value       reflect.Value
    fmt         fmt          // width, precision, flags
    reordered   bool         // %[N] was used
    goodArgNum  bool         // %[N] referred to an existing argument
    panicking   bool
    erroring    bool
    wrapErrs    bool         // recognise %w (Errorf only)
    wrappedErrs []int        // indices in `args` of wrapped errors
}

Pool¶

var ppFree = sync.Pool{New: func() any { return new(pp) }}

pp.free() returns the printer state to the pool unless its buffer exceeds 64 KiB (to avoid pinning memory).

18. Acceptance Tests¶

type stringerS struct{ V int }
func (s stringerS) String() string { return "S!" }

func TestStringerCalled(t *testing.T) {
    type S struct{ V int }
    if got := fmt.Sprintf("%v", S{42}); got != "{42}" { t.Fatalf("got %q", got) }
}

func TestStringerOverride(t *testing.T) {
    if got := fmt.Sprintf("%v", stringerS{42}); got != "S!" { t.Fatalf("got %q", got) }
}

func TestErrorfWraps(t *testing.T) {
    inner := errors.New("inner")
    outer := fmt.Errorf("outer: %w", inner)
    if !errors.Is(outer, inner) { t.Fatal("expected outer to wrap inner") }
}

func TestWInSprintfFallback(t *testing.T) {
    s := fmt.Sprintf("%w", errors.New("x"))
    if !strings.HasPrefix(s, "%!w(") { t.Fatalf("got %q", s) }
}

19. Related Specs¶

• Go spec — %w and errors
• Go blog — Working with Errors in Go 1.13
• Go release notes 1.20 — multiple %w
• staticcheck — printf checks
• vet's printf analyzer

20. Summary¶

fmt exposes a small, stable surface: nine printer functions (three families × three variants), Errorf, the scan family, and three customisation interfaces. Verbs follow %[flags][width] [.prec][index]verb. %v is the default; %w is the wrapping marker recognised only by Errorf. Custom types implement Stringer, GoStringer, or Formatter to control representation, with a fixed dispatch order: Formatter → error → Stringer → reflection. The implementation uses a pooled pp printer state to amortise per-call cost. The package has been stable since Go 1.0, with the most consequential additions being %w (Go 1.13) and multi-%w (Go 1.20).