6. Utilities - PropSet, Random, DataTable, Concat, LinkList, StrUtil 

CEETRON SAM provides modules for managing vectors, strings or sets of specialized quantities. The PropSet module maintains a set of named properties which may be one of several primitive types such as integer, float, vector of doubles, character string, etc. The Random module generates random numbers in the interval [0.,1.]; The DataTable module stores, retrieves and interpolates vectors of double precision data as a function of an independent variable. The Concat module provides for data records of arbitrary length to be stored in an efficient concatenated form. It is most useful for storing many small records of data. The LinkList module provides for data records of a specified fixed length to be stored in a linked list. The StrUtil module provides string conversion and length queries for wide character and UTF-8 encoded strings.

6.1. Property Sets - PropSet 

The PropSet module maintains an arbitrarily large set of named properties which may be one of several primitive types such as integer, float, vector of doubles, character string, etc. This module is built upon and is a generalization of the Dictionary collection module.

Begin and end an instance of an object, return object error flag
- vsy_PropSetBegin() - create an instance of a PropSet object
- vsy_PropSetEnd() - destroy an instance of a PropSet object
- vsy_PropSetError() - return PropSet object error flag
- vsy_PropSetCopy() - make a copy of a PropSet object
Set and query properties
- vsy_PropSetDef() - suggest number of properties
- vsy_PropSetInq() - get current storage capacity
- vsy_PropSetCount() - get number of contained properties
- vsy_PropSetInsert() - place property in the property set
- vsy_PropSetLookup() - return property parameters by name
- vsy_PropSetLookupDouble() - return double property by name
- vsy_PropSetLookupFloat() - return float property by name
- vsy_PropSetLookupInteger() - return integer property by name
- vsy_PropSetLookupObject() - return object property by name
- vsy_PropSetLookupString() - return string property by name
- vsy_PropSetRemove() - remove any property with the specified name
- vsy_PropSetClear() - remove all properties from a PropSet
- vsy_PropSetInitIter() - prepare to successively visit each property
- vsy_PropSetNextIter() - return the next property name in the set

Instance a PropSet object using vsy_PropSetBegin(). Once a PropSet is instanced, an approximate number of properties to be stored may defined using vsy_PropSetDef(). As properties are inserted the PropSet module will adjust memory as required. The actual size of the allocated storage may be determined by calling vsy_PropSetInq().

Each new property is placed in the property set by calling vsy_PropSetInserti(), vsy_PropSetInsertfv(), etc. depending upon the property type. The total number of properties contained in the property set may be found with vsy_PropSetCount(). The property with a specified name may be found by calling vsy_PropSetLookupInteger(), vsy_PropSetLookupFloat(), etc. The property parameters such as data type, size, etc. may be returned using vsy_PropSetLookup(). A property may be removed using vsy_PropSetRemove(). The method vsy_PropSetClear() removes all properties from the property set.

Each property in the property set may be processed with an “iterator” construct. The pair of methods vsy_PropSetInitIter() and vsy_PropSetNextIter() are used to visit each property name using a loop. Call the first method before the body of the loop to prepare the PropSet object for the iteration. Within the loop body, call vsy_PropSetNextIter(). It will return the name of a property each time it is called. It will return a NULL pointer when all of the properties have been visited.

6.1.1. Function Descriptions

The currently available PropSet functions are described in detail in this section.

vsy_PropSet *vsy_PropSetBegin(void)

create an instance of a PropSet object

Create an instance of a PropSet object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a PropSet object using

void vsy_PropSetEnd (vsy_PropSet *propset)

Return the current value of a PropSet object error flag using

Vint vsy_PropSetError (vsy_PropSet *propset)

Make a copy of a PropSet object. The private data from the frompropset object is copied to the PropSet object. Any previous private data in propset is lost.

void vsy_PropSetCopy (vsy_PropSet *propset,
                     vsy_PropSet *frompropset)

Returns:: The function returns a pointer to the newly created PropSet object. If the object creation fails, NULL is returned.

void vsy_PropSetEnd(vsy_PropSet *p)

destroy an instance of a PropSet object

See vsy_PropSetBegin()

Vint vsy_PropSetError(vsy_PropSet *p)

return the current value of a PropSet object error flag

See vsy_PropSetBegin()

void vsy_PropSetDef(vsy_PropSet *p, Vint numobj)

define initial size

Suggest a number of properties to be stored in the PropSet. This is used to allocate an initial array of storage which is used to hold the pointer to each stored property. Since the names and properties are stored sparsely within the PropSet module, the actual length of the internal array is larger than this supplied number. This function removes any previously entered properties.

Find the number of properties which may be managed by the currently allocated internal storage of a PropSet using

void vsy_PropSetInq (const vsy_PropSet *propset,
                     Vint *numobj,

Errors: SYS_ERROR_MEMORY is generated if new storage was unable to be allocated.

Parameters:

p – Pointer to PropSet object.
numobj – Estimated number of objects to be held.

void vsy_PropSetInq(const vsy_PropSet *p, Vint *nument)

find the number of properties which may be managed by the currently allocated internal storage

See vsy_PropSetDef()

void vsy_PropSetCount(const vsy_PropSet *p, Vint *num)

get number of contained properties

Get the number of properties which have been inserted and not yet removed.

Parameters:

p – Pointer to PropSet object.
num – [out] Number of properties held the in PropSet object.

void vsy_PropSetInserti(vsy_PropSet *p, const Vchar *name, Vint v)