RPL program (AKA secondary) (COL)


Functions

bool isCOL (SatAddr src)
 is the object at src a COL?
bool COLdecode (SatAddr src, char *dst, int *nibbles)
 Extract the code from a COL.
SatAddr COLencode (const char *src, const int nibbles, SatAddr dst)
 construct a CODE object
SatAddr COLencodeV (SatAddr dst,...)
 create a COL containing the specified objects
SatAddr COLencodeN (int n, SatAddr obs[], SatAddr dst)
 create a COL containing the objects specified in an array
SatAddr makeCOL (unsigned nibbles)
 Allocate space for a COL with nibbles data.
int COLnibbles (SatAddr src)
 Return the size in nibbles of the COL at src.
int COLbytes (SatAddr src)
SatAddr COLfirstOb (SatAddr col, SatAddr *iter)
 Get the first object in a COL.
SatAddr COLnextOb (SatAddr *iter)
 Get the next object in a COL.
SatAddr COLfirstEntry (SatAddr col)
 Get the first entry in a COL.
SatAddr COLnextEntry (SatAddr entry)
 Get the next entry in a COL.

Detailed Description

An RPL program is probably called a COL because its source code begins with "::". Except for its prolog, an RPL program is structured identically to a list.

Function Documentation

int COLbytes ( SatAddr  src  ) 

brief Return the number of bytes required to store the data in a COL object

Parameters:
src The Saturn address of a COL object
Returns:
the number of bytes, or -1 if src doesn't point to a COL object

bool COLdecode ( SatAddr  src,
char *  dst,
int *  nibbles 
)

Extract the code from a COL.

Parameters:
src Saturn address of a COL object
dst If non-null, then the contents of the COL object will be copied here (everything after the prolog and before the terminating SEMI. Dst must point to sufficient space to store the code. See COLbytes().
nibbles If non-null then the number of nibbles copied will be stored here.
See also:
COLbytes()
Returns:
true on success, 0 if src isn't a COL or an error occurs.

SatAddr COLencode ( const char *  src,
const int  nibbles,
SatAddr  dst 
)

construct a CODE object

Parameters:
src The data to be stored in the CODE object
nibbles The number of nibbles in src to store.
dst If non-null, then this is the Saturn address where the CODE object will be stored. If null, then a new CODE object is allocated in tempOb.
Returns:
The Saturn address of the new CODE object, or zero if src is NULL or a new CODE object can't be allocated.

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

create a COL containing the objects specified in an array

Parameters:
n The number of objects to put in the COL.
obs An array of n Saturn Addresses. At each address is an object or a pointer to an object. If an item in the array is an indirect pointer (i.e. the Saturn address of a pointer to an object), then the pointer is put in the COL, not the object. If the parameter is an in ROM (addresses 0-0x40000) then a pointer to the object is added to the COL, not the object itself.
dst The Saturn address where the COL should be stored. If dst is zero (the expected case) then space is allocated for the COL. Otherwise dst must point to sufficient space for the COL. See the warning under makeCOL
Returns:
the Saturn address of the new COL. Returns 0 on error (can't allocate space, a parameter isn't an object or a pointer to an object, etc.
Warning:
Note that a SEMI is automatically appended to the end of the COL, so you don't need to include it in the obs array. Indeed, if you include it, you will confuse the garbage collector and probably crash your calculator.

SatAddr COLencodeV ( SatAddr  dst,
  ... 
)

create a COL containing the specified objects

Parameters:
dst The Saturn address where the COL should be stored. If dst is zero (the expected case) then space is allocated for the COL. Otherwise dst must point to sufficient space for the COL. See the warning under makeCOL
ob1,ob2,... The Saturn addresses of the objects to put in the COL. 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 COL, not the object. If the parameter is in ROM (addresses 0-0x40000) then the pointer to the object is added to the COL, 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 COL. Returns 0 on error (can't allocate space, a parameter isn't an object or a pointer to an object, etc.
Warning:
Note that a SEMI is automatically appended to the end of the COL, so you don't need to include it in the parameter list. Indeed, if you include it, you will confuse the garbage collector and probably crash your calculator.

SatAddr COLfirstEntry ( SatAddr  col  ) 

Get the first entry in a COL.

The difference between COLfirstEntry() and COLfirstOb() is that COLfirstEntry() returns whatever is in the list, whether it's an object or an indirect pointer to an object. COLfirstOb() always returns the address of the object.

This has the same semantics as LISTfirstEntry(), but works on a COL object.

See also:
LISTfirstEntry(), LISTnextEntry(), COLnextEntry()

SatAddr COLfirstOb ( SatAddr  col,
SatAddr iter 
)

Get the first object in a COL.

This has the same semantics as LISTfirstOb(), but works on a COL object

See also:
LISTfirstOb(), LISTnextOb(), COLnextOb()

SatAddr COLnextEntry ( SatAddr  entry  ) 

Get the next entry in a COL.

This has the same semantics as LISTnextEntry(), but works on a COL object.

See also:
LISTfirstEntry, LISTnextEntry(), COLfirstEntry()

SatAddr COLnextOb ( SatAddr iter  ) 

Get the next object in a COL.

This has the same semantics as LISTnextOb(), but works on a COL object

See also:
LISTfirstOb(), LISTnextOb(), COLfirstOb()

int COLnibbles ( SatAddr  src  ) 

Return the size in nibbles of the COL at src.

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

bool isCOL ( SatAddr  src  ) 

is the object at src a COL?

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

SatAddr makeCOL ( unsigned  nibbles  ) 

Allocate space for a COL with nibbles data.

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

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


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