README
¶
encode
Provides utilities for encoding and decoding structures into raw bytes.
Normal usage of this package looks like this:
type encodableFoo struct {
a uint16
b string
c bool
}
func (e encodableFoo) encoding() encode.Encoding {
return encode.New(
encode.BigEndianUint16(&e.a),
encode.LengthDelimString(&e.b),
encode.Bool(&e.c),
)
}
func (e encodableFoo) Encode() []byte {
return e.encoding().Encode()
}
func (e encodableFoo) Decode(b []byte) error {
return e.encoding().Decode(b)
}
Documentation
¶
Overview ¶
Package encode provides utilities for encoding and decoding structures into raw bytes.
Normal usage of this package looks like this:
type encodableFoo struct {
a uint16
b string
c bool
}
func (e encodableFoo) encoding() encode.Encoding {
return encode.New(
encode.FixedUint16(&e.a),
encode.LengthDelimString(&e.b),
encode.Bool(&e.c),
)
}
func (e encodableFoo) Encode() []byte {
return e.encoding().Encode()
}
func (e encodableFoo) Decode(b []byte) error {
return e.encoding().Decode(b)
}
Index ¶
- Variables
- type BitpackItem
- type Encoding
- type Item
- type Tuple
- type TupleItem
- func Bitpacked(items ...BitpackItem) TupleItem
- func Bool(v *bool) TupleItem
- func Byte(v *byte) TupleItem
- func Bytes16(v *[16]byte) TupleItem
- func Bytes32(v *[32]byte) TupleItem
- func DelimBytes(v *[]byte, delim byte) TupleItem
- func FixedUint16(v *uint16) TupleItem
- func FixedUint32(v *uint32) TupleItem
- func FixedUint64(v *uint64) TupleItem
- func OrdUvarint64(v *uint64) TupleItem
- func OrdVarint64(v *int64) TupleItem
- func Padding(n int) TupleItem
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidBool = errors.New("encode: invalid bool, encoded value not 0 or 1")
var ErrInvalidVarint = errors.New("encode: invalid varint")
var ErrOverflowVarint = errors.New("encode: overflowed varint")
Functions ¶
This section is empty.
Types ¶
type BitpackItem ¶
type BitpackItem interface {
// contains filtered or unexported methods
}
See Bitpacked() for usage.
func BitFlags ¶
func BitFlags(v ...*bool) BitpackItem
Encode each value as a single bit, high-order to low-order.
type Item ¶
type Item interface {
// Encode this item into buf. buf will be at least Size() bytes.
Encode(buf []byte)
// Decode buf into this item, mutating it to match the representation in buf.
Decode(buf []byte) error
// The number of bytes that Encode() will use.
Size() int
}
func LengthDelimBytes ¶
Encode v as a uvarint of v's length, followed by v.
func LengthDelimString ¶
Encode v as a uvarint of v's length, followed by v.
func Uvarint32 ¶
Encode v using a variable-length encoding, so that smaller numbers use fewer bytes.
See more at https://developers.google.com/protocol-buffers/docs/encoding#varints
input bits high order low order uuuuwwwwwwwzzzzzzzyyyyyyyxxxxxxx min max encoded size encoding 0 2^7 - 1 1 0xxxxxxx 2^7 2^14 - 1 2 1xxxxxxx 0yyyyyyy 2^14 2^21 - 1 3 1xxxxxxx 1yyyyyyy 0zzzzzzz 2^21 2^28 - 1 4 1xxxxxxx 1yyyyyyy 1zzzzzzz 0wwwwwww 2^28 2^32 - 1 5 1xxxxxxx 1yyyyyyy 1zzzzzzz 1wwwwwww 0000uuuu
func Uvarint64 ¶
Encode v using a variable-length encoding, so that smaller numbers use fewer bytes.
See more at https://developers.google.com/protocol-buffers/docs/encoding#varints
input bits high order low order ddcccccccbbbbbbbaaaaaaavvvvvvvuuuuuuwwwwwwwzzzzzzzyyyyyyyxxxxxxx min max encoded size encoding 0 2^7 - 1 1 0xxxxxxx 2^7 2^14 - 1 2 1xxxxxxx 0yyyyyyy 2^14 2^21 - 1 3 1xxxxxxx 1yyyyyyy 0zzzzzzz 2^21 2^28 - 1 4 1xxxxxxx 1yyyyyyy 1zzzzzzz 0wwwwwww 2^28 2^35 - 1 5 1xxxxxxx 1yyyyyyy 1zzzzzzz 1wwwwwww 0uuuuuuu 2^35 2^42 - 1 6 1xxxxxxx 1yyyyyyy 1zzzzzzz 1wwwwwww 1uuuuuuu 0vvvvvvv 2^42 2^49 - 1 7 1xxxxxxx 1yyyyyyy 1zzzzzzz 1wwwwwww 1uuuuuuu 1vvvvvvv 0aaaaaaa 2^49 2^56 - 1 8 1xxxxxxx 1yyyyyyy 1zzzzzzz 1wwwwwww 1uuuuuuu 1vvvvvvv 1aaaaaaa 0bbbbbbb 2^56 2^63 - 1 9 1xxxxxxx 1yyyyyyy 1zzzzzzz 1wwwwwww 1uuuuuuu 1vvvvvvv 1aaaaaaa 1bbbbbbb 0ccccccc 2^63 2^64 - 1 10 1xxxxxxx 1yyyyyyy 1zzzzzzz 1wwwwwww 1uuuuuuu 1vvvvvvv 1aaaaaaa 1bbbbbbb 1ccccccc 000000dd
type Tuple ¶
type Tuple struct {
// contains filtered or unexported fields
}
func (Tuple) EncodePrefix ¶
type TupleItem ¶
type TupleItem interface {
Item
EncodeTuple(buf []byte, last bool)
DecodeTuple(buf []byte, last bool) error
SizeTuple(last bool) int
OrderPreserving()
}
func Bitpacked ¶
func Bitpacked(items ...BitpackItem) TupleItem
Encodes the bitpacked items, from high-order to low-order, packed directly next to each other. Pads the end to the nearest byte.
Example ¶
b := make([]byte, 3)
threeBits := byte(0x3)
sixBits := byte(0x2A)
fourBits := byte(0xD)
flag1 := true
flag2 := false
flag3 := true
flag4 := true
Bitpacked(
Bits8(&threeBits, 3), // 011
Bits8(&sixBits, 6), // 101010
Bits8(&fourBits, 4), // 1101
BitPadding(5), // 00000
BitFlags(
&flag1, // 1
&flag2, // 0
&flag3, // 1
&flag4, // 1
),
).Encode(b)
fmt.Printf("%08b %08b %08b\n", b[0], b[1], b[2])
Output: 01110101 01101000 00101100
func DelimBytes ¶
Encodes v, using {delim,0x00} as the ending delimeter. delim is allowed to appear in v, and will be escaped with a following 0xFF per occurrence.
func FixedUint16 ¶
Encode v in big endian order, taking 2 bytes.
func FixedUint32 ¶
Encode v in big endian order, taking 4 bytes.
func FixedUint64 ¶
Encode v in big endian order, taking 8 bytes.
func OrdUvarint64 ¶
Similar to Uvarint64, produces a variable-length encoding for v. However, it has two advantages: it preserves ordering, in that the encoded bytes will lexicographically order the same as the inputs would be ordered numerically; and it uses one fewer byte for numbers larger than 2^63-1.
It does this by using a similar technique to UTF-8 (see https://en.wikipedia.org/wiki/UTF-8#Examples), where only significant bits are encoded, and a number of leading ones is used to determine the length of the encoding.
min max encoded size encoding, where x is an input bit 0 2^7 - 1 1 0xxxxxxx 2^7 2^14 - 1 2 10xxxxxx xxxxxxxx 2^14 2^21 - 1 3 110xxxxx xxxxxxxx xxxxxxxx 2^21 2^28 - 1 4 1110xxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^28 2^35 - 1 5 11110xxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^35 2^42 - 1 6 111110xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^42 2^49 - 1 7 1111110x xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^49 2^56 - 1 8 11111110 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^56 2^64 - 1 9 11111111 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
func OrdVarint64 ¶
Similar to Varint64, produces a variable-length encoding for v. However, OrdVarint64's encoding lexicographically orders in the same order as the input.
The encoding places the sign in the higest-order bit, with 0 meaning negative, so that negative numbers order before all positive numbers. Leading zeroes for positive numbers and leading ones for negative numbers are left off, encoding only the k lowest-order bits according to the following scheme:
min max encoded size encoding, where x is an input bit -2^63 -2^55 - 1 9 00000000 0xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx -2^55 -2^48 - 1 8 00000000 1xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx -2^48 -2^41 - 1 7 00000001 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx -2^41 -2^34 - 1 6 0000001x xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx -2^34 -2^27 - 1 5 000001xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx -2^27 -2^20 - 1 4 00001xxx xxxxxxxx xxxxxxxx xxxxxxxx -2^20 -2^13 - 1 3 0001xxxx xxxxxxxx xxxxxxxx -2^13 -2^6 - 1 2 001xxxxx xxxxxxxx -2^6 -1 1 01xxxxxx 0 2^6 - 1 1 10xxxxxx 2^6 2^13 - 1 2 110xxxxx xxxxxxxx 2^13 2^20 - 1 3 1110xxxx xxxxxxxx xxxxxxxx 2^20 2^27 - 1 4 11110xxx xxxxxxxx xxxxxxxx xxxxxxxx 2^27 2^34 - 1 5 111110xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^34 2^41 - 1 6 1111110x xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^41 2^48 - 1 7 11111110 xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^48 2^55 - 1 8 11111111 0xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx 2^55 2^63 - 1 9 11111111 1xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
Source Files