home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / MorphOS / Epic4_mos / share / epic / help / 6_functions / setitem < prev    next >
Encoding:
Text File  |  2002-10-28  |  1.6 KB  |  41 lines
  1. Synopsis:
  2.    $setitem(<array> <item#> <data>)
  3.  
  4. Technical:
  5.    This function creates a new cell in the specified array.  If the array
  6.    does not exist, the client will try to create it.
  7.  
  8. Practical:
  9.    This function is the single doorway into EPIC's arrays.  It must be used
  10.    to create or add to an array.  The array name may be anything,
  11.    consisting of any characters (even spaces, if escaped) and being of any
  12.    length.  In general, though, it is usually advisable to limit array
  13.    names to printable characters.
  14.  
  15.    The item number is the cell in which to place the new data.  It must be
  16.    no higher than the number of the next available cell (see $numitems()
  17.    for a trick to get this).  If the cell exists, it is overwritten.  If
  18.    the array is to be created, the item number must be 0 (zero).  Thus,
  19.    all array items are numbered from 0.
  20.  
  21.    The data may be anything at all.  The client will preserve the case of
  22.    any data entered.
  23.  
  24. Returns:
  25.    -2    could not find item number, or item number too large
  26.    -1    could not find array, or item number not 0 for new array
  27.     0    existing item was overwritten
  28.     1    new array created
  29.     2    new item number added to existing array
  30.  
  31. Examples:
  32.    $setitem(foo 1 blah)           returns -1, no such array
  33.    $setitem(foo 0 blah blah)      returns 1, new array created
  34.    $setitem(foo 1 fubar booya)    returns 2, new item added
  35.    $setitem(foo 5 booya)          returns -2, item number too large
  36.    $setitem(foo 0 ha ha)          returns 0, item overwritten
  37.  
  38. See Also:
  39.    Arrays(7); delitem(6); getitem(6); numitems(6)
  40.  
  41.