binary

package
v1.4.5 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2024 License: UPL-1.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeMapValue added in v1.4.4 

func DecodeMapValue(v any, mv *types.MapValue) error

DecodeMapValue decodes the data in an existing MapValue into the given native struct. v must be a pointer to a struct.

func Marshal added in v1.4.4 

func Marshal(v any) ([]byte, error)

Marshal returns the NoSQL "NSON" encoding of v. the NSON encoding is a compact binary format used by most Oracle NoSQL components to transfer record data. This format is only used internally and should not be needed or used outside of the NoSQL SDK code.

Marshal traverses the value v recursively. Marshal uses the following type-dependent default encodings:

Boolean values encode as NoSQL booleans.

Floating point, integer, and [Number] values encode as NoSQL numbers. NaN and +/-Inf values will return an UnsupportedValueError.

String values encode as NoSQL strings.

Array and slice values encode as NoSQL arrays, except that []byte encodes as NoSQL Binary, and a nil slice encodes as the null NoSQL value.

Struct values encode as NoSQL MapValues. Each exported struct field becomes a member of the object, using the field name as the object key, unless the field is omitted for one of the reasons given below.

The encoding of each struct field can be customized by the format string stored under the "nosql" key in the struct field's tag. The format string gives the name of the field, possibly followed by a comma-separated list of options. The name may be empty in order to specify options without overriding the default field name.

The "omitempty" option specifies that the field should be omitted from the encoding if the field has an empty value, defined as false, 0, a nil pointer, a nil interface value, and any empty array, slice, map, or string.

As a special case, if the field tag is "-", the field is always omitted. Note that a field with name "-" can still be generated using the tag "-,".

Examples of struct field tags and their meanings: 

// Field appears in NoSQL as key "myName".
Field int `nosql:"myName"`

// Field appears in NoSQL as key "myName" and
// the field is omitted from the object if its value is empty,
// as defined above.
Field int `nosql:"myName,omitempty"`

// Field appears in NoSQL as key "Field" (the default), but
// the field is skipped if empty.
// Note the leading comma.
Field int `nosql:",omitempty"`

// Field is ignored by this package.
Field int `nosql:"-"`

// Field appears in NoSQL as key "-".
Field int `nosql:"-,"`

The "string" option signals that a field is stored as NoSQL inside a NoSQL-encoded string. It applies only to fields of string, floating point, integer, or boolean types. This extra level of encoding is sometimes used when communicating with JavaScript programs: 

Int64String int64 `nosql:",string"`

The key name will be used if it's a non-empty string consisting of only Unicode letters, digits, and ASCII punctuation except quotation marks, backslash, and comma.

Embedded struct fields are usually marshaled as if their inner exported fields were fields in the outer struct, subject to the usual Go visibility rules amended as described in the next paragraph. An anonymous struct field with a name given in its NoSQL tag is treated as having that name, rather than being anonymous. An anonymous struct field of interface type is treated the same as having that type as its name, rather than being anonymous.

The Go visibility rules for struct fields are amended for NoSQL when deciding which field to marshal or unmarshal. If there are multiple fields at the same level, and that level is the least nested (and would therefore be the nesting level selected by the usual Go rules), the following extra rules apply:

1) Of those fields, if any are NoSQL-tagged, only tagged fields are considered, even if there are multiple untagged fields that would otherwise conflict.

2) If there is exactly one field (tagged or not according to the first rule), that is selected.

3) Otherwise there are multiple fields, and all are ignored; no error occurs.

Handling of anonymous struct fields is new in Go 1.1. Prior to Go 1.1, anonymous struct fields were ignored. To force ignoring of an anonymous struct field in both current and earlier versions, give the field a NoSQL tag of "-".

Map values encode as NoSQL objects. The map's key type must either be a string or an integer type. The map keys are sorted and used as NoSQL object keys by applying the following rules, subject to the UTF-8 coercion described for string values above:

  • keys of any string type are used directly
  • integer keys are converted to strings

Pointer values encode as the value pointed to. A nil pointer encodes as the null NoSQL value.

Interface values encode as the value contained in the interface. A nil interface value encodes as the null NoSQL value.

Channel, complex, and function values cannot be encoded in NoSQL. Attempting to encode such a value causes Marshal to return an UnsupportedTypeError.

NoSQL cannot represent cyclic data structures and Marshal does not handle them. Passing cyclic structures to Marshal will result in an error.

func MarshalToWriter added in v1.4.4 

func MarshalToWriter(v any, w *Writer) error

MarshalToWriter does the same as above, but writes to the existing underlying byte buffer in the given Writer.

func UnmarshalFromReader added in v1.4.4 

func UnmarshalFromReader(v any, r *Reader) error

Types

type InvalidUTF8Error deprecated added in v1.4.4 

type InvalidUTF8Error struct {
	S string // the whole string value that caused the error
}

Before Go 1.2, an InvalidUTF8Error was returned by Marshal when attempting to encode a string value with invalid UTF-8 sequences. As of Go 1.2, Marshal instead coerces the string to valid UTF-8 by replacing invalid bytes with the Unicode replacement rune U+FFFD.

Deprecated: No longer used; kept for compatibility.

func (*InvalidUTF8Error) Error added in v1.4.4 

func (e *InvalidUTF8Error) Error() string

type Reader 

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

Reader reads byte sequences from the underlying io.Reader and decodes the bytes to construct in-memory representations according to the Binary Protocol which defines the data exchange format between the Oracle NoSQL Database proxy and drivers.

Reader implements the io.Reader and io.ByteReader interfaces.

func NewReader 

func NewReader(r *bytes.Buffer) *Reader

NewReader creates a reader for the binary protocol.

func (*Reader) GetBuffer added in v1.4.0 

func (r *Reader) GetBuffer() *bytes.Buffer

GetBuffer returns the underlying bytes Buffer.

func (*Reader) Read 

func (r *Reader) Read(p []byte) (n int, err error)

Read reads up to len(p) bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered.

func (*Reader) ReadArray 

func (r *Reader) ReadArray() ([]types.FieldValue, error)

ReadArray reads a structured byte sequences that represent the encoding of an array, decodes the bytes and returns as a slice of types.FieldValue.

func (*Reader) ReadBoolean 

func (r *Reader) ReadBoolean() (bool, error)

ReadBoolean reads and decodes a single byte as a bool value. A zero byte is decoded as false, and any other non-zero byte is decoded as true.

func (*Reader) ReadByte 

func (r *Reader) ReadByte() (byte, error)

ReadByte reads and returns a single byte or any error encountered.

func (*Reader) ReadByteArray 

func (r *Reader) ReadByteArray() ([]byte, error)

ReadByteArray reads byte sequences and returns as a slice of byte or any error encountered. The returned bytes could be nil.

func (*Reader) ReadByteArrayWithInt 

func (r *Reader) ReadByteArrayWithInt() ([]byte, error)

ReadByteArrayWithInt reads byte sequences and returns as a slice of byte or any error encountered. The returned bytes is non-nil.

func (*Reader) ReadDouble 

func (r *Reader) ReadDouble() (float64, error)

ReadDouble reads and decodes 8 bytes as a float64 value.

func (*Reader) ReadFieldValue 

func (r *Reader) ReadFieldValue() (types.FieldValue, error)

ReadFieldValue reads a fixed or variable length of bytes, decodes them as a value of a table field and returns the value or any error encountered.

func (*Reader) ReadInt 

func (r *Reader) ReadInt() (int, error)

ReadInt reads and decodes 4 bytes as an int32 value.

func (*Reader) ReadInt16 

func (r *Reader) ReadInt16() (int16, error)

ReadInt16 reads and decodes 2 bytes as an int16 value.

func (*Reader) ReadMap 

func (r *Reader) ReadMap() (*types.MapValue, error)

ReadMap reads a structured byte sequences that represent the encoding of a Map value, decodes the bytes and returns as an ordered *types.MapValue.

func (*Reader) ReadNonNilString added in v1.4.0 

func (r *Reader) ReadNonNilString() (string, error)

ReadNonNilString reads a string. If there is an error, it will return an empty string and the error.

func (*Reader) ReadPackedInt 

func (r *Reader) ReadPackedInt() (int, error)

ReadPackedInt reads a variable length of bytes that is an encoding of packed integer, decodes the bytes as an int32 value.

func (*Reader) ReadPackedLong 

func (r *Reader) ReadPackedLong() (int64, error)

ReadPackedLong reads a variable length of bytes that is an encoding of packed long value, decodes the bytes as an int64 value.

func (*Reader) ReadString 

func (r *Reader) ReadString() (*string, error)

ReadString reads a variable length of bytes that is an encoding of packed UTF-8 string value, decodes the bytes as a string. It returns a pointer to the string value or any error encountered.

func (*Reader) ReadStructValue added in v1.4.4 

func (r *Reader) ReadStructValue(v any) error

ReadStructValue deserializes data into a native struct. The passed in value must be a pointer to a struct.

func (*Reader) ReadVersion 

func (r *Reader) ReadVersion() (types.Version, error)

ReadVersion reads byte sequences and decodes as a types.Version.

type StructReader added in v1.4.4 

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

StructReader reads byte sequences from the underlying binary.Reader and decodes the bytes to construct native structs according to the Binary Protocol which defines the data exchange format between the Oracle NoSQL Database proxy and drivers.

func NewStructReader added in v1.4.4 

func NewStructReader(b *bytes.Buffer) *StructReader

NewStructReader creates a reader for the binary protocol.

func (*StructReader) DiscardArray added in v1.4.4 

func (sr *StructReader) DiscardArray() error

DiscardArray reads a structured byte sequences that represent the encoding of an array, decodes the bytes and discards them. It is used when skipping over unused or unknown struct fields.

func (*StructReader) DiscardMap added in v1.4.4 

func (sr *StructReader) DiscardMap() error

DisardMap reads and discards a map value. It is used when skipping over unused/unknown fields.

func (*StructReader) ReadArray added in v1.4.4 

func (sr *StructReader) ReadArray(v reflect.Value) error

ReadArray reads a structured byte sequences that represent the encoding of an array, decodes the bytes and puts the values into the given array.

func (*StructReader) ReadFieldValue added in v1.4.4 

func (sr *StructReader) ReadFieldValue(v reflect.Value) error

ReadFieldValue reads a fixed or variable length of bytes, decodes them and sets the result into the passed-in Value

func (*StructReader) ReadMap added in v1.4.4 

func (sr *StructReader) ReadMap(v reflect.Value) error

ReadMap reads a structured byte sequences that represent the encoding of a Map value, and decodes the bytes into the passed-in field, which must be either a struct or a map[string]<specific type>

func (*StructReader) Unmarshal added in v1.4.4 

func (sr *StructReader) Unmarshal(v any) (err error)

type UnsupportedTypeError added in v1.4.4 

type UnsupportedTypeError struct {
	Type reflect.Type
}

An UnsupportedTypeError is returned by Marshal when attempting to encode an unsupported value type.

func (*UnsupportedTypeError) Error added in v1.4.4 

func (e *UnsupportedTypeError) Error() string

type UnsupportedValueError added in v1.4.4 

type UnsupportedValueError struct {
	Value reflect.Value
	Str   string
}

An UnsupportedValueError is returned by Marshal when attempting to encode an unsupported value.

func (*UnsupportedValueError) Error added in v1.4.4 

func (e *UnsupportedValueError) Error() string

type Writer 

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

Writer encodes data into the wire format for the Binary Protocol and writes to a buffer. The Binary Protocol defines the data exchange format between the Oracle NoSQL Database proxy and drivers.

Writer implements the io.Write and io.ByteWriter interfaces.

func NewWriter 

func NewWriter() *Writer

NewWriter creates a writer for the binary protocol.

func (*Writer) Bytes 

func (w *Writer) Bytes() []byte

Bytes returns a slice of bytes in the buffer.

func (*Writer) Reset 

func (w *Writer) Reset()

Reset resets the buffer.

func (*Writer) Size 

func (w *Writer) Size() int

Size returns the number of bytes in the buffer.

func (*Writer) Write 

func (w *Writer) Write(p []byte) (n int, err error)

Write writes len(p) bytes from p to the buffer.

func (*Writer) WriteArray 

func (w *Writer) WriteArray(value []types.FieldValue) (n int, err error)

WriteArray encodes and writes an array of FieldValues to the buffer.

func (*Writer) WriteBoolean 

func (w *Writer) WriteBoolean(value bool) (int, error)

WriteBoolean encodes and writes the bool value to the buffer. A true value is encoded as 1 while a false value is encoded as 0.

func (*Writer) WriteByte 

func (w *Writer) WriteByte(b byte) error

WriteByte writes a single byte.

This implements io.ByteWriter.

func (*Writer) WriteByteArray 

func (w *Writer) WriteByteArray(value []byte) (n int, err error)

WriteByteArray encodes and writes a slice of bytes to the buffer. The slice of bytes could be nil.

func (*Writer) WriteByteArrayWithInt 

func (w *Writer) WriteByteArrayWithInt(value []byte) (n int, err error)

WriteByteArrayWithInt encodes and writes a slice of bytes to the buffer. The slice of bytes must be non-nil.

func (*Writer) WriteCapacityMode added in v1.3.0 

func (w *Writer) WriteCapacityMode(lm types.CapacityMode, serialVersion int16) (int, error)

WriteCapacityMode encodes and writes the limits mode value to the buffer.

func (*Writer) WriteConsistency 

func (w *Writer) WriteConsistency(c types.Consistency) (int, error)

WriteConsistency encodes and writes the consistency value to the buffer.

func (*Writer) WriteDouble 

func (w *Writer) WriteDouble(value float64) (int, error)

WriteDouble encodes and writes the float64 value to the buffer.

func (*Writer) WriteDurability added in v1.3.0 

func (w *Writer) WriteDurability(c types.Durability, serialVersion int16) (int, error)

WriteDurability encodes and writes the Durability value to the buffer.

func (*Writer) WriteFieldRange 

func (w *Writer) WriteFieldRange(fieldRange *types.FieldRange) (n int, err error)

WriteFieldRange encodes and writes the FieldRange to the buffer.

func (*Writer) WriteFieldValue 

func (w *Writer) WriteFieldValue(value types.FieldValue) (int, error)

WriteFieldValue encodes and writes the specified field value to the buffer.

func (*Writer) WriteInt 

func (w *Writer) WriteInt(value int) (int, error)

WriteInt encodes and writes the int value to the buffer. It assumes the provided value fits into a signed 32-bit integer.

func (*Writer) WriteInt16 

func (w *Writer) WriteInt16(value int16) (int, error)

WriteInt16 encodes and writes the int16 value to the buffer.

func (*Writer) WriteIntAtOffset added in v1.4.0 

func (w *Writer) WriteIntAtOffset(value int, offset int) (int, error)

WriteIntAtOffset encodes and writes the int value to the buffer at a specific offset. It assumes the provided value fits into a signed 32-bit integer.

func (*Writer) WriteMap 

func (w *Writer) WriteMap(value *types.MapValue) (n int, err error)

WriteMap encodes and writes the map value to the buffer.

func (*Writer) WriteOpCode 

func (w *Writer) WriteOpCode(op proto.OpCode) (int, error)

WriteOpCode encodes and writes the OpCode op to the buffer.

func (*Writer) WritePackedInt 

func (w *Writer) WritePackedInt(value int) (int, error)

WritePackedInt encodes the int value using packed integer encoding and writes to the buffer. It assumes the provided value fits into a signed 32-bit integer.

func (*Writer) WritePackedLong 

func (w *Writer) WritePackedLong(value int64) (int, error)

WritePackedLong encodes the int64 value using packed long encoding and writes to the buffer.

func (*Writer) WriteSerialVersion 

func (w *Writer) WriteSerialVersion(v int16) (int, error)

WriteSerialVersion encodes and writes the SerialVersion v to the buffer.

func (*Writer) WriteString 

func (w *Writer) WriteString(value *string) (n int, err error)

WriteString encodes and writes the string value to the buffer.

func (*Writer) WriteStructValue added in v1.4.4 

func (w *Writer) WriteStructValue(value any) (n int, err error)

func (*Writer) WriteTTL 

func (w *Writer) WriteTTL(ttl *types.TimeToLive) (n int, err error)

WriteTTL encodes and writes the TTL value to the buffer.

func (*Writer) WriteTimeout 

func (w *Writer) WriteTimeout(timeout time.Duration) (int, error)

WriteTimeout encodes and writes the timeout value to the buffer.

func (*Writer) WriteVersion 

func (w *Writer) WriteVersion(version types.Version) (int, error)

WriteVersion encodes and writes the specified version to the buffer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.