Functions
SAT_OBJECT	sat3_createlist (SAT_OBJECT where, int allocsize)
	Create an empty list object.
SAT_OBJECT	sat3_listhead (SAT_OBJECT list)
	Get the first object (head) on a list.
SAT_OBJECT	sat3_listnext (SAT_OBJECT obj)
	Get the next object on a list.
SAT_OBJECT	sat3_listtail (SAT_OBJECT list)
	Get the tail of a list.
SAT_OBJECT	sat3_listget (SAT_OBJECT list, int position)
	Get a pointer to the specified object within a list.
int	sat3_listcount (SAT_OBJECT list)
	Get the number of elements on a list.
BOOL	sat3_listclose (SAT_OBJECT position)
	Truncate a list.
BOOL	sat3_listinsert (SAT_OBJECT position, SAT_OBJECT object)
	Insert an object into a list.
BOOL	sat3_listremove (SAT_OBJECT position)
	Remove an object from a list.
BOOL	sat3_listappend (SAT_OBJECT list, SAT_OBJECT object)
	Insert an object at the end of a list.

Detailed Description

This group includes all functions used to create/convert/manipulate lists.

Function Documentation

SAT_OBJECT sat3_createlist	(	SAT_OBJECT	where,
		int	allocsize
	)

Create an empty list object.

Creates a new list, initially empty, and allocates the specified amount of memory to let the list grow as new objects are inserted/appended. Lists can be filled in two different ways. One involves inserting/appending existing objects into the list, the other method creates the object directly within a list. Sample code for both methods follows.

Parameters:

where	Defines where to allocate memory from. Can be one of the following constants: ALLOC_HEAP Allocates from the C-heap using malloc() ALLOC_TEMPOB Allocates memory from the TEMPOB calculator area or... it can be an element (SAT_OBJECT) within a composite object, (array, list or any other).
allocsize	Size in nibbles to allocate for the list.

Returns:: SAT_OBJECT with the new list object, or zero if it fails. When a SAT_OBJECT is given to the 'where' parameter, the same SAT_OBJECT is returned or 0 if error.

Note:: IMPORTANT - This function requires a garbage collection before program exit if ALLOC_TEMPOB was used. See fnncreate and sat3_garbcol for details.

See also:: Object creation and manipulation

// LIST CREATION: DIRECT OBJECT CREATION METHOD
// THIS SAMPLE CODE WILL CREATE A LIST WITH 3 REAL NUMBERS { 1. 2. 3. }

SAT_OBJECT mylist=sat3_createlist(ALLOC_HEAP,1000);  // create the list on the C heap and reserve 1000 nibbles
if(!mylist) exit(0);      // failed to create

// HERE: mylist = { }

SAT_OBJECT position=sat3_listhead(mylist);              // obtain the head of the list

if(!sat3_createreal_int(position,1)) exit(0);          // create the real directly within the list, check for failure

// HERE: mylist = { 1. [no closing bracket, the list is now invalid until creation is finished]

position=sat3_listnext(position);           // advance to the next position (after the number 1.)

if(!sat3_createreal_int(position,2)) exit(0);          // create the real directly within the list, check for failure

// HERE: mylist = { 1. 2. [no closing bracket]

position=sat3_listnext(position);           // advance to the next position (after the number 2.)

if(!sat3_createreal_int(position,3)) exit(0);          // create the real directly within the list, check for failure

// HERE: mylist = { 1. 2. 3. [no closing bracket]

position=sat3_listnext(position);           // advance to the next position (after the number 3.)

if(!sat3_listclose(position)) exit(0);          // close the list, check for failure

// HERE: mylist = { 1. 2. 3. }

// FROM THIS POINT ON, THE LIST IS VALID AGAIN AND ALL sat3_list... FUNCTIONS CAN BE SAFELY USED
// DON'T USE ANY OF THE sat3_list... FUNCTIONS UNTIL THE LIST IS VALID OR RESULTS WILL BE UNPREDICTABLE

// LIST CREATION: EXISTING OBJECTS CREATION METHOD
// THIS SAMPLE CODE WILL CREATE A LIST WITH 3 REAL NUMBERS { 1. 2. 3. }

SAT_OBJECT mylist=sat3_createlist(ALLOC_HEAP,1000);  // create the list on the C heap and reserve 1000 nibbles
if(!mylist) exit(0);      // failed to create

// HERE: mylist = { }

// FIRST, CREATE THE NUMBERS

SAT_OBJECT one=sat3_createreal_int(ALLOC_HEAP,1);
SAT_OBJECT two=sat3_createreal_int(ALLOC_HEAP,2);
SAT_OBJECT three=sat3_createreal_int(ALLOC_HEAP,3);

if(!one || !two || !three) exit(0);             // check for failure

if(!sat3_listappend(mylist,one)) exit(0);          // append the number, check for failure

// HERE: mylist = { 1. } [the list is still valid]

if(!sat3_listappend(mylist,two)) exit(0);          // append the number, check for failure

// HERE: mylist = { 1. 2. } [the list is still valid]

if(!sat3_listappend(mylist,three)) exit(0);          // append the number, check for failure

// HERE: mylist = { 1. 2. 3. } [the list is still valid]

// USING THIS PROCEDURE, THE LIST IS VALID AT ALL TIMES. THE FUNCTIONS sat3_listremove, sat3_listinsert
// CAN ALSO BE USED DURING THIS PROCESS, AS WELL AS ALL OTHERR sat3_list... FUNCTIONS

// NOW RELEASE THE TEMPORARY MEMORY ALLOCATED FOR THE NUMBERS

sat3_free(one);
sat3_free(two);
sat3_free(three);

BOOL sat3_listappend	(	SAT_OBJECT	list,
		SAT_OBJECT	object
	)

Insert an object at the end of a list.

Inserts a copy of the given object at the end of the list.

Parameters:

list	A list object.
object	Any arbitrary object to apendd to the list.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_listclose sat3_listremove sat3_listappend

BOOL sat3_listclose ( SAT_OBJECT position )

Truncate a list.

Inserts a closing bracket at the given position. The position is given as a SAT_OBJECT pointer obtained using sat3_listhead, sat3_listtail, sat3_listnext, sat3_listget. Truncating at the tail has no effect, while truncating at the head turns the list into an empty list.

Parameters:

position A SAT_OBJECT pointer within a list object. (MUST be within a list, otherwise results are unpredictable)

Returns:: Returns true if successful, false otherwise.

Note:: IMPORTANT - Truncating a list that resides in TEMPOB can cause the calculator to crash, unless a garbage collection is performed before program exit. Working on the C heap does not require garbage collection. See fnncreate and sat3_garbcol for details.

See also:: sat3_listinsert sat3_listremove sat3_listappend

int sat3_listcount ( SAT_OBJECT list )

Get the number of elements on a list.

Obtain the number of objects in the given list.

Parameters:

list	A list object.

Returns:: Integer with the number of elements on the list, zero if the list is empty and -1 if not a list.

See also:: sat3_listget

SAT_OBJECT sat3_listget	(	SAT_OBJECT	list,
		int	position
	)

Get a pointer to the specified object within a list.

Obtain a specific object from a list. The position is an ordinal, where the first object is zero, one is the second object and so on. The tail (closing bracket) is a valid position. For example:

// ASSUME mylist IS A VALID LIST CONTAINING { 1 2 3 }

SAT_OBJECT one=sat3_listget(mylist,0); // returns a pointer to the first object { [one->] 1 2 3 }
SAT_OBJECT two=sat3_listget(mylist,1); // returns a pointer to the second object { 1 [two->] 2 3 }
SAT_OBJECT three=sat3_listget(mylist,2); // returns a pointer to the third object { 1 2 [three->] 3 }
SAT_OBJECT tail=sat3_listget(mylist,3); // returns a pointer to the fourth object (the tail in this case) { 1 2 3 [tail->] }

// TO SCAN A LIST FROM START TO END, IT'S FASTER TO USE sat3_listnext (RECOMMENDED)
// THE CORRECT CODE TO SCAN A LIST USING sat3_listget IS:

int total=sat3_listcount(mylist);  // return 3 elements on the list
int i;
SAT_OBJECT myelement;

for(i=0;i<total;++i) {             // count from 0 to (total-1) since total would be the closing bracket position
myelement=sat3_listget(mylist,i);  // get all elements sequentially
// DO SOMETHING WITH THE ELEMENTS
}

Parameters:

list	A list object.

Returns:: SAT_OBJECT with the requested object on the list, or zero if not a list or invalid position indexx.

See also:: sat3_head sat3_listnext sat3_listtail sat3_listcount

SAT_OBJECT sat3_listhead ( SAT_OBJECT list )

Get the first object (head) on a list.

Obtain the first object on a list. If the list is empty, the returned SAT_OBJECT pointer will be pointing to the closing bracket, and will be equal to the pointer returned by the sat3_tail function.

Parameters:

list	A list object.

Returns:: SAT_OBJECT with the first object on the list, or zero if not a list.

See also:: sat3_listnext sat3_listtail

BOOL sat3_listinsert	(	SAT_OBJECT	position,
		SAT_OBJECT	object
	)

Insert an object into a list.

Inserts a copy of the given object at the given position. The position is given as a SAT_OBJECT pointer obtained using sat3_listhead, sat3_listtail, sat3_listnext, sat3_listget. Inserting at the tail causes the same effect as sat3_listappend, while inserting at the head makes the given object the first in the list.

Parameters:

position	A SAT_OBJECT pointer within a list object. (MUST be within a list, otherwise results are unpredictable)
object	Any arbitrary object to insert into the list.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_listclose sat3_listremove sat3_listappend

SAT_OBJECT sat3_listnext ( SAT_OBJECT obj )

Get the next object on a list.

Obtain the object that follows a given object on a list. If the given object is the last object on the list, a pointer to the closing bracket will be returned. If the given object is the closing bracket, then null will be returned.

The correct sequence to scan a list is:

// ASSUME mylist IS A SAT_OBJECT POINTING TO A LIST CONTAINING { 1 2 3 }

SAT_OBJECT position,tail;

tail=sat3_listtail(mylist);             // tail POINTS TO THE CLOSING BRACKET  { 1 2 3 [tail->] }
position=sat3_listhead(mylist); // position POINTS TO THE HEAD { [position->] 1 2 3 }

while(position!=tail) {

// DO SOMETHING WITH THE OBJECTS HERE

position=sat3_listnext(position);  // position WILL POINT TO THE NEXT OBJECT, ON THE FIRST PASS WILL BE { 1 [position->] 2 3 }

}

 *

Parameters:

obj	An object, which must be embedded within a list.

Returns:: SAT_OBJECT with the next object on the list, or zero if at the end of the list.

See also:: sat3_listhead sat3_listtail

BOOL sat3_listremove ( SAT_OBJECT position )

Remove an object from a list.

Remove the object at the given position. The position is given as a SAT_OBJECT pointer obtained using sat3_listhead, sat3_listtail, sat3_listnext, sat3_listget. Removing at the tail will fail.

Parameters:

position A SAT_OBJECT pointer within a list object. (MUST be within a list, otherwise results are unpredictable)

Returns:: Returns true if successful, false otherwise.

See also:: sat3_listclose sat3_listinsert sat3_listappend

SAT_OBJECT sat3_listtail ( SAT_OBJECT list )

Get the tail of a list.

Obtain a SAT_OBJECT pointer to the position of the closing bracket on a list. If the list is empty, the returned SAT_OBJECT pointer will be equal to the pointer returned by the sat3_head function.

Parameters:

list	A list object.

Returns:: SAT_OBJECT with the closing bracket of the list, or zero if not a list.

See also:: sat3_listnext sat3_listhead

List functions

Functions

Detailed Description

Function Documentation