Buffer

---

final class Buffer

Data in memory.

Buffer is used to temporarily store data in memory before writing to a file, or after reading from a file. It follows the JSON data model, where data is arranged hierachically into objects (dictionaries, mappings) of key-value entries, and arrays (lists, sequences) of elements. The representation is schemaless.

Keys are strings. Values and elements may be strings, reals, integers, Booleans or nulls---or, recursively, other Buffer objects. Special provisions are made for efficient storage of numerical vectors and matrices.

Set and retrieve entries from objects (in the JSON sense) using the set() and get() member functions. Construct and iterate through arrays (in the JSON sense) using the push() and walk() member functions.

Factory Functions

Name	Description
Buffer	Create a Buffer.
Buffer	Create a Buffer.
Buffer	Create a Buffer.
Buffer	Create a Buffer representing an object (in the JSON sense).

Member Functions

Name	Description
isNil	Is the value nil?
isNil	Is the value of an entry nil?
setNil	Set to nil.
setNil	Set the value of an entry to nil.
isEmpty	Is the value empty?
isEmpty	Is the value of an entry empty?
setEmptyObject	Set to an empty object.
setEmptyObject	Set the value of an entry to an empty object.
setEmptyArray	Set to an empty array.
setEmptyArray	Set the value of an entry to an empty array.
split	Split a vector into an array of single elements, or a matrix into an array of vectors.
size	Size.
size	Size of an entry.
get	Get the value.
get	Get the value of an entry.
get	Get the value.
get	Get the value of an entry.
get	Get the value of an entry as a buffer.
set	Set as an object (in the JSON sense).
set	Set the value.
set	Set the value.
set	Set an entry as an object (in the JSON sense).
set	Set the value of an entry.
set	Set the value of an entry.
set	Set the value of an entry.
walk	Obtain an iterator.
walk	Obtain an iterator over an entry.
push	Push a value.
push	Push a value.
push	Push a value.
push	Push a value to an entry.
push	Push a value to an entry.
push	Push a value to an entry .
pushNil	Push a nil value.
pushNil	Push a nil value to an entry.

Factory Function Details

function Buffer() -> Buffer

Create a Buffer.

function Buffer<Type>(root:Type) -> Buffer

Create a Buffer.

• root: Root value.

function Buffer<Type>(t:Integer, root:Type) -> Buffer

Create a Buffer.

• t: Step number.
• root: Root value.

function Buffer(keys:String[_], values:Buffer[_]) -> Buffer

Create a Buffer representing an object (in the JSON sense).

• keys: Keys.
• values: Values.

Member Function Details

get

function get<Type>() -> Type?

Get the value.

• Type: The desired type.

Returns: An optional with a value if the contents of the entry can be coerced to the desired type, otherwise with no value.

function get<Type>(key:String) -> Type?

Get the value of an entry.

• Type: The desired type.

• key: Key of the entry.

Returns: An optional with a value if the contents of the entry can be coerced to the desired type, otherwise with no value.

function get<Type>(o:Type)

Get the value.

• Type: The desired type.

• o: Existing object.

This version is used when reading objects of class type, where instead of constructing a new object then calling its read() function, an existing object is provided, calling its read() function directly.

function get<Type>(key:String, o:Type)

Get the value of an entry.

• Type: The desired type.

• key: Key of the entry.

• o: Existing object.

This version is used when reading objects of class type, where instead of constructing a new object then calling its read() function, an existing object is provided, calling its read() function directly.

function get(key:String) -> Buffer?

Get the value of an entry as a buffer.

• key: Key of the entry.

Return: An optional with a value if the entry exists, otherwise no value.

isEmpty

function isEmpty() -> Boolean

Is the value empty? A value is empty if it is nil, or an empty object, or an empty array.

function isEmpty(key:String) -> Boolean

Is the value of an entry empty? If the given key does not exist, returns true.

isNil

function isNil() -> Boolean

Is the value nil?

function isNil(key:String) -> Boolean

Is the value of an entry nil? If the given key does not exist, returns true.

push

function push<Type>(x:Type)

Push a value.

• x: Value.

If the buffer is empty, the result is an array with the single element x. If the buffer is a non-empty object or scalar, the result is an array with two elements: that value followed by x. If the buffer is a non-empty array then x is appended to the end.

function push<Type>(t:Integer, x:Type)

Push a value.

• t: Step number.
• x: Value.

function push(x:Buffer)

Push a value.

• x: Value.

function push<Type>(key:String, x:Type)

Push a value to an entry.

• key: Key of the entry.
• x: Value.

If the entry does not exists then it is created, its value an array containing the single element x.

function push<Type>(key:String, t:Integer, x:Type)

Push a value to an entry.

• key: Key of the entry.
• t: Step number.
• x: Value.

function push(key:String, x:Buffer)

Push a value to an entry .

• key: Key of the entry.
• x: Value.

pushNil

function pushNil()

Push a nil value.

function pushNil(key:String)

Push a nil value to an entry.

• key: Key of the entry.

set

function set(keys:String[_], values:Buffer[_])

Set as an object (in the JSON sense).

• keys: Keys.
• values: Values.

function set<Type>(x:Type)

Set the value.

• x: Value.

function set<Type>(t:Integer, x:Type)

Set the value.

• t: Step number.
• x: Value.

function set(key:String, keys:String[_], values:Buffer[_])

Set an entry as an object (in the JSON sense).

• key: Key of the entry.
• keys: Keys.
• values: Values.

If the buffer value is not already an object, it is cleared before setting the new entry.

function set<Type>(key:String, x:Type)

Set the value of an entry.

• key: Key of the entry.
• x: Value of the entry.

If the buffer value is not already an object, it is cleared before setting the new entry.

function set<Type>(key:String, t:Integer, x:Type)

Set the value of an entry.

• key: Key of the entry.
• t: Step number.
• x: Value of the entry.

If the buffer value is not already an object, it is cleared before setting the new entry.

function set(key:String, x:Buffer)

Set the value of an entry.

• key: Key of the entry.
• x: Value of the entry.

If the buffer value is not already an object, it is cleared before setting the new entry.

setEmptyArray

function setEmptyArray()

Set to an empty array.

function setEmptyArray(key:String)

Set the value of an entry to an empty array.

setEmptyObject

function setEmptyObject()

Set to an empty object.

function setEmptyObject(key:String)

Set the value of an entry to an empty object.

setNil

function setNil()

Set to nil.

function setNil(key:String)

Set the value of an entry to nil.

size

function size() -> Integer

Size. For a nil buffer the size is zero, for an object or scalar it is one, for an array it is the length. For an array, if it represents a numerical vector, its length is the same as the length of that vector; if it represents a numerical matrix, its length is the same as the number of rows in that matrix.

function size(key:String) -> Integer

Size of an entry.

• key: Key of the entry.

Returns: The size. In the case that the key does not exist, returns 0.

split

function split()

Split a vector into an array of single elements, or a matrix into an array of vectors.

walk

function walk() -> Iterator<Buffer>

Obtain an iterator. For a nil buffer this is an empty iterator, for an object or scalar it is a singleton iterator, for an array it is over the elements. Where the array represents a numerical vector the iterator is similarly over the elements of that vector; where it represents a numerical matrix it is over the rows of that matrix.

function walk(key:String) -> Iterator<Buffer>

Obtain an iterator over an entry.

• key: Key of the entry.

Returns: The iterator. In the case that the key does not exist, returns the empty iterator.