NAME
    assoc - create a new association array

SYNOPSIS
    assoc()

TYPES
    return	association

DESCRIPTION
    This functions returns an empty association array.

    Associations are special values that act like matrices, except
    that they are more general (and slower) than normal matrices.
    Unlike matrices, associations can be indexed by arbitrary values.
    For example, if 'val' was an association, you could do the following:

	    val['hello'] = 11;
	    val[4.5] = val['hello'];
	    print val[9/2];

    and 11 would be printed.

    Associations are created by the 'assoc' function.  It takes no
    arguments, and simply returns an empty association.  You can then
    insert elements into the association by indexing the returned value
    as shown above.

    Associations are multi-dimensional.  You can index them using one to
    four dimensions as desired, and the elements with different numbers
    of dimensions will remain separated.  For example, 'val[3]' and
    'val[3,0]' can both be used in the same association and will be
    distinct elements.

    When references are made to undefined elements of an association,
    a null value is simply returned.  Therefore no bounds errors can
    occur when indexing an association.  Assignments of a null value
    to an element of an association does not delete the element, but
    a later reference to that element will return the null value as if
    the element was undefined.  Elements with null values are implicitly
    created on certain other operations which require an address to be
    taken, such as the += operator and using & in a function call.

    The elements of an association are stored in a hash table for
    quick access.  The index values are hashed to select the correct
    hash chain for a small sequential search for the element.  The hash
    table will be resized as necessary as the number of entries in
    the association becomes larger.

    The size function returns the number of elements in an association.
    This size will include elements with null values.

    Double bracket indexing can be used for associations to walk through
    the elements of the association.  The order that the elements are
    returned in as the index increases is essentially random.  Any
    change made to the association can reorder the elements, this making
    a sequential scan through the elements difficult.

    The search and rsearch functions can search for an element in an
    association which has the specified value.  They return the index
    of the found element, or a NULL value if the value was not found.

    Associations can be copied by an assignment, and can be compared
    for equality.  But no other operations on associations have meaning,
    and are illegal.

EXAMPLE
    > print assoc()

      assoc (0 elements):

LIMITS
    none

LIBRARY
    none

SEE ALSO
    isassoc, rsearch, search, size