pack

package module
v0.2.12 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2021 License: MIT Imports: 11 Imported by: 58

README

📦 pack

GitHub Coverage Report

Documentation

In distributed systems, message passing often requires marshaling/unmarshaling messages in order to send them over the network. This is also useful for writing messages to logs, for persistence and debugging. The 📦 pack library defines a generic application binary interface for serialising values without losing their type information. It supports:

  • Bool,
  • U8, U16, U32, U16, U32, U64, U128, U256,
  • String, Bytes, Bytes32, Bytes65,
  • Struct,
  • List, and
  • custom types.

Values

The primary interface for working with 📦 pack is the Value interface. All values implement this interface, allowing them to be marshaling to binary and JSON, and to expose their type information.

import (
    "fmt"

    "github.com/renproject/pack"
)

func main() {
    point := pack.NewStruct(
        "x", pack.NewU64(42),
        "y", pack.NewU64(100),
    )
    fmt.Printf("type: %v", point.Type())
}

Types

By default, values do not marshal their types. This means that values cannot be unmarshalled, because there it is not always possible to know what type you are looking at without additional context. Consider the following examples:

import (
    "fmt"

    "github.com/renproject/pack"
    "github.com/renproject/surge"
)

func main() {
    x := pack.NewU64(1)
    xData, _ := surge.ToBinary(x)

    y := pack.NewString("1")
    yData, _ := surge.ToBinary(x)

    fmt.Printf("x: %v", pack.Bytes(xData))
    fmt.Printf("y: %v", pack.Bytes(yData))
}

Looking only at the binary representation of the values, it is impossible to distingish between the types of these values when unmarshalling. This presents a common problem in distributed systems: how do my services tell each other about the type context? Well, with 📦 pack we use the Typed value:

import (
    "encoding/json"
    "fmt"

    "github.com/renproject/pack"
)

func main() {
    typed := pack.NewTyped(
        "x", pack.NewU64(1),
        "y", pack.NewString("1"),
    )
    fmt.Printf("type: %v", typed.Type())

    typedData, _ := json.MarshalIndent(typed, "", "  ")
    fmt.Printf("json: %v", string(typedData))
}

Now, we can see that the type information of our value has also been marshalled. In the case of JSON, the type information favours being verbose, so that it is easily debuggable by humans. However, the binary representation is much more compact. In practice, most services in distributed systems should use binary marshalling, unless they are in debug mode (binary marshalling is not only more compact, but it is also faster to marshal).

Kinds

Types are not always simple. In the case of integers, there is minimal information that we need to know: what kind of integer is it? The only answers are U8, U16, U32, U64, U128, and U256. However, structs and lists are more complex data types and the same question has an infinite possible answers. This is where kinds are useful. The kind of a value can be thought of as the "type of the type". We can understand this better with a few examples:

import (
    "fmt"

    "github.com/renproject/pack"
)

func main() {
    x := pack.NewStruct("foo", pack.NewString("bar"))
    y := pack.NewStruct("bar", pack.NewBool(true))

    fmt.Printf("x type: %v", x.Type())
    fmt.Printf("y type: %v", y.Type())

    fmt.Printf("x kind: %v", x.Type().Kind())
    fmt.Printf("y kind: %v", y.Type().Kind())
}

We can see from this example that, although x and y have different types, they both have the same kind; they are both structs. It turns out that the existence of kinds is necessary when marshaling/unmarshaling type information, but you should very rarely need to explicitly use kinds.

Custom Types

It is often convenient to use strongly-typed values at the language level (e.g. define/use custom Go structs). Using 📦 pack, we can Encode and Decode to/from custom structs:

import (
    "fmt"

    "github.com/renproject/pack"
)

type Foo struct {
    X pack.U64 `json:"x"`
    Y pack.U64 `json:"y"`
}

func main() {
    foo := Foo {
        X: pack.NewU64(1),
        Y: pack.NewU64(2),
    }
    bar := pack.NewStruct(
        "x", pack.NewU64(3),
        "y", pack.NewU64(4),
    )
    
    packed, err := pack.Encode(foo)
    if err != nil {
        panic(err)
    }

    fmt.Printf("foo type: %v", packed.Type())
    fmt.Printf("bar type: %v", bar.Type())
    
    if err := pack.Decode(&foo, bar); err != nil {
        panic(err)
    }
    
    fmt.Printf("foo.X: %v", foo.X)
    fmt.Printf("foo.Y: %v", foo.Y)
}

Contribution

Built with ❤ by Ren.

Documentation

Index

Constants

View Source 
const (
	// KindNil should never be used.
	KindNil = Kind(0)

	// KindBool is the kind of all Bool values.
	KindBool = Kind(1)
	// KindU8 is the kind of all U8 values.
	KindU8 = Kind(2)
	// KindU16 is the kind of all U16 values.
	KindU16 = Kind(3)
	// KindU32 is the kind of all U32 values.
	KindU32 = Kind(4)
	// KindU64 is the kind of all U64 values.
	KindU64 = Kind(5)
	// KindU128 is the kind of all U128 values.
	KindU128 = Kind(6)
	// KindU256 is the kind of all U256 values.
	KindU256 = Kind(7)

	// KindString is the kind of all utf8 strings.
	KindString = Kind(10)
	// KindBytes is the kind of all dynamic byte arrays.
	KindBytes = Kind(11)
	// KindBytes32 is the kind of all 32-byte arrays.
	KindBytes32 = Kind(12)
	// KindBytes65 is the kind of all 65-byte arrays.
	KindBytes65 = Kind(13)

	// KindStruct is the kind of all struct values. It is abstract, because it does
	// not specify the fields in the struct.
	KindStruct = Kind(20)
	// KindList is the kind of all list values. It is abstract, because it does
	// not specify the type of the elements in the list.
	KindList = Kind(21)
)

Variables

View Source 
var (
	MaxU8 = func() U8 {
		return U8(255)
	}()
	MaxU16 = func() U16 {
		return U16(65535)
	}()
	MaxU32 = func() U32 {
		return U32(4294967295)
	}()
	MaxU64 = func() U64 {
		return U64(18446744073709551615)
	}()
	MaxU128 = func() U128 {
		x, _ := new(big.Int).SetString("340282366920938463463374607431768211455", 10)
		return U128{inner: x}
	}()
	MaxU256 = func() U256 {
		x, _ := new(big.Int).SetString("115792089237316195423570985008687907853269984665640564039457584007913129639935", 10)
		return U256{inner: x}
	}()
)

Maximum values for unsigned integers.

View Source 
var MaxBytes = 32 * 1024 * 1024

MaxBytes of an object. Defaults to 32 MB.

Functions

func Decode added in v0.2.0 

func Decode(interf interface{}, v Value) (err error)

Decode a Value interface into a Go interface. The Go interface must be a pointer.

func Generate 

func Generate(r *rand.Rand, size int, allowStruct, allowList bool) reflect.Value

Generate a random value. This is helpful when implementing generators for other types. See https://golang.org/pkg/testing/quick/#Generator for more information.

func GenerateFromKind added in v0.2.6 

func GenerateFromKind(r *rand.Rand, size int, kind Kind, allowStruct, allowList bool) reflect.Value

GenerateFromKind generates a random value given a Kind.

func MarshalType 

func MarshalType(t Type, buf []byte, rem int) ([]byte, int, error)

MarshalType to binary.

func SizeHintType 

func SizeHintType(t Type) int

SizeHintType returns the number of bytes requires to represent this type in binary.

func UnmarshalType 

func UnmarshalType(t *Type, buf []byte, rem int) ([]byte, int, error)

UnmarshalType from binary.

Types

type Bool 

type Bool bool

Bool represents a value that can be true or false.

func NewBool 

func NewBool(x bool) Bool

NewBool wraps an existing raw boolean.

func (Bool) Equal 

func (x Bool) Equal(y Bool) bool

Equal returns true when x is equal to y. Otherwise, it returns false.

func (Bool) Generate 

func (Bool) Generate(r *rand.Rand, size int) reflect.Value

Generate a random boolean. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (Bool) Marshal 

func (x Bool) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the boolean to binary.

func (Bool) MarshalJSON 

func (x Bool) MarshalJSON() ([]byte, error)

MarshalJSON marshals the boolean to JSON. This is done using the default JSON marshaler for raw booleans.

func (Bool) SizeHint 

func (x Bool) SizeHint() int

SizeHint returns the number of bytes required to represent the boolean in binary.

func (Bool) String 

func (x Bool) String() string

String returns "true" when the boolean is true. Otherwise, it returns "false".

func (Bool) Type 

func (x Bool) Type() Type

Type returns boolean type.

func (*Bool) Unmarshal 

func (x *Bool) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the boolean from binary.

func (*Bool) UnmarshalJSON 

func (x *Bool) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the boolean from JSON. This is done using the default JSON unmarshaler for raw booleans.

type Bytes 

type Bytes []byte

Bytes represents a slice of bytes with a dynamic length.

func NewBytes 

func NewBytes(x []byte) Bytes

NewBytes wraps an exsiting raw slice of bytes.

func (Bytes) Equal 

func (x Bytes) Equal(y Bytes) bool

Equal returns true when x is equal to y. Otherwise, it returns false.

func (Bytes) Generate 

func (Bytes) Generate(r *rand.Rand, size int) reflect.Value

Generate a random byte slice. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (Bytes) Marshal 

func (x Bytes) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the bytes to binary.

func (Bytes) MarshalJSON 

func (x Bytes) MarshalJSON() ([]byte, error)

MarshalJSON marshals the bytes to JSON. This is done by encoding the bytes into a base64 raw URL encoded string.

func (Bytes) MarshalText added in v0.2.3 

func (x Bytes) MarshalText() ([]byte, error)

MarshalText marshals the bytes to text. This is done by encoding the bytes into a base64 raw URL encoded string.

func (Bytes) SizeHint 

func (x Bytes) SizeHint() int

SizeHint returns the number of bytes required to represent the bytes in binary. This includes the length prefix that encodes the dynamic length of the bytes.

func (Bytes) String 

func (x Bytes) String() string

String returns a base64 raw URL encoding of the bytes.

func (Bytes) Type 

func (Bytes) Type() Type

Type returns the bytes type.

func (*Bytes) Unmarshal 

func (x *Bytes) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the bytes from binary.

func (*Bytes) UnmarshalJSON 

func (x *Bytes) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the bytes from JSON. This is done by decoding the bytes from a base64 raw URL encoded string.

func (*Bytes) UnmarshalText added in v0.2.3 

func (x *Bytes) UnmarshalText(text []byte) error

UnmarshalText unmarshals the bytes from text. This is done by decoding the bytes from a base64 raw URL encoded string.

type Bytes32 

type Bytes32 [32]byte

Bytes32 represents a static-sized 32-byte array.

func NewBytes32 

func NewBytes32(x [32]byte) Bytes32

NewBytes32 wraps an existing raw 32-byte array.

func (Bytes32) Bytes 

func (x Bytes32) Bytes() []byte

Bytes returns a copy of the byte array as a dynamic byte slice.

func (Bytes32) Equal 

func (x Bytes32) Equal(y *Bytes32) bool

Equal returns true when x is equal to y. Otherwise, it returns false.

func (Bytes32) Generate 

func (Bytes32) Generate(r *rand.Rand, size int) reflect.Value

Generate a random 32-byte array. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (Bytes32) Marshal 

func (x Bytes32) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the 32-byte array to binary.

func (Bytes32) MarshalJSON 

func (x Bytes32) MarshalJSON() ([]byte, error)

MarshalJSON marshals the 32-byte array to JSON. This is done by encoding the bytes into a base64 raw URL encoded string.

func (Bytes32) MarshalText added in v0.2.3 

func (x Bytes32) MarshalText() ([]byte, error)

MarshalText marshals the 32-byte array to text. This is done by encoding the bytes into a base64 raw URL encoded string.

func (Bytes32) SizeHint 

func (x Bytes32) SizeHint() int

SizeHint returns the number of bytes required to represent the 32-byte array in binary.

func (Bytes32) String 

func (x Bytes32) String() string

String returns a base64 raw URL encoding of the bytes.

func (Bytes32) Type 

func (Bytes32) Type() Type

Type returns the 32-byte array type.

func (*Bytes32) Unmarshal 

func (x *Bytes32) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the 32-byte array from binary.

func (*Bytes32) UnmarshalJSON 

func (x *Bytes32) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the 32-byte array from JSON. This is done by decoding the bytes from a base64 raw URL encoded string.

func (*Bytes32) UnmarshalText added in v0.2.3 

func (x *Bytes32) UnmarshalText(text []byte) error

UnmarshalText unmarshals the 32-byte array from text. This is done by decoding the bytes from a base64 raw URL encoded string.

type Bytes65 

type Bytes65 [65]byte

Bytes65 represents a static-sized 65-byte array.

func NewBytes65 

func NewBytes65(x [65]byte) Bytes65

NewBytes65 wraps an existing raw 65-byte array.

func (Bytes65) Bytes 

func (x Bytes65) Bytes() []byte

Bytes returns a copy of the byte array as a dynamic byte slice.

func (Bytes65) Equal 

func (x Bytes65) Equal(y *Bytes65) bool

Equal returns true when x is equal to y. Otherwise, it returns false.

func (Bytes65) Generate 

func (Bytes65) Generate(r *rand.Rand, size int) reflect.Value

Generate a random 65-byte array. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (Bytes65) Marshal 

func (x Bytes65) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the 65-byte array to binary.

func (Bytes65) MarshalJSON 

func (x Bytes65) MarshalJSON() ([]byte, error)

MarshalJSON marshals the 65-byte array to JSON. This is done by encoding the bytes into a base64 raw URL encoded string.

func (Bytes65) MarshalText added in v0.2.3 

func (x Bytes65) MarshalText() ([]byte, error)

MarshalText marshals the 65-byte array to text. This is done by encoding the bytes into a base64 raw URL encoded string.

func (Bytes65) SizeHint 

func (x Bytes65) SizeHint() int

SizeHint returns the number of bytes required to represent the 65-byte array in binary.

func (Bytes65) String 

func (x Bytes65) String() string

String returns a base64 raw URL encoding of the bytes.

func (Bytes65) Type 

func (Bytes65) Type() Type

Type returns the 65-byte array type.

func (*Bytes65) Unmarshal 

func (x *Bytes65) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the 65-byte array from binary.

func (*Bytes65) UnmarshalJSON 

func (x *Bytes65) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the 65-byte array from JSON. This is done by decoding the bytes from a base64 raw URL encoded string.

func (*Bytes65) UnmarshalText added in v0.2.3 

func (x *Bytes65) UnmarshalText(text []byte) error

UnmarshalText unmarshals the 65-byte array from text. This is done by decoding the bytes from a base64 raw URL encoded string.

type Kind 

type Kind uint8

A Kind is an optionally abstract type identifier. It can be thought of as the "type of a type", or the "constructor for a type". For example, a struct is an abstract type identifier, because it does not bind the respective value to have any specific fields (or types for those fields). Similarly, a list is an abstract type identifier, because it does not bind the respective value to a specific type of element.

func (Kind) Generate 

func (kind Kind) Generate(r *rand.Rand, size int) reflect.Value

Generate a random kind. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (Kind) Marshal 

func (kind Kind) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the kind into binary.

func (Kind) MarshalText 

func (kind Kind) MarshalText() ([]byte, error)

MarshalText from the kind. Unrecognised kinds will be marshaled into the "nil" string.

func (Kind) SizeHint 

func (kind Kind) SizeHint() int

SizeHint returns the number of bytes required to represent the kind in binary.

func (Kind) String 

func (kind Kind) String() string

func (*Kind) Unmarshal 

func (kind *Kind) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the kind from binary.

func (*Kind) UnmarshalText 

func (kind *Kind) UnmarshalText(text []byte) error

UnmarshalText into the kind. Unrecognised text will be unmarshaled into the KindNil, and will be considered invalid.

type List added in v0.2.6 

type List struct {
	T     Type
	Elems []Value
}

func EmptyList added in v0.2.8 

func EmptyList(t Type) List

func NewList added in v0.2.6 

func NewList(vs ...Value) (List, error)

func (List) Generate added in v0.2.6 

func (List) Generate(r *rand.Rand, size int) reflect.Value

Generate a random list. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information. Generated lists will never contain embedded lists.

func (List) Marshal added in v0.2.6 

func (v List) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the list into binary.

func (List) MarshalJSON added in v0.2.6 

func (v List) MarshalJSON() ([]byte, error)

MarshalJSON marshals the list to JSON.

func (List) SizeHint added in v0.2.6 

func (v List) SizeHint() int

SizeHint returns the number of bytes required to represent the list in binary.

func (List) String added in v0.2.6 

func (v List) String() string

String returns the list in its JSON representation.

func (List) Type added in v0.2.6 

func (v List) Type() Type

Type returns the list type.

func (*List) Unmarshal added in v0.2.6 

func (v *List) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the list from binary.

type String 

type String string

String represents a slice of bytes that should be interpreted as a UTF-8 encoded string.

func NewString 

func NewString(x string) String

NewString wraps an existing raw string.

func (String) Equal 

func (x String) Equal(y String) bool

Equal returns true when x is equal to y. Otherwise, it returns false.

func (String) Generate 

func (String) Generate(r *rand.Rand, size int) reflect.Value

Generate a random string. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (String) Marshal 

func (x String) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the string to binary.

func (String) MarshalJSON 

func (x String) MarshalJSON() ([]byte, error)

MarshalJSON marshals the string to JSON. This is done using the default JSON marshaler for raw strings.

func (String) SizeHint 

func (x String) SizeHint() int

SizeHint returns the number of bytes required to represent the string in binary.

func (String) String 

func (x String) String() string

String returns the raw string. This method exists to implement the Stringer interface.

func (String) Type 

func (String) Type() Type

Type returns the string stype.

func (*String) Unmarshal 

func (x *String) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the string from binary.

func (*String) UnmarshalJSON 

func (x *String) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the string from JSON. This is done using the default JSON unmarshaler for raw strings.

type Struct 

type Struct []StructField

Struct represents a structured record.

func NewStruct 

func NewStruct(vs ...interface{}) Struct

NewStruct returns a new struct from a slice of variadic arguments. The arguments are expected to be of the form ("name", value)* otherwise the function will panic. The same field name must not be used more than once. 

x := NewStruct(
    "foo", NewU64(42),
    "bar", NewString("pack is awesome"),
    "baz", NewBool(true),
)

func (Struct) Generate 

func (Struct) Generate(r *rand.Rand, size int) reflect.Value

Generate a random struct field. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information. Generated structs will never contain embedded structs.

func (Struct) Get 

func (v Struct) Get(name string) Value

Get a field value from the struct, given the field name. This method has O(n) complexity, where N is the number of fields in the struct.

func (Struct) Marshal 

func (v Struct) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the struct into binary.

func (Struct) MarshalJSON 

func (v Struct) MarshalJSON() ([]byte, error)

MarshalJSON marshals the struct to JSON. This is done by marshaling the struct as if it was a JSON object, where each field in the struct is a field in the JSON object with the same name.

func (*Struct) Set 

func (v *Struct) Set(name string, value Value) Value

Set a field value in the struct, given the field name. This method has O(n) complexity, where N is the number of fields in the struct.

func (Struct) SizeHint 

func (v Struct) SizeHint() int

SizeHint returns the number of bytes required to represent the struct in binary.

func (Struct) String 

func (v Struct) String() string

String returns the struct in its JSON representation.

func (Struct) Type 

func (v Struct) Type() Type

Type returns the structured record type. This method has O(n) complexity, where N is the number of fields in the struct.

type StructField 

type StructField struct {
	Name  string
	Value Value
}

StructField represents a named field within a struct. It is not, by itself, a value or a type. It is only meant to be used to build structs.

func NewStructField 

func NewStructField(name string, value Value) StructField

NewStructField returns a struct field with the given name and value.

func (StructField) Generate 

func (x StructField) Generate(r *rand.Rand, size int) reflect.Value

Generate a random struct field. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information. Generated struct fields will never have structs as values.

func (StructField) Marshal 

func (x StructField) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the struct field into binary.

func (StructField) SizeHint 

func (x StructField) SizeHint() int

SizeHint returns the number of bytes required to represent the struct field in binary.

type Type 

type Type interface {
	surge.Marshaler
	json.Marshaler

	// Kind returns the abstract "type of the type" for this type.
	Kind() Kind

	// Equals returns a boolean indicating whether or not the given type is
	// identical to the current one.
	Equals(other Type) bool

	// Unmarshal a value of this type from binary.
	UnmarshalValue(buf []byte, rem int) (Value, []byte, int, error)

	// Unmarshal a value of this type from JSON.
	UnmarshalValueJSON(data []byte) (Value, error)
}

A Type is a concrete type definition for a value.

type Typed 

type Typed Struct

A Typed struct is a wrapper around a struct. It includes a type definition when marshaled to binary or JSON. This type definition allows for well-typed unmarshaling over-the-wire. This is particularly useful when sending well-typed values over a network, or when saving them to the disk.

func NewTyped 

func NewTyped(vs ...interface{}) Typed

NewTyped returns a well-typed struct from a slice of variadic arguments. The arguments are expected to be of the form ("name", value)* otherwise the function will panic. 

x := NewTyped(
    "foo", NewU64(42),
    "bar", NewString("pack is awesome"),
    "baz", NewBool(true),
)

func (Typed) Generate 

func (Typed) Generate(r *rand.Rand, size int) reflect.Value

Generate a random well-typed struct. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information. Generated typed values will never contain embedded structs.

func (Typed) Get added in v0.1.1 

func (typed Typed) Get(name string) Value

Get a field value from the struct, given the field name. This method has O(n) complexity, where N is the number of fields in the struct.

func (Typed) Marshal 

func (typed Typed) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the typed value into binary. The type definition for the typed values will be marshaled first, and then the actual value will be marshaled.

func (Typed) MarshalJSON 

func (typed Typed) MarshalJSON() ([]byte, error)

MarshalJSON marshals the typed value into JSON. It will marshal an object with fields "t" and "v". The "t" field defines the type of the "v" field. The "v" field is the JSON marshaling of the value.

func (*Typed) Set added in v0.1.1 

func (typed *Typed) Set(name string, value Value) Value

Set a field value in the struct, given the field name. This method has O(n) complexity, where N is the number of fields in the struct.

func (Typed) SizeHint 

func (typed Typed) SizeHint() int

SizeHint returns the number of bytes required to represent the typed value in binary.

func (Typed) String 

func (typed Typed) String() string

String returns the struct in its JSON representation.

func (Typed) Type 

func (typed Typed) Type() Type

Type returns the inner structured record type. This method has O(n) complexity, where N is the number of fields in the well-typed struct.

func (*Typed) Unmarshal 

func (typed *Typed) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the typed value from binary. The type definition will be unmarshaled first, and then this will be used to unmarshal the actual value into a well-typed struct.

func (*Typed) UnmarshalJSON 

func (typed *Typed) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the typed value from JSON. It will unmarshal the object and expect two fields: "t" and "v". It will use the "t" field to understand the type of "v". It will then use this understanding to unmarshal "v" into a well-typed struct.

type U128 

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

func NewU128 

func NewU128(x [16]byte) U128

func NewU128FromInt 

func NewU128FromInt(x *big.Int) U128

func NewU128FromU16 

func NewU128FromU16(x U16) U128

func NewU128FromU32 

func NewU128FromU32(x U32) U128

func NewU128FromU64 

func NewU128FromU64(x U64) U128

func NewU128FromU8 

func NewU128FromU8(x U8) U128

func NewU128FromUint16 added in v0.2.4 

func NewU128FromUint16(x uint16) U128

func NewU128FromUint32 added in v0.2.4 

func NewU128FromUint32(x uint32) U128

func NewU128FromUint64 added in v0.2.4 

func NewU128FromUint64(x uint64) U128

func NewU128FromUint8 added in v0.2.4 

func NewU128FromUint8(x uint8) U128

func (U128) Add 

func (u128 U128) Add(other U128) U128

func (*U128) AddAssign 

func (u128 *U128) AddAssign(other U128)

func (U128) Bytes 

func (u128 U128) Bytes() []byte

func (U128) Bytes16 

func (u128 U128) Bytes16() [16]byte

func (U128) Div added in v0.2.4 

func (u128 U128) Div(other U128) U128

func (U128) Equal 

func (u128 U128) Equal(other U128) bool

func (U128) Generate 

func (u128 U128) Generate(r *rand.Rand, size int) reflect.Value

Generate a random int. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (U128) GreaterThan added in v0.2.5 

func (u128 U128) GreaterThan(other U128) bool

func (U128) GreaterThanEqual added in v0.2.5 

func (u128 U128) GreaterThanEqual(other U128) bool

func (U128) Int 

func (u128 U128) Int() *big.Int

func (U128) LessThan added in v0.2.5 

func (u128 U128) LessThan(other U128) bool

func (U128) LessThanEqual added in v0.2.5 

func (u128 U128) LessThanEqual(other U128) bool

func (U128) Marshal 

func (u128 U128) Marshal(buf []byte, rem int) ([]byte, int, error)

func (U128) MarshalJSON 

func (u128 U128) MarshalJSON() ([]byte, error)

func (U128) Mul added in v0.2.4 

func (u128 U128) Mul(other U128) U128

func (U128) SizeHint 

func (u128 U128) SizeHint() int

func (U128) String 

func (u128 U128) String() string

func (U128) Sub 

func (u128 U128) Sub(other U128) U128

func (*U128) SubAssign 

func (u128 *U128) SubAssign(other U128)

func (U128) Type 

func (U128) Type() Type

Type returns the type of this value.

func (*U128) Unmarshal 

func (u128 *U128) Unmarshal(buf []byte, rem int) ([]byte, int, error)

func (*U128) UnmarshalJSON 

func (u128 *U128) UnmarshalJSON(data []byte) error

type U16 

type U16 uint16

U16 represents a 16-bit unsigned integer.

func NewU16 

func NewU16(x uint16) U16

NewU16 returns a uint16 wrapped as a U16.

func NewU16FromU8 

func NewU16FromU8(x U8) U16

NewU16FromU8 returns a uint16 wrapped as a U16.

func (U16) Add 

func (u16 U16) Add(other U16) U16

Add one U16 to another and return the result.

func (*U16) AddAssign 

func (u16 *U16) AddAssign(other U16)

AddAssign will add one U16 to another and assign the result to the left-hand side.

func (U16) Equal 

func (u16 U16) Equal(other U16) bool

Equal compares one U16 to another. If they are equal, then it returns true. Otherwise, it returns false.

func (U16) Generate 

func (u16 U16) Generate(r *rand.Rand, size int) reflect.Value

Generate a random int. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (U16) Marshal 

func (u16 U16) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the U16 to binary.

func (U16) MarshalJSON 

func (u16 U16) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSON marshaler interface. U16s are marshaled as decimal strings (for consistency with larger integer types).

func (U16) SizeHint 

func (u16 U16) SizeHint() int

SizeHint returns the number of bytes required to represent a U16 in binary.

func (U16) String 

func (u16 U16) String() string

func (U16) Sub 

func (u16 U16) Sub(other U16) U16

Sub one U16 from another and return the result.

func (*U16) SubAssign 

func (u16 *U16) SubAssign(other U16)

SubAssign will sub one U16 from another and assign the result to the left-hand side.

func (U16) Type 

func (U16) Type() Type

Type returns the type of this value.

func (U16) Uint16 

func (u16 U16) Uint16() uint16

Uint16 returns the inner uint16.

func (*U16) Unmarshal 

func (u16 *U16) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the U16 from binary.

func (*U16) UnmarshalJSON 

func (u16 *U16) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the JSON unmarshaler interface. U16s are unmarshaled as decimal strings (for consistency with larger integer types).

type U256 

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

func NewU256 

func NewU256(x [32]byte) U256

func NewU256FromInt 

func NewU256FromInt(x *big.Int) U256

func NewU256FromU128 

func NewU256FromU128(x U128) U256

func NewU256FromU16 

func NewU256FromU16(x U16) U256

func NewU256FromU32 

func NewU256FromU32(x U32) U256

func NewU256FromU64 

func NewU256FromU64(x U64) U256

func NewU256FromU8 

func NewU256FromU8(x U8) U256

func NewU256FromUint16 added in v0.2.4 

func NewU256FromUint16(x uint16) U256

func NewU256FromUint32 added in v0.2.4 

func NewU256FromUint32(x uint32) U256

func NewU256FromUint64 added in v0.2.4 

func NewU256FromUint64(x uint64) U256

func NewU256FromUint8 added in v0.2.4 

func NewU256FromUint8(x uint8) U256

func (U256) Add 

func (u256 U256) Add(other U256) U256

func (*U256) AddAssign 

func (u256 *U256) AddAssign(other U256)

func (U256) Bytes 

func (u256 U256) Bytes() []byte

func (U256) Bytes32 

func (u256 U256) Bytes32() [32]byte

func (U256) Div added in v0.2.4 

func (u256 U256) Div(other U256) U256

func (U256) Equal 

func (u256 U256) Equal(other U256) bool

func (U256) Generate 

func (u256 U256) Generate(r *rand.Rand, size int) reflect.Value

Generate a random int. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (U256) GreaterThan added in v0.2.5 

func (u256 U256) GreaterThan(other U256) bool

func (U256) GreaterThanEqual added in v0.2.5 

func (u256 U256) GreaterThanEqual(other U256) bool

func (U256) Int 

func (u256 U256) Int() *big.Int

func (U256) LessThan added in v0.2.5 

func (u256 U256) LessThan(other U256) bool

func (U256) LessThanEqual added in v0.2.5 

func (u256 U256) LessThanEqual(other U256) bool

func (U256) Marshal 

func (u256 U256) Marshal(buf []byte, rem int) ([]byte, int, error)

func (U256) MarshalJSON 

func (u256 U256) MarshalJSON() ([]byte, error)

func (U256) Mul added in v0.2.4 

func (u256 U256) Mul(other U256) U256

func (U256) SizeHint 

func (u256 U256) SizeHint() int

func (U256) String 

func (u256 U256) String() string

func (U256) Sub 

func (u256 U256) Sub(other U256) U256

func (*U256) SubAssign 

func (u256 *U256) SubAssign(other U256)

func (U256) Type 

func (U256) Type() Type

Type returns the type of this value.

func (*U256) Unmarshal 

func (u256 *U256) Unmarshal(buf []byte, rem int) ([]byte, int, error)

func (*U256) UnmarshalJSON 

func (u256 *U256) UnmarshalJSON(data []byte) error

type U32 

type U32 uint32

U32 represents a 32-bit unsigned integer.

func NewU32 

func NewU32(x uint32) U32

NewU32 returns a uint32 wrapped as a U32.

func NewU32FromU16 

func NewU32FromU16(x U16) U32

NewU32FromU16 returns a uint32 wrapped as a U32.

func NewU32FromU8 

func NewU32FromU8(x U8) U32

NewU32FromU8 returns a uint32 wrapped as a U32.

func (U32) Add 

func (u32 U32) Add(other U32) U32

Add one U32 to another and return the result.

func (*U32) AddAssign 

func (u32 *U32) AddAssign(other U32)

AddAssign will add one U32 to another and assign the result to the left-hand side.

func (U32) Equal 

func (u32 U32) Equal(other U32) bool

Equal compares one U32 to another. If they are equal, then it returns true. Otherwise, it returns false.

func (U32) Generate 

func (u32 U32) Generate(r *rand.Rand, size int) reflect.Value

Generate a random int. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (U32) Marshal 

func (u32 U32) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the U32 to binary.

func (U32) MarshalJSON 

func (u32 U32) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSON marshaler interface. U32s are marshaled as decimal strings (for consistency with larger integer types).

func (U32) SizeHint 

func (u32 U32) SizeHint() int

SizeHint returns the number of bytes required to represent a U32 in binary.

func (U32) String 

func (u32 U32) String() string

func (U32) Sub 

func (u32 U32) Sub(other U32) U32

Sub one U32 from another and return the result.

func (*U32) SubAssign 

func (u32 *U32) SubAssign(other U32)

SubAssign will sub one U32 from another and assign the result to the left-hand side.

func (U32) Type 

func (U32) Type() Type

Type returns the type of this value.

func (U32) Uint32 

func (u32 U32) Uint32() uint32

Uint32 returns the inner uint32.

func (*U32) Unmarshal 

func (u32 *U32) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the U32 from binary.

func (*U32) UnmarshalJSON 

func (u32 *U32) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the JSON unmarshaler interface. U32s are unmarshaled as decimal strings (for consistency with larger integer types).

type U64 

type U64 uint64

U64 represents a 64-bit unsigned integer.

func NewU64 

func NewU64(x uint64) U64

NewU64 returns a uint64 wrapped as a U64.

func NewU64FromU16 

func NewU64FromU16(x U16) U64

NewU64FromU16 returns a uint64 wrapped as a U64.

func NewU64FromU32 

func NewU64FromU32(x U32) U64

NewU64FromU32 returns a uint32 wrapped as a U64.

func NewU64FromU8 

func NewU64FromU8(x U8) U64

NewU64FromU8 returns a uint64 wrapped as a U64.

func (U64) Add 

func (u64 U64) Add(other U64) U64

Add one U64 to another and return the result.

func (*U64) AddAssign 

func (u64 *U64) AddAssign(other U64)

AddAssign will add one U64 to another and assign the result to the left-hand side.

func (U64) Equal 

func (u64 U64) Equal(other U64) bool

Equal compares one U64 to another. If they are equal, then it returns true. Otherwise, it returns false.

func (U64) Generate 

func (u64 U64) Generate(r *rand.Rand, size int) reflect.Value

Generate a random int. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (U64) Marshal 

func (u64 U64) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the U64 to binary.

func (U64) MarshalJSON 

func (u64 U64) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSON marshaler interface. U64s are marshaled as decimal strings (for consistency with larger integer types).

func (U64) SizeHint 

func (u64 U64) SizeHint() int

SizeHint returns the number of bytes required to represent a U64 in binary.

func (U64) String 

func (u64 U64) String() string

func (U64) Sub 

func (u64 U64) Sub(other U64) U64

Sub one U64 from another and return the result.

func (*U64) SubAssign 

func (u64 *U64) SubAssign(other U64)

SubAssign will sub one U64 from another and assign the result to the left-hand side.

func (U64) Type 

func (U64) Type() Type

Type returns the type of this value.

func (U64) Uint64 

func (u64 U64) Uint64() uint64

Uint64 returns the inner uint64.

func (*U64) Unmarshal 

func (u64 *U64) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the U64 from binary.

func (*U64) UnmarshalJSON 

func (u64 *U64) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the JSON unmarshaler interface. U64s are unmarshaled as decimal strings (for consistency with larger integer types).

type U8 

type U8 uint8

U8 represents an 8-bit unsigned integer.

func NewU8 

func NewU8(x uint8) U8

NewU8 returns a uint8 wrapped as a U8.

func (U8) Add 

func (u8 U8) Add(other U8) U8

Add one U8 to another and return the result.

func (*U8) AddAssign 

func (u8 *U8) AddAssign(other U8)

AddAssign will add one U8 to another and assign the result to the left-hand side.

func (U8) Equal 

func (u8 U8) Equal(other U8) bool

Equal compares one U8 to another. If they are equal, then it returns true. Otherwise, it returns false.

func (U8) Generate 

func (u8 U8) Generate(r *rand.Rand, size int) reflect.Value

Generate a random int. This method is implemented for use in quick tests. See https://golang.org/pkg/testing/quick/#Generator for more information.

func (U8) Marshal 

func (u8 U8) Marshal(buf []byte, rem int) ([]byte, int, error)

Marshal the U8 to binary.

func (U8) MarshalJSON 

func (u8 U8) MarshalJSON() ([]byte, error)

MarshalJSON implements the JSON marshaler interface. U8s are marshaled as decimal strings (for consistency with larger integer types).

func (U8) SizeHint 

func (u8 U8) SizeHint() int

SizeHint returns the number of bytes required to represent a U8 in binary.

func (U8) String 

func (u8 U8) String() string

func (U8) Sub 

func (u8 U8) Sub(other U8) U8

Sub one U8 from another and return the result.

func (*U8) SubAssign 

func (u8 *U8) SubAssign(other U8)

SubAssign will sub one U8 from another and assign the result to the left-hand side.

func (U8) Type 

func (U8) Type() Type

Type returns the type of this value.

func (U8) Uint8 

func (u8 U8) Uint8() uint8

Uint8 returns the inner uint8.

func (*U8) Unmarshal 

func (u8 *U8) Unmarshal(buf []byte, rem int) ([]byte, int, error)

Unmarshal the U8 from binary.

func (*U8) UnmarshalJSON 

func (u8 *U8) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the JSON unmarshaler interface. U8s are unmarshaled as decimal strings (for consistency with larger integer types).

type Value 

type Value interface {
	surge.Marshaler
	json.Marshaler

	Type() Type
}

A Value is a common interface for all values that are able to be marshaled to binary and JSON, and are able to express their type information.

func Encode added in v0.2.0 

func Encode(v interface{}) (val Value, err error)

Encode a Go interface into a Value interface.

Source Files

View all Source files

Directories

Path Synopsis

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.