Documentation
¶
Overview ¶
Package rezi, the Rarefied Encoding (Compressible) Interpreter, contains functions for marshaling data as binary bytes using a simple encoding scheme. Encoding output length is variable based on data size. For bools, this is accomplished by having constant length of encoded output. Encoded ints are represented as one or more bytes depending on their value, with values closer to 0 taking up fewer bytes. Encoded strings are represented by an encoded int that gives the unicode codepoint count followed by the contents of the string encoded as UTF-8. For other types, an encoded integer is placed at the head of the bytes which indicates how many bytes that follow are part of the value being decoded.
Index ¶
- func DecBinary(data []byte, b encoding.BinaryUnmarshaler) (int, error)
- func DecBool(data []byte) (bool, int, error)
- func DecInt(data []byte) (int, int, error)
- func DecMapStringToBinary[E encoding.BinaryUnmarshaler](data []byte) (map[string]E, int, error)
- func DecMapStringToInt(data []byte) (map[string]int, int, error)
- func DecSliceBinary[E encoding.BinaryUnmarshaler](data []byte) ([]E, int, error)
- func DecSliceString(data []byte) ([]string, int, error)
- func DecString(data []byte) (string, int, error)
- func EncBinary(b encoding.BinaryMarshaler) []byte
- func EncBool(b bool) []byte
- func EncInt(i int) []byte
- func EncMapStringToBinary[E encoding.BinaryMarshaler](m map[string]E) []byte
- func EncMapStringToInt(m map[string]int) []byte
- func EncSliceBinary[E encoding.BinaryMarshaler](sl []E) []byte
- func EncSliceString(sl []string) []byte
- func EncString(s string) []byte
- type Decoder
- type Encoder
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecBinary ¶
func DecBinary(data []byte, b encoding.BinaryUnmarshaler) (int, error)
DecBinary decodes a value at the start of the given bytes and calls UnmarshalBinary on the provided object with those bytes.
It returns the total number of bytes read from the data bytes.
func DecBool ¶
DecBool decodes a bool value at the start of the given bytes and returns the value and the number of bytes read.
func DecInt ¶
DecInt decodes an integer value at the start of the given bytes and returns the value and the number of bytes read.
func DecMapStringToBinary ¶
func DecSliceBinary ¶
func DecSliceBinary[E encoding.BinaryUnmarshaler](data []byte) ([]E, int, error)
func DecString ¶
DecString decodes a string value at the start of the given bytes and returns the value and the number of bytes read.
func EncBinary ¶
func EncBinary(b encoding.BinaryMarshaler) []byte
EncBinary encodes a BinaryMarshaler as a slice of bytes. The value can later be decoded with DecBinary. Encoded output starts with an integer (as encoded by EncBinaryInt) indicating the number of bytes following that make up the object, followed by that many bytes containing the encoded value.
The output will be variable length; it will contain 8 bytes followed by the number of bytes encoded in those 8 bytes.
func EncBool ¶
EncBool encodes the bool value as a slice of bytes. The value can later be decoded with DecBool. No type indicator is included in the output; it is up to the caller to add this if they so wish it.
The output will always contain exactly 1 byte.
func EncInt ¶
EncInt encodes the int value as a slice of bytes. The value can later be decoded with DecInt. No type indicator is included in the output; it is up to the caller to add this if they so wish it. Integers up to 64 bits are supported with this encoding scheme.
The returned slice will be 1 to 9 bytes long. Integers larger in magnitude will result in longer slices; only 0 is encoded as a single byte.
Encoded integers start with an info byte that packs the sign and the number of following bytes needed to represent the value together. The sign is encoded as the most significant bit (the first/leftmost bit) of the byte, with 0 being positive and 1 being negative. The next significant 3 bits are unused. The least significant 4 bits contain the number of bytes that are used to encode the integer value. The bits in the info byte can be represented as `SXXXLLLL`, where S is the sign bit, X are unused bits, and L are the bits that encode the remaining length.
The remaining bytes give the value being encoded as a 2's complement 64-bit big-endian integer, omitting any leading bytes that would be encoded as 0x00 if the integer is positive, or 0xff if the integer is negative. The value 0 is special and is encoded as with infobyte 0x00 with no additional bytes. Because two's complement is used and as a result of the rules, -1 also requires no bytes besides the info byte (because it would simply be a series of eight 0xff bytes), and is therefore encoded as 0x80.
Additional examples: 1 would be encoded as [0x01 0x01], 2 as [0x01 0x02], 500 as [0x02 0x01 0xf4], etc. -2 would be encoded as [0x81 0xfe], -500 as [0x82 0xfe 0x0c], etc.
func EncMapStringToBinary ¶
func EncMapStringToBinary[E encoding.BinaryMarshaler](m map[string]E) []byte
Order of keys in output is gauranteed to be consistent.
func EncMapStringToInt ¶
Order of keys in output is gauranteed to be consistent.
func EncSliceBinary ¶
func EncSliceBinary[E encoding.BinaryMarshaler](sl []E) []byte
func EncSliceString ¶
func EncString ¶
EncString encodes a string value as a slice of bytes. The value can later be decoded with DecString. Encoded string output starts with an integer (as encoded by EncInt) indicating the number of bytes following that make up the string, followed by that many bytes containing the string encoded as UTF-8.
The output will be variable length; it will contain 8 bytes followed by the bytes that make up X characters, where X is the int value contained in the first 8 bytes. Due to the specifics of how UTF-8 strings are encoded, this may or may not be the actual number of bytes used.
Types ¶
type Decoder ¶
type Decoder[E any] interface { // DecodeBool decodes a bool value at the current position within the buffer // of the Decoder and advances the current position past the read bytes. DecodeBool() (bool, error) // DecodeInt decodes an int value at the current position within the buffer // of the Decoder and advances the current position past the read bytes. DecodeInt() (int, error) // DecodeString decodes a string value at the current position within the // buffer of the Decoder and advances the current position past the read // bytes. DecodeString() (string, error) // Decode decodes a value at the current position within the buffer of the // Decoder and advances the current position past the read bytes. Unlike the // other functions, instead of returning the value this one will set the // value of the given item. Decode(o E) error }
Decoder decodes the primitive types bool, int, and string, as well as a type that is specified by its type parameter (usually an interface of some XMarshaler type, such as BinaryUnmarshaler).
func NewBinaryDecoder ¶
func NewBinaryDecoder() Decoder[encoding.BinaryUnmarshaler]
NewBinaryDecoder creates a Decoder that can decode bytes and uses an object's UnmarshalBinary method to decode non-trivial types.
type Encoder ¶
type Encoder[E any] interface { EncodeBool(b bool) EncodeInt(i int) EncodeString(s string) Encode(o E) // Bytes returns all encoded values as sequential bytes. Bytes() []byte }
Encoder encodes the primitive types bool, int, and string, as well as a type that is specified by its type parameter (usually an interface of some XMarshaler type, such as BinaryMarshaler).
func NewBinaryEncoder ¶
func NewBinaryEncoder() Encoder[encoding.BinaryMarshaler]
NewBinaryEncoder creates an Encoder that can encode to bytes and uses an object's MarshalBinary method to encode non-trivial types.
Source Files