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

LINK LIBRARY
    none

SEE ALSO
    isassoc, rsearch, search, size

## Copyright (C) 1999  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc 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.	 See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA.
##
## @(#) $Revision: 29.1 $
## @(#) $Id: assoc,v 29.1 1999/12/14 09:15:42 chongo Exp $
## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/assoc,v $
##
## Under source code control:	1994/09/25 20:22:31
## File existed as early as:	1994
##
## chongo <was here> /\oo/\	http://reality.sgi.com/chongo/
## Share and enjoy!  :-)	http://reality.sgi.com/chongo/tech/comp/calc/