Documentation
¶
Overview ¶
Package encode implements a binary marshaling engine for Protocol Buffers messages. It encodes protobuf messages by iterating a list of field encodings, writing tags, dispatching scalar encoding via the scalar package, and encoding nested messages with varint length prefixing.
All encoding methods follow the append pattern: they accept a byte slice b, append encoded bytes to it, and return the extended slice. This allows callers to pre-allocate capacity and reuse buffers across marshal calls without heap allocation on the encoding path.
The Encoder type is a stateless struct following the same pattern as wire.Codec and scalar.Codec. It provides methods for encoding individual tagged fields (scalar, bytes, string, and nested message) and for encoding a complete message from a slice of FieldEncoding values.
The FieldEncoding type is a self-contained unit that captures a field number, an encoding closure, and a pre-computed encoded size. The SortFields function sorts a slice of FieldEncoding values by ascending field number, enabling deterministic wire output when called before EncodeMessage.
Package-level Size*Field functions (SizeScalarField, SizeBytesField, SizeStringField, SizeMessageField) compute the encoded size of each field type without allocating, supporting pre-allocation of output buffers.
This package depends on wire/, scalar/, and proto/ from the module, and sort from the standard library.
Index ¶
- func SizeBytesField(fieldNumber uint32, dataLen int) int
- func SizeMessageField(fieldNumber uint32, msgSize int) int
- func SizeScalarField(fieldNumber uint32, kind scalar.Kind, v uint64) int
- func SizeStringField(fieldNumber uint32, strLen int) int
- func SortFields(fields []FieldEncoding)
- type Encoder
- func (e *Encoder) EncodeBytesField(b []byte, fieldNumber uint32, data []byte) []byte
- func (e *Encoder) EncodeMessage(b []byte, fields []FieldEncoding) ([]byte, error)
- func (e *Encoder) EncodeMessageField(b []byte, fieldNumber uint32, msg proto.MarshalAppender, size int) []byte
- func (e *Encoder) EncodeScalarField(b []byte, fieldNumber uint32, kind scalar.Kind, v uint64) []byte
- func (e *Encoder) EncodeStringField(b []byte, fieldNumber uint32, s string) []byte
- type FieldEncoding
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SizeBytesField ¶
SizeBytesField returns the number of bytes required to encode a tagged length-delimited bytes field with the given field number and data length.
func SizeMessageField ¶
SizeMessageField returns the number of bytes required to encode a tagged nested message field with the given field number and pre-computed message size.
func SizeScalarField ¶
SizeScalarField returns the number of bytes required to encode a tagged scalar field with the given field number, kind, and value.
func SizeStringField ¶
SizeStringField returns the number of bytes required to encode a tagged length-delimited string field with the given field number and string length.
func SortFields ¶
func SortFields(fields []FieldEncoding)
SortFields sorts the given slice of FieldEncoding values in-place by ascending FieldNumber. Callers opt into deterministic encoding by calling SortFields on their field list before passing it to EncodeMessage.
Types ¶
type Encoder ¶
type Encoder struct{}
Encoder provides methods for encoding individual tagged protobuf fields and complete messages. It is a stateless struct following the wire.Codec and scalar.Codec pattern. All encoding methods follow the append pattern: they accept a byte slice b, append encoded bytes to it, and return the extended slice. The Encoder does not own or manage buffers; buffer lifecycle is the caller's responsibility.
func NewEncoder ¶
func NewEncoder() *Encoder
NewEncoder returns a pointer to a new zero-value Encoder instance.
func (*Encoder) EncodeBytesField ¶
EncodeBytesField appends a tagged length-delimited bytes field to b and returns the extended slice.
func (*Encoder) EncodeMessage ¶
func (e *Encoder) EncodeMessage(b []byte, fields []FieldEncoding) ([]byte, error)
EncodeMessage iterates the field list and calls each field's Encode closure to append its encoded form. It returns the extended byte slice and the first error encountered. On error, EncodeMessage short-circuits and does not call subsequent field encoders. Fields are encoded in slice order by default; callers opt into deterministic encoding by calling SortFields before EncodeMessage.
func (*Encoder) EncodeMessageField ¶
func (e *Encoder) EncodeMessageField(b []byte, fieldNumber uint32, msg proto.MarshalAppender, size int) []byte
EncodeMessageField appends a tagged length-delimited nested message field to b and returns the extended slice. It writes the field tag with wire type WireBytes, appends the varint-encoded size as the length prefix, and then delegates to msg.MarshalAppend to write the inner content. The size parameter is pre-computed by the caller and trusted without verification. Errors from msg.MarshalAppend are not propagated at this level; they are handled by EncodeMessage.
func (*Encoder) EncodeScalarField ¶
func (e *Encoder) EncodeScalarField(b []byte, fieldNumber uint32, kind scalar.Kind, v uint64) []byte
EncodeScalarField appends a tagged scalar field to b and returns the extended slice. It writes the field tag (using kind.WireType()) followed by the scalar value encoding. This method handles all varint, zigzag, and fixed-width scalar kinds in a single entry point. For zigzag kinds, the caller must pass the already-zigzag-encoded uint64 value.
type FieldEncoding ¶
type FieldEncoding struct {
// FieldNumber is the protobuf field number for this field.
FieldNumber uint32
// Encode appends the encoded form of this field (tag + value) to b and
// returns the extended slice.
Encode func(b []byte) ([]byte, error)
// EncodedSize is the pre-computed encoded size of this field including its
// tag. It is used by deterministic sorting and size pre-computation.
EncodedSize int
}
FieldEncoding is a self-contained unit that captures a protobuf field number, a closure that performs the actual tag + value encoding, and a pre-computed encoded size. Message types construct a []FieldEncoding slice in their MarshalAppend method, including only fields with non-default values. The Encode closure captures the field value and encoding parameters, keeping FieldEncoding uniform across scalar, bytes, string, and message field types.
fieldalignment: fields ordered for API clarity (number, encode, size)
Source Files