Object creation and manipulation

The Saturn module includes functions to create Saturn objects from most C-style data types. All object creation functions share a common form:

 SAT_OBJECT sat3_createXXX_YYY(SAT_OBJECT where, ... );

Where XXX is a calculator object type (for example a real), and YYY is a C data type to use as a source to create the object (for example a double).

All sat3_create... require as a first argument the parameter 'where' to specify the location where the object will be created. It can be one of the constants , or a pointer to a specific location. When one of the constants is used, a block of memory from the specified region will be allocated (the user will be responsible for freeing the block). A pointer can be used to force the creation of the object at a specific (preallocated) memory location. It is normally used to create objects directly within a container object (a list, for instance), for which memory has been previously allocated.

All sat3_create... functions return a SAT_OBJECT pointing to the newly created object or NULL if object creation failed for any reason.

 // EXAMPLES OF sat3_create... FUNCTIONS

 // CREATE A real FROM A dbl IN TEMPOB, WITH THE VALUE 3.141592
 SAT_OBJECT myreal = sat3_createreal_dbl(ALLOC_TEMPOB,3.141592);

 // CREATE A real FROM A int IN THE HEAP, WITH THE VALUE 2007
 SAT_OBJECT myreal = sat3_createreal_int(ALLOC_HEAP,2007);
 *

The creation of composite objects (list, matrix, and others) for which the size is unknown at creation time requires to specify the maximum size in nibbles. The specified amount of memory will be reserved even if not used. Later, as objects are inserted into (or appended to) the composite object, its actual size will increase up to the maximum size specified at creation. When the maximum size is reached, no more objects can be inserted and such operation will fail. An allocated object cannot be expanded, so if more space is needed a new object needs to be allocated. This operation is not made automatically to ensure all references to the composite and its contents are properly updated (which is left to the user).

IMPORTANT: The calculator does not support working with objects in TEMPOB that don't use the entire memory block allocated for them. This means the user must be very careful when creating lists, matrices and other composite objects in TEMPOB. It is therefore recommended practice to create those objects in the C heap, and only copy them to TEMPOB once the composite is finished. If it is needed to create composites directly in TEMPOB, the C program must execute a garbage collection before returning to the calculator. This can be easily achieved by calling sat3_garbcol which uses a special garbage collection procedure that also shrinks all oversized objects to the proper size. Composite objects allocated in the C heap don't need to call for garbage collection.

There is a complete family of sat3_createXXX_YYY functions for each calculator object and each C data type.

The syntax for calculator object names (XXX) is:

• Bint functions
• ZINT functions
• Real functions
• Complex functions
• Variable name (ID object) functions
• String functions
• Hex string functions
• CHAR functions
• Real array functions
• Complex array functions
• Tagged objects functions
• List functions
• Matrix functions

The syntax for C data types (YYY) is:

• int
• llong (for LONGLONG)
• dbl (for double)
• xreal (for special XREAL type - see XREAL module documentation)
• decn (for special decNumber type - see decNumber library documentation)
• char
• str (for a C text string char[])
• substr (for a substring within a C string)
• bytes (for an arbitrary set of bytes in a buffer)

Object Conversion functions

The complement of the sat3_create... family of functions are the sat3_convert... functions, which can extract information from calculator objects and convert it to C data types. The general syntax is in one of the forms:

 C-type sat3_convertXXX_YYY(SAT_OBJECT object, ...);

 BOOL sat3_convertXXX_YYY(SAT_OBJECT object, C-type *ptr, ...);

In the first case, the function converts calculator type XXX into type YYY, returning the C-type corresponding to YYY. For example:

 double sat3_convertreal_dbl(myreal);

The second form is used when the converted object cannot be returned directly, either because multiple values need to be returned, as in the case of a complex number, or because memory needs to be allocated and a possible error condition needs to be returned. In any case, the function performs the conversion, storing the result in the pointers passed, and returns TRUE. In the event of an error, it returns FALSE, and no value is written to the given pointers.

There is one sat3_convert... routine for every sat3_create... routine.

Next: Function Reference Prev: Object creation and manipulation