Toml Value¶

1

import "std/text/toml-value";

TomlValue struct¶

Represents a single TOML value.

Composite values (arrays and tables) own their children as heap pointers, so a TomlValue is always reached via TomlValue* once it has been parsed. Destroying a value recursively destroys everything below it, so a whole tree is released with a single deleteTomlValue call on its root. Accessors like getField hand out borrowed pointers that stay owned by their parent, while addArrayItem and addTableField take ownership of what they are given.

Note that the root cannot simply be held in a heap TomlValue* and left to the compiler: the heap qualifier only emits a raw deallocation when the variable goes out of scope and never runs the destructor of the pointee, so the children below the root would be lost. Unlike JSON, TOML distinguishes integers from floats, so both are stored separately. Date-times are kept in their lexical form (e.g. 1979-05-27T07:32:00Z), which the parser validates and the serializer emits verbatim. Table entries preserve insertion order and TOML has no null value.

Parsing lives in "std/text/toml-parser" and serialization in "std/text/toml-serializer", so programs only pull in what they use.

Constructors¶

ctor¶

1

public p TomlValue.ctor()

Construct an empty TOML table, which is what a TOML document is rooted at

ctor¶

1

public p TomlValue.ctor(TomlValueKind kind)

Construct an empty TOML value of the given kind. Useful for building arrays and tables from scratch.

Parameters

ctor¶

1

public p TomlValue.ctor(TomlValueKind kind, const String& value)

Construct a TOML value that carries text, which is either a string or a date-time in its lexical form.

Parameters

ctor¶

1

public p TomlValue.ctor(bool value)

Construct a TOML boolean value

Parameters

ctor¶

1

public p TomlValue.ctor(long value)

Construct a TOML integer value

Parameters

ctor¶

1

public p TomlValue.ctor(double value)

Construct a TOML float value

Parameters

ctor¶

1

public p TomlValue.ctor(const String& value)

Construct a TOML string value

Parameters

dtor¶

1

public p TomlValue.dtor()

Destruct the TOML value, releasing every array item and table entry it owns. Since the children are destroyed the same way, this tears down the whole subtree below the value.

Methods¶

getKind¶

1

public f<TomlValueKind> TomlValue.getKind()

Retrieve the kind of the TOML value

Returns: TomlValueKind — Kind of the value

isString¶

1

public f<bool> TomlValue.isString()

Check whether the TOML value is a string

Returns: bool — true if the value is a string, false otherwise

isInteger¶

1

public f<bool> TomlValue.isInteger()

Check whether the TOML value is an integer

Returns: bool — true if the value is an integer, false otherwise

isFloat¶

1

public f<bool> TomlValue.isFloat()

Check whether the TOML value is a float

Returns: bool — true if the value is a float, false otherwise

isBool¶

1

public f<bool> TomlValue.isBool()

Check whether the TOML value is a boolean

Returns: bool — true if the value is a boolean, false otherwise

isDateTime¶

1

public f<bool> TomlValue.isDateTime()

Check whether the TOML value is a date-time

Returns: bool — true if the value is a date-time, false otherwise

isArray¶

1

public f<bool> TomlValue.isArray()

Check whether the TOML value is an array

Returns: bool — true if the value is an array, false otherwise

isTable¶

1

public f<bool> TomlValue.isTable()

Check whether the TOML value is a table

Returns: bool — true if the value is a table, false otherwise

getString¶

1

public f<const String&> TomlValue.getString()

Retrieve the string payload. Panics if the value is not a string.

Returns: const String& — String value

getInteger¶

1

public f<long> TomlValue.getInteger()

Retrieve the integer payload. Panics if the value is not an integer.

Returns: long — Integer value

getFloat¶

1

public f<double> TomlValue.getFloat()

Retrieve the float payload. Panics if the value is not a float.

Returns: double — Float value

getBool¶

1

public f<bool> TomlValue.getBool()

Retrieve the boolean payload. Panics if the value is not a boolean.

Returns: bool — Boolean value

getDateTime¶

1

public f<const String&> TomlValue.getDateTime()

Retrieve the date-time payload in its lexical form. Panics if the value is not a date-time.

Returns: const String& — Date-time value

getArraySize¶

1

public f<unsigned long> TomlValue.getArraySize()

Retrieve the number of items in the array. Panics if the value is not an array.

Returns: unsigned long — Number of array items

getArrayItem¶

1

public f<TomlValue*> TomlValue.getArrayItem(unsigned long idx)

Retrieve the array item at the given index. Panics if the value is not an array.

Parameters

Returns: TomlValue* — Pointer to the array item

getArrayItem¶

1

public f<TomlValue*> TomlValue.getArrayItem(unsigned int idx)

Retrieve the array item at the given index. Panics if the value is not an array.

Parameters

Returns: TomlValue* — Pointer to the array item

addArrayItem¶

1

public p TomlValue.addArrayItem(TomlValue* item)

Append an item to the array. Panics if the value is not an array. The array takes ownership of the heap-allocated item.

Parameters

getTableSize¶

1

public f<unsigned long> TomlValue.getTableSize()

Retrieve the number of entries in the table. Panics if the value is not a table.

Returns: unsigned long — Number of table entries

getTableKey¶

1

public f<const String&> TomlValue.getTableKey(unsigned long idx)

Retrieve the key of the table entry at the given index, in insertion order. Panics if the value is not a table.

Parameters

Returns: const String& — Entry key

getTableValue¶

1

public f<TomlValue*> TomlValue.getTableValue(unsigned long idx)

Retrieve the value of the table entry at the given index, in insertion order. Panics if the value is not a table.

Parameters

Returns: TomlValue* — Pointer to the entry value

hasField¶

1

public f<bool> TomlValue.hasField(const String& key)

Check whether the table contains an entry with the given key

Parameters

Returns: bool — true if the entry exists, false otherwise

hasField¶

1

public f<bool> TomlValue.hasField(string key)

Check whether the table contains an entry with the given key

Parameters

Returns: bool — true if the entry exists, false otherwise

getFieldOrNil¶

1

public f<TomlValue*> TomlValue.getFieldOrNil(const String& key)

Retrieve the value of the table entry with the given key, or nil if the value is not a table or the entry does not exist.

Parameters

Returns: TomlValue* — Pointer to the entry value, or nil

getFieldOrNil¶

1

public f<TomlValue*> TomlValue.getFieldOrNil(string key)

Retrieve the value of the table entry with the given key, or nil if the value is not a table or the entry does not exist.

Parameters

Returns: TomlValue* — Pointer to the entry value, or nil

getField¶

1

public f<TomlValue*> TomlValue.getField(const String& key)

Retrieve the value of the table entry with the given key. Panics if the value is not a table or the entry does not exist.

Parameters

Returns: TomlValue* — Pointer to the entry value

getField¶

1

public f<TomlValue*> TomlValue.getField(string key)

Retrieve the value of the table entry with the given key. Panics if the value is not a table or the entry does not exist.

Parameters

Returns: TomlValue* — Pointer to the entry value

addTableField¶

1

public p TomlValue.addTableField(const String& key, TomlValue* value)

Append an entry to the table. Panics if the value is not a table. The table takes ownership of the heap-allocated entry value.

Parameters

Functions¶

deleteTomlValue¶

1

public p deleteTomlValue(TomlValue*& value)

Destroys a heap-allocated TOML value together with everything it owns and sets the given handle to nil, so releasing a whole tree only takes one call on its root.

Note that this is what sDelete would normally be used for. It cannot be used here, because a value tree is destroyed recursively and the compiler does not emit an explicit dtor that is only reached through sDestruct.

Parameters

tomlInfinity¶

1

public f<double> tomlInfinity()

Retrieve positive infinity, which TOML spells inf. Spice has no literal for it, so it is provided here for building and inspecting float values.

Returns: double — Positive infinity

tomlNaN¶

1

public f<double> tomlNaN()

Retrieve a quiet NaN, which TOML spells nan. Spice has no literal for it, so it is provided here for building float values.

Returns: double — Not a number

tomlIsNaN¶

1

public f<bool> tomlIsNaN(double value)

Checks whether the given float is a NaN. The usual value != value trick does not work in Spice, since its float comparisons are ordered ones.

Parameters

Returns: bool — true if the value is a NaN, false otherwise

TomlValueKind enum¶

Tag for the variant stored inside a TomlValue.