List of objects (LIST)


Functions

bool isLIST (SatAddr src)
 is the object at src a LIST?
SatAddr makeLIST (unsigned nibbles)
 Allocate space for a list with nibbles data.
int LISTnibbles (SatAddr list)
 Return the size in nibbles of the LIST at src.
int LISTsize (SatAddr src)
 Returns the number of elements in a LIST.
bool LISTadd (SatAddr dst, SatAddr obj)
 Make a copy of obj and append it to the list at dst.
SatAddr LISTcat (SatAddr src, SatAddr obj)
 Concatenate an existing list and an object to create a new list.
SatAddr LISTmerge (SatAddr list1, SatAddr list2)
 Merge two lists to create a third. Equivalent to RPL "+" operator aplied to two lists.
SatAddr LISTencode (SatAddr dst,...)
 create a list containing the specified objects
SatAddr LISTencodeN (int n, SatAddr obs[], SatAddr dst)
 create a list from an array of Saturn Addresses. This is like the RPL ->LIST command
SatAddr LISTfirstOb (SatAddr list, SatAddr *iter)
 Get the first object in a list and update the list iterator.
SatAddr LISTnextOb (SatAddr *iter)
 return the next object in a list and update the list iterator.
SatAddr LISTfirstEntry (SatAddr list)
 Get the first entry in a list.
SatAddr LISTnextEntry (SatAddr entry)
 return the next entry in a list or zero if the end has been reached

Function Documentation

bool isLIST ( SatAddr  src  ) 

is the object at src a LIST?

Parameters:
src Saturn address of an object
Returns:
true if the object at src is a LIST

bool LISTadd ( SatAddr  dst,
SatAddr  obj 
)

Make a copy of obj and append it to the list at dst.

Parameters:
dst The LIST to append to
obj The object to append
Returns:
true on success, false if dst isn't a list or obj isn't an object.
Warning:
See the warning on makeLIST()

SatAddr LISTcat ( SatAddr  src,
SatAddr  obj 
)

Concatenate an existing list and an object to create a new list.

LISTcat creates a new list from an existing list src and an object obj. The original list and object remain unchanged. This is equivalent to the RPL "+" opertor applied to a list and an object.

Parameters:
src the existing list
dst the existing object
Returns:
The Saturn address of a new list formed by adding obj to src

SatAddr LISTencode ( SatAddr  dst,
  ... 
)

create a list containing the specified objects

Parameters:
dst The Saturn address where the list should be stored. If dst is zero (the expected case) then space is allocated for the list. Otherwise dst must point to sufficient space for the list. See the warning under makeLIST
ob1,ob2,... The Saturn addresses of the objects to put in the list. If the parameter is an indirect pointer (i.e. the Saturn address of a pointer to an object), then the pointer is put in the list, not the object. If the parameter points to an object in ROM (addresses 0-0x40000) then the pointer to the object is added to the list, not the object itself.
0 The parameter list must end with 0! Otherwise the function won't know when to stop adding objects.
Returns:
the Saturn address of the new list. Returns 0 on error (can't allocate space, a parameter isn't an object or a pointer to an object, etc.

SatAddr LISTencodeN ( int  n,
SatAddr  obs[],
SatAddr  dst 
)

create a list from an array of Saturn Addresses. This is like the RPL ->LIST command

Parameters:
n the number of items to put in the list
obs an array of n Saturn Addresses (SatAddrs). The list will contain these N objects. If an entry in the array is an address between 0 and 0x40000, then it points to ROM and the address is copied to the list instead of the object itself. Otherwise if the array entry is the address of an object then the object is copied to the list, othewise if the array entry is the address of a pointer to an object, then the pointer is copied to the list.
dst The Saturn address where the list should be stored. If dst is zero (the expected case) then space is allocated for the list. Otherwise dst must point to sufficient space for the list. See the warning under makeLIST

SatAddr LISTfirstEntry ( SatAddr  list  ) 

Get the first entry in a list.

Use LISTfirstEntry() and LISTnextEntry() to iterate through the contents of a list. Note that lists can contain objects or pointers to objects (indirect objects). These functions always return the Saturn address of what is actually stored in the list. In other words, the address returned may point to an object or a pointer.

For example:

SatAddr addr, myList;
...
for (addr = LISTfirstEntry(myList); addr; addr = LISTnextEntry(addr)) {
    // do something with addr
}

Parameters:
list the list to iterate through
Returns:
the Saturn address of the first entry in the list, or zero if the list is empty.
See also:
LISTnextEntry(), LISTfirstOb(), LISTnextOb(), directPtr(), isOb()

SatAddr LISTfirstOb ( SatAddr  list,
SatAddr iter 
)

Get the first object in a list and update the list iterator.

Use LISTfirstOb() and LISTnextOb() to iterate through the objects of a list. Note that lists can contain objects or pointers to objects (indirect objects). These functions always return the Saturn address of the object itself.

For example:

SatAddr iter, obj, myList;
...
for (obj = LISTfirstOb(myList, &iter); obj; obj = LISTnextOb(&iter)) {
    // do something with obj
}

Parameters:
list the list to iterate through
iter pointer to a SatAddr variable. The variable will be used to store the state of the iteration.
Returns:
the Saturn address of the first object in the list, or zero if the list is empty.
See also:
LISTnextOb(), LISTfirstEntry(), LISTnextEntry()

SatAddr LISTmerge ( SatAddr  list1,
SatAddr  list2 
)

Merge two lists to create a third. Equivalent to RPL "+" operator aplied to two lists.

Parameters:
list1 the list that will apear first
list2 the list that will appear second
Returns:
a new list that combines list1 and list 2. Returns 0 if list1 or list2 isn't a LIST object, or if space for a new list cannot be allocated. For example if list1 is {1 2 3} and list2 is {4 5 6} then it returns {1 2 3 4 5 6}

SatAddr LISTnextEntry ( SatAddr  entry  ) 

return the next entry in a list or zero if the end has been reached

Parameters:
entry the value returned by a previous call to LISTfirstEntry() or LISTnextEntry()
Returns:
the Saturn address of the next entry in the list, or zero if there are no more entries in the list.
See also:
LISTfirstEntry(), LISTfirstOb(), LISTnextOb(), directPtr(), isOb()

SatAddr LISTnextOb ( SatAddr iter  ) 

return the next object in a list and update the list iterator.

Parameters:
iter pointer to a SatAddr variable that was previously passed to LISTfirstOb() or LISTnextOb().
Returns:
the Saturn address of the next object in the list, or zero if there are no more entries in the list.
See also:
LISTfirstOb(), LISTfirstEntry(), LISTnextEntry()

int LISTnibbles ( SatAddr  list  ) 

Return the size in nibbles of the LIST at src.

Parameters:
src the Saturn address of a LIST object
Returns:
the size of the LIST in nibbles, or zero if src is not a LIST

int LISTsize ( SatAddr  src  ) 

Returns the number of elements in a LIST.

Parameters:
src the Saturn address of a LIST object
Returns:
the number of elements in the LIST, or -1 if src is not a LIST

SatAddr makeLIST ( unsigned  nibbles  ) 

Allocate space for a list with nibbles data.

This allocates space for a list with nibbles data in it and puts an empty list at the beginning of the allocated space.

Parameters:
nibbles the number of nibbles to allocate
Returns:
Saturn address of the empty list
Warning:
Because of the way space is allocated on the calculator, you must fill the list up so its size is exactly the number of nibbles allocated. For this reason, you should use this function only when absolutely necessary. Use LISTencode() or LISTencodeN() to create lists instead.


Generated on Sat Apr 3 16:38:31 2010 for HPObjects by  doxygen 1.5.0