NAME
    assoc - create a new association array

SYNOPSIS
    assoc()

TYPES
    return	association

DESCRIPTION
    This function returns an empty association array.

    After A = assoc(), elements can be added to the association by
    assignments of the forms

	A[a_1] = v_1
	A[a_1, a_2] = v_2
	A[a_1, a_2, a_3] = v_3
	A[a_1, a_2, a_3, a_4] = v_4

    There are no restrictions on the values of the "indices" a_i or
    the "values" v_i.

    After the above assignments, so long as no new values have been
    assigned to A[a_i], etc., the expressions A[a_1], A[a_1, a_2], etc.
    will return the values v_1, v_2, ...

    Until A[a_1], A[a_1, a_2], ... are defined as described above, these
    expressions return the null value.

    Thus associations act like matrices except that different elements
    may have different numbers (between 1 and 4 inclusive) of indices,
    and these indices need not be integers in specified ranges.

    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 is undefined.

    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
    > A = assoc(); print A
     assoc (0 elements):

    > A["zero"] = 0; A["one"] = 1; A["two"] = 2; A["three"] = 3;
    > A["smallest", "prime"] = 2;
    > print A
    assoc (5 elements);
    ["two"] = 2
    ["three"] = 3
    ["one"] = 1
    ["zero"] = 0
    ["smallest","prime"] = 2

LIMITS
    none

LIBRARY
    none

SEE ALSO
    isassoc, rsearch, search, size