cdc

Documentation

Overview

Package cdc provides support for unmarshalling cadence.Values to ideomatic Go types

Index

• func Unmarshal(data cadence.Value, v interface{}) (err error)
• type InvalidUnmarshalError
  • func (e *InvalidUnmarshalError) Error() string
• type UnmarshalTypeError
  • func (e *UnmarshalTypeError) Error() string
• type Unmarshaler

Examples

• Unmarshal

Functions

func Unmarshal

func Unmarshal(data cadence.Value, v interface{}) (err error)

Unmarshal parses the cadence data and stores the result in the value pointed to by v. If v is nil or not a pointer, Unmarshal returns an InvalidUnmarshalError.

Unmarshal allocates maps, slices, and pointers as necessary, with the following additional rules:

To unmarshal cadence into a pointer, Unmarshal first handles the case of the cadence being void or nil. In that case, Unmarshal sets the pointer to nil. Otherwise, Unmarshal unmarshals the cadence into the value pointed at by the pointer. If the pointer is nil, Unmarshal allocates a new value for it to point to.

To unmarshal cadence into a value implementing the Unmarshaler interface, Unmarshal calls that value's UnmarshalCadence method, including when the input is a cadence void or nil.

To unmarshal cadence into a struct, Unmarshal matches incoming field keys to either the struct field name or its tag, preferring an exact match but also accepting a case-insensitive match. Cadence fields which don't have a corresponding struct field are ignored.

To unmarshal cadence into an interface value, Unmarshal stores one of these in the interface value:

bool, for cadence booleans
int64, for cadence Int[x]
uint64, for cadence UInt[x] and Word[x]
float64, for cadence Fix64 and UFix64
string, for cadence strings
[]interface{}, for cadence arrays
map[string]interface{}, for cadence maps and composite values
nil for cadence nil

To unmarshal a cadence array into a slice, Unmarshal resets the slice length to zero and then appends each element to the slice. As a special case, to unmarshal an empty cadence array into a slice, Unmarshal replaces the slice with a new empty slice.

To unmarshal a cadence array into a Go array, Unmarshal decodes cadence array elements into corresponding Go array elements. If the Go array is smaller than the cadence array, the additional cadence array elements are discarded. If the cadence array is smaller than the Go array, the additional Go array elements are set to zero values.

To unmarshal a cadence dictionary or composite value into a map, Unmarshal first establishes a map to use. If the map is nil, Unmarshal allocates a new map. Otherwise Unmarshal reuses the existing map, keeping existing entries. Unmarshal then stores key-value pairs from the cadence object into the map. The map's key type must either be any string type, an integer, or implement cdc.Unmarshaler.

If a cadence value is not appropriate for a given target type, or if a cadence number overflows the target type, Unmarshal skips that field and completes the unmarshaling as best it can. If no more serious errors are encountered, Unmarshal returns an UnmarshalTypeError describing the earliest such error. In any case, it's not guaranteed that all the remaining fields following the problematic one will be unmarshaled into the target object.

Example

package main

import (
	"fmt"

	"github.com/onflow/cadence"
)

func cdcString(str string) cadence.String {
	resp, _ := cadence.NewString(str)
	return resp
}

func main() {
	fix1, _ := cadence.NewUFix64("1.23")
	fix2, _ := cadence.NewUFix64("45.6")
	cadenceVal := cadence.Struct{
		Fields: []cadence.Value{
			cdcString("a string value"),
			cadence.NewInt(123),
			cadence.NewDictionary([]cadence.KeyValuePair{
				{Key: cdcString("a"), Value: fix1},
				{Key: cdcString("b"), Value: fix2},
			}),
		},
		StructType: &cadence.StructType{
			Fields: []cadence.Field{
				{Identifier: `str`, Type: cadence.StringType{}},
				{Identifier: `integer`, Type: cadence.IntType{}},
				{Identifier: `dict`, Type: cadence.DictionaryType{
					KeyType:     cadence.StringType{},
					ElementType: cadence.UFix64Type{},
				}},
			},
		},
	}

	type Nicer struct {
		Str     string             `json:"str"`
		Integer int64              `json:"integer"`
		Dict    map[string]float64 `json:"dict"`
	}
	nicer := Nicer{}

	err := Unmarshal(cadenceVal, &nicer)
	if err != nil {
		fmt.Println(`Unmarshal failed:`, err)
		return
	}
	fmt.Println(`Unmarshal succeeded:`, nicer.Dict[`b`])
}

Output:

Unmarshal succeeded: 45.6

Types

type InvalidUnmarshalError

type InvalidUnmarshalError struct {
	Type reflect.Type
}

func (*InvalidUnmarshalError) Error

func (e *InvalidUnmarshalError) Error() string

type UnmarshalTypeError

type UnmarshalTypeError struct {
	Value  string       // description of value - "bool", "array", "number -5"
	Type   reflect.Type // type of Go value it could not be assigned to
	Struct string       // name of the struct type containing the field
	Field  string       // the full path from root node to the field
}

An UnmarshalTypeError describes a cadence value that was not appropriate for a value of a specific Go type.

func (*UnmarshalTypeError) Error

func (e *UnmarshalTypeError) Error() string

type Unmarshaler

type Unmarshaler interface {
	UnmarshalCadence(cadence.Value) error
}

Unmarshaler is the interface implemented by types that can unmarshal a cadence description of themselves. UnmarshalCadence must copy the cadence data if it wishes to retain the data after returning.