help/assoc

   1 NAME
   2     assoc - create a new association array
   3
   4 SYNOPSIS
   5     assoc()
   6
   7 TYPES
   8     return      association
   9
  10 DESCRIPTION
  11     This function returns an empty association array.
  12
  13     After A = assoc(), elements can be added to the association by
  14     assignments of the forms
  15
  16         A[a_1] = v_1
  17         A[a_1, a_2] = v_2
  18         A[a_1, a_2, a_3] = v_3
  19         A[a_1, a_2, a_3, a_4] = v_4
  20
  21     There are no restrictions on the values of the "indices" a_i or
  22     the "values" v_i.
  23
  24     After the above assignments, so long as no new values have been
  25     assigned to A[a_i], etc., the expressions A[a_1], A[a_1, a_2], etc.
  26     will return the values v_1, v_2, ...
  27
  28     Until A[a_1], A[a_1, a_2], ... are defined as described above, these
  29     expressions return the null value.
  30
  31     Thus associations act like matrices except that different elements
  32     may have different numbers (between 1 and 4 inclusive) of indices,
  33     and these indices need not be integers in specified ranges.
  34
  35     Assignment of a null value to an element of an association does not
  36     delete the element, but a later reference to that element will return
  37     the null value as if the element is undefined.
  38
  39     The elements of an association are stored in a hash table for
  40     quick access.  The index values are hashed to select the correct
  41     hash chain for a small sequential search for the element.  The hash
  42     table will be resized as necessary as the number of entries in
  43     the association becomes larger.
  44
  45     The size function returns the number of elements in an association.
  46     This size will include elements with null values.
  47
  48     Double bracket indexing can be used for associations to walk through
  49     the elements of the association.  The order that the elements are
  50     returned in as the index increases is essentially random.  Any
  51     change made to the association can reorder the elements, this making
  52     a sequential scan through the elements difficult.
  53
  54     The search and rsearch functions can search for an element in an
  55     association which has the specified value.  They return the index
  56     of the found element, or a NULL value if the value was not found.
  57
  58     Associations can be copied by an assignment, and can be compared
  59     for equality.  But no other operations on associations have meaning,
  60     and are illegal.
  61
  62 EXAMPLE
  63     > A = assoc(); print A
  64      assoc (0 elements):
  65
  66     > A["zero"] = 0; A["one"] = 1; A["two"] = 2; A["three"] = 3;
  67     > A["smallest", "prime"] = 2;
  68     > print A
  69     assoc (5 elements);
  70     ["two"] = 2
  71     ["three"] = 3
  72     ["one"] = 1
  73     ["zero"] = 0
  74     ["smallest","prime"] = 2
  75
  76 LIMITS
  77     none
  78
  79 LINK LIBRARY
  80     none
  81
  82 SEE ALSO
  83     isassoc, rsearch, search, size
  84