Site Tools


setitem

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

setitem [2006/08/29 16:08] (current)
Line 1: Line 1:
 +# $EPIC: setitem.txt,​v 1.2 2006/08/20 17:01:26 sthalik Exp $
 +======Synopsis:​======
 +$__setitem__(<​array>​ <​item#>​ <​data>​)
 +
 +======Technical:​======
 +This function creates a new cell in the specified array. ​ If the array
 +does not exist, the client will try to create it.
 +
 +======Practical:​======
 +This function is the single doorway into EPIC's arrays. ​ It must be used
 +to create or add to an array. ​ The array name may be anything,
 +consisting of any characters (even spaces, if escaped) and being of any
 +length. ​ In general, though, it is usually advisable to limit array
 +names to printable characters.
 +
 +The item number is the cell in which to place the new data.  It must be
 +no higher than the number of the next available cell (see $[[numitems]]()
 +for a trick to get this). ​ If the cell exists, it is overwritten. ​ If
 +the array is to be created, the item number must be 0 (zero). ​ Thus,
 +all array items are numbered from 0.
 +
 +The data may be anything at all.  The client will preserve the case of
 +any data entered.
 +
 +======Returns:​======
 +<​file>​
 +-2    could not find item number, or item number too large
 +-1    could not find array, or item number not 0 for new array
 + ​0 ​   existing item was overwritten
 + ​1 ​   new array created
 + ​2 ​   new item number added to existing array
 +</​file>​
 +
 +======Examples:​======
 +$setitem(foo 1 blah)           ​returns -1, no such array
 +$setitem(foo 0 blah blah)      returns 1, new array created
 +$setitem(foo 1 fubar booya) ​   returns 2, new item added
 +$setitem(foo 5 booya) ​         returns -2, item number too large
 +$setitem(foo 0 ha ha)          returns 0, item overwritten
  
setitem.txt ยท Last modified: 2006/08/29 16:08 (external edit)