From 67d4a28707fe948b4d5fe3e171717ab887730c2b Mon Sep 17 00:00:00 2001 From: Alan Donovan Date: Fri, 18 Jul 2025 14:57:38 -0400 Subject: [PATCH] fmt: document space behavior of Append Also, introduce the {Print,Fprint,Sprint,Append}{,f,ln} cross product of functions at the top of the docs. Fixes #74656 Change-Id: I85a156cd545ca866e579d8020ddf165cd4bcb26f Reviewed-on: https://go-review.googlesource.com/c/go/+/688877 Reviewed-by: Rob Pike LUCI-TryBot-Result: Go LUCI Reviewed-by: Damien Neil --- src/fmt/doc.go | 14 +++++++++++++- src/fmt/print.go | 1 + 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/src/fmt/doc.go b/src/fmt/doc.go index fa0ffa7f00..46f30b44e9 100644 --- a/src/fmt/doc.go +++ b/src/fmt/doc.go @@ -9,6 +9,18 @@ are simpler. # Printing +There are four families of printing functions defined by their output destination. +[Print], [Println] and [Printf] write to [os.Stdout]; +[Sprint], [Sprintln] and [Sprintf] return a string; +[Fprint], [Fprintln] and [Fprintf] write to an [io.Writer]; and +[Append], [Appendln] and [Appendf] append the output to a byte slice. + +The functions within each family do the formatting according to the end of the name. +Print, Sprint, Fprint and Append use the default format for each argument, +adding a space between operands when neither is a string. +Println, Sprintln, Fprintln and Appendln always add spaces and append a newline. +Printf, Sprintf, Fprintf and Appendf use a sequence of "verbs" to control the formatting. + The verbs: General: @@ -222,7 +234,7 @@ formatting methods such as Error or String on unexported fields. # Explicit argument indexes -In [Printf], [Sprintf], and [Fprintf], the default behavior is for each +In [Printf], [Sprintf], [Fprintf], and [Appendf], the default behavior is for each formatting verb to format successive arguments passed in the call. However, the notation [n] immediately before the verb indicates that the nth one-indexed argument is to be formatted instead. The same notation diff --git a/src/fmt/print.go b/src/fmt/print.go index 01cfa1a1c7..2340ceed8f 100644 --- a/src/fmt/print.go +++ b/src/fmt/print.go @@ -284,6 +284,7 @@ func Sprint(a ...any) string { // Append formats using the default formats for its operands, appends the result to // the byte slice, and returns the updated slice. +// Spaces are added between operands when neither is a string. func Append(b []byte, a ...any) []byte { p := newPrinter() p.doPrint(a) -- 2.52.0