codec

type Appender ¶

type Appender interface {
	Codec
	// Append encodes v and appends the bytes onto dst. The returned slice
	// MUST contain the prior contents of dst followed by the encoded form.
	Append(dst []byte, v any) (out []byte, err error)
}

Appender is the optional extension implemented by codecs that can encode directly into a caller-supplied byte slice instead of allocating their own. Hot paths (logger record formatting, NDJSON streams, batch sinks) consume this interface to avoid the buffer-copy cost imposed by Marshal.

Implementations MUST:

• Append the encoded representation of v onto dst (typically via the standard append(dst, …) idiom).
• Return the (possibly re-allocated) buffer back to the caller.
• Be safe for concurrent use by multiple goroutines.

The returned buffer's length grows by the number of bytes written; the underlying array MAY be a fresh allocation when dst's capacity is too small. Callers retain ownership of dst and SHOULD reuse it across calls.

type BoundedStreamingCodec ¶ added in v0.27.0

type BoundedStreamingCodec interface {
	StreamingCodec
	NewBoundedDecoder(r io.Reader, maxBytes int64) (dec Decoder, err error)
}

BoundedStreamingCodec is the optional extension of a streaming codec whose Decoder holds a byte ceiling the caller chooses (#891) — a sibling of StreamingCodec, never a wider Decoder (ADR 0039).

NewBoundedDecoder returns a Decoder that refuses a value longer than maxBytes — counted from the end of the previous value to the end of this one, so a long stream of small values is never refused — with the codec's SIZE_EXCEEDED, which IsTooLarge reads, after reading at most maxBytes+1 bytes of it: a hostile stream grows the process by the ceiling, not by the size of its value. A ceiling of zero or below is refused with BoundInvalid: a bound has no value meaning unlimited (ADR 0031).

type Codec ¶

type Codec interface {
	Name() string
	MIMETypes() []string
	Extensions() []string
	Marshal(v any) (data []byte, err error)
	Unmarshal(data []byte, v any) (err error)
}

Codec is the minimum contract every format codec satisfies. Instances MUST be safe for concurrent use; format-specific options are supplied via the codec's constructor, not via the Codec interface.

func Lookup(f Format) (c Codec, ok bool)

func LookupExt(ext string) (c Codec, ok bool)

func LookupMIME(raw string) (c Codec, ok bool)

func Register(c Codec) Codec

type Decoder ¶

type Decoder interface {
	Decode(v any) (err error)
	More() (ok bool)
}

Decoder reads one or more values from the wrapped reader.

type Encoder ¶

type Encoder interface {
	Encode(v any) (err error)
	Close() (err error)
}

Encoder writes one or more values to the wrapped writer.

type Format ¶

type Format string

Format is the typed string identifier of a codec.

func Available() []Format

func Detect(prefix []byte) (f Format, ok bool)

func (f Format) Known() bool

func (f Format) String() string

type PositionValue ¶ added in v0.27.0

type PositionValue struct {
	// Offset is the 0-based byte offset of the problem in the input.
	Offset int
	// Line is the 1-based line of the problem, zero when unknown.
	Line int
	// Column is the 1-based column of the problem, zero when unknown.
	Column int
}

PositionValue places a decode refusal in its input (#1125). Offset is the 0-based byte, Line and Column are 1-based, a zero Line or Column is unknown. A text format places by line and column — characters for yaml and toml, bytes for csv — and adds the offset when it knows a non-zero one; a binary format places by offset alone, so with no Line the Offset is meant even when zero: the input's first byte. json carries the offset and xml the line their standard library's errors give.

func PositionOf(err error) (p PositionValue, ok bool)

type Sniffer ¶ added in v0.27.0

type Sniffer interface {
	Codec
	Sniff(prefix []byte) (confident bool)
}

Sniffer is the optional extension of a codec whose encoding opens with a recognisable head (#909). Sniff reports whether prefix — the first bytes of an input, at most 512 of them, possibly cut inside a value — is confidently this codec's: a head no other format's output starts with, not merely bytes the codec could parse. It reads nothing past prefix, keeps nothing and allocates nothing. Detect asks every Sniffer and answers only when exactly one claims the bytes.

type StreamingCodec ¶

type StreamingCodec interface {
	Codec
	NewEncoder(w io.Writer) Encoder
	NewDecoder(r io.Reader) Decoder
}

StreamingCodec is the optional extension for formats that support incremental encode/decode over io.Writer / io.Reader. Codecs that CAN stream SHOULD implement it; consumers detect support with a type assertion.