Reference

std/encoding/values

std/encoding/src/values.trb

A value without its type: EncodedValue, the Values encoder that builds one, and the ValueDecoder that reads a typed value back out of one.

EncodedValue is what a program holds where it has left the type behind - a quotation's captures, a field default in a schema, the text rendered shows. It is one format among many, an encoder that writes into memory, and nothing goes through it unless a program asks for a value without its type.

ValueDecoder is the one Decoder every buffering format shares: a text format with unordered fields parses into an EncodedValue and hands it over, instead of writing a state machine of its own.

type EncodedValue

type EncodedValue with Show

Any Encode value, held without its type. Every scalar of the vocabulary has a case, so nothing is lost: a narrow number is already widened, and a Decimal stays exact.

Examples

type Point {
  x: Int
  y: Int
}

print EncodedValue.of(Point(1, 2))

Related

  • rendered - the same, as the text a message shows.

case Nothing

case Nothing

An absent value: what None writes.

case Bool

case Bool(value: Bool)

A truth value.

case Int

case Int(value: Int64)

A whole number, widened to 64 bits.

case Unsigned

case Unsigned(value: UInt64)

A whole number that may not fit into an Int64.

case Float

case Float(value: Float64)

A floating point number.

case String

case String(value: String)

A text. An exact Decimal is held as its text too, which is exact and which every format can read back.

case Bytes

case Bytes(value: List<UInt8>)

Raw bytes.

case Sequence

case Sequence(items: List<EncodedValue>)

The items of a sequence, in order.

case Mapping

case Mapping(entries: List<EncodedValue>)

The entries of a map, flat: a key, then its value, then the next key.

case Record

case Record(typeName: String, fields: List<EncodedField>)

A record, with the qualified name of its type and its fields in declaration order.

case Variant

case Variant(typeName: String, name: String, fields: List<EncodedField>)

One case of a type with cases, with the fields of that case.

fn of

static fn of<Value: Encode>(value: Value, privateFields: Bool = false): EncodedValue

EncodedValue.of(user): the value, written by Values. With privateFields, a private field with a default is written as well, so the value is the whole value and not only its data (Encoder.writesPrivateFields).

fn show

fn show(): String

Price(amount: 19.99, currency: "EUR"): the shape the generated Show of the type has, too.

fn plain

fn plain(): String

The unquoted text of a scalar, which is what a SQL default and a --help line want.

extend EncodedValue with Encode

extend EncodedValue with Encode

An EncodedValue writes itself into any encoder, which is what makes it useful: a captured value can be bound as a SQL parameter, and a document nobody has a type for can be written out again.

fn encode

fn encode<Target: Encoder>(var target: Target)

type EncodedField

type EncodedField

One named field of an EncodedValue.Record or EncodedValue.Variant.

field name

name: String

The field's name, as the type declares it.

field value

value: EncodedValue

What the field holds.

fn show

fn show(): String

name: value, the way a record shows its fields.

fn rendered

fn rendered<Value: Encode>(value: Value): String

Any Encode value as readable text, for messages and debugging: User(name: "Ada", tags: ["math"]). It is EncodedValue.of and then EncodedValue.show.

Examples

print rendered([1, 2, 3])

type Values

type Values with Encoder

An Encoder that builds an EncodedValue. It is a format like any other, and the only one without bytes.

A record that announced no field and holds one value is a wrapper, and it becomes that value.

field privateFields

privateFields: Bool = false

Whether a private field with a default is written as well (Encoder.writesPrivateFields).

fn writesPrivateFields

fn writesPrivateFields(): Bool

Not documented.

fn result

fn result(): EncodedValue

What was written. Nothing when nothing was.

fn nothing

var fn nothing()

Not documented.

fn bool

var fn bool(value: Bool)

Not documented.

fn int

var fn int(value: Int64)

Not documented.

fn unsigned

var fn unsigned(value: UInt64)

Not documented.

fn float

var fn float(value: Float64)

Not documented.

fn decimal

var fn decimal(value: Decimal)

An exact number is held as its text, which loses nothing: ValueDecoder.decimal reads it back.

fn string

var fn string(value: String)

Not documented.

fn bytes

var fn bytes(value: List<UInt8>)

Not documented.

fn sequence

var fn sequence(length: Int?)

Not documented.

fn map

var fn map(length: Int?)

Not documented.

fn record

var fn record(typeName: String)

Not documented.

fn variant

var fn variant(typeName: String, name: String)

Not documented.

fn field

var fn field(name: String)

Not documented.

fn finish

var fn finish()

Not documented.

type ValueDecoder

type ValueDecoder with Decoder

A Decoder over an EncodedValue. A format whose input has to be buffered anyway - a text format with unordered fields, a tabular row, a command line - parses into an EncodedValue and hands it to this decoder.

lenient is what a format without numbers needs: XML, CSV and a command line have only text, so int() and float() parse what they are given. naming is how the format spelled the field names, and strict reports a field of the input that no type asked for. All three are options of the format, decided once, and never a question a type asks.

A record's fields are also a map with text keys, and a text key is read as a number or a truth value where the key type asks for one: JSON writes every key of an object as a text.

Examples

var source = ValueDecoder.of EncodedValue.Sequence([EncodedValue.Int(1), EncodedValue.Int(2)])
print List<Int>.decode(source)

fn of

static fn of(value: EncodedValue, lenient: Bool = false, naming: Naming = Naming.Unchanged, strict: Bool = false, privateFields: Bool = false): ValueDecoder

A decoder that reads value, with the options of the format that parsed it. privateFields reads back what EncodedValue.of(value, privateFields: true) wrote: the whole value.

fn readsPrivateFields

fn readsPrivateFields(): Bool

Not documented.

fn nothing

var fn nothing(): Bool

Not documented.

fn bool

var fn bool(): Result<Bool, DecodeError>

Not documented.

fn int

var fn int(): Result<Int64, DecodeError>

Not documented.

fn unsigned

var fn unsigned(): Result<UInt64, DecodeError>

Not documented.

fn float

var fn float(): Result<Float64, DecodeError>

Not documented.

fn decimal

var fn decimal(): Result<Decimal, DecodeError>

Not documented.

fn string

var fn string(): Result<String, DecodeError>

Not documented.

fn bytes

var fn bytes(): Result<List<UInt8>, DecodeError>

Bytes, or a sequence of numbers that each fit into a byte: the way a text format writes them.

fn sequence

var fn sequence(): Result<Int?, DecodeError>

Not documented.

fn map

var fn map(): Result<Int?, DecodeError>

A mapping, or a record read as a map from its field names: the only map a text format has is an object.

fn hasNext

var fn hasNext(): Result<Bool, DecodeError>

Not documented.

fn record

var fn record(typeName: String): Result<Void, DecodeError>

The name is not compared: a tabular row and a JSON object do not carry one, and the type asked for this one.

A bare value where a record was asked for is a wrapper: it comes back as the one thing the record holds, which is exactly what the writing side put there.

fn variant

var fn variant(typeName: String): Result<String, DecodeError>

Not documented.

fn field

var fn field(name: String): Result<Bool, DecodeError>

Not documented.

fn finish

var fn finish(): Result<Void, DecodeError>

Not documented.