# 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.