Documentation ¶
Index ¶
- func IsIO(err error) bool
- func Marshal(w io.Writer, v interface{}) (int, error)
- func Unmarshal(r io.Reader, v interface{}) (int, error)
- func UnmarshalLimited(r io.Reader, v interface{}, maxSize uint) (int, error)
- type Decoder
- func (d *Decoder) Decode(v interface{}) (int, error)
- func (d *Decoder) DecodeBool() (bool, int, error)
- func (d *Decoder) DecodeDouble() (float64, int, error)
- func (d *Decoder) DecodeEnum(validEnums map[int32]bool) (int32, int, error)
- func (d *Decoder) DecodeFixedOpaque(size int32) ([]byte, int, error)
- func (d *Decoder) DecodeFloat() (float32, int, error)
- func (d *Decoder) DecodeHyper() (int64, int, error)
- func (d *Decoder) DecodeInt() (int32, int, error)
- func (d *Decoder) DecodeOpaque() ([]byte, int, error)
- func (d *Decoder) DecodeString() (string, int, error)
- func (d *Decoder) DecodeUhyper() (uint64, int, error)
- func (d *Decoder) DecodeUint() (uint32, int, error)
- type Encoder
- func (enc *Encoder) Encode(v interface{}) (int, error)
- func (enc *Encoder) EncodeBool(v bool) (int, error)
- func (enc *Encoder) EncodeDouble(v float64) (int, error)
- func (enc *Encoder) EncodeEnum(v int32, validEnums map[int32]bool) (int, error)
- func (enc *Encoder) EncodeFixedOpaque(v []byte) (int, error)
- func (enc *Encoder) EncodeFloat(v float32) (int, error)
- func (enc *Encoder) EncodeHyper(v int64) (int, error)
- func (enc *Encoder) EncodeInt(v int32) (int, error)
- func (enc *Encoder) EncodeOpaque(v []byte) (int, error)
- func (enc *Encoder) EncodeString(v string) (int, error)
- func (enc *Encoder) EncodeUhyper(v uint64) (int, error)
- func (enc *Encoder) EncodeUint(v uint32) (int, error)
- type ErrorCode
- type MarshalError
- type UnmarshalError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsIO ¶
IsIO returns a boolean indicating whether the error is known to report that the underlying reader or writer encountered an ErrIO.
func Marshal ¶
Marshal writes the XDR encoding of v to writer w and returns the number of bytes written. It traverses v recursively and automatically indirects pointers through arbitrary depth to encode the actual value pointed to.
Marshal uses reflection to determine the type of the concrete value contained by v and performs a mapping of Go types to the underlying XDR types as follows:
Go Type -> XDR Type -------------------- int8, int16, int32, int -> XDR Integer uint8, uint16, uint32, uint -> XDR Unsigned Integer int64 -> XDR Hyper Integer uint64 -> XDR Unsigned Hyper Integer bool -> XDR Boolean float32 -> XDR Floating-Point float64 -> XDR Double-Precision Floating-Point string -> XDR String byte -> XDR Integer []byte -> XDR Variable-Length Opaque Data [#]byte -> XDR Fixed-Length Opaque Data []<type> -> XDR Variable-Length Array [#]<type> -> XDR Fixed-Length Array struct -> XDR Structure map -> XDR Variable-Length Array of two-element XDR Structures time.Time -> XDR String encoded with RFC3339 nanosecond precision
Notes and Limitations:
- Automatic marshalling of variable and fixed-length arrays of uint8s requires a special struct tag `xdropaque:"false"` since byte slices and byte arrays are assumed to be opaque data and byte is a Go alias for uint8 thus indistinguishable under reflection
- Channel, complex, and function types cannot be encoded
- Interfaces without a concrete value cannot be encoded
- Cyclic data structures are not supported and will result in infinite loops
- Strings are marshalled with UTF-8 character encoding which differs from the XDR specification of ASCII, however UTF-8 is backwards compatible with ASCII so this should rarely cause issues
If any issues are encountered during the marshalling process, a MarshalError is returned with a human readable description as well as an ErrorCode value for further inspection from sophisticated callers. Some potential issues are unsupported Go types, attempting to encode more opaque data than can be represented by a single opaque XDR entry, and exceeding max slice limitations.
func Unmarshal ¶
Unmarshal parses XDR-encoded data into the value pointed to by v reading from reader r and returning the total number of bytes read. An addressable pointer must be provided since Unmarshal needs to both store the result of the decode as well as obtain target type information. Unmarhsal traverses v recursively and automatically indirects pointers through arbitrary depth, allocating them as necessary, to decode the data into the underlying value pointed to.
Unmarshal uses reflection to determine the type of the concrete value contained by v and performs a mapping of underlying XDR types to Go types as follows:
Go Type <- XDR Type -------------------- int8, int16, int32, int <- XDR Integer uint8, uint16, uint32, uint <- XDR Unsigned Integer int64 <- XDR Hyper Integer uint64 <- XDR Unsigned Hyper Integer bool <- XDR Boolean float32 <- XDR Floating-Point float64 <- XDR Double-Precision Floating-Point string <- XDR String byte <- XDR Integer []byte <- XDR Variable-Length Opaque Data [#]byte <- XDR Fixed-Length Opaque Data []<type> <- XDR Variable-Length Array [#]<type> <- XDR Fixed-Length Array struct <- XDR Structure map <- XDR Variable-Length Array of two-element XDR Structures time.Time <- XDR String encoded with RFC3339 nanosecond precision
Notes and Limitations:
- Automatic unmarshalling of variable and fixed-length arrays of uint8s requires a special struct tag `xdropaque:"false"` since byte slices and byte arrays are assumed to be opaque data and byte is a Go alias for uint8 thus indistinguishable under reflection
- Cyclic data structures are not supported and will result in infinite loops
If any issues are encountered during the unmarshalling process, an UnmarshalError is returned with a human readable description as well as an ErrorCode value for further inspection from sophisticated callers. Some potential issues are unsupported Go types, attempting to decode a value which is too large to fit into a specified Go type, and exceeding max slice limitations.
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
A Decoder wraps an io.Reader that is expected to provide an XDR-encoded byte stream and provides several exposed methods to manually decode various XDR primitives without relying on reflection. The NewDecoder function can be used to get a new Decoder directly.
Typically, Unmarshal should be used instead of manual decoding. A Decoder is exposed so it is possible to perform manual decoding should it be necessary in complex scenarios where automatic reflection-based decoding won't work.
func NewDecoder ¶
NewDecoder returns a Decoder that can be used to manually decode XDR data from a provided reader. Typically, Unmarshal should be used instead of manually creating a Decoder.
func NewDecoderLimited ¶
NewDecoderLimited is identical to NewDecoder but it sets maxReadSize in order to cap reads.
func (*Decoder) Decode ¶
Decode operates identically to the Unmarshal function with the exception of using the reader associated with the Decoder as the source of XDR-encoded data instead of a user-supplied reader. See the Unmarhsal documentation for specifics.
func (*Decoder) DecodeBool ¶
DecodeBool treats the next 4 bytes as an XDR encoded boolean value and returns the result as a bool along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining or the parsed value is not a 0 or 1.
Reference:
RFC Section 4.4 - Boolean Represented as an XDR encoded enumeration where 0 is false and 1 is true
func (*Decoder) DecodeDouble ¶
DecodeDouble treats the next 8 bytes as an XDR encoded double-precision floating point and returns the result as a float64 along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining.
Reference:
RFC Section 4.7 - Double-Precision Floating Point 64-bit double-precision IEEE 754 floating point
func (*Decoder) DecodeEnum ¶
DecodeEnum treats the next 4 bytes as an XDR encoded enumeration value and returns the result as an int32 after verifying that the value is in the provided map of valid values. It also returns the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining or the parsed enumeration value is not one of the provided valid values.
Reference:
RFC Section 4.3 - Enumeration Represented as an XDR encoded signed integer
func (*Decoder) DecodeFixedOpaque ¶
DecodeFixedOpaque treats the next 'size' bytes as XDR encoded opaque data and returns the result as a byte slice along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining to satisfy the passed size, including the necessary padding to make it a multiple of 4.
Reference:
RFC Section 4.9 - Fixed-Length Opaque Data Fixed-length uninterpreted data zero-padded to a multiple of four
func (*Decoder) DecodeFloat ¶
DecodeFloat treats the next 4 bytes as an XDR encoded floating point and returns the result as a float32 along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining.
Reference:
RFC Section 4.6 - Floating Point 32-bit single-precision IEEE 754 floating point
func (*Decoder) DecodeHyper ¶
DecodeHyper treats the next 8 bytes as an XDR encoded hyper value and returns the result as an int64 along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining.
Reference:
RFC Section 4.5 - Hyper Integer 64-bit big-endian signed integer in range [-9223372036854775808, 9223372036854775807]
func (*Decoder) DecodeInt ¶
DecodeInt treats the next 4 bytes as an XDR encoded integer and returns the result as an int32 along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining.
Reference:
RFC Section 4.1 - Integer 32-bit big-endian signed integer in range [-2147483648, 2147483647]
func (*Decoder) DecodeOpaque ¶
DecodeOpaque treats the next bytes as variable length XDR encoded opaque data and returns the result as a byte slice along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining or the opaque data is larger than the max length of a Go slice.
Reference:
RFC Section 4.10 - Variable-Length Opaque Data Unsigned integer length followed by fixed opaque data of that length
func (*Decoder) DecodeString ¶
DecodeString treats the next bytes as a variable length XDR encoded string and returns the result as a string along with the number of bytes actually read. Character encoding is assumed to be UTF-8 and therefore ASCII compatible. If the underlying character encoding is not compatibile with this assumption, the data can instead be read as variable-length opaque data (DecodeOpaque) and manually converted as needed.
An UnmarshalError is returned if there are insufficient bytes remaining or the string data is larger than the max length of a Go slice.
Reference:
RFC Section 4.11 - String Unsigned integer length followed by bytes zero-padded to a multiple of four
func (*Decoder) DecodeUhyper ¶
DecodeUhyper treats the next 8 bytes as an XDR encoded unsigned hyper value and returns the result as a uint64 along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining.
Reference:
RFC Section 4.5 - Unsigned Hyper Integer 64-bit big-endian unsigned integer in range [0, 18446744073709551615]
func (*Decoder) DecodeUint ¶
DecodeUint treats the next 4 bytes as an XDR encoded unsigned integer and returns the result as a uint32 along with the number of bytes actually read.
An UnmarshalError is returned if there are insufficient bytes remaining.
Reference:
RFC Section 4.2 - Unsigned Integer 32-bit big-endian unsigned integer in range [0, 4294967295]
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
An Encoder wraps an io.Writer that will receive the XDR encoded byte stream. See NewEncoder.
func NewEncoder ¶
NewEncoder returns an object that can be used to manually choose fields to XDR encode to the passed writer w. Typically, Marshal should be used instead of manually creating an Encoder. An Encoder, along with several of its methods to encode XDR primitives, is exposed so it is possible to perform manual encoding of data without relying on reflection should it be necessary in complex scenarios where automatic reflection-based encoding won't work.
func (*Encoder) Encode ¶
Encode operates identically to the Marshal function with the exception of using the writer associated with the Encoder for the destination of the XDR-encoded data instead of a user-supplied writer. See the Marshal documentation for specifics.
func (*Encoder) EncodeBool ¶
EncodeBool writes the XDR encoded representation of the passed boolean to the encapsulated writer and returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.4 - Boolean Represented as an XDR encoded enumeration where 0 is false and 1 is true
func (*Encoder) EncodeDouble ¶
EncodeDouble writes the XDR encoded representation of the passed 64-bit (double-precision) floating point to the encapsulated writer and returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.7 - Double-Precision Floating Point 64-bit double-precision IEEE 754 floating point
func (*Encoder) EncodeEnum ¶
EncodeEnum treats the passed 32-bit signed integer as an enumeration value and, if it is in the list of passed valid enumeration values, writes the XDR encoded representation of it to the encapsulated writer. It returns the number of bytes written.
A MarshalError is returned if the enumeration value is not one of the provided valid values or if writing the data fails.
Reference:
RFC Section 4.3 - Enumeration Represented as an XDR encoded signed integer
func (*Encoder) EncodeFixedOpaque ¶
EncodeFixedOpaque treats the passed byte slice as opaque data of a fixed size and writes the XDR encoded representation of it to the encapsulated writer. It returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.9 - Fixed-Length Opaque Data Fixed-length uninterpreted data zero-padded to a multiple of four
func (*Encoder) EncodeFloat ¶
EncodeFloat writes the XDR encoded representation of the passed 32-bit (single-precision) floating point to the encapsulated writer and returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.6 - Floating Point 32-bit single-precision IEEE 754 floating point
func (*Encoder) EncodeHyper ¶
EncodeHyper writes the XDR encoded representation of the passed 64-bit signed integer to the encapsulated writer and returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.5 - Hyper Integer 64-bit big-endian signed integer in range [-9223372036854775808, 9223372036854775807]
func (*Encoder) EncodeInt ¶
EncodeInt writes the XDR encoded representation of the passed 32-bit signed integer to the encapsulated writer and returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.1 - Integer 32-bit big-endian signed integer in range [-2147483648, 2147483647]
func (*Encoder) EncodeOpaque ¶
EncodeOpaque treats the passed byte slice as opaque data of a variable size and writes the XDR encoded representation of it to the encapsulated writer. It returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.10 - Variable-Length Opaque Data Unsigned integer length followed by fixed opaque data of that length
func (*Encoder) EncodeString ¶
EncodeString writes the XDR encoded representation of the passed string to the encapsulated writer and returns the number of bytes written. Character encoding is assumed to be UTF-8 and therefore ASCII compatible. If the underlying character encoding is not compatible with this assumption, the data can instead be written as variable-length opaque data (EncodeOpaque) and manually converted as needed.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.11 - String Unsigned integer length followed by bytes zero-padded to a multiple of four
func (*Encoder) EncodeUhyper ¶
EncodeUhyper writes the XDR encoded representation of the passed 64-bit unsigned integer to the encapsulated writer and returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.5 - Unsigned Hyper Integer 64-bit big-endian unsigned integer in range [0, 18446744073709551615]
func (*Encoder) EncodeUint ¶
EncodeUint writes the XDR encoded representation of the passed 32-bit unsigned integer to the encapsulated writer and returns the number of bytes written.
A MarshalError with an error code of ErrIO is returned if writing the data fails.
Reference:
RFC Section 4.2 - Unsigned Integer 32-bit big-endian unsigned integer in range [0, 4294967295]
type ErrorCode ¶
type ErrorCode int
ErrorCode identifies a kind of error.
const ( // ErrBadArguments indicates arguments passed to the function are not // what was expected. ErrBadArguments ErrorCode = iota // ErrUnsupportedType indicates the Go type is not a supported type for // marshalling and unmarshalling XDR data. ErrUnsupportedType // ErrBadEnumValue indicates an enumeration value is not in the list of // valid values. ErrBadEnumValue // ErrNotSettable indicates an interface value cannot be written to. // This usually means the interface value was not passed with the & // operator, but it can also happen if automatic pointer allocation // fails. ErrNotSettable // ErrOverflow indicates that the data in question is too large to fit // into the corresponding Go or XDR data type. For example, an integer // decoded from XDR that is too large to fit into a target type of int8, // or opaque data that exceeds the max length of a Go slice. ErrOverflow // ErrNilInterface indicates an interface with no concrete type // information was encountered. Type information is necessary to // perform mapping between XDR and Go types. ErrNilInterface // ErrIO indicates an error was encountered while reading or writing to // an io.Reader or io.Writer, respectively. The actual underlying error // will be available via the Err field of the MarshalError or // UnmarshalError struct. ErrIO // ErrParseTime indicates an error was encountered while parsing an // RFC3339 formatted time value. The actual underlying error will be // available via the Err field of the UnmarshalError struct. ErrParseTime // ErrBadDiscriminant indicates that a non-integer field of a struct // was marked as a union discriminant through a struct tag. ErrBadDiscriminant // ErrBadOptional indicates that a non-pointer field of a struct // was marked as an optional-data. ErrBadOptional )
type MarshalError ¶
type MarshalError struct { ErrorCode ErrorCode // Describes the kind of error Func string // Function name Value interface{} // Value actually parsed where appropriate Description string // Human readable description of the issue Err error // The underlying error for IO errors }
MarshalError describes a problem encountered while marshaling data. Some potential issues are unsupported Go types, attempting to encode more opaque data than can be represented by a single opaque XDR entry, and exceeding max slice limitations.
func (*MarshalError) Error ¶
func (e *MarshalError) Error() string
Error satisfies the error interface and prints human-readable errors.
type UnmarshalError ¶
type UnmarshalError struct { ErrorCode ErrorCode // Describes the kind of error Func string // Function name Value interface{} // Value actually parsed where appropriate Description string // Human readable description of the issue Err error // The underlying error for IO errors }
UnmarshalError describes a problem encountered while unmarshaling data. Some potential issues are unsupported Go types, attempting to decode a value which is too large to fit into a specified Go type, and exceeding max slice limitations.
func (*UnmarshalError) Error ¶
func (e *UnmarshalError) Error() string
Error satisfies the error interface and prints human-readable errors.