Documentation
¶
Overview ¶
Package scalar provides a type-safe encoding, decoding, and size computation layer for all protobuf scalar types. It builds on top of the wire package, bridging raw wire format primitives to protobuf-typed values such as int32, sint64, double, bool, string, and bytes.
All encoding functions follow the append pattern inherited from wire: they take a byte slice, append the encoded value, and return the extended slice. All decoding functions follow the consume pattern: they read from the front of a byte slice and return the decoded value along with the number of bytes consumed. A negative bytes-consumed value signals an error propagated from the wire layer.
The Kind type enumerates all 18 protobuf field kinds (double through group) and provides methods for wire type mapping, packability queries, and string representation. The Codec type offers dynamic dispatch of scalar encoding and decoding by Kind, using uint64 as the universal value representation for numeric types.
Index ¶
- func AppendBool(b []byte, v bool) []byte
- func AppendBytes(b []byte, v []byte) []byte
- func AppendDouble(b []byte, v float64) []byte
- func AppendEnum(b []byte, v int32) []byte
- func AppendFixed32(b []byte, v uint32) []byte
- func AppendFixed64(b []byte, v uint64) []byte
- func AppendFloat(b []byte, v float32) []byte
- func AppendInt32(b []byte, v int32) []byte
- func AppendInt64(b []byte, v int64) []byte
- func AppendSfixed32(b []byte, v int32) []byte
- func AppendSfixed64(b []byte, v int64) []byte
- func AppendSint32(b []byte, v int32) []byte
- func AppendSint64(b []byte, v int64) []byte
- func AppendString(b []byte, v string) []byte
- func AppendUint32(b []byte, v uint32) []byte
- func AppendUint64(b []byte, v uint64) []byte
- func ConsumeBool(b []byte) (bool, int)
- func ConsumeBytes(b []byte) ([]byte, int)
- func ConsumeDouble(b []byte) (float64, int)
- func ConsumeEnum(b []byte) (int32, int)
- func ConsumeFixed32(b []byte) (uint32, int)
- func ConsumeFixed64(b []byte) (uint64, int)
- func ConsumeFloat(b []byte) (float32, int)
- func ConsumeInt32(b []byte) (int32, int)
- func ConsumeInt64(b []byte) (int64, int)
- func ConsumeSfixed32(b []byte) (int32, int)
- func ConsumeSfixed64(b []byte) (int64, int)
- func ConsumeSint32(b []byte) (int32, int)
- func ConsumeSint64(b []byte) (int64, int)
- func ConsumeString(b []byte) (string, int)
- func ConsumeUint32(b []byte) (uint32, int)
- func ConsumeUint64(b []byte) (uint64, int)
- func DefaultValue(k Kind) any
- func SizeBool(_ bool) int
- func SizeBytes(v []byte) int
- func SizeDouble(float64) int
- func SizeEnum(v int32) int
- func SizeFixed32(uint32) int
- func SizeFixed64(uint64) int
- func SizeFloat(float32) int
- func SizeInt32(v int32) int
- func SizeInt64(v int64) int
- func SizeSfixed32(int32) int
- func SizeSfixed64(int64) int
- func SizeSint32(v int32) int
- func SizeSint64(v int64) int
- func SizeString(v string) int
- func SizeUint32(v uint32) int
- func SizeUint64(v uint64) int
- type Codec
- type InvalidKindError
- type Kind
- type UnsupportedKindError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendBool ¶
AppendBool appends the protobuf varint encoding of v to b and returns the extended slice. True is encoded as varint 1 and false as varint 0.
func AppendBytes ¶
AppendBytes appends a length-delimited byte field to b and returns the extended slice. The data length is encoded as a varint prefix followed by the raw data bytes.
func AppendDouble ¶
AppendDouble appends the little-endian IEEE 754 encoding of v to b and returns the extended slice.
func AppendEnum ¶
AppendEnum appends the protobuf varint encoding of enum value v to b and returns the extended slice. Enum encoding is identical to int32 encoding.
func AppendFixed32 ¶
AppendFixed32 appends the little-endian encoding of v to b and returns the extended slice.
func AppendFixed64 ¶
AppendFixed64 appends the little-endian encoding of v to b and returns the extended slice.
func AppendFloat ¶
AppendFloat appends the little-endian IEEE 754 encoding of v to b and returns the extended slice.
func AppendInt32 ¶
AppendInt32 appends the protobuf varint encoding of v to b and returns the extended slice. Negative values are sign-extended to 64 bits, producing a 10-byte varint per the protobuf specification.
func AppendInt64 ¶
AppendInt64 appends the protobuf varint encoding of v to b and returns the extended slice. Negative values are encoded as their two's-complement uint64 representation, producing a 10-byte varint.
func AppendSfixed32 ¶
AppendSfixed32 appends the little-endian encoding of v to b and returns the extended slice. The signed int32 is reinterpreted as uint32 for encoding.
func AppendSfixed64 ¶
AppendSfixed64 appends the little-endian encoding of v to b and returns the extended slice. The signed int64 is reinterpreted as uint64 for encoding.
func AppendSint32 ¶
AppendSint32 appends the ZigZag-then-varint encoding of v to b and returns the extended slice. ZigZag encoding maps small absolute values to small unsigned values, producing compact output for values near zero.
func AppendSint64 ¶
AppendSint64 appends the ZigZag-then-varint encoding of v to b and returns the extended slice. ZigZag encoding maps small absolute values to small unsigned values, producing compact output for values near zero.
func AppendString ¶
AppendString appends a length-delimited string field to b and returns the extended slice. The string length is encoded as a varint prefix followed by the raw string bytes.
func AppendUint32 ¶
AppendUint32 appends the protobuf varint encoding of v to b and returns the extended slice.
func AppendUint64 ¶
AppendUint64 appends the protobuf varint encoding of v to b and returns the extended slice.
func ConsumeBool ¶
ConsumeBool reads a protobuf varint from the front of b and returns the decoded bool value and the number of bytes consumed. Any non-zero varint value decodes as true per the protobuf specification. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeBytes ¶
ConsumeBytes reads a length-delimited byte field from the front of b and returns the decoded data as a sub-slice of the input and the number of bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeDouble ¶
ConsumeDouble reads a little-endian IEEE 754 encoded float64 from the front of b. It returns the decoded value and the number of bytes consumed (8). A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeEnum ¶
ConsumeEnum reads a protobuf varint from the front of b and returns the decoded enum value as int32 and the number of bytes consumed. Enum decoding is identical to int32 decoding. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeFixed32 ¶
ConsumeFixed32 reads a little-endian encoded uint32 from the front of b. It returns the decoded value and the number of bytes consumed (4). A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeFixed64 ¶
ConsumeFixed64 reads a little-endian encoded uint64 from the front of b. It returns the decoded value and the number of bytes consumed (8). A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeFloat ¶
ConsumeFloat reads a little-endian IEEE 754 encoded float32 from the front of b. It returns the decoded value and the number of bytes consumed (4). A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeInt32 ¶
ConsumeInt32 reads a protobuf varint from the front of b and returns the decoded int32 value and the number of bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeInt64 ¶
ConsumeInt64 reads a protobuf varint from the front of b and returns the decoded int64 value and the number of bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeSfixed32 ¶
ConsumeSfixed32 reads a little-endian encoded int32 from the front of b. It returns the decoded value and the number of bytes consumed (4). The uint32 wire representation is reinterpreted as int32. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeSfixed64 ¶
ConsumeSfixed64 reads a little-endian encoded int64 from the front of b. It returns the decoded value and the number of bytes consumed (8). The uint64 wire representation is reinterpreted as int64. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeSint32 ¶
ConsumeSint32 reads a ZigZag-encoded varint from the front of b, decodes it to the original signed int32 value, and returns the value and bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeSint64 ¶
ConsumeSint64 reads a ZigZag-encoded varint from the front of b, decodes it to the original signed int64 value, and returns the value and bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeString ¶
ConsumeString reads a length-delimited string field from the front of b and returns the decoded string and the number of bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeUint32 ¶
ConsumeUint32 reads a protobuf varint from the front of b and returns the decoded uint32 value and the number of bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func ConsumeUint64 ¶
ConsumeUint64 reads a protobuf varint from the front of b and returns the decoded uint64 value and the number of bytes consumed. A negative bytesConsumed signals an error propagated from the wire layer.
func DefaultValue ¶
DefaultValue returns the Go zero value for the given protobuf field kind. Each kind maps to a specific Go type: float64 for double, float32 for float, int32 for int32/sint32/sfixed32/enum, int64 for int64/sint64/sfixed64, uint32 for uint32/fixed32, uint64 for uint64/fixed64, bool for bool, string for string, []byte(nil) for bytes, and nil for message/group. Invalid Kind values return nil.
func SizeBool ¶
SizeBool returns the number of bytes required to encode a bool value as a protobuf varint. Both true (varint 1) and false (varint 0) require exactly one byte.
func SizeBytes ¶
SizeBytes returns the number of bytes required to encode a length-delimited byte field. The result includes both the varint-encoded length prefix and the data itself.
func SizeDouble ¶
SizeDouble returns the encoded size of a double value, which is always 8.
func SizeEnum ¶
SizeEnum returns the number of bytes required to varint-encode enum value v. Enum sizing is identical to int32 sizing.
func SizeFixed32 ¶
SizeFixed32 returns the encoded size of a fixed32 value, which is always 4.
func SizeFixed64 ¶
SizeFixed64 returns the encoded size of a fixed64 value, which is always 8.
func SizeInt32 ¶
SizeInt32 returns the number of bytes required to varint-encode v. Negative values are sign-extended to 64 bits, matching the encoding behavior of AppendInt32, and always produce a 10-byte varint.
func SizeInt64 ¶
SizeInt64 returns the number of bytes required to varint-encode v. Negative values are encoded as their two's-complement uint64 representation.
func SizeSfixed32 ¶
SizeSfixed32 returns the encoded size of an sfixed32 value, which is always 4.
func SizeSfixed64 ¶
SizeSfixed64 returns the encoded size of an sfixed64 value, which is always 8.
func SizeSint32 ¶
SizeSint32 returns the number of bytes required to encode v as a ZigZag-then-varint value, without performing the encoding.
func SizeSint64 ¶
SizeSint64 returns the number of bytes required to encode v as a ZigZag-then-varint value, without performing the encoding.
func SizeString ¶
SizeString returns the number of bytes required to encode a length-delimited string field. The result includes both the varint-encoded length prefix and the string data itself.
func SizeUint32 ¶
SizeUint32 returns the number of bytes required to varint-encode v.
func SizeUint64 ¶
SizeUint64 returns the number of bytes required to varint-encode v.
Types ¶
type Codec ¶
type Codec struct{}
Codec is a stateless struct that provides dynamic dispatch of scalar encoding, decoding, and size computation by Kind. All numeric values are represented as uint64 and the caller is responsible for type conversion. Length-delimited kinds (string, bytes, message) and group are not supported and cause a panic.
func (*Codec) AppendScalar ¶
AppendScalar appends the wire encoding of v (represented as uint64) to b for the given Kind and returns the extended slice. For zigzag kinds, v must already contain the zigzag-encoded value. Length-delimited and group kinds panic.
func (*Codec) ConsumeScalar ¶
ConsumeScalar reads the wire encoding for the given Kind from the front of b and returns the raw uint64 value and the number of bytes consumed. For zigzag kinds, the returned value is the raw varint (caller applies zigzag decode). Length-delimited and group kinds panic.
type InvalidKindError ¶
InvalidKindError indicates that a Codec operation was called with a kind value outside the valid range (1-18). It carries the method name and the offending Kind for diagnostic context.
func (*InvalidKindError) Error ¶
func (e *InvalidKindError) Error() string
Error returns a human-readable message describing the invalid kind.
type Kind ¶
type Kind int8
Kind represents one of the 18 protobuf field kinds. It is a named type over int8 to provide type safety. The zero value is intentionally invalid.
const ( KindDouble Kind = iota + 1 // 1 KindFloat // 2 KindInt64 // 3 KindUint64 // 4 KindInt32 // 5 KindFixed64 // 6 KindFixed32 // 7 KindBool // 8 KindString // 9 KindBytes // 10 KindUint32 // 11 KindEnum // 12 KindSfixed32 // 13 KindSfixed64 // 14 KindSint32 // 15 KindSint64 // 16 KindMessage // 17 KindGroup // 18 )
Kind constants for all 18 protobuf field kinds. Values start at 1 so that the zero value of Kind is invalid by design.
func (Kind) IsPackable ¶
IsPackable reports whether fields of this kind can use packed repeated encoding. Numeric and bool kinds are packable; string, bytes, message, and group are not.
func (Kind) String ¶
String returns the lowercase protobuf name of the kind. For the 18 valid kinds (1-18) it returns names such as "double" and "sint64". For out-of-range values it returns a formatted string like "Kind(19)".
type UnsupportedKindError ¶
UnsupportedKindError indicates that a Codec operation was called with a kind it does not support (e.g., length-delimited or group kinds passed to AppendScalar). It carries the method name and the offending Kind for diagnostic context.
func (*UnsupportedKindError) Error ¶
func (e *UnsupportedKindError) Error() string
Error returns a human-readable message describing the unsupported kind.
Source Files