serializer

package module
v0.0.0-...-25ef478 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 12, 2023 License: Apache-2.0, BSD-2-Clause Imports: 8 Imported by: 34

Documentation

Index

Constants

View Source
const (
	// OneByte is the byte size of a single byte.
	OneByte = 1
	// Int16ByteSize is the byte size of an int16.
	Int16ByteSize = 2
	// UInt16ByteSize is the byte size of a uint16.
	UInt16ByteSize = 2
	// Int32ByteSize is the byte size of an int32.
	Int32ByteSize = 4
	// UInt32ByteSize is the byte size of a uint32.
	UInt32ByteSize = 4
	// Float32ByteSize is the byte size of a float32.
	Float32ByteSize = 4
	// Int64ByteSize is the byte size of an int64.
	Int64ByteSize = 8
	// UInt64ByteSize is the byte size of an uint64.
	UInt64ByteSize = 8
	// Float64ByteSize is the byte size of a float64.
	Float64ByteSize = 8
	// TypeDenotationByteSize is the size of a type denotation.
	TypeDenotationByteSize = UInt32ByteSize
	// SmallTypeDenotationByteSize is the size of a type denotation for a small range of possible values.
	SmallTypeDenotationByteSize = OneByte
	// PayloadLengthByteSize is the size of the payload length denoting bytes.
	PayloadLengthByteSize = UInt32ByteSize
	// MinPayloadByteSize is the minimum size of a payload (together with its length denotation).
	MinPayloadByteSize = UInt32ByteSize + OneByte
)

Variables

View Source
var (
	// ErrInvalidBytes gets returned when data is invalid for deserialization.
	ErrInvalidBytes = errors.New("invalid bytes")
	// ErrDeserializationTypeMismatch gets returned when a denoted type for a given object is mismatched.
	// For example, while trying to deserialize a signature unlock block, a reference unlock block is seen.
	ErrDeserializationTypeMismatch = errors.New("data type is invalid for deserialization")
	// ErrUnknownArrayValidationMode gets returned for unknown array validation modes.
	ErrUnknownArrayValidationMode = errors.New("unknown array validation mode")
	// ErrArrayValidationMinElementsNotReached gets returned if the count of elements is too small.
	ErrArrayValidationMinElementsNotReached = errors.New("min count of elements within the array not reached")
	// ErrArrayValidationMaxElementsExceeded gets returned if the count of elements is too big.
	ErrArrayValidationMaxElementsExceeded = errors.New("max count of elements within the array exceeded")
	// ErrArrayValidationViolatesUniqueness gets returned if the array elements are not unique.
	ErrArrayValidationViolatesUniqueness = errors.New("array elements must be unique")
	// ErrArrayValidationOrderViolatesLexicalOrder gets returned if the array elements are not in lexical order.
	ErrArrayValidationOrderViolatesLexicalOrder = errors.New("array elements must be in their lexical order (byte wise)")
	// ErrDeserializationNotEnoughData gets returned if there is not enough data available to deserialize a given object.
	ErrDeserializationNotEnoughData = errors.New("not enough data for deserialization")
	// ErrDeserializationInvalidBoolValue gets returned when a bool value is tried to be read but it is neither 0 or 1.
	ErrDeserializationInvalidBoolValue = errors.New("invalid bool value")
	// ErrDeserializationLengthInvalid gets returned if a length denotation exceeds a specified limit.
	ErrDeserializationLengthInvalid = errors.New("length denotation invalid")
	// ErrDeserializationNotAllConsumed gets returned if not all bytes were consumed during deserialization of a given type.
	ErrDeserializationNotAllConsumed = errors.New("not all data has been consumed but should have been")
)

Functions

func CheckExactByteLength

func CheckExactByteLength(exact int, length int) error

CheckExactByteLength checks that the given length equals exact.

func CheckMinByteLength

func CheckMinByteLength(min int, length int) error

CheckMinByteLength checks that length is min. min.

func CheckType

func CheckType(data []byte, shouldType uint32) error

CheckType checks that the denoted type equals the shouldType.

func CheckTypeByte

func CheckTypeByte(data []byte, shouldType byte) error

CheckTypeByte checks that the denoted type byte equals the shouldType.

Types

type ArrayOf32Bytes

type ArrayOf32Bytes = [32]byte

ArrayOf32Bytes is an array of 32 bytes.

type ArrayOf49Bytes

type ArrayOf49Bytes = [49]byte

ArrayOf49Bytes is an array of 49 bytes.

type ArrayOf64Bytes

type ArrayOf64Bytes = [64]byte

ArrayOf64Bytes is an array of 64 bytes.

type ArrayRules

type ArrayRules struct {
	// The min array bound.
	Min uint
	// The max array bound.
	Max uint
	// The mode of validation.
	ValidationMode ArrayValidationMode
}

ArrayRules defines rules around a to be deserialized array. Min and Max at 0 define an unbounded array.

func (*ArrayRules) CheckBounds

func (ar *ArrayRules) CheckBounds(count uint) error

CheckBounds checks whether the given count violates the array bounds.

func (*ArrayRules) ElementUniqueValidator

func (ar *ArrayRules) ElementUniqueValidator() ElementValidationFunc

ElementUniqueValidator returns an ElementValidationFunc which returns an error if the given element is not unique.

func (*ArrayRules) ElementValidationFunc

func (ar *ArrayRules) ElementValidationFunc(mode ArrayValidationMode) ElementValidationFunc

ElementValidationFunc returns a new ElementValidationFunc according to the given mode.

func (*ArrayRules) LexicalOrderValidator

func (ar *ArrayRules) LexicalOrderValidator() ElementValidationFunc

LexicalOrderValidator returns an ElementValidationFunc which returns an error if the given byte slices are not ordered lexicographically.

func (*ArrayRules) LexicalOrderWithoutDupsValidator

func (ar *ArrayRules) LexicalOrderWithoutDupsValidator() ElementValidationFunc

LexicalOrderWithoutDupsValidator returns an ElementValidationFunc which returns an error if the given byte slices are not ordered lexicographically or any elements are duplicated.

type ArrayValidationMode

type ArrayValidationMode byte

ArrayValidationMode defines the mode of array validation.

const (
	// ArrayValidationModeNone instructs the array validation to perform no validation.
	ArrayValidationModeNone ArrayValidationMode = 0
	// ArrayValidationModeNoDuplicates instructs the array validation to check for duplicates.
	ArrayValidationModeNoDuplicates ArrayValidationMode = 1 << 0
	// ArrayValidationModeLexicalOrdering instructs the array validation to check for lexical order.
	ArrayValidationModeLexicalOrdering ArrayValidationMode = 1 << 1
)

func (ArrayValidationMode) HasMode

func (av ArrayValidationMode) HasMode(mode ArrayValidationMode) bool

HasMode checks whether the array element validation mode includes the given mode.

type DeSerializationMode

type DeSerializationMode byte

DeSerializationMode defines the mode of de/serialization.

const (
	// DeSeriModeNoValidation instructs de/serialization to perform no validation.
	DeSeriModeNoValidation DeSerializationMode = 0
	// DeSeriModePerformValidation instructs de/serialization to perform validation.
	DeSeriModePerformValidation DeSerializationMode = 1 << 0
	// DeSeriModePerformLexicalOrdering instructs de/deserialization to perform ordering of certain struct arrays by their lexical serialized form.
	DeSeriModePerformLexicalOrdering DeSerializationMode = 1 << 1
)

func (DeSerializationMode) HasMode

func (sm DeSerializationMode) HasMode(mode DeSerializationMode) bool

HasMode checks whether the de/serialization mode includes the given mode.

type Deserializer

type Deserializer struct {
	// contains filtered or unexported fields
}

Deserializer is a utility to deserialize bytes.

func NewDeserializer

func NewDeserializer(src []byte) *Deserializer

NewDeserializer creates a new Deserializer.

func (*Deserializer) AbortIf

func (d *Deserializer) AbortIf(errProducer ErrProducer) *Deserializer

AbortIf calls the given ErrProducer if the Deserializer did not encounter an error yet. Return nil from the ErrProducer to indicate continuation of the deserialization.

func (*Deserializer) ConsumedAll

func (d *Deserializer) ConsumedAll(errProducer ErrProducerWithLeftOver) *Deserializer

ConsumedAll calls the given ErrProducerWithLeftOver if not all bytes have been consumed from the Deserializer's src.

func (*Deserializer) Do

func (d *Deserializer) Do(f func()) *Deserializer

Do calls f in the Deserializer chain.

func (*Deserializer) Done

func (d *Deserializer) Done() (int, error)

Done finishes the Deserializer by returning the read bytes and occurred errors.

func (*Deserializer) ReadArrayOf32Bytes

func (d *Deserializer) ReadArrayOf32Bytes(arr *ArrayOf32Bytes, errProducer ErrProducer) *Deserializer

ReadArrayOf32Bytes reads an array of 32 bytes.

func (*Deserializer) ReadArrayOf49Bytes

func (d *Deserializer) ReadArrayOf49Bytes(arr *ArrayOf49Bytes, errProducer ErrProducer) *Deserializer

ReadArrayOf49Bytes reads an array of 49 bytes.

func (*Deserializer) ReadArrayOf64Bytes

func (d *Deserializer) ReadArrayOf64Bytes(arr *ArrayOf64Bytes, errProducer ErrProducer) *Deserializer

ReadArrayOf64Bytes reads an array of 64 bytes.

func (*Deserializer) ReadBool

func (d *Deserializer) ReadBool(dest *bool, errProducer ErrProducer) *Deserializer

ReadBool reads a bool into dest.

func (*Deserializer) ReadByte

func (d *Deserializer) ReadByte(dest *byte, errProducer ErrProducer) *Deserializer

ReadByte reads a byte into dest.

func (*Deserializer) ReadBytes

func (d *Deserializer) ReadBytes(slice *[]byte, numBytes int, errProducer ErrProducer) *Deserializer

ReadBytes reads specified number of bytes. Use this function only to read fixed size slices/arrays, otherwise use ReadVariableByteSlice instead.

func (*Deserializer) ReadNum

func (d *Deserializer) ReadNum(dest interface{}, errProducer ErrProducer) *Deserializer

ReadNum reads a number into dest.

func (*Deserializer) ReadObject

ReadObject reads an object, using the given SerializableSelectorFunc.

func (*Deserializer) ReadPayload

ReadPayload reads a payload.

func (*Deserializer) ReadSliceOfArraysOf32Bytes

func (d *Deserializer) ReadSliceOfArraysOf32Bytes(slice *SliceOfArraysOf32Bytes, deSeriMode DeSerializationMode, lenType SeriLengthPrefixType, arrayRules *ArrayRules, errProducer ErrProducer) *Deserializer

ReadSliceOfArraysOf32Bytes reads a slice of arrays of 32 bytes.

func (*Deserializer) ReadSliceOfArraysOf64Bytes

func (d *Deserializer) ReadSliceOfArraysOf64Bytes(slice *SliceOfArraysOf64Bytes, deSeriMode DeSerializationMode, lenType SeriLengthPrefixType, arrayRules *ArrayRules, errProducer ErrProducer) *Deserializer

ReadSliceOfArraysOf64Bytes reads a slice of arrays of 64 bytes.

func (*Deserializer) ReadSliceOfObjects

func (d *Deserializer) ReadSliceOfObjects(f ReadObjectsConsumerFunc, deSeriMode DeSerializationMode, lenType SeriLengthPrefixType, typeDen TypeDenotationType, serSel SerializableSelectorFunc, arrayRules *ArrayRules, errProducer ErrProducer) *Deserializer

ReadSliceOfObjects reads a slice of objects.

func (*Deserializer) ReadString

func (d *Deserializer) ReadString(s *string, lenType SeriLengthPrefixType, errProducer ErrProducer, maxSize ...int) *Deserializer

ReadString reads a string.

func (*Deserializer) ReadTime

func (d *Deserializer) ReadTime(dest *time.Time, errProducer ErrProducer) *Deserializer

ReadTime reads a Time value from the internal buffer.

func (*Deserializer) ReadVariableByteSlice

func (d *Deserializer) ReadVariableByteSlice(slice *[]byte, lenType SeriLengthPrefixType, errProducer ErrProducer, maxRead ...int) *Deserializer

ReadVariableByteSlice reads a variable byte slice which is denoted by the given SeriLengthPrefixType.

func (*Deserializer) Skip

func (d *Deserializer) Skip(skip int, errProducer ErrProducer) *Deserializer

Skip skips the number of bytes during deserialization.

type ElementValidationFunc

type ElementValidationFunc func(index int, next []byte) error

ElementValidationFunc is a function which runs during array validation (e.g. lexical ordering).

type ErrProducer

type ErrProducer func(err error) error

ErrProducer produces an error.

type ErrProducerWithLeftOver

type ErrProducerWithLeftOver func(left int, err error) error

ErrProducerWithLeftOver produces an error and is called with the bytes left to read.

type LexicalOrdered32ByteArrays

type LexicalOrdered32ByteArrays [][32]byte

LexicalOrdered32ByteArrays are 32 byte arrays ordered in lexical order.

func (LexicalOrdered32ByteArrays) Len

func (LexicalOrdered32ByteArrays) Less

func (l LexicalOrdered32ByteArrays) Less(i, j int) bool

func (LexicalOrdered32ByteArrays) Swap

func (l LexicalOrdered32ByteArrays) Swap(i, j int)

type LexicalOrderedByteSlices

type LexicalOrderedByteSlices [][]byte

LexicalOrderedByteSlices are byte slices ordered in lexical order.

func (LexicalOrderedByteSlices) Len

func (l LexicalOrderedByteSlices) Len() int

func (LexicalOrderedByteSlices) Less

func (l LexicalOrderedByteSlices) Less(i, j int) bool

func (LexicalOrderedByteSlices) Swap

func (l LexicalOrderedByteSlices) Swap(i, j int)

type ReadObjectConsumerFunc

type ReadObjectConsumerFunc func(seri Serializable)

ReadObjectConsumerFunc gets called after an object has been deserialized from a Deserializer.

type ReadObjectsConsumerFunc

type ReadObjectsConsumerFunc func(seri Serializables)

ReadObjectsConsumerFunc gets called after objects have been deserialized from a Deserializer.

type SeriLengthPrefixType

type SeriLengthPrefixType byte

SeriLengthPrefixType defines the type of the value denoting the length of a collection.

const (
	// SeriLengthPrefixTypeAsByte defines a collection length to be denoted by a byte.
	SeriLengthPrefixTypeAsByte SeriLengthPrefixType = iota
	// SeriLengthPrefixTypeAsUint16 defines a collection length to be denoted by a uint16.
	SeriLengthPrefixTypeAsUint16
	// SeriLengthPrefixTypeAsUint32 defines a collection length to be denoted by a uint32.
	SeriLengthPrefixTypeAsUint32
)

type Serializable

type Serializable interface {
	json.Marshaler
	json.Unmarshaler
	// Deserialize deserializes the given data (by copying) into the object and returns the amount of bytes consumed from data.
	// If the passed data is not big enough for deserialization, an error must be returned.
	// During deserialization additional validation may be performed if the given modes are set.
	Deserialize(data []byte, deSeriMode DeSerializationMode) (int, error)
	// Serialize returns a serialized byte representation.
	// This function does not check the serialized data for validity.
	// During serialization additional validation may be performed if the given modes are set.
	Serialize(deSeriMode DeSerializationMode) ([]byte, error)
}

Serializable is something which knows how to serialize/deserialize itself from/into bytes. This is almost analogous to BinaryMarshaler/BinaryUnmarshaler.

type SerializableSelectorFunc

type SerializableSelectorFunc func(ty uint32) (Serializable, error)

SerializableSelectorFunc is a function that given a type byte, returns an empty instance of the given underlying type. If the type doesn't resolve, an error is returned.

type Serializables

type Serializables []Serializable

Serializables is a slice of Serializable.

type Serializer

type Serializer struct {
	// contains filtered or unexported fields
}

Serializer is a utility to serialize bytes.

func NewSerializer

func NewSerializer() *Serializer

NewSerializer creates a new Serializer.

func (*Serializer) AbortIf

func (s *Serializer) AbortIf(errProducer ErrProducer) *Serializer

AbortIf calls the given ErrProducer if the Serializer did not encounter an error yet. Return nil from the ErrProducer to indicate continuation of the serialization.

func (*Serializer) Do

func (s *Serializer) Do(f func()) *Serializer

Do calls f in the Serializer chain.

func (*Serializer) Serialize

func (s *Serializer) Serialize() ([]byte, error)

Serialize finishes the serialization by returning the serialized bytes or an error if any intermediate step created one.

func (*Serializer) Write32BytesArraySlice

func (s *Serializer) Write32BytesArraySlice(data SliceOfArraysOf32Bytes, deSeriMode DeSerializationMode, lenType SeriLengthPrefixType, arrayRules *ArrayRules, errProducer ErrProducer) *Serializer

Write32BytesArraySlice writes a slice of arrays of 32 bytes to the Serializer.

func (*Serializer) Write64BytesArraySlice

func (s *Serializer) Write64BytesArraySlice(data SliceOfArraysOf64Bytes, deSeriMode DeSerializationMode, lenType SeriLengthPrefixType, arrayRules *ArrayRules, errProducer ErrProducer) *Serializer

Write64BytesArraySlice writes a slice of arrays of 64 bytes to the Serializer.

func (*Serializer) WriteBool

func (s *Serializer) WriteBool(v bool, errProducer ErrProducer) *Serializer

WriteBool writes the given bool to the Serializer.

func (*Serializer) WriteByte

func (s *Serializer) WriteByte(data byte, errProducer ErrProducer) *Serializer

WriteByte writes the given byte to the Serializer.

func (*Serializer) WriteBytes

func (s *Serializer) WriteBytes(data []byte, errProducer ErrProducer) *Serializer

WriteBytes writes the given byte slice to the Serializer. Use this function only to write fixed size slices/arrays, otherwise use WriteVariableByteSlice instead.

func (*Serializer) WriteNum

func (s *Serializer) WriteNum(v interface{}, errProducer ErrProducer) *Serializer

WriteNum writes the given num v to the Serializer.

func (*Serializer) WriteObject

func (s *Serializer) WriteObject(seri Serializable, deSeriMode DeSerializationMode, errProducer ErrProducer) *Serializer

WriteObject writes the given Serializable to the Serializer.

func (*Serializer) WritePayload

func (s *Serializer) WritePayload(payload Serializable, deSeriMode DeSerializationMode, errProducer ErrProducer) *Serializer

WritePayload writes the given payload Serializable into the Serializer. This is different to WriteObject as it also writes the length denotation of the payload.

func (*Serializer) WriteSliceOfObjects

func (s *Serializer) WriteSliceOfObjects(seris Serializables, deSeriMode DeSerializationMode, lenType SeriLengthPrefixType, woc WrittenObjectConsumer, errProducer ErrProducer) *Serializer

WriteSliceOfObjects writes Serializables into the Serializer. For every written Serializable, the given WrittenObjectConsumer is called if it isn't nil.

func (*Serializer) WriteString

func (s *Serializer) WriteString(str string, lenType SeriLengthPrefixType, errProducer ErrProducer) *Serializer

WriteString writes the given string to the Serializer.

func (*Serializer) WriteTime

func (s *Serializer) WriteTime(timeToWrite time.Time, errProducer ErrProducer) *Serializer

WriteTime writes a marshaled Time value to the internal buffer.

func (*Serializer) WriteVariableByteSlice

func (s *Serializer) WriteVariableByteSlice(data []byte, lenType SeriLengthPrefixType, errProducer ErrProducer) *Serializer

WriteVariableByteSlice writes the given slice with its length to the Serializer.

func (*Serializer) Written

func (s *Serializer) Written() int

Written returns the amount of bytes written into the Serializer.

type SliceOfArraysOf32Bytes

type SliceOfArraysOf32Bytes = []ArrayOf32Bytes

SliceOfArraysOf32Bytes is a slice of arrays of which each is 32 bytes.

func RemoveDupsAndSortByLexicalOrderArrayOf32Bytes

func RemoveDupsAndSortByLexicalOrderArrayOf32Bytes(slice SliceOfArraysOf32Bytes) SliceOfArraysOf32Bytes

RemoveDupsAndSortByLexicalOrderArrayOf32Bytes returns a new SliceOfArraysOf32Bytes sorted by lexical order and without duplicates.

type SliceOfArraysOf64Bytes

type SliceOfArraysOf64Bytes = []ArrayOf64Bytes

SliceOfArraysOf64Bytes is a slice of arrays of which each is 64 bytes.

type SortedSerializables

type SortedSerializables Serializables

SortedSerializables are Serializables sorted by their serialized form.

func (SortedSerializables) Len

func (ss SortedSerializables) Len() int

func (SortedSerializables) Less

func (ss SortedSerializables) Less(i, j int) bool

func (SortedSerializables) Swap

func (ss SortedSerializables) Swap(i, j int)

type TypeDenotationType

type TypeDenotationType byte

TypeDenotationType defines a type denotation.

const (
	// TypeDenotationUint32 defines a denotation which defines a type ID by a uint32.
	TypeDenotationUint32 TypeDenotationType = iota
	// TypeDenotationByte defines a denotation which defines a type ID by a byte.
	TypeDenotationByte
	// TypeDenotationNone defines that there is no type denotation.
	TypeDenotationNone
)

type WrittenObjectConsumer

type WrittenObjectConsumer func(index int, written []byte) error

WrittenObjectConsumer gets called after an object has been serialized into a Serializer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL