# Container objects

This chapter is a reference of the reserved container objects with their respective builtin methods. Some of these container objects are iterable objects.

When an object is iterable, an iterator constructor constructor is provided. The `iterable-p` predicate returns true if the container is an iterable object. The `get-iterator` method can be used to construct an object iterator. For a given iterator, the predicates `end-p` and `valid-p` can be used to check for the end or a valid iterator position. The `next` method move the iterator to its next position. The `prev` method move the iterator -- if possible -- to its previous position. The `get-object` method returns the object at the current iterator position.

Cons

A `Cons` instance or simply a cons cell is a simple element used to build linked list. The cons cell holds an object and a pointer to the next cons cell. The cons cell object is called car and the next cons cell is called the cdr. Historically, car means Current Address Register and cdr means Current Data Register. This notation is still present here for the sake of tradition.

cons-p
Serial
Iterable
Cons
none

The `Cons` constructor create a default cons cell with the car and cdr set to `nil`.

Cons
Objects...

The `Cons` constructor create a list of cons cells with the object arguments. Each argument object is assigned to the car of the cons cell while the cdr is used to link the cell together.

get-car
Object
none

The `get-car` method returns the car of the calling cons cell.

get-cdr
Cons
none

The `get-cdr` method returns the cdr of the calling cons cell.

get-cadr
Object
none

The `get-cadr` method returns the car of the cdr of the calling cons cell or nil if the cdr is nil.

get-caddr
Object
none

The `get-caddr` method returns the car of the cdr of the cdr of the calling cons cell or nil if the cdr is nil.

get-cadddr
Object
none

The `get-cadddr` method returns the car of the cdr of the cdr of the cdr of the calling cons cell or nil if the cdr is nil.

length
Integer
none

The `length` method returns the length of the cons cell. The minimum length returned is always 1.

nil-p
Boolean
none

The `nil-p` predicate returns true if the car of the calling cons cell is nil, false otherwise.

block-p
Boolean
none

The `block-p` predicate returns true if the cons cell is of type block, false otherwise.

get-iterator
Iterator
none

The `get-iterator` returns a forward iterator for this cons cell. No backward methods are supported for this object.

set-car
Object
Object

The `set-car` set the car of the calling cons cell. The object argument is returned by the method.

set-cdr
Cons
Cons

The `set-cdr` set the cdr of the calling cons cell. The cons cell argument is returned by the method.

add
Object
Object

The `add` method appends an object at the end of the cons cell chain by creating a new cons cell and linking it with the last cdr. The object argument is returned by this method.

get
Object
Integer

The `get` method returns the car of the cons cell chain at a certain position specified by the integer index argument.

Enum

The `Enum` builtin object is an enumeration object. The enumeration is constructed with the reserved keyword `enum` and a list of literals or by string name with a constructor.

enum-p
Object
Enum
none

The `Enum` constructor create an empty enumeration.

Enum
String...

The `Enum` constructor create an enumeration from a list of string arguments.

reset
none
none

The `reset` method resets the enumeration and makes it empty.

length
Integer
none

The `length` method returns the number of items in the enumeration.

exists-p
Boolean
String

The `exists-p` predicate returns true if the name argument exists as an item. The name argument must be a lexical name or an exception is thrown.

add
none
String

The `add` method adds a new item to the enumeration by name. This method returns nil.

get
String
Integer

The `get` method returns an item string representation by index. The integer argument is the item index.

List

The `List` builtin object provides the facility of a double-link list. The `List` object is another example of iterable object. The `List` object provides support for forward and backward iteration.

list-p
Iterable
List
none

The `List` constructor create an empty list.

List
Object...

The `List` constructor create a list from a list of object arguments.

length
Integer
none

The `length` method returns the length of the list. The minimum length is 0 for an empty list.

get-iterator
Iterator
none

The `get-iterator` returns a forward/backward iterator for this list.

add
Object
Object

The `add` method appends an object at the end of the list. The object argument is returned by this method.

insert
Object
Object

The `insert` method inserts an object at the beginning of the list. The object argument is returned by this method.

get
Object
Integer

The `get` method returns the object in the list at a certain position specified by the integer index argument.

Strvec

The `Strvec` builtin object provides the facility of an index array of strings. The `Strvec` object is serializable object that stores strings. The strings can be added with an optional preference for a unique string value. The class is similar to the general purpose `Vector` class.

strvec-p
Serial
Strvec
none

The `Strvec` constructor create an empty string vector.

Strvec
Integer|Boolean

The `Strvec` constructor create a string vector with a predefined size or with a uniq flag. In the first form, the preferred vector size is given as an argument. In the second form, the string unicity flag is given as an argument.

Strvec
Integer Boolean

The `Strvec` constructor create a string vector with a predefined size and a uniq flag. The first argument is the preferred vector size. The second argument is the string unicity flag.

reset
none
none

The `reset` method resets the string vector. When the method is complete, the string vector is empty.

length
Integer
none

The `length` method returns the length of the string vector. The minimum length is 0 for an empty vector.

min-length
Integer
none

The `min-length` method returns the minimum string length of the string vector.

max-length
Integer
none

The `max-length` method returns the maximum string length of the string vector.

empty-p
Boolean
none

The `empty-p` predicate returns true if the vector is empty.

active-p
Boolean
none

The `active-p` predicate returns true if the vector is not empty. This predicate is the negation of the `empty-p` predicate.

get
String
Integer

The `get` method returns the string in the vector at a certain position specified by the integer index argument.

set
none
Integer String

The `set` method set a vector position with a string. The first argument is the vector index. The second argument is the string to set.

first
String
none

The `first` method returns the first string in the vector.

last
String
none

The `last` method returns the last string in the vector.

pop
Object
none

The `pop` method removes the first element in the string vector and returns it.

pop-last
String
none

The `pop-last` method removes the last element in the string vector and returns it.

find
Integer
String

The `find` method try to find a string in the vector. If the string is found, the vector index is returned else the -1 value is returned.

lookup
Integer
String

The `lookup` method try to find a string in the vector. If the string is found, the vector index is returned else an exception is raised.

add
none
String

The `add` method adds an object at the end of the vector. If the uniq flag is active, the string argument is not added if it already exists.

exists-p
Boolean
String

The `exists-p` method returns true if the string argument exists in the vector.

remove
none
Integer|String

The `remove` method removes a string from the vector by index or value. In the first form, the vector index is used as the place to remove. In the second form, the string argument is used as a key for removal. This method repacks the vector when the string has been removed.

set-unique
none
Boolean

The `set-unique` method set the string vector unique flag. When the unique flag is set, there is only no string duplicate in the vector.

get-unique
Boolean

The `get-unique` method returns the string vector unique flag value.

concat
String
none | Character

The `concat` method concatenates the string vector elements with a character separator. In the first form, with a separator character, the resulting string is the concatenation of the string vector elements. In the second form, the resulting string is the concatenation of the vector elements with a character separator. If the character separator is `nil` then no separator is placed.

Vector

The `Vector` builtin object provides the facility of an index array of objects. The `Vector` object is another example of iterable object. The `Vector` object provides support for forward and backward iteration.

vector-p
Serial
Iterable
Vector
none

The `Vector` constructor create an empty vector.

Vector
Object...

The `Vector` constructor create a vector from a list of object arguments.

reset
none
none

The `reset` method reset the vector. When the method is complete, the vector is empty.

length
Integer
none

The `length` method returns the length of the vector. The minimum length is 0 for an empty vector.

empty-p
Boolean
none

The `empty-p` predicate returns true if the vector is empty.

get
Object
Integer

The `get` method returns the object in the vector at a certain position specified by the integer index argument.

set
Object
Integer Object

The `set` method set a vector position with an object. The first argument is the vector index. The second argument is the object to set. The method returns the object to set.

first
Object
none

The `first` method returns the first element in the vector.

last
Object
none

The `last` method returns the last element in the vector.

pop
Object
none

The `pop` method removes the first element in the vector and returns it.

pop-last
Object
none

The `pop-last` method removes the last element in the vector and returns it.

find
Integer
Object

The `find` method try to find an object in the vector. If the object is found, the vector index is returned as an Integer object, else nilp is returned.

add
Object
Object|Integer Object

The `add` method appends an object at the end of the vector or at a certain index. In the first form, the object argument is added at the end of the vector. In the second form, the object argument is inserted in the vector at the specified index. In both cases, the object argument is returned by this method.

exists-p
Boolean
Object

The `exists-p` method returns true if the object argument exists in the vector. This method is useful to make sure that only one occurrence of an object is added to a vector.

clean
none
Integer

The `clean` method removes an object from the vector by index and repack the vector.

remove
none
Object

The `remove` method removes an object from the vector and repack the vector. If duplicate exists in the file, only one is removed.

get-iterator
Iterator
none

The `get-iterator` returns a forward/backward iterator for this vector.

HashTable

The `HashTable` builtin object is a container object which maps an object with a name. The hash table is dynamic and get resized automatically when needed. The lookup method throw an exception if the name is not found. The get method returns nilp if the object is not found.

hashtable-p
Object
HashTable
none

The `HashTable` constructor create an empty table.

HashTable
Integer

The `HashTable` constructor create a table with a specific size.

add
none
String Object

The `add` method adds a new object in the table by key. The first argument is the key used to associate the object in the table. The second argument is the object to add.

length
Object
none

The `length` returns the number of objects in the table.

empty-p
Boolean
none

The `empty-p` predicate returns true if the table is empty.

reset
none
none

The `reset` method resets the table so that it becomes empty.

get
Object
String

The `get` method returns the object associated with a key. If the key is not found, nil is returned.

lookup
Object
String

The `lookup` method returns the object associated with a key. If the key is not found, an exception is raised.

get-key
String
Integer

The `get-key` method returns the key associated with an entry in the table by index. If the index is out of range, an exception is raised.

get-object
Object
Integer

The `get-object` method returns the object associated with an entry in the table by index. If the index is out of range, an exception is raised.

Set

The `Set` builtin object provides the facility of a uniform set of objects. The `Set` object is another example of iterable object. The `Set` object provides support for forward and backward iteration.

set-p
Serial
Iterable
Set
none

The `Set` constructor create an empty set.

Set
Object...

The `Set` constructor create a set from a list of object arguments.

reset
none
none

The `reset` method reset the set. When the method is complete, the set is empty.

length
Integer
none

The `length` method returns the number of elements in the set. The minimum length is 0 for an empty set.

add
Object
Object

The `add` method appends an object in the set. If the object already exists in the set, it is not added twice. This is the main difference between a set and a vector. The object argument is returned by this method.

get
Object
Integer

The `get` method return object by index.

exists
Boolean
Object

The `exists` method returns true if the object argument exists in the set.

merge
none
Set

The `merge` method merges the set argument into the calling set. If an element already exists in the set, it is not added.

remix
none
Integer

The `remix` method mixes the set by randomly swapping all the elements. This method is useful when the set has been filled with a certain order by the access must be done randomly.

remove
Boolean
Object

The `remove` method removes the object argument from the set. if the object is removed, the method returns true. If the object is not in the set, the method returns false.

get-random-subset
Set
Integer

The `get-random-subset` method returns a subset those cardinal is at least the size argument with a set of randomly chosen elements. The result set might have a cardinal less than the requested size if the calling set cardinal is less than the requested size.

get-iterator
Iterator
none

The `get-iterator` returns an iterator for this set. The iterator supports forward and backward iteration.

Queue

The `Queue` builtin object is a container used to queue and dequeue objects. The order of entry in the queue defines the order of exit from the queue. The queue is constructed either empty or with a set of objects.

queue-p
Object
Queue
none

The `Queue` constructor create an empty queue.

Queue
Object...

The `Queue` constructor create a queue with a list of object arguments

enqueue
Object
Object

The `enqueue` adds an object in the queue and returns the queued object.

dequeue
Object
none

The `dequeue` dequeue an object in the order it was queued.

length
Object
none

The `length` returns the number of queued objects.

empty-p
Boolean
none

The `empty-p` method returns true if the queue is empty.

flush
none
none

The `flush` method flushes the queue so that it is empty.

Heap

The `Heap` builtin object is an object based heap class that organizes object with respect to a key. The heap is organized as a binary tree those root element is either the object with the highest or the lowest key. A flag controls whether the heap is operating in ascending or descending mode. By default, the heap operates in ascending mode, which means that the root node is the lowest one. The heap is self-resizable. The object insertion is also controlled by a minimum and maximum key. if the key is below the minimum key or above the maximum key, the object is not inserted.

heap-p
Object
Heap
none

The `Heap` constructor create an empty heap. By default the heap operates in ascending mode.

Heap
Integer

The `Heap` constructor create a heap with a specific size. By default the heap operates in ascending mode.

Heap
Boolean

The `Heap` constructor create a heap with a specific mode. If the mode is true, the heap operates in ascending order. If the mode is false, the heap operates in descending order. In ascending order, the first object is the object with the lowest key.

Heap
Integer Boolean

The `Heap` constructor create a heap with a specific size and mode. The first argument is the heap size. The second argument is the heap mode. If the mode is true, the heap operates in ascending order. If the mode is false, the heap operates in descending order. In ascending order, the first object is the object with the lowest key.

add
none
Integer Object

The `add` method adds a new object in the heap by key. The first argument is the key used to set the object position in the heap. The second argument is the object to add.

pop
Object
none

The `pop` pops the first available in the heap. If the heap is empty, an exception is raised.

length
Object
none

The `length` returns the number of objects in the heap.

empty-p
Boolean
none

The `empty-p` method returns true if the heap is empty.

reset
none
none

The `reset` method reset the heap so that it becomes empty.

get-key
Integer
Integer

The `get-key` method returns the key associated with an entry in the heap by index. If the index is out of range, an exception is raised.

get-object
Object
Integer

The `get-object` method returns the object associated with an entry in the heap by index. If the index is out of range, an exception is raised.

get-mode
Boolean
none

The `get-mode` method returns the heap operating mode. If the mode is true, the heap operates in ascending order. If the mode is false, the heap operates in descending order. In ascending order, the first object is the object with the lowest key.

min-key-p
Boolean
none

The `min-key-p` predicate returns true if a minimum key has been set. The `get-min-key` method can be used to retrieve the minimum key value.

max-key-p
Boolean
none

The `max-key-p` predicate returns true if a maximum key has been set. The `get-max-key` method can be used to retrieve the maximum key value.

reset-min-key
none
none

The `reset-min-key` method resets the minimum key flag and value.

reset-max-key
none
none

The `reset-max-key` method resets the maximum key flag and value.

set-min-key
none
Integer

The `set-min-key` method sets the minimum key value.

get-min-key
Integer
none

The `get-min-key` method returns the minimum key value.

set-max-key
none
Integer

The `set-max-key` method sets the maximum key value.

get-max-key
Integer
none

The `get-max-key` method returns the maximum key value.

resize
none
none

The `resize` method resize the heap with a new size. if the size is lower than the number of elements, the procedure does nothing.

Bitset

The `Bitset` builtin object is a container for multi bit storage. The size of the bitset is determined at construction. With the use of an index, a particular bit can be set, cleared and tested.

bitset-p
Object
Bitset
none

The `BitSet` constructor create an empty bitset.

Bitset
Integer

The `Bitset` constructor create a bitset those size is given by the integer argument.

Bitset
String

The `Bitset` constructor create a bitset by parsing the string argument. The string can be either in the normal binary form with or without the `0b` prefix or in hexadecimal form with the `0x` prefix.

Bitset
Buffer Boolean

The `Bitset` constructor create a bitset from a buffer content. Each byte in the buffer is to be placed in the bitset. The boolean argument is the ascending flag. When true the buffer bytes are used in ascending index order, thus making the fist byte in the buffer to be used as the first right byte in the bitset. When false, the buffer bytes are used in descending index order, thus making the last byte in the buffer to be used as the first byte in the bitset.

reset
none
none

The `reset` method reset the bitset and force the initial size to 0.

marked-p
Boolean
Integer

The `marked-p` predicate returns true if the bit is set at the index argument.

clear
none
Integer

The `clear` method clears a bit by the index argument.

mark
none
Integer

The `mark` method marks a bit by the index argument.

mark
none
Integer Boolean

The `mark` method set the bit value by the index argument with the boolean second argument.

add
none
Integer Boolean

The `add` method add a bit in the bitset at the given position. The first argument is the bit position and the second argument is the bit value. The add method is the only method that resize a bitset.

set
none
Integer|String

The `set` method set a bitset with an integer value. In the first form with an integer argument, the bitset is completely reset to a 64 bits bitset and the value set as an unsigned integer. In the second form with a string argument, the bitset is reset and the string argument is parsed as a binary string with or without binary prefix or as a hexadecimal string.

clamp
none
Boolean

The `clamp` method clamp a bitset by boolean value. The bitset size is determined by finding the upper bit index that match the boolean argument.

length
Integer
none

The `length` method returns the length of the bitset in bits.

to-byte
Integer
Byte

The `to-byte` method maps a portion of the bitset to a byte at a specific position. The integer argument is the bit position that is mapped to the byte lsb.

subset
Integer
Bitset

The `subset` method returns a sub bitset by size.

subset
Integer Integer
Bitset

The `subset` method returns a sub bitset by size and position. The first integer argument is the sub bitset size. The second argument is the bitset position where the sub bitset is extracted.

Buffer

The `Buffer` builtin object is a byte buffer that is widely used with i/o operations. The buffer can be constructed with or without literal arguments. The standard methods to add or push-back byte or characters are available. One attractive method is the write method which can write a complete buffer to an output stream specified as an argument. By default, the buffer operates in resize mode. If the buffer is configured to operate in non-resize mode, an exception is raised when trying to add a character when the buffer is full.

buffer-p
Object
Buffer
none

The `Buffer` constructor create an empty buffer. The buffer is configured to operate in resize mode.

Buffer
Literal...

The `Buffer` constructor create a buffer with a list of literal object arguments. Each literal argument is used to produce a byte representation which is added into the buffer.

add
Integer
Byte|Literal|Buffer

The `add` method adds a byte, a literal object or a buffer to the calling buffer. The object argument is automatically converted to a sequence of bytes. For a buffer, the entire content is copied into the buffer. The method returns the number of bytes added into the buffer.

get
Byte
none

The `get` method returns the next available byte in the buffer but do not remove it.

read
Byte
none

The `read` method returns the next available character and remove it from the buffer.

reset
none
none

The `reset` method reset the entire buffer and destroy its contents.

length
Integer
none

The `length` method returns the length of the buffer.

full-p
Boolean
none

The `full-p` predicate return true if the buffer is full. If the buffer is re-sizeable, the method always return false.

empty-p
Boolean
none

The `empty-p` predicate return true if the buffer is empty.

resize-p
Boolean
none

The `resize-p` predicate return true if the buffer is re-sizeable.

to-string
String
none

The `to-string` method returns a string representation of the buffer.

format
String
none

The `format` method returns an octet string representation of the buffer.

pushback
Integer
Byte|Literal|Buffer

The `pushback` method push back a byte, a literal object or a buffer in the calling buffer. The object argument is automatically converted to a sequence of bytes. For a buffer, the entire content is copied into the buffer. The method returns the number of byte pushbacked.

get-host-word
Integer
none

The `get-host-word` method reads a word from the buffer and convert it to an integer. The word is assumed to be in network byte order and is converted into the host byte order before becoming an integer.

get-host-quad
Integer
none

The `get-host-quad` method reads a quad from the buffer and convert it to an integer. The quad is assumed to be in network byte order and is converted into the host byte order before becoming an integer.

get-host-octa
Integer
none

The `get-host-octa` method reads an octa from the buffer and convert it to an integer. The octa is assumed to be in network byte order and is converted into the host byte order before becoming an integer.

set-resize
none
Boolean

The `set-resize` method set the resize flag for a particular buffer. This method can be used at any time.

shl
none
Integer

The `shl` method shift left the buffer by a certain number of characters. The integer argument is the number of characters to shift.

BlockBuffer

The `BlockBuffer` builtin object is a special buffer class designed to hold bytes in a bound or unbound way. In the bound mode, the buffer size is know and the buffer cannot be resized. In the unbound mode, the buffer size is unknown and the buffer can be resized as needed. The block buffer is designed to be loaded by various means, including data, buffer or stream. Additionaly, the block buffer can be used to write into another buffer or a stream by block. By default the read and write block size is the system block size and the default mode is the bound mode, which can be changed by setting the buffer resize flag.

block-buffer-p
Buffer
BlockBuffer
none

The `BlockBuffer` constructor create a non-resizable empty block buffer.

BlockBuffer
Integer

The `BlockBuffer` constructor create a non-resizable block buffer. The integer argument is the block buffer size.

read-count
Integer
none

The `read-count` method returns the number of characters read by the buffer. The read counter is increased during any read operation that might decrease the buffer length.

write-count
Byte
none

The `write-count` method returns the number of characters writen into the buffer.

copy
Integer
String|Buffer|InputStream|OutputStream

The `copy` method copies an object into or from the block buffer. Inthe first form, a string, a buffer or an input stream is isued to fill the buffer. If the buffer is resizable, the whole contents of the objects are copied into the block buffer. If the buffer is not resizable, the copy operation stops when the buffer is full. The copy method consumes characters with a buffer or an input stream object. With an output stream object, the block buffer characters are consumed while beeing written to the output stream. The total number of characters copied is returned by this method. When using a multiple types object that implements both the input and output stream model, the priority is given to the input stream type.

copy-input-stream
Integer
InputStream

The `copy-input-stream` method copies an input stream into the block buffer. This method is similar to the `copy` method except that it operates only with an input stream. Such method is usefull when using object that implements multiple stream types.

copy-output-stream
Integer
OutputStream

The `copy-output-stream` method copies an output stream into the block buffer. This method is similar to the `copy` method except that it operates only with an output stream. Such method is usefull when using object that implements multiple stream types.

Property

The `Property` builtin object is container for a name/value pair. Generally, the property object is used within a property list. An optional information field can be inserted into the property.

property-p
Serial
Property
none

The `Property` constructor create an empty property.

Property
String

The `Property` constructor create a property by name. The first argument is the property name.

Property
String Literal

The `Property` constructor create a property by name and value. The first argument is the property name. The second argument is the property value.

Property
String String Literal

The `Property` constructor create a property by name, info and value. The first argument is the property name. The second argument is the property info. The third argument is the property value.

set
none
String Literal

The `set` method sets the property name and value. The first argument is the property name. The second argument is the property value, which is a literal converted to its string representation.

set-name
none
String

The `set-name` method sets the property name.

get-name
String
none

The `get-name` method returns the property name.

set-info
none
String

The `set-info` method sets the property information.

get-info
String
none

The `get-info` method returns the property information.

set-value
none
Literal

The `set-value` method sets the property value. The literal argument is converted to its string representation.

get-value
String
none

The `get-value` method returns the property string value.

get-boolean-value
Boolean
none

The `get-boolean-value` method returns the property boolean value.

get-integer-value
Integer
none

The `get-integer-value` method returns the property integer value.

get-real-value
Real
none

The `get-real-value` method returns the property real value.

Plist

The `Plist` builtin object is a base container class used to manage property objects in an ordered way. The property list operates by maintaining a vector of property object along with a hash table that permits to find the object quickly.

plist-p
Serial
Iterable
Plist
none

The `Plist` constructor create an empty property list.

add
none
Property | String Literal | String String Literal

The `add` method add a property by object or name and value in the property list. In its first form the object is a property object. In the second form, the first argument is the property name and the second argument is the property value. In the the third form the first argument is the property name, the second argument is the property info and the this argument is the property value. if the property already exists an exception is raised.

set
none
String Literal

The `set` method add or sets the property name and value in the property list. The first argument is the property name. The second argument is the property value. If the property already exists, the property value is changed.

get
Property
Integer

The `get` method returns a property by index.

reset
none
none

The `reset` method resets the property lists

empty-p
Boolean
none

The `emptyp-` predicate returns true if the property list is empty.

length
Integer
none

The `length` method returns the number of properties in the property list.

exists-p
Boolean
String

The `exists-p` method returns true if a property exists. The string argument is the property name.

find
Property
String

The `find` method finds a property by name. The string argument is the property name. If the property does not exists, nil is returned.

lookup
Property
String

The `lookup` method finds a property by name. The string argument is the property name. If the property does not exists, an exception is raised.

get-value
String
String

The `get-value` method returns the property value. The string argument is the property name. If the property does not exist, an exception is raised.