Release calc version 2.10.2t30

help/assoc

@@ -0,0 +1,79 @@
+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