ion

package
v1.1.3 Latest Latest
Warning

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

 Go to latest Published: Jul 9, 2021 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// SymbolIDUnknown is placeholder for when a symbol token has no symbol ID.
	SymbolIDUnknown = -1
)

Variables

View Source 
var (
	// ErrNoInput is returned when there is no input to decode
	ErrNoInput = errors.New("ion: no input to decode")
)
View Source 
var V1SystemSymbolTable = NewSharedSymbolTable("$ion", 1, []string{
	"$ion",
	"$ion_1_0",
	"$ion_symbol_table",
	"name",
	"version",
	"imports",
	"symbols",
	"max_id",
	"$ion_shared_symbol_table",
})

V1SystemSymbolTable is the (implied) system symbol table for Ion v1.0.

Functions

func IsContainer 

func IsContainer(t Type) bool

IsContainer determines if the type is a container type

func IsScalar 

func IsScalar(t Type) bool

IsScalar determines if the type is a scalar type

func MarshalBinary 

func MarshalBinary(v interface{}, ssts ...SharedSymbolTable) ([]byte, error)

MarshalBinary marshals values to binary ion.

func MarshalBinaryLST 

func MarshalBinaryLST(v interface{}, lst SymbolTable) ([]byte, error)

MarshalBinaryLST marshals values to binary ion with a fixed local symbol table.

func MarshalText 

func MarshalText(v interface{}) ([]byte, error)

MarshalText marshals values to text ion.

Different Go types can be passed into MarshalText() to be marshalled to their corresponding Ion types. e.g., 

    val, err := MarshalText(9)
    if err != nil {
        t.Fatal(err)
    }
    fmt.Println(string(val)) // prints out: 9

	   type inner struct {
		   B int `ion:"b"`
	   }
	   type root struct {
		   A inner `ion:"a"`
		   C int `ion:"c"`
	   }

    v = root{A: inner{B: 6}, C: 7}
	   val, err = MarshalText(v)
	   if err != nil {
        t.Fatal(err)
    }
	   fmt.Println(string(val)) // prints out: {a:{b:6},c:7}

Should the value for marshalling require annotations, it must be wrapped in a Go struct with exactly 2 fields, where the other field of the struct is a slice of string and tagged `ion:",annotations"`, and this field can carry all the desired annotations. 

type foo struct {
    Value   int
    AnyName []string `ion:",annotations"`
}

v := foo{5, []string{"some", "annotations"}}   //some::annotations::5
val, err := MarshalText(v)
if err != nil {
    t.Fatal(err)
}

func MarshalTo 

func MarshalTo(w Writer, v interface{}) error

MarshalTo marshals the given value to the given writer. It does not call Finish, so is suitable for encoding values inside of a partially-constructed Ion value.

func Unmarshal 

func Unmarshal(data []byte, v interface{}, ssts ...SharedSymbolTable) error

Unmarshal unmarshals Ion data to the given object.

User must pass the proper object type to the unmarshalled Ion data. Below is the mapping between Go native type and Ion types. e.g., 

boolBytes := []byte{0xE0, 0x01, 0x00, 0xEA, 0x11}
var boolVal bool
err := Unmarshal(boolBytes, &boolVal)
if err != nil {
    t.Fatal(err)
}
fmt.Println(boolVal) // prints out: true

err = UnmarshalString("true", &boolVal)
if err != nil {
    t.Fatal(err)
}
fmt.Println(boolVal) // prints out: true

To unmarshal an Ion value with annotations, the object passed to Unmarshal must be a Go struct with exactly two fields, where one field's type is in accordance with the Ion type which needs to be unmarshalled (list of mapping between Go native types and Ion types below); and the other field must be of type []string and tagged as `ion:",annotations"`. 

  type foo struct {
      Value   int    // or interface{}
      AnyName []string `ion:",annotations"`
  }

  var val foo
  err := UnmarshalString("age::10", &val)
  if err != nil {
      t.Fatal(err)
  }
  fmt.Println(val) // prints out: {10 [age]}

  Go native type                                  Ion Type
--------------------------                     ---------------
  nil/interface{}                                 null
  bool/interface{}                                bool
  Any ints/uints/big.Int/interface{}              int
  float32/float64/interface{}                     float
  ion.Decimal/interface{}                         decimal
  ion.Timestamp/interface{}                       timestamp
  string/interface{}                              symbol
  string/interface{}                              string
  []byte/[]interface{}{}                          clob
  []byte/[]interface{}{}                          blob
  []interface{}{}                                 list
  []interface{}{}                                 sexp
  map[string]interface{}{}/struct/interface{}     struct

func UnmarshalFrom 

func UnmarshalFrom(r Reader, v interface{}) error

UnmarshalFrom unmarshal Ion data from a reader to the given object.

func UnmarshalString 

func UnmarshalString(data string, v interface{}) error

UnmarshalString unmarshals Ion data from a string to the given object.

Types

type Catalog 

type Catalog interface {
	FindExact(name string, version int) SharedSymbolTable
	FindLatest(name string) SharedSymbolTable
}

A Catalog provides access to shared symbol tables.

func NewCatalog 

func NewCatalog(ssts ...SharedSymbolTable) Catalog

NewCatalog creates a new basic catalog containing the given symbol tables.

type Decimal 

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

Decimal is an arbitrary-precision decimal value.

func MustParseDecimal 

func MustParseDecimal(in string) *Decimal

MustParseDecimal parses the given string into a decimal object, panicking on error.

func NewDecimal 

func NewDecimal(n *big.Int, exp int32, negZero bool) *Decimal

NewDecimal creates a new decimal whose value is equal to n * 10^exp.

func NewDecimalInt 

func NewDecimalInt(n int64) *Decimal

NewDecimalInt creates a new decimal whose value is equal to n.

func ParseDecimal 

func ParseDecimal(in string) (*Decimal, error)

ParseDecimal parses the given string into a decimal object, returning an error on failure.

func (*Decimal) Abs 

func (d *Decimal) Abs() *Decimal

Abs returns the absolute value of this Decimal.

func (*Decimal) Add 

func (d *Decimal) Add(o *Decimal) *Decimal

Add returns the result of adding this Decimal to another Decimal.

func (*Decimal) Cmp 

func (d *Decimal) Cmp(o *Decimal) int

Cmp compares two decimals, returning -1 if d is smaller, +1 if d is larger, and 0 if they are equal (ignoring precision).

func (*Decimal) CoEx 

func (d *Decimal) CoEx() (*big.Int, int32)

CoEx returns this decimal's coefficient and exponent.

func (*Decimal) Equal 

func (d *Decimal) Equal(o *Decimal) bool

Equal determines if two decimals are equal (discounting precision, at least for now).

func (*Decimal) Mul 

func (d *Decimal) Mul(o *Decimal) *Decimal

Mul multiplies two decimals and returns the result.

func (*Decimal) Neg 

func (d *Decimal) Neg() *Decimal

Neg returns the negative of this Decimal.

func (*Decimal) ShiftL 

func (d *Decimal) ShiftL(shift int) *Decimal

ShiftL returns a new decimal shifted the given number of decimal places to the left. It's a computationally-cheap way to compute d * 10^shift.

func (*Decimal) ShiftR 

func (d *Decimal) ShiftR(shift int) *Decimal

ShiftR returns a new decimal shifted the given number of decimal places to the right. It's a computationally-cheap way to compute d / 10^shift.

func (*Decimal) Sign 

func (d *Decimal) Sign() int

Sign returns -1 if the value is less than 0, 0 if it is equal to zero, and +1 if it is greater than zero.

func (*Decimal) String 

func (d *Decimal) String() string

String formats the decimal as a string in Ion text format.

func (*Decimal) Sub 

func (d *Decimal) Sub(o *Decimal) *Decimal

Sub returns the result of substrating another Decimal from this Decimal.

func (*Decimal) Truncate 

func (d *Decimal) Truncate(precision int) *Decimal

Truncate returns a new decimal, truncated to the given number of decimal digits of precision. It does not round, so 19.Truncate(1) = 1d1.

type Decoder 

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

A Decoder decodes go values from an Ion reader.

func NewDecoder 

func NewDecoder(r Reader) *Decoder

NewDecoder creates a new decoder.

func NewTextDecoder 

func NewTextDecoder(in io.Reader) *Decoder

NewTextDecoder creates a new text decoder. Well, a decoder that uses a reader with no shared symbol tables, it'll work to read binary too if the binary doesn't reference any shared symbol tables.

func (*Decoder) Decode 

func (d *Decoder) Decode() (interface{}, error)

Decode decodes a value from the underlying Ion reader without any expectations about what it's going to get. Structs become map[string]interface{}s, Lists and Sexps become []interface{}s.

func (*Decoder) DecodeTo 

func (d *Decoder) DecodeTo(v interface{}) error

DecodeTo decodes an Ion value from the underlying Ion reader into the value provided.

type Encoder 

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

An Encoder writes Ion values to an output stream.

func NewBinaryEncoder 

func NewBinaryEncoder(w io.Writer, ssts ...SharedSymbolTable) *Encoder

NewBinaryEncoder creates a new binary Encoder.

func NewBinaryEncoderLST 

func NewBinaryEncoderLST(w io.Writer, lst SymbolTable) *Encoder

NewBinaryEncoderLST creates a new binary Encoder with a fixed local symbol table.

func NewEncoder 

func NewEncoder(w Writer) *Encoder

NewEncoder creates a new encoder.

func NewEncoderOpts 

func NewEncoderOpts(w Writer, opts EncoderOpts) *Encoder

NewEncoderOpts creates a new encoder with the specified options.

func NewTextEncoder 

func NewTextEncoder(w io.Writer) *Encoder

NewTextEncoder creates a new text Encoder.

func (*Encoder) Encode 

func (m *Encoder) Encode(v interface{}) error

Encode marshals the given value to Ion, writing it to the underlying writer.

func (*Encoder) EncodeAs 

func (m *Encoder) EncodeAs(v interface{}, hint Type) error

EncodeAs marshals the given value to Ion with the given type hint. Use it to encode symbols, clobs, or sexps (which by default get encoded to strings, blobs, and lists respectively).

func (*Encoder) Finish 

func (m *Encoder) Finish() error

Finish finishes writing the current Ion datagram.

type EncoderOpts 

type EncoderOpts uint

EncoderOpts holds bit-flag options for an Encoder. 

const (
	// EncodeSortMaps instructs the encoder to write map keys in sorted order.
	EncodeSortMaps EncoderOpts = 1
)

type IOError 

type IOError struct {
	Err error
}

An IOError is returned when there is an error reading from or writing to an underlying io.Reader or io.Writer.

func (*IOError) Error 

func (e *IOError) Error() string

type ImportSource 

type ImportSource struct {
	// The name of the shared symbol table that this token refers to.
	Table string

	// The ID of the interned symbol text within the shared SymbolTable.
	// This must be greater or equal to 1.
	SID int64
}

ImportSource is a reference to a SID within a shared symbol table.

func (*ImportSource) Equal 

func (is *ImportSource) Equal(o *ImportSource) bool

Equal figures out if two import sources are equal for each component.

type IntSize 

type IntSize uint8

IntSize represents the size of an integer. 

const (
	// NullInt is the size of null.int and other things that aren't actually ints.
	NullInt IntSize = iota
	// Int32 is the size of an Ion integer that can be losslessly stored in an int32.
	Int32
	// Int64 is the size of an Ion integer that can be losslessly stored in an int64.
	Int64
	// BigInt is the size of an Ion integer that can only be losslessly stored in a big.Int.
	BigInt
)

func (IntSize) String 

func (i IntSize) String() string

String implements fmt.Stringer for IntSize.

type InvalidTagByteError 

type InvalidTagByteError struct {
	Byte   byte
	Offset uint64
}

An InvalidTagByteError is returned when a binary Reader encounters an invalid tag byte.

func (*InvalidTagByteError) Error 

func (e *InvalidTagByteError) Error() string

type Marshaler 

type Marshaler interface {
	MarshalIon(w Writer) error
}

Marshaler is the interface implemented by types that can marshal themselves to Ion.

type ParseError 

type ParseError struct {
	Num string
	Msg string
}

A ParseError is returned if ParseDecimal is called with a parameter that cannot be parsed as a Decimal.

func (*ParseError) Error 

func (e *ParseError) Error() string

type Reader 

type Reader interface {
	// Next advances the Reader to the next position in the current value stream.
	// It returns true if this is the position of an Ion value, and false if it
	// is not. On error, it returns false and sets Err.
	Next() bool

	// Err returns an error if a previous call call to Next has failed.
	Err() error

	// Type returns the type of the Ion value the Reader is currently positioned on.
	// It returns NoType if the Reader is positioned before or after a value.
	Type() Type

	// IsNull returns true if the current value is an explicit null. This may be true
	// even if the Type is not NullType (for example, null.struct has type Struct).
	IsNull() bool

	// Annotations returns the annotations associated with the current value as a list of SymbolTokens.
	// It returns nil if there is no current value or the current value has no annotations.
	Annotations() ([]SymbolToken, error)

	// StepIn steps in to the current value if it is a container. It returns an error if there
	// is no current value or if the value is not a container. On success, the Reader is
	// positioned before the first value in the container.
	StepIn() error

	// StepOut steps out of the current container value being read. It returns an error if
	// this Reader is not currently stepped in to a container. On success, the Reader is
	// positioned after the end of the container, but before any subsequent values in the
	// stream.
	StepOut() error

	// BoolValue returns the current value as a boolean (if that makes sense). It returns nil
	// if the value is an Ion null. If the current value is not an Ion bool, it returns an error.
	BoolValue() (*bool, error)

	// IntSize returns the size of integer needed to losslessly represent the current value
	// (if that makes sense). It returns an error if the current value is not an Ion int.
	IntSize() (IntSize, error)

	// IntValue returns the current value as a 32-bit integer (if that makes sense). It returns
	// nil if the value is an Ion null. It returns an error if the current value is not an Ion integer
	// or requires more than 32 bits to represent losslessly.
	IntValue() (*int, error)

	// Int64Value returns the current value as a 64-bit integer (if that makes sense). It returns
	// nil if the value is an Ion null. It returns an error if the current value is not an Ion integer
	// or requires more than 64 bits to represent losslessly.
	Int64Value() (*int64, error)

	// BigIntValue returns the current value as a big.Integer (if that makes sense). It returns
	// nil if the value is an Ion null. It returns an error if the current value is not an Ion integer.
	BigIntValue() (*big.Int, error)

	// FloatValue returns the current value as a 64-bit floating point number (if that makes
	// sense). It returns nil if the value is null. It returns an error if the current value
	// is not an Ion float.
	FloatValue() (*float64, error)

	// DecimalValue returns the current value as an arbitrary-precision Decimal (if that makes
	// sense). It returns nil if the value is null. It returns an error if the current value is
	// not an Ion decimal.
	DecimalValue() (*Decimal, error)

	// TimestampValue returns the current value as a timestamp (if that makes sense). It returns
	// nil if the value is null. It returns an error if the current value is not an Ion timestamp.
	TimestampValue() (*Timestamp, error)

	// StringValue returns the current value as a string (if that makes sense). Returns `nil` for Ion null string.
	// It returns an error if the current value is not an Ion string.
	StringValue() (*string, error)

	// ByteValue returns the current value as a byte slice (if that makes sense). It returns
	// an error if the current value is not an Ion clob or an Ion blob.
	ByteValue() ([]byte, error)

	// IsInStruct indicates if the reader is currently positioned in a struct.
	IsInStruct() bool

	// FieldName returns the field name associated with the current value as a SymbolToken. It returns
	// nil if there is no current value or the current value has no field name. It returns an error if
	// the `SymbolToken` SID is not found in the symbol table.
	FieldName() (*SymbolToken, error)

	// SymbolValue returns the SymbolToken associated with the current value. It returns an
	// error if the current value is not an Ion symbol.
	SymbolValue() (*SymbolToken, error)

	// SymbolTable returns the current symbol table, or nil if there isn't one.
	// Text Readers do not, generally speaking, have an associated symbol table.
	// Binary Readers do.
	SymbolTable() SymbolTable
}

A Reader reads a stream of Ion values.

The Reader has a logical position within the stream of values, influencing the values returned from its methods. Initially, the Reader is positioned before the first value in the stream. A call to Next advances the Reader to the first value in the stream, with subsequent calls advancing to subsequent values. When a call to Next moves the Reader to the position after the final value in the stream, it returns false, making it easy to loop through the values in a stream. 

var r Reader
for r.Next() {
	// ...
}

Next also returns false in case of error. This can be distinguished from a legitimate end-of-stream by calling Err after exiting the loop.

When positioned on an Ion value, the type of the value can be retrieved by calling Type. If it has an associated field name (inside a struct) or annotations, they can be read by calling FieldName and Annotations respectively.

For atomic values, an appropriate XxxValue method can be called to read the value. For lists, sexps, and structs, you should instead call StepIn to move the Reader in to the contained sequence of values. The Reader will initially be positioned before the first value in the container. Calling Next without calling StepIn will skip over the composite value and return the next value in the outer value stream.

At any point while reading through a composite value, including when Next returns false to indicate the end of the contained values, you may call StepOut to move back to the outer sequence of values. The Reader will be positioned at the end of the composite value, such that a call to Next will move to the immediately-following value (if any). 

r := NewTextReaderStr("[foo, bar] [baz]")
for r.Next() {
	if err := r.StepIn(); err != nil {
		return err
	}
	for r.Next() {
		fmt.Println(r.StringValue())
	}
	if err := r.StepOut(); err != nil {
		return err
	}
}
if err := r.Err(); err != nil {
	return err
}

func NewReader 

func NewReader(in io.Reader) Reader

NewReader creates a new Ion reader of the appropriate type by peeking at the first several bytes of input for a binary version marker.

func NewReaderBytes 

func NewReaderBytes(in []byte) Reader

NewReaderBytes creates a new reader for the given bytes.

func NewReaderCat 

func NewReaderCat(in io.Reader, cat Catalog) Reader

NewReaderCat creates a new reader with the given catalog.

func NewReaderString 

func NewReaderString(str string) Reader

NewReaderString creates a new reader from a string.

type SharedSymbolTable 

type SharedSymbolTable interface {
	SymbolTable

	// Name returns the name of this shared symbol table.
	Name() string
	// Version returns the version of this shared symbol table.
	Version() int
	// Adjust returns a new shared symbol table limited or extended to the given max ID.
	Adjust(maxID uint64) SharedSymbolTable
}

A SharedSymbolTable is distributed out-of-band and referenced from a local SymbolTable to save space.

func NewSharedSymbolTable 

func NewSharedSymbolTable(name string, version int, symbols []string) SharedSymbolTable

NewSharedSymbolTable creates a new shared symbol table.

type SymbolTable 

type SymbolTable interface {
	// Imports returns the symbol tables this table imports.
	Imports() []SharedSymbolTable
	// Symbols returns the symbols this symbol table defines.
	Symbols() []string
	// MaxID returns the maximum ID this symbol table defines.
	MaxID() uint64
	// Find finds the SymbolToken by its name.
	Find(symbol string) *SymbolToken
	// FindByName finds the ID of a symbol by its name.
	FindByName(symbol string) (uint64, bool)
	// FindByID finds the name of a symbol given its ID.
	FindByID(id uint64) (string, bool)
	// WriteTo serializes the symbol table to an ion.Writer.
	WriteTo(w Writer) error
	// String returns an ion text representation of the symbol table.
	String() string
}

A SymbolTable maps binary-representation symbol IDs to text-representation strings and vice versa.

func NewLocalSymbolTable 

func NewLocalSymbolTable(imports []SharedSymbolTable, symbols []string) SymbolTable

NewLocalSymbolTable creates a new local symbol table.

type SymbolTableBuilder 

type SymbolTableBuilder interface {
	SymbolTable

	// Add adds a symbol to this symbol table.
	Add(symbol string) (uint64, bool)
	// Build creates an immutable local symbol table.
	Build() SymbolTable
}

A SymbolTableBuilder helps you iteratively build a local symbol table.

func NewSymbolTableBuilder 

func NewSymbolTableBuilder(imports ...SharedSymbolTable) SymbolTableBuilder

NewSymbolTableBuilder creates a new symbol table builder with the given imports.

type SymbolToken 

type SymbolToken struct {
	// The string text of the token or nil if unknown.
	Text *string
	// Local symbol ID associated with the token.
	LocalSID int64
	// The shared symbol table location that this token came from, or nil if undefined.
	Source *ImportSource
}

SymbolToken is the representation for annotations, field names, and the textual content of Ion symbol values. The `nil` value for SymbolToken is the SID `$0`.

func NewSymbolToken 

func NewSymbolToken(symbolTable SymbolTable, text string) (SymbolToken, error)

NewSymbolToken will check and return a symbol token if it exists in a symbol table, otherwise return a new symbol token.

func NewSymbolTokenBySID 

func NewSymbolTokenBySID(symbolTable SymbolTable, sid int64) (SymbolToken, error)

NewSymbolTokenBySID will check and return a symbol token if the given id exists in a symbol table, otherwise return a new symbol token.

func NewSymbolTokenFromString added in v1.1.0 

func NewSymbolTokenFromString(text string) SymbolToken

NewSymbolTokenFromString returns a Symbol Token with the given text value and undefined SID and Source.

func NewSymbolTokens 

func NewSymbolTokens(symbolTable SymbolTable, textVals []string) ([]SymbolToken, error)

NewSymbolTokens will check and return a list of symbol tokens if they exists in a symbol table, otherwise return a list of new symbol tokens.

func (*SymbolToken) Equal 

func (st *SymbolToken) Equal(o *SymbolToken) bool

Equal figures out if two symbol tokens are equivalent.

func (*SymbolToken) String 

func (st *SymbolToken) String() string

type SyntaxError 

type SyntaxError struct {
	Msg    string
	Offset uint64
}

A SyntaxError is returned when a Reader encounters invalid input for which no more specific error type is defined.

func (*SyntaxError) Error 

func (e *SyntaxError) Error() string

type System 

type System struct {
	Catalog Catalog
}

A System is a reader factory wrapping a catalog.

func (System) NewReader 

func (s System) NewReader(in io.Reader) Reader

NewReader creates a new reader using this system's catalog.

func (System) NewReaderBytes 

func (s System) NewReaderBytes(in []byte) Reader

NewReaderBytes creates a new reader using this system's catalog.

func (System) NewReaderString 

func (s System) NewReaderString(in string) Reader

NewReaderString creates a new reader using this system's catalog.

func (System) Unmarshal 

func (s System) Unmarshal(data []byte, v interface{}) error

Unmarshal unmarshals Ion data using this system's catalog.

func (System) UnmarshalString 

func (s System) UnmarshalString(data string, v interface{}) error

UnmarshalString unmarshals Ion data using this system's catalog.

type TextWriterOpts 

type TextWriterOpts uint8

TextWriterOpts defines a set of bit flag options for text writers. 

const (
	// TextWriterQuietFinish disables emiting a newline in Finish(). Convenient if you
	// know you're only emiting one datagram; dangerous if there's a chance you're going
	// to emit another datagram using the same Writer.
	TextWriterQuietFinish TextWriterOpts = 1

	// TextWriterPretty enables pretty-printing mode.
	TextWriterPretty TextWriterOpts = 2
)

type Timestamp 

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

Timestamp struct

func MustParseTimestamp added in v1.1.0 

func MustParseTimestamp(dateStr string) Timestamp

MustParseTimestamp parses the given string into an ion timestamp object, panicking on error.

func NewDateTimestamp 

func NewDateTimestamp(dateTime time.Time, precision TimestampPrecision) Timestamp

NewDateTimestamp constructor meant for timestamps that only have a date portion (ie. no time portion).

func NewTimestamp 

func NewTimestamp(dateTime time.Time, precision TimestampPrecision, kind TimezoneKind) Timestamp

NewTimestamp constructor

func NewTimestampFromStr 

func NewTimestampFromStr(dateStr string, precision TimestampPrecision, kind TimezoneKind) (Timestamp, error)

NewTimestampFromStr constructor

func NewTimestampWithFractionalSeconds 

func NewTimestampWithFractionalSeconds(dateTime time.Time, precision TimestampPrecision, kind TimezoneKind, fractionPrecision uint8) Timestamp

NewTimestampWithFractionalSeconds constructor

func ParseTimestamp added in v1.1.0 

func ParseTimestamp(dateStr string) (Timestamp, error)

ParseTimestamp parses a timestamp string and returns an ion timestamp.

func (Timestamp) Equal 

func (ts Timestamp) Equal(ts1 Timestamp) bool

Equal figures out if two timestamps are equal for each component.

func (Timestamp) GetDateTime 

func (ts Timestamp) GetDateTime() time.Time

GetDateTime returns the timestamps date time.

func (Timestamp) GetNumberOfFractionalSeconds 

func (ts Timestamp) GetNumberOfFractionalSeconds() uint8

GetNumberOfFractionalSeconds returns the number of precision units in the timestamp's fractional seconds.

func (Timestamp) GetPrecision 

func (ts Timestamp) GetPrecision() TimestampPrecision

GetPrecision returns the timestamp's precision.

func (Timestamp) GetTimezoneKind 

func (ts Timestamp) GetTimezoneKind() TimezoneKind

GetTimezoneKind returns the kind of timezone.

func (Timestamp) String 

func (ts Timestamp) String() string

String returns a formatted Timestamp string.

func (Timestamp) TruncatedNanoseconds 

func (ts Timestamp) TruncatedNanoseconds() int

TruncatedNanoseconds returns nanoseconds with trailing values removed up to the difference of max fractional precision - time stamp's fractional precision e.g. 123456000 with fractional precision: 3 will get truncated to 123.

type TimestampPrecision 

type TimestampPrecision uint8

TimestampPrecision is for tracking the precision of a timestamp 

const (
	TimestampNoPrecision TimestampPrecision = iota
	TimestampPrecisionYear
	TimestampPrecisionMonth
	TimestampPrecisionDay
	TimestampPrecisionMinute
	TimestampPrecisionSecond
	TimestampPrecisionNanosecond
)

Possible TimestampPrecision values

func (TimestampPrecision) Layout 

func (tp TimestampPrecision) Layout(kind TimezoneKind, precisionUnits uint8) string

Layout returns a suitable format string to be used in time.Parse() or time.Format(). The idea of the format string is to format the particular date Mon Jan 2 15:04:05 MST 2006 (Unix time 1136239445) in the desired layout we want to use to format other dates.

func (TimestampPrecision) String 

func (tp TimestampPrecision) String() string

type TimezoneKind 

type TimezoneKind uint8

TimezoneKind tracks the type of timezone. 

const (
	// TimezoneUnspecified is for timestamps without a timezone such as dates with no time component (ie. Year/Month/Day precision).
	// Negative zero offsets (ie. yyyy-mm-ddThh:mm-00:00) are also considered Unspecified.
	TimezoneUnspecified TimezoneKind = iota

	// TimezoneUTC is for UTC timestamps and they are usually denoted with a trailing 'Z' (ie. yyyy-mm-ddThh:mmZ).
	// Timestamps with a positive zero offset (ie. yyyy-mm-ddThh:mm+00:00) are also considered UTC.
	TimezoneUTC

	// TimezoneLocal is for timestamps that have a non-zero offset from UTC (ie. 2001-02-03T04:05+08:30, 2009-05-18T16:20-04:00).
	TimezoneLocal
)

type Type 

type Type uint8

A Type represents the type of an Ion Value. 

const (
	// NoType is returned by a Reader that is not currently pointing at a value.
	NoType Type = iota

	// NullType is the type of the (unqualified) Ion null value.
	NullType

	// BoolType is the type of an Ion boolean, true or false.
	BoolType

	// IntType is the type of a signed Ion integer of arbitrary size.
	IntType

	// FloatType is the type of a fixed-precision Ion floating-point value.
	FloatType

	// DecimalType is the type of an arbitrary-precision Ion decimal value.
	DecimalType

	// TimestampType is the type of an arbitrary-precision Ion timestamp.
	TimestampType

	// SymbolType is the type of an Ion symbol, mapped to an integer ID by a SymbolTable
	// to (potentially) save space.
	SymbolType

	// StringType is the type of a non-symbol Unicode string, represented directly.
	StringType

	// ClobType is the type of a character large object. Like a BlobType, it stores an
	// arbitrary sequence of bytes, but it represents them in text form as an escaped-ASCII
	// string rather than a base64-encoded string.
	ClobType

	// BlobType is the type of a binary large object; a sequence of arbitrary bytes.
	BlobType

	// ListType is the type of a list, recursively containing zero or more Ion values.
	ListType

	// SexpType is the type of an s-expression. Like a ListType, it contains a sequence
	// of zero or more Ion values, but with a lisp-like syntax when encoded as text.
	SexpType

	// StructType is the type of a structure, recursively containing a sequence of named
	// (by an Ion symbol) Ion values.
	StructType
)

func (Type) String 

func (t Type) String() string

String implements fmt.Stringer for Type.

type UnexpectedEOFError 

type UnexpectedEOFError struct {
	Offset uint64
}

An UnexpectedEOFError is returned when a Reader unexpectedly encounters an io.EOF error.

func (*UnexpectedEOFError) Error 

func (e *UnexpectedEOFError) Error() string

type UnexpectedRuneError 

type UnexpectedRuneError struct {
	Rune   rune
	Offset uint64
}

An UnexpectedRuneError is returned when a text Reader encounters an unexpected rune.

func (*UnexpectedRuneError) Error 

func (e *UnexpectedRuneError) Error() string

type UnexpectedTokenError 

type UnexpectedTokenError struct {
	Token  string
	Offset uint64
}

An UnexpectedTokenError is returned when a text Reader encounters an unexpected token.

func (*UnexpectedTokenError) Error 

func (e *UnexpectedTokenError) Error() string

type UnsupportedVersionError 

type UnsupportedVersionError struct {
	Major  int
	Minor  int
	Offset uint64
}

An UnsupportedVersionError is returned when a Reader encounters a binary version marker with a version that this library does not understand.

func (*UnsupportedVersionError) Error 

func (e *UnsupportedVersionError) Error() string

type UsageError 

type UsageError struct {
	API string
	Msg string
}

A UsageError is returned when you use a Reader or Writer in an inappropriate way.

func (*UsageError) Error 

func (e *UsageError) Error() string

type Writer 

type Writer interface {
	// FieldName sets the field name for the next value written.
	FieldName(val SymbolToken) error

	// Annotation adds a single annotation to the next value written.
	Annotation(val SymbolToken) error

	// Annotations adds multiple annotations to the next value written.
	Annotations(values ...SymbolToken) error

	// WriteNull writes an untyped null value.
	WriteNull() error

	// WriteNullType writes a null value with a type qualifier, e.g. null.bool.
	WriteNullType(t Type) error

	// WriteBool writes a boolean value.
	WriteBool(val bool) error

	// WriteInt writes an integer value.
	WriteInt(val int64) error

	// WriteUint writes an unsigned integer value.
	WriteUint(val uint64) error

	// WriteBigInt writes a big integer value.
	WriteBigInt(val *big.Int) error

	// WriteFloat writes a floating-point value.
	WriteFloat(val float64) error

	// WriteDecimal writes an arbitrary-precision decimal value.
	WriteDecimal(val *Decimal) error

	// WriteTimestamp writes a timestamp value.
	WriteTimestamp(val Timestamp) error

	// WriteSymbol writes a symbol value given a SymbolToken.
	WriteSymbol(val SymbolToken) error

	// WriteSymbolFromString writes a symbol value given a string.
	WriteSymbolFromString(val string) error

	// WriteString writes a string value.
	WriteString(val string) error

	// WriteClob writes a clob value.
	WriteClob(val []byte) error

	// WriteBlob writes a blob value.
	WriteBlob(val []byte) error

	// BeginList begins writing a list value.
	BeginList() error

	// EndList finishes writing a list value.
	EndList() error

	// BeginSexp begins writing an s-expression value.
	BeginSexp() error

	// EndSexp finishes writing an s-expression value.
	EndSexp() error

	// BeginStruct begins writing a struct value.
	BeginStruct() error

	// EndStruct finishes writing a struct value.
	EndStruct() error

	// Finish finishes writing values and flushes any buffered data.
	Finish() error

	// IsInStruct indicates if we are currently writing a struct or not.
	IsInStruct() bool
}

A Writer writes a stream of Ion values.

The various Write methods write atomic values to the current output stream. The Begin methods begin writing a list, sexp, or struct respectively. Subsequent calls to Write will write values inside of the container until a matching End method is called. 

var w Writer
w.BeginSexp()
{
	w.WriteInt(1)
	w.WriteSymbolFromString("+")
	w.WriteInt(1)
}
w.EndSexp()

When writing values inside a struct, the FieldName method must be called before each value to set the value's field name. The Annotation method may likewise be called before writing any value to add an annotation to the value. 

var w Writer
w.Annotation("user")
w.BeginStruct()
{
	w.FieldName("id")
	w.WriteString("foo")
	w.FieldName("name")
	w.WriteString("bar")
}
w.EndStruct()

When you're done writing values, you should call Finish to ensure everything has been flushed from in-memory buffers. While individual methods all return an error on failure, implementations will remember any errors, no-op subsequent calls, and return the previous error. This lets you keep code a bit cleaner by only checking the return value of the final method call (generally Finish). 

var w Writer
writeSomeStuff(w)
if err := w.Finish(); err != nil {
	return err
}

func NewBinaryWriter 

func NewBinaryWriter(out io.Writer, sts ...SharedSymbolTable) Writer

NewBinaryWriter creates a new binary writer that will construct a local symbol table as it is written to.

func NewBinaryWriterLST 

func NewBinaryWriterLST(out io.Writer, lst SymbolTable) Writer

NewBinaryWriterLST creates a new binary writer with a pre-built local symbol table.

func NewTextWriter 

func NewTextWriter(out io.Writer, sts ...SharedSymbolTable) Writer

NewTextWriter returns a new text writer that will construct a local symbol table as it is written to.

func NewTextWriterOpts 

func NewTextWriterOpts(out io.Writer, opts TextWriterOpts, sts ...SharedSymbolTable) Writer

NewTextWriterOpts returns a new text writer with the given options.

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.