import "android.googlesource.com/platform/tools/gpu/binary"
Package binary implements encoding and decoding of various primitive data types to and from a binary stream. The package holds BitStream for packing and unpacking sequences of bits, Float16 for dealing with 16 bit floating- point values and Reader/Writer for encoding and decoding various value types to a binary stream. There is also the higher level Encoder/Decoder that can be used for serializing object hierarchies.
binary.Reader and binary.Writer provide a symmetrical pair of methods for encoding and decoding various data types to a binary stream. For performance reasons, each data type has a separate method for encoding and decoding rather than having a single pair of methods encoding and decoding boxed values in an interface{}.
binary.Encoder and binary.Decoder extend the binary.Reader and binary.Writer interfaces by also providing a symmetrical pair of methods for encoding and decoding object types.
const IDSize = 20
IDSize is the size of an ID.
type BitStream struct { Data []byte // The byte slice containing the bits ReadPos uint32 // The current read offset from the start of the Data slice (in bits) WritePos uint32 // The current write offset from the start of the Data slice (in bits) }
BitStream provides methods for reading and writing bits to a slice of bytes. Bits are packed in a least-significant-bit to most-significant-bit order.
func (s *BitStream) Read(count uint32) uint32
Read reads the specified number of bits from the BitStream, increamenting the ReadPos by the specified number of bits and returning the bits packed into a uint32. The bits are packed into the uint32 from LSB to MSB.
func (s *BitStream) ReadBit() uint32
ReadBit reads a single bit from the BitStream, incrementing ReadPos by one.
func (s *BitStream) Write(bits, count uint32)
Write writes the specified number of bits from the packed uint32, increamenting the WritePos by the specified number of bits. The bits are read from the uint32 from LSB to MSB.
func (s *BitStream) WriteBit(bit uint32)
WriteBit writes a single bit to the BitStream, incrementing WritePos by one.
type Class interface { // ID should be a sha1 has of the types signature, such that // no two classes generate the same ID, and any change to the types name or // fields causes it's id to change. ID() ID // Encode writes the supplied object to the supplied Encoder. // The object must be a type the Class understands, the implementation is // allowed to panic if it is not. Encode(Encoder, Object) error // Decode reads a single object from the supplied Decoder. Decode(Decoder) (Object, error) // DecodeTo reads into the supplied object from the supplied Decoder. // The object must be a type the Class understands, the implementation is // allowed to panic if it is not. DecodeTo(Decoder, Object) error // Skip moves over a single object from the supplied Decoder. // This must skip the same data that Decode would have read. Skip(Decoder) error }
Class represents a struct type in the binary registry.
type Decoder interface { Reader // ID decodes a binary.ID from the stream. ID() (ID, error) // SkipID skips over a binary.ID in the stream. SkipID() error // Value decodes an Object from the stream. Value(Object) error // SkipValue must skip the same data that a call to Value would read. // The value may be a typed nil. SkipValue(Object) error // Variant decodes and returns an Object from the stream. The Class in the // stream must have been previously registered with binary.registry.Add. Variant() (Object, error) // SkipVariant must skip the same data that a call to Variant would read. SkipVariant() (ID, error) // Object decodes and returns an Object from the stream. Object instances // that were encoded multiple times may be decoded and returned as a shared, // single instance. The Class in the stream must have been previously // registered with binary.registry.Add. Object() (Object, error) // SkipObject must skip the same data that a call to Object would read. SkipObject() (ID, error) }
Decoder extends Reader with additional methods for decoding objects.
type Encoder interface { Writer // ID writes a binary.ID to the stream. ID(ID) error // Object encodes an Object with no type preamble and no sharing. Value(obj Object) error // Variant encodes an Object with no sharing. The type of obj must have // been previously registered with binary.registry.Add. Variant(obj Object) error // Object encodes an Object, optionally encoding objects only on the first // time it sees them. The type of obj must have been previously registered // with binary.registry.Add. Object(obj Object) error }
Encoder extends Writer with additional methods for encoding objects.
type Float16 uint16
Float16 represents a 16-bit floating point number, containing a single sign bit, 5 exponent bits and 10 fractional bits. This corresponds to IEEE 754-2008 binary16 (or half precision float) type.
MSB LSB ╔════╦════╤════╤════╤════╤════╦════╤════╤════╤════╤════╤════╤════╤════╤════╤════╗ ║Sign║ E₄ │ E₃ │ E₂ │ E₁ │ E₀ ║ F₉ │ F₈ │ F₇ │ F₆ │ F₅ │ F₄ │ F₃ │ F₂ │ F₁ │ F₀ ║ ╚════╩════╧════╧════╧════╧════╩════╧════╧════╧════╧════╧════╧════╧════╧════╧════╝ Where E is the exponent bits and F is the fractional bits.
func NewFloat16(f32 float32) Float16
NewFloat16 returns a Float16 encoding of a 32-bit floating point number. Infinities and NaNs are encoded as such. Very large and very small numbers get rounded to infinity and zero respectively.
func NewFloat16Inf(sign int) Float16
Float16Inf returns positive infinity if sign >= 0, negative infinity if sign < 0.
func NewFloat16NaN() Float16
Float16NaN returns an “not-a-number” value.
func (f Float16) Float32() float32
Float32 returns the Float16 value expanded to a float32. Infinities and NaNs are expanded as such.
func (f Float16) IsInf(sign int) bool
IsInf reports whether f is an infinity, according to sign. If sign > 0, IsInf reports whether f is positive infinity. If sign < 0, IsInf reports whether f is negative infinity. If sign == 0, IsInf reports whether f is either infinity.
func (f Float16) IsNaN() bool
IsNaN reports whether f is an “not-a-number” value.
type Generate struct{}
Generate is used to tag structures that need an auto generated Class. The codergen function searches packages for structs that have this type as an anonymous field, and then automatically generates the encoding and decoding functionality for those structures. For example, the following struct would create the Class with methods needed to encode and decode the Name and Value fields, and register that class. The embedding will also fully implement the binary.Object interface, but with methods that panic. This will get overridden with the generated Methods. This is important because it means the package is resolvable without the generated code, which means the types can be correctly evaluated during the generation process.
type MyNamedValue struct {
binary.Generate Name string Value []byte
}
func (Generate) Class() Class
type ID [IDSize]byte
ID is a codeable unique identifier.
func NewID(data ...[]byte) ID
Create a new ID that is the sha1 hash of the supplied data.
func ParseID(s string) (id ID, err error)
ParseID parses lowercase string s as a 20 byte hex-encoded ID.
func (id ID) Format(f fmt.State, c rune)
func (id ID) String() string
func (id ID) Valid() bool
Valid returns true if the id is not the default value.
type Object interface { // Class returns the serialize information and functionality for this type. // The method should be valid on a nil pointer. Class() Class }
Object is the interface to any class that wants to be encoded/decoded.
type Reader interface { // Data writes the data bytes in their entirety. Data([]byte) error // Skip jumps past count bytes. Skip(count uint32) error // Bool decodes and returns a boolean value from the Reader. Bool() (bool, error) // Int8 decodes and returns a signed, 8 bit integer value from the Reader. Int8() (int8, error) // Uint8 decodes and returns an unsigned, 8 bit integer value from the Reader. Uint8() (uint8, error) // Int16 decodes and returns a signed, 16 bit integer value from the Reader. Int16() (int16, error) // Uint16 decodes and returns an unsigned, 16 bit integer value from the Reader. Uint16() (uint16, error) // Int32 decodes and returns a signed, 32 bit integer value from the Reader. Int32() (int32, error) // Uint32 decodes and returns an unsigned, 32 bit integer value from the Reader. Uint32() (uint32, error) // Float32 decodes and returns a 32 bit floating-point value from the Reader. Float32() (float32, error) // Int64 decodes and returns a signed, 64 bit integer value from the Reader. Int64() (int64, error) // Uint64 decodes and returns an unsigned, 64 bit integer value from the Reader. Uint64() (uint64, error) // Float64 decodes and returns a 64 bit floating-point value from the Reader. Float64() (float64, error) // String decodes and returns a string from the Reader. String() (string, error) // SkipString skips over a single string from the Reader. SkipString() error }
Reader provides methods for decoding values.
type Writer interface { // Data writes the data bytes in their entirety. Data([]byte) error // Bool encodes a boolean value to the Writer. Bool(bool) error // Int8 encodes a signed, 8 bit integer value to the Writer. Int8(int8) error // Uint8 encodes an unsigned, 8 bit integer value to the Writer. Uint8(uint8) error // Int16 encodes a signed, 16 bit integer value to the Writer. Int16(int16) error // Uint16 encodes an unsigned, 16 bit integer value to the Writer. Uint16(uint16) error // Int32 encodes a signed, 32 bit integer value to the Writer. Int32(int32) error // Uint32 encodes an usigned, 32 bit integer value to the Writer. Uint32(uint32) error // Float32 encodes a 32 bit floating-point value to the Writer. Float32(float32) error // Int64 encodes a signed, 64 bit integer value to the Writer. Int64(int64) error // Uint64 encodes an unsigned, 64 bit integer value to the Encoders's io.Writer. Uint64(uint64) error // Float64 encodes a 64 bit floating-point value to the Writer. Float64(float64) error // String encodes a string to the Writer. String(string) error }
Writer provides methods for encoding values.