Standard library · Encoding and data

encoding/value

A dynamic value for data whose shape you do not know in advance; the shared language of every format in this group.

import encoding.value

On this page

Types
Constants and variables
Functions

When you read JSON whose shape you do not know in advance, it cannot be poured into a fixed struct. That is what Value is for: every value carries its own kind, and it may be an array or an object of further values.

JSON, YAML, TOML, MessagePack, CSV and XML can all be turned into a Value and built from one; the encoding.serde package uses exactly this to convert between formats.

Types

`Value`

struct Value

A dynamic value: null, boolean, whole number, decimal, string, array or object.

Name	Type	Description
`kind`	`int`	The kind of the value; one of the Kind constants.
`b`	`bool = false`	The boolean value.
`i`	`i64 = 0`	The whole number value.
`n`	`f64 = 0`	The decimal value.
`s`	`str = ""`	The string value.
`arr`	`Vector`	The elements of an array.
`obj`	`HashMap`	The keys and values of an object.

encoding-value-Value.salam

import encoding.value

func main:
    mut user := value.NewValueObject()
    value.ObjectSet(user, "name", value.ValueString("Narges"))
    value.ObjectSet(user, "age", value.ValueInt(34))
    value.ObjectSet(user, "height", value.ValueFloat(1.68))
    value.ObjectSet(user, "admin", value.ValueBool(false))
    value.ObjectSet(user, "phone", value.ValueNull())
    mut languages := value.NewValueArray()
    value.ArrayPush(languages, value.ValueString("fa"))
    value.ArrayPush(languages, value.ValueString("en"))
    value.ArraySet(languages, 1, value.ValueString("ar"))
    value.ObjectSet(user, "langs", languages)
    println value.ToDebugString(user)
    println value.ObjectLen(user), value.ObjectHas(user, "age"), value.ObjectKeys(user)
    println value.AsString(value.ObjectGet(user, "name")), value.AsInt(value.ObjectGet(user, "age")), value.AsFloat(value.ObjectGet(user, "height")), value.AsBool(value.ObjectGet(user, "admin"))
    langs := value.ObjectGet(user, "langs")
    println value.IsArray(langs), value.ArrayLen(langs), value.AsString(value.ArrayGet(langs, 1))
    mut present := false
    _ := value.ObjectGetOk(user, "email", present)
    println present
    phone := value.ObjectGet(user, "phone")
    println value.IsNull(phone), value.IsBool(phone), value.IsInt(value.ValueInt(1)), value.IsFloat(value.ValueFloat(1.0)), value.IsNumber(value.ValueInt(1))
    println value.IsString(value.ValueString("")), value.IsObject(user), phone.kind == value.KindNull, value.KindObject
    mut copy := value.ValueClone(user)
    println value.Equal(copy, user)
    removed := value.ObjectDelete(copy, "phone")
    println removed, value.Equal(copy, user)
    mut numbers := Vector {} as Vector<value.Value>
    numbers.push(value.ValueInt(1))
    mut fields := HashMap {} as HashMap<str, value.Value>
    fields.put("x", value.ValueArray(numbers))
    println value.ToDebugString(value.ValueObject(fields))
    value.ValueFree(copy)
end

Outputobject{name: string(Narges), height: float(1.68), age: int(34), admin: bool(false), langs: array[string(fa), string(ar)], phone: null} 6 true ["name", "height", "age", "admin", "langs", "phone"] Narges 34 1.68 false true 2 ar false true false true true true true true true 6 true true false object{x: array[int(1)]}

Constants and variables

`KindNull`

const KindNull: i32 = 0

Null.

The example for this item is shown with the ones above: encoding-value-Value.salam

`KindBool`

const KindBool: i32 = 1

Boolean.

The example for this item is shown with the ones above: encoding-value-Value.salam

`KindInt`

const KindInt: i32 = 2

Whole number.

The example for this item is shown with the ones above: encoding-value-Value.salam

`KindFloat`

const KindFloat: i32 = 3

Decimal.

The example for this item is shown with the ones above: encoding-value-Value.salam

`KindString`

const KindString: i32 = 4

String.

The example for this item is shown with the ones above: encoding-value-Value.salam

`KindArray`

const KindArray: i32 = 5

Array.

The example for this item is shown with the ones above: encoding-value-Value.salam

`KindObject`

const KindObject: i32 = 6

Object.

The example for this item is shown with the ones above: encoding-value-Value.salam

Functions

`ToDebugString`

func ToDebugString(v: Value): str

A readable form with the kind of every element, such as object{name: string(Ali)}, for debugging.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueNull`

func ValueNull(): Value

A null value.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueBool`

func ValueBool(b: bool): Value

A boolean value.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueInt`

func ValueInt(i: i64): Value

A whole number value.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueFloat`

func ValueFloat(n: f64): Value

A decimal value.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueString`

func ValueString(s: str): Value

A string value.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueArray`

func ValueArray(items: Vector<Value>): Value

An array from a vector.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueObject`

func ValueObject(fields: HashMap<str, Value>): Value

An object from a map.

The example for this item is shown with the ones above: encoding-value-Value.salam

`NewValueArray`

func NewValueArray(): Value

An empty array.

The example for this item is shown with the ones above: encoding-value-Value.salam

`NewValueObject`

func NewValueObject(): Value

An empty object.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsNull`

func IsNull(v: Value): bool

True when the value is null.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsBool`

func IsBool(v: Value): bool

True when it is a boolean.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsInt`

func IsInt(v: Value): bool

True when it is a whole number.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsFloat`

func IsFloat(v: Value): bool

True when it is a decimal.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsNumber`

func IsNumber(v: Value): bool

True when it is a whole number or a decimal.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsString`

func IsString(v: Value): bool

True when it is a string.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsArray`

func IsArray(v: Value): bool

True when it is an array.

The example for this item is shown with the ones above: encoding-value-Value.salam

`IsObject`

func IsObject(v: Value): bool

True when it is an object.

The example for this item is shown with the ones above: encoding-value-Value.salam

`AsBool`

func AsBool(v: Value): bool

The boolean value; false for any other kind.

The example for this item is shown with the ones above: encoding-value-Value.salam

`AsInt`

func AsInt(v: Value): i64

The whole number value; a decimal is truncated.

The example for this item is shown with the ones above: encoding-value-Value.salam

`AsFloat`

func AsFloat(v: Value): f64

The decimal value; a whole number is converted.

The example for this item is shown with the ones above: encoding-value-Value.salam

`AsString`

func AsString(v: Value): str

The string value; an empty string for any other kind.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ArrayLen`

func ArrayLen(v: Value): int

The number of elements in an array.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ArrayGet`

func ArrayGet(v: Value, i: int): Value

Element number i; the index has to be less than ArrayLen.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ArraySet`

func ArraySet(v &: Value, i: int, item: Value)

Replaces element number i.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ArrayPush`

func ArrayPush(v &: Value, item: Value)

Adds an element at the end of an array.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ObjectLen`

func ObjectLen(v: Value): int

The number of keys in an object.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ObjectHas`

func ObjectHas(v: Value, key: str): bool

True when the key is there.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ObjectGet`

func ObjectGet(v: Value, key: str): Value

The value for a key, or null when it is absent.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ObjectGetOk`

func ObjectGetOk(v: Value, key: str, ok &: bool): Value

The value for a key, with ok saying whether the key was there; for telling "absent" apart from "null".

The example for this item is shown with the ones above: encoding-value-Value.salam

`ObjectSet`

func ObjectSet(v &: Value, key: str, item: Value)

Sets a key.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ObjectDelete`

func ObjectDelete(v &: Value, key: str): bool

Removes a key and says whether it was there.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ObjectKeys`

func ObjectKeys(v: Value): Vector<str>

The keys of an object. Their order is not fixed.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueClone`

func ValueClone(v: Value): Value

A complete, independent copy of a value.

The example for this item is shown with the ones above: encoding-value-Value.salam

`ValueFree`

func ValueFree(v &: Value)

Releases the memory of a value and its elements.

The example for this item is shown with the ones above: encoding-value-Value.salam

`Equal`

func Equal(a: Value, b: Value): bool

True when two values, with all their nested elements, are equal.

The example for this item is shown with the ones above: encoding-value-Value.salam