# 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. We retain in this notation 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.

append
Object
Object

The `append` 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.

link
Object
Object

The `link` method is similar to the `append` except that a new cons cell is not created if the car is nil. Instead the car is set with the calling object. 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.

append
Object
Object

The `append` 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.

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 `first` method returns the last element in the vector.

back-track
Object
none

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

pop
Object
none

The `pop` method removes the first 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.

append
Object
Object|Object Integer

The `append` 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 `append` 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.

get
Boolean
Integer

The `get` method returns the bit value by the index argument.

set
none
Integer Boolean

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

mark
none
Integer

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

clear
none
Integer

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

length
Integer
none

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

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

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.

write
none
Output

The `write` method writes the buffer contents to the output stream argument.

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.

pushback
none
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.

get-word
Integer
none

The `get-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 to the host format before becoming an integer.

get-quad
Integer
none

The `get-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 to the host format before becoming an integer.

get-octa
Integer
none

The `get-quad` 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 to the host format 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.

Property

The `Property` builtin object is container for a name/value pair. Generally, the property object is used within a property list.

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, which is a literal converted to its string representation.

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

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, which is a literal converted to its string representation. 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, which is a literal converted to its string representation. 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.