All of the types ILIST, DLIST, POINT, and PLIST have implementations
of the following methods.

int TYPE_allocate(TYPE **object),
int TYPE_initialize(TYPE *object),
int TYPE_finalize(TYPE *object),
int TYPE_deallocate(TYPE *object),
int TYPE_copy(TYPE *from, TYPE *to),
TYPE *TYPE_clone(TYPE *from).

For statically allocated objects, ie those you get from a declaration
like

    TYPE object;

the compiler takes care of allocating space for the objects elements
but does not initialize them.  Before the object can be used, it must
be initialized with

    TYPE_initialize(&object);

All routines which are passed pointers to these objects expect them to
be initialized.  You can re-initialize an object by finalizing and
then initializing again:

    TYPE_finalize(&object);
    TYPE_intialize(&object);


For dynamically allocated objects, they must be allocated and then
initialized before they can be used.  This can (so far) be done two
ways.  First like so:

    TYPE *object;

    TYPE_allocate(&object);
    TYPE_initialize(object);

TYPE_allocate() does as much as the compiler automatically does for
statically allocated objects and no more.  You must still call
TYPE_initialize().  Another possibility is to clone an already
existing (allocated and initialized) object:

    TYPE *object;

    object = TYPE_clone(&another_object);

You can reuse a dynamically allocated object without reallocation as
with statically allocated objects:

    TYPE_finalize(object);
    TYPE_intialize(object);

When you want to get rid of the dynamic object, finalize then
deallocate:

    TYPE_finalize(object);
    TYPE_deallocate(object);


The other common function copies the values of one allocated and
initialized object into another already allocated and initialized
object. For example:

    TYPE object1, *object2;

    TYPE_initialize(&object1)
    TYPE_allocate(&object2);
    TYPE_initialize(object2);

    something which places values in object1

    TYPE_copy(&object1, object2);

    now object1 and *object2 have the same values.

All but TYPE_clone() return an error code.  0 if no problems, other
than 0 if something went wrong.


The LIST types also have append and extend routines.

    TYPE_append(TYPE *object, ??? value)

appends value to the list.  For ILIST, it is  int value.
For DLIST it is double value.  For PLIST, it is POINT *value.

TYPE_append() will call TYPE_extend() if necessary to allocate more
memory.  TYPE_extend() should not be called otherwise.