8.20 strconv — Specification¶

Reference card. Function signatures, semantics, and edge cases. Authoritative source: $GOROOT/src/strconv/.

1. Constants and variables¶

const IntSize = 32 << (^uint(0) >> 63) // 32 or 64, depending on platform

var ErrRange = errors.New("value out of range")
var ErrSyntax = errors.New("invalid syntax")

IntSize is the bit-size of int on the build target. Use it sparingly; explicit 32/64 is clearer in code.

2. Errors¶

type NumError struct {
    Func string // e.g., "ParseInt"
    Num  string // the input that failed to parse
    Err  error  // strconv.ErrRange or strconv.ErrSyntax
}

func (e *NumError) Error() string
func (e *NumError) Unwrap() error

Error() formats as strconv.{Func}: parsing {Num}: {Err}. Unwrap() returns Err so errors.Is(err, strconv.ErrRange) works through the chain.

3. Integer conversions¶

Parse¶

func Atoi(s string) (int, error)
func ParseInt(s string, base, bitSize int) (int64, error)
func ParseUint(s string, base, bitSize int) (uint64, error)

Inputs accepted:

• Optional leading + or - for ParseInt only (not ParseUint).
• Decimal digits 0-9, or hex 0-9a-fA-F, etc., for higher bases.
• For base == 0, prefix selects: 0x/0X (hex), 0b/0B (bin, Go 1.13+), 0o/0O (oct, Go 1.13+), 0 followed by digits (oct, legacy), otherwise decimal.

Returns ErrSyntax for malformed input, ErrRange if the value exceeds the target bitSize.

Atoi(s) is equivalent to ParseInt(s, 10, 0) with a slight fast path for short decimal strings.

Format¶

func Itoa(i int) string
func FormatInt(i int64, base int) string
func FormatUint(i uint64, base int) string

func AppendInt(dst []byte, i int64, base int) []byte
func AppendUint(dst []byte, i uint64, base int) []byte

base must be in [2, 36]. Letters in output are lowercase ('a'..'z'). For uppercase, post-process or use fmt.

Itoa(i) is equivalent to FormatInt(int64(i), 10).

Append* writes into dst's tail capacity, growing if needed, and returns the new slice header. Pass nil to start fresh; pass a pre-allocated slice for zero-allocation use.

4. Float conversions¶

Parse¶

func ParseFloat(s string, bitSize int) (float64, error)

bitSize is 32 or 64. Always returns float64; the bit pattern matches float32 rounding when bitSize == 32.

Inputs accepted:

• Decimal: [+-]?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?
• Hex (Go 1.13+): [+-]?0[xX][0-9a-fA-F]+(\.[0-9a-fA-F]+)?([pP][+-]?[0-9]+)?
• inf, +inf, -inf, Inf (case-insensitive)
• nan, NaN, etc.

Format¶

func FormatFloat(f float64, fmt byte, prec, bitSize int) string
func AppendFloat(dst []byte, f float64, fmt byte, prec, bitSize int) []byte

fmt (format byte):

prec:

• For 'f', 'e', 'E': digits after decimal point.
• For 'g', 'G': total significant digits.
• For 'b', 'x', 'X': ignored.
• -1: shortest representation that round-trips through ParseFloat.

bitSize is 32 or 64, matching the source value's precision.

Special values:

5. Bool conversions¶

func ParseBool(s string) (bool, error)
func FormatBool(b bool) string
func AppendBool(dst []byte, b bool) []byte

Accepted inputs for ParseBool (exact match, case-sensitive exceptions noted):

Any other input returns ErrSyntax.

FormatBool(true) returns "true"; FormatBool(false) returns "false".

6. Quote and unquote¶

func Quote(s string) string
func QuoteToASCII(s string) string
func QuoteToGraphic(s string) string
func AppendQuote(dst []byte, s string) []byte
func AppendQuoteToASCII(dst []byte, s string) []byte
func AppendQuoteToGraphic(dst []byte, s string) []byte

func QuoteRune(r rune) string
func QuoteRuneToASCII(r rune) string
func QuoteRuneToGraphic(r rune) string
func AppendQuoteRune(dst []byte, r rune) []byte
func AppendQuoteRuneToASCII(dst []byte, r rune) []byte
func AppendQuoteRuneToGraphic(dst []byte, r rune) []byte

func Unquote(s string) (string, error)
func UnquoteChar(s string, quote byte) (value rune, multibyte bool, tail string, err error)

func CanBackquote(s string) bool
func IsPrint(r rune) bool
func IsGraphic(r rune) bool

Quote(s) returns s as a Go double-quoted string literal. Non-printable characters use Go escape syntax (\n, \xNN, \uNNNN, \UNNNNNNNN).

QuoteToASCII escapes all non-ASCII runes additionally.

QuoteToGraphic keeps printable Unicode runes as-is; escapes only non-graphic characters.

Unquote(s) parses s as a Go string/rune literal. Accepts:

• Backtick-quoted: contents copied verbatim, no escape processing.
• Double-quoted: full escape processing.
• Single-quoted: exactly one rune (or escape).

Returns (value, nil) on success, ("", ErrSyntax) on failure.

UnquoteChar parses one rune from a partially-quoted string; useful for custom parsers.

CanBackquote(s) reports whether s can be a raw string literal (no backticks, no \r, no \x00 etc.).

IsPrint and IsGraphic are exported because Quote uses them; the predicates match Unicode tables baked into the package.

7. Method tables¶

Allocation behavior¶

Concurrency¶

All functions are pure and safe for concurrent use.

8. Behavior table for common inputs¶

Atoi¶

ParseBool¶

ParseFloat special values¶

Quote edge cases¶

9. Compatibility notes¶

• All strconv functions are part of the Go 1 compatibility promise. Signatures have not changed since Go 1.0.
• Hex floats (0x1.8p1) added in Go 1.13.
• Binary (0b1010) and octal (0o755) prefixes for base == 0 added in Go 1.13.
• Multiple-%w not applicable here (no fmt).
• Ryū for FormatFloat with prec=-1: Go 1.12+.
• Eisel-Lemire for ParseFloat: Go 1.15+.

10. Complexity summary¶

11. References¶

• pkg.go.dev/strconv
• Source: $GOROOT/src/strconv/
• Cross-links: ../18-fmt/, ../04-encoding-json/, ../19-strings-bytes/