<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = chapter-3.xml                                                      = -->
<!-- = afnix reference manual - chapter 3                                 = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter volume="2" number="3">
  <title>Container objects</title>

  <p>
  This chapter is a reference of the <afnix/> reserved container objects
  with their respective builtin methods. Some of these container
  objects are <em>iterable objects</em>.

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

  <!-- =================================================================== -->
  <!-- = cons object                                                     = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Cons</name>

    <p>
    A <code>Cons</code> instance or simply a <em>cons cell</em> 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 <em>car</em> and the next cons cell is called the
    <em>cdr</em>. Historically, <em>car</em> means <em>Current Address
    Register</em> and <em>cdr</em> means <em>Current Data
    Register</em>. We retain in <afnix/> this notation for the sake of
    tradition.
    </p>

    <!-- predicate -->
    <pred>cons-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Serial</name>
      <name>Iterable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Cons</name>
      <args>none</args>
      <p>
      The <code>Cons</code> constructor create a default cons cell with
      the <em>car</em> and <em>cdr</em> set to <code>nil</code>. 
      </p>
    </ctor>

    <ctor>
      <name>Cons</name>
      <args>Objects...</args>
      <p>
      The <code>Cons</code> constructor create a list of cons cells with
      the object arguments. Each argument object is assigned to the
      <em>car</em> of the cons cell while the <em>cdr</em> is used to link
      the cell together.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get-car</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>get-car</code> method returns the car of the calling
      cons cell.
      </p>
    </method>

    <method>
      <name>get-cdr</name>
      <retn>Cons</retn>
      <args>none</args>
      <p>
      The <code>get-cdr</code> method returns the cdr of the calling cons
      cell.
      </p>
    </method>

    <method>
      <name>get-cadr</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>get-cadr</code> method returns the car of the cdr of the
      calling cons cell or nil if the cdr is nil.
      </p>
    </method>

    <method>
      <name>get-caddr</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>get-caddr</code> method returns the car of the cdr of the
      cdr of the calling cons cell or nil if the cdr is nil.
      </p>
    </method>

    <method>
      <name>get-cadddr</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>get-cadddr</code> 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.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the length of the cons
      cell. The minimum length returned is always 1. 
      </p>
    </method>

    <method>
      <name>nil-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>nil-p</code> predicate returns true if the car of the
      calling cons cell is nil, false otherwise. 
      </p>
    </method>
  
    <method>
      <name>block-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>block-p</code> predicate returns true if the cons cell
      is of type block, false otherwise. 
      </p>
    </method>

    <method>
      <name>get-iterator</name>
      <retn>Iterator</retn>
      <args>none</args>
      <p>
      The <code>get-iterator</code> returns a forward iterator for this
      cons cell. No backward methods are supported for this object.
      </p>
    </method>

    <method>
      <name>set-car</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>set-car</code> set the car of the calling cons cell. The
      object argument is returned by the method.
      </p>
    </method>

    <method>
      <name>set-cdr</name>
      <retn>Cons</retn>
      <args>Cons</args>
      <p>
      The <code>set-cdr</code> set the cdr of the calling cons cell. The
      cons cell argument is returned by the method.
      </p>
    </method>

    <method>
      <name>append</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>append</code> 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.
      </p>
    </method>

    <method>
      <name>link</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>link</code> method is similar to the <code>append</code>
      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.
      </p>
    </method>

    <method>
      <name>get</name>
      <retn>Object</retn>
      <args>Integer</args>
      <p>
      The <code>get</code> method returns the car of the cons cell chain
      at a certain position specified by the integer index argument.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = enum object                                                     = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Enum</name>

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

    <!-- predicate -->
    <pred>enum-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Enum</name>
      <args>none</args>
      <p>
      The <code>Enum</code> constructor create an empty enumeration.
      </p>
    </ctor>

    <ctor>
      <name>Enum</name>
      <args>String...</args>
      <p>
      The <code>Enum</code> constructor create an enumeration from a
      list of string arguments.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method resets the enumeration and makes
      it empty.
      </p>
    </method>
    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the number of items in
      the enumeration.
      </p>
    </method>
    <method>
      <name>exists-p</name>
      <retn>Boolean</retn>
      <args>String</args>
      <p>
      The <code>exists-p</code> predicate returns true if the name
      argument exists as an item. The name argument must be a lexical
      name or an exception is thrown.
      </p>
    </method>
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>add</code> method adds a new item to the enumeration by
      name. This method returns nil.
      </p>
    </method>
    <method>
      <name>get</name>
      <retn>String</retn>
      <args>Integer</args>
      <p>
      The <code>get</code> method returns an item string
      representation by index. The integer argument is the item index.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = list object                                                     = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>List</name>

    <p>
    The <code>List</code> builtin object provides the facility of a
    double-link list. The <code>List</code> object is another example of
    <em>iterable object</em>. The <code>List</code> object provides
    support for forward and backward iteration.
    </p>

    <!-- predicate -->
    <pred>list-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Iterable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>List</name>
      <args>none</args>
      <p>
      The <code>List</code> constructor create an empty list.
      </p>
    </ctor>

    <ctor>
      <name>List</name>
      <args>Object...</args>
      <p>
      The <code>List</code> constructor create a list from a list of
      object arguments.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the length of the
      list. The minimum length is 0 for an empty list.
      </p>
    </method>

    <method>
      <name>get-iterator</name>
      <retn>Iterator</retn>
      <args>none</args>
      <p>
      The <code>get-iterator</code> returns a forward/backward iterator
      for this list.
      </p>
    </method>

    <method>
      <name>append</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>append</code> method appends an object at the end of the
      list.	The object argument is returned by this method.
      </p>
    </method>

    <method>
      <name>insert</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>insert</code> method inserts an object at the beginning of
      the list. The object argument is returned by this method.
      </p>
    </method>

    <method>
      <name>get</name>
      <retn>Object</retn>
      <args>Integer</args>
      <p>
      The <code>get</code> method returns the object in the list at a
      certain position specified by the integer index argument. 
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = vector object                                                   = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Vector</name>

    <p>
    The <code>Vector</code> builtin object provides the facility of an index
    array of objects. The <code>Vector</code> object is another example
    of  <em>iterable object</em>. The <code>Vector</code> object
    provides support for forward and backward iteration.
    </p>

    <!-- predicate -->
    <pred>vector-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Serial</name>
      <name>Iterable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Vector</name>
      <args>none</args>
      <p>
      The <code>Vector</code> constructor create an empty vector.
      </p>
    </ctor>

    <ctor>
      <name>Vector</name>
      <args>Object...</args>
      <p>
      The <code>Vector</code> constructor create a vector from a list of
      object arguments.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the vector. When the method is
      complete, the vector is empty.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the length of the vector. The
      minimum length is 0 for an empty vector.
      </p>
    </method>

    <method>
      <name>empty-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>empty-p</code> predicate returns true if the vector is empty.
      </p>
    </method>

    <method>
      <name>get</name>
      <retn>Object</retn>
      <args>Integer</args>
      <p>
      The <code>get</code> method returns the object in the vector at a
      certain position specified by the integer index argument.
      </p>
    </method>

    <method>
      <name>set</name>
      <retn>Object</retn>
      <args>Integer Object</args>
      <p>
      The <code>set</code> 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.
      </p>
    </method>

    <method>
      <name>first</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>first</code> method returns the first element in the
      vector.
      </p>
    </method>

    <method>
      <name>last</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>first</code> method returns the last element in the
      vector.
      </p>
    </method>

    <method>
      <name>back-track</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>back-track</code> method removes the last element in the
      vector and returns it.
      </p>
    </method>

    <method>
      <name>pop</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>pop</code> method removes the first element in the
      vector and returns it.
      </p>
    </method>

    <method>
      <name>find</name>
      <retn>Integer</retn>
      <args>Object</args>
      <p>
      The <code>find</code> 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.
      </p>
    </method>

    <method>
      <name>append</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>append</code> method appends an object at the end of
      the vector. The object argument is returned by this method.
      </p>
    </method>

    <method>
      <name>exists-p</name>
      <retn>Boolean</retn>
      <args>Object</args>
      <p>
      The <code>exists-p</code> 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.
      </p>
    </method>

    <method>
      <name>remove</name>
      <retn>none</retn>
      <args>Object</args>
      <p>
      The <code>remove</code> method removes an object from the vector.
      </p>
    </method>

    <method>
      <name>get-iterator</name>
      <retn>Iterator</retn>
      <args>none</args>
      <p>
      The <code>get-iterator</code> returns a forward/backward iterator
      for this vector.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = hash table object                                               = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>HashTable</name>

    <p>
    The <code>HashTable</code> 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.
    </p>

    <!-- predicate -->
    <pred>hashtable-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>HashTable</name>
      <args>none</args>
      <p>
      The <code>HashTable</code> constructor create an empty table.
      </p>
    </ctor>

    <ctor>
      <name>HashTable</name>
      <args>Integer</args>
      <p>
      The <code>HashTable</code> constructor create a table with a specific
      size.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>String Object</args>
      <p>
      The <code>add</code> 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.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>length</code> returns the number of objects in the table.
      </p>
    </method>

    <method>
      <name>empty-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>empty-p</code> predicate returns true if the table is empty.
      </p>
    </method>

    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method resets the table so that it becomes empty.
      </p>
    </method>

    <method>
      <name>get</name>
      <retn>Object</retn>
      <args>String</args>
      <p>
      The <code>get</code> method returns the object associated with
      a key. If the key is not found, nil is returned.
      </p>
    </method>


    <method>
      <name>lookup</name>
      <retn>Object</retn>
      <args>String</args>
      <p>
      The <code>lookup</code> method returns the object associated with
      a key. If the key is not found, an exception is raised.
      </p>
    </method>

    <method>
      <name>get-key</name>
      <retn>String</retn>
      <args>Integer</args>
      <p>
      The <code>get-key</code> method returns the key associated with
      an entry in the table by index. If the index is out of range, an
      exception is raised.
      </p>
    </method>

    <method>
      <name>get-object</name>
      <retn>Object</retn>
      <args>Integer</args>
      <p>
      The <code>get-object</code> method returns the object associated with
      an entry in the table by index. If the index is out of range, an
      exception is raised.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = set object                                                      = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Set</name>

    <p>
    The <code>Set</code> builtin object provides the facility of a uniform
    set of objects. The <code>Set</code> object is another example
    of  <em>iterable object</em>. The <code>Set</code> object
    provides support for forward and backward iteration.
    </p>

    <!-- predicate -->
    <pred>set-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Serial</name>
      <name>Iterable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Set</name>
      <args>none</args>
      <p>
      The <code>Set</code> constructor create an empty set.
      </p>
    </ctor>

    <ctor>
      <name>Set</name>
      <args>Object...</args>
      <p>
      The <code>Set</code> constructor create a set from a list of
      object arguments.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the set. When the method is
      complete, the set is empty.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the number of elements in
      the set. The minimum length is 0 for an empty set.
      </p>
    </method>

    <method>
      <name>add</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>append</code> 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.
      </p>
    </method>

    <method>
      <name>get</name>
      <retn>Object</retn>
      <args>Integer</args>
      <p>
      The <code>get</code> method return object by index.
      </p>
    </method>

    <method>
      <name>exists</name>
      <retn>Boolean</retn>
      <args>Object</args>
      <p>
      The <code>exists</code> method returns true if the object
      argument exists in the set.
      </p>
    </method>

    <method>
      <name>merge</name>
      <retn>none</retn>
      <args>Set</args>
      <p>
      The <code>merge</code> method merges the set argument into the
      calling set. If an element already exists in the set, it is not
      added.
      </p>
    </method>

    <method>
      <name>remix</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>remix</code> 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.
      </p>
    </method>

    <method>
      <name>remove</name>
      <retn>Boolean</retn>
      <args>Object</args>
      <p>
      The <code>remove</code> 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.
      </p>
    </method>

    <method>
      <name>get-random-subset</name>
      <retn>Set</retn>
      <args>Integer</args>
      <p>
      The <code>get-random-subset</code> 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.
      </p>
    </method>

    <method>
      <name>get-iterator</name>
      <retn>Iterator</retn>
      <args>none</args>
      <p>
      The <code>get-iterator</code> returns an iterator for
      this set. The iterator supports forward and backward iteration.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = queue object                                                    = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Queue</name>

    <p>
    The <code>Queue</code> 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.
    </p>

    <!-- predicate -->
    <pred>queue-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Queue</name>
      <args>none</args>
      <p>
      The <code>Queue</code> constructor create an empty queue.
      </p>
    </ctor>

    <ctor>
      <name>Queue</name>
      <args>Object...</args>
      <p>
      The <code>Queue</code> constructor create a queue with a list of
      object arguments
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>enqueue</name>
      <retn>Object</retn>
      <args>Object</args>
      <p>
      The <code>enqueue</code> adds an object in the queue and returns the
      queued object.
      </p>
    </method>

    <method>
      <name>dequeue</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>dequeue</code> dequeue an object in the order it was
      queued.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>length</code> returns the number of queued objects.
      </p>
    </method>

    <method>
      <name>empty-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>empty-p</code> method returns true if the queue is empty.
      </p>
    </method>

    <method>
      <name>flush</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>flush</code> method flushes the queue so that it is empty.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = heap object                                                     = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Heap</name>

    <p>
    The <code>Heap</code> 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.   
    </p>

    <!-- predicate -->
    <pred>heap-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Heap</name>
      <args>none</args>
      <p>
      The <code>Heap</code> constructor create an empty heap. By
      default the heap operates in ascending mode.
      </p>
    </ctor>

    <ctor>
      <name>Heap</name>
      <args>Integer</args>
      <p>
      The <code>Heap</code> constructor create a heap with a specific
      size. By default the heap operates in ascending mode.
      </p>
    </ctor>

    <ctor>
      <name>Heap</name>
      <args>Boolean</args>
      <p>
      The <code>Heap</code> 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.
      </p>
    </ctor>

    <ctor>
      <name>Heap</name>
      <args>Integer Boolean</args>
      <p>
      The <code>Heap</code> 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.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>Integer Object</args>
      <p>
      The <code>add</code> 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.
      </p>
    </method>

    <method>
      <name>pop</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>pop</code> pops the first available in the heap. If
      the heap is empty, an exception is raised.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Object</retn>
      <args>none</args>
      <p>
      The <code>length</code> returns the number of objects in the heap.
      </p>
    </method>

    <method>
      <name>empty-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>empty-p</code> method returns true if the heap is empty.
      </p>
    </method>

    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the heap so that it becomes empty.
      </p>
    </method>

    <method>
      <name>get-key</name>
      <retn>Integer</retn>
      <args>Integer</args>
      <p>
      The <code>get-key</code> method returns the key associated with
      an entry in the heap by index. If the index is out of range, an
      exception is raised.
      </p>
    </method>

    <method>
      <name>get-object</name>
      <retn>Object</retn>
      <args>Integer</args>
      <p>
      The <code>get-object</code> method returns the object associated with
      an entry in the heap by index. If the index is out of range, an
      exception is raised.
      </p>
    </method>

    <method>
      <name>get-mode</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>get-mode</code> 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.
      </p>
    </method>

    <method>
      <name>min-key-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>min-key-p</code> predicate returns true if a minimum
      key has been set. The <code>get-min-key</code> method can be
      used to retrieve the minimum key value.
      </p>
    </method>

    <method>
      <name>max-key-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>max-key-p</code> predicate returns true if a maximum
      key has been set. The <code>get-max-key</code> method can be
      used to retrieve the maximum key value.
      </p>
    </method>

    <method>
      <name>reset-min-key</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset-min-key</code> method resets the minimum key
      flag and value.
      </p>
    </method>

    <method>
      <name>reset-max-key</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset-max-key</code> method resets the maximum key
      flag and value.
      </p>
    </method>

    <method>
      <name>set-min-key</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-min-key</code> method sets the minimum key value.
      </p>
    </method>

    <method>
      <name>get-min-key</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-min-key</code> method returns the minimum key value.
      </p>
    </method>

    <method>
      <name>set-max-key</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-max-key</code> method sets the maximum key value.
      </p>
    </method>

    <method>
      <name>get-max-key</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-max-key</code> method returns the maximum key value.
      </p>
    </method>

    <method>
      <name>resize</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>resize</code> method resize the heap with a new
      size. if the size is lower than the number of elements, the
      procedure does nothing.
      </p>
    </method>   
  </object>

  <!-- =================================================================== -->
  <!-- = bitset object                                                   = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>BitSet</name>
    
    <p>
    The <code>BitSet</code> 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.
    </p>

    <!-- predicate -->
    <pred>bitset-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>BitSet</name>
      <args>none</args>
      <p>
      The <code>BitSet</code> constructor create an empty bitset.
      </p>
    </ctor>

    <ctor>
      <name>BitSet</name>
      <args>Integer</args>
      <p>
      The <code>Bitset</code> constructor create a bitset those size is
      given by the integer argument.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>get</name>
      <retn>Boolean</retn>
      <args>Integer</args>
      <p>
      The <code>get</code> method returns the bit value by the index
      argument.
      </p>
    </method>

    <method>
      <name>set</name>
      <retn>none</retn>
      <args>Integer Boolean</args>
      <p>
      The <code>set</code> method set the bit value by the index argument
      with the boolean second argument.
      </p>
    </method>

    <method>
      <name>mark</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>mark</code> method marks a bit by the index argument.
      </p>
    </method>

    <method>
      <name>clear</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>clear</code> method clears a bit by the index argument.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the length of the bitset.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = buffer object                                                   = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Buffer</name>

    <p>
    The <code>Buffer</code> 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. 
    </p>

    <!-- predicate -->
    <pred>buffer-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Buffer</name>
      <args>none</args>
      <p>
      The <code>Buffer</code> constructor create an empty buffer. The
      buffer is configured to operate in resize mode.
      </p>
    </ctor>

    <ctor>
      <name>Buffer</name>
      <args>Literal...</args>
      <p>
      The <code>Buffer</code> 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.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>Byte|Literal|Buffer</args>
      <p>
      The <code>add</code> 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.
      </p>
    </method>

    <method>
      <name>get</name>
      <retn>Byte</retn>
      <args>none</args>
      <p>
      The <code>get</code> method returns the next available byte in
      the buffer but do not remove it.
      </p>
    </method>

    <method>
      <name>read</name>
      <retn>Byte</retn>
      <args>none</args>
      <p>
      The <code>read</code> method returns the next available character
      and remove it from the buffer.
      </p>
    </method>

    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the entire buffer and destroy
      its contents.
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the length of the buffer.
      </p>
    </method>

    <method>
      <name>write</name>
      <retn>none</retn>
      <args>Output</args>
      <p>
      The <code>write</code> method writes the buffer contents to the
      output stream argument.
      </p>
    </method>

    <method>
      <name>full-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>full-p</code> predicate return true if the buffer is
      full. If the buffer is re-sizeable, the method always return false.
      </p>
    </method>

    <method>
      <name>empty-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>empty-p</code> predicate return true if the buffer is
      empty.
      </p>
    </method>

    <method>
      <name>resize-p</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>resize-p</code> predicate return true if the buffer is
      re-sizeable.
      </p>
    </method>
  
    <method>
      <name>to-string</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>to-string</code> method returns a string representation of
      the buffer.
      </p>
    </method>

    <method>
      <name>pushback</name>
      <retn>none</retn>
      <args>Byte|Literal|Buffer</args>
      <p>
      The <code>pushback</code> 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.
      </p>
    </method>

    <method>
      <name>get-word</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-word</code> 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.
      </p>
    </method>

    <method>
      <name>get-quad</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-quad</code> 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.
      </p>
    </method>

    <method>
      <name>get-octa</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-quad</code> 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.
      </p>
    </method>

    <method>
      <name>set-resize</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-resize</code> method set the resize flag for a
      particular buffer. This method can be used at any time.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = property object                                                 = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Property</name>

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

    <!-- predicate -->
    <pred>property-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Serial</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Property</name>
      <args>none</args>
      <p>
      The <code>Property</code> constructor create an empty property.
      </p>
    </ctor>

    <ctor>
      <name>Property</name>
      <args>String</args>
      <p>
      The <code>Property</code> constructor create a property by
      name. The first argument is the property name.
      </p>
    </ctor>

    <ctor>
      <name>Property</name>
      <args>String Literal</args>
      <p>
      The <code>Property</code> 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.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>set</name>
      <retn>none</retn>
      <args>String Literal</args>
      <p>
      The <code>set</code> 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.
      </p>
    </method>

    <method>
      <name>set-name</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-name</code> method sets the property name.
      </p>
    </method>

    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the property name.
      </p>
    </method>

    <method>
      <name>set-value</name>
      <retn>none</retn>
      <args>Literal</args>
      <p>
      The <code>set-value</code> method sets the property value. The
      literal argument is converted to its string representation.
      </p>
    </method>

    <method>
      <name>get-value</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-value</code> method returns the property value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = plist object                                                    = -->
  <!-- =================================================================== -->

  <object type="reserved">
    <name>Plist</name>

    <p>
    The <code>Plist</code> 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.
    </p>

    <!-- predicate -->
    <pred>plist-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Serial</name>
      <name>Iterable</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Plist</name>
      <args>none</args>
      <p>
      The <code>Plist</code> constructor create an empty property list.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>add</name>
      <retn>none</retn>
      <args>Property | String Literal</args>
      <p>
      The <code>add</code> 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.
      </p>
    </method>

    <method>
      <name>set</name>
      <retn>none</retn>
      <args>String Literal</args>
      <p>
      The <code>set</code> 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.
      </p>
    </method>

    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method resets the property lists
      </p>
    </method>

    <method>
      <name>length</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length</code> method returns the number of properties
      in the property list.
      </p>
    </method>

    <method>
      <name>exists-p</name>
      <retn>Boolean</retn>
      <args>String</args>
      <p>
      The <code>exists-p</code> method returns true if a property
      exists. The string argument is the property name.
      </p>
    </method>

    <method>
      <name>find</name>
      <retn>Property</retn>
      <args>String</args>
      <p>
      The <code>find</code> method  finds a property by name. The string
      argument is the property name. If the property does not exists,
      nil is returned.
      </p>
    </method>

    <method>
      <name>lookup</name>
      <retn>Property</retn>
      <args>String</args>
      <p>
      The <code>lookup</code> method finds a property by name. The string
      argument is the property name. If the property does not exists,
      an exception is raised.
      </p>
    </method>

    <method>
      <name>get-value</name>
      <retn>String</retn>
      <args>String</args>
      <p>
      The <code>get-value</code> method returns the property
      value. The string argument is the property name. If the property
      does not exist, an exception is raised.
      </p>
    </method>
  </object>
</chapter>
