Table of Contents

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

DevTools 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.

Table of Contents

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.

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.

Table of Contents

6.2 Function Descriptions

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

Table of Contents , PropSet

NAME

*vsy_PropSetBegin - create an instance of an PropSet object

C SPECIFICATION

vsy_PropSet *vsy_PropSetBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , PropSet

NAME

vsy_PropSetDef - define initial size

C SPECIFICATION

void vsy_PropSetDef (vsy_PropSet *propset,
                     Vint numobj)

INPUT ARGUMENTS

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

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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,

Table of Contents , PropSet

NAME

vsy_PropSetCount - get number of contained properties

C SPECIFICATION

void vsy_PropSetCount (const vsy_PropSet *propset,
                       Vint *num)

INPUT ARGUMENTS

propset      Pointer to PropSet object.

OUTPUT ARGUMENTS

num          Number of properties held the in PropSet object.

DESCRIPTION

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

Table of Contents , PropSet

NAME

vsy_PropSetInsert - place a property in the property set

C SPECIFICATION

void vsy_PropSetInsertc (vsy_PropSet *propset,
                         const Vchar *name, Vchar *cprop)

void vsy_PropSetInsertd (vsy_PropSet *propset,
                         const Vchar *name, Vdouble dprop)

void vsy_PropSetInsertf (vsy_PropSet *propset,
                         const Vchar *name, Vfloat fprop)

void vsy_PropSetInserti (vsy_PropSet *propset,
                         const Vchar *name, Vint iprop)

void vsy_PropSetInsertp (vsy_PropSet *propset,
                         const Vchar *name, Vobject *pprop)

void vsy_PropSetInsertdv (vsy_PropSet *propset,
                          const Vchar *name, Vint num, Vdouble dprop[])

void vsy_PropSetInsertfv (vsy_PropSet *propset,
                          const Vchar *name, Vint num, Vfloat fprop[])

void vsy_PropSetInsertiv (vsy_PropSet *propset,
                          const Vchar *name, Vint num, Vint iprop[])

void vsy_PropSetInsertpv (vsy_PropSet *propset,
                          const Vchar *name, Vint num, Vobject *pprop[])

INPUT ARGUMENTS

propset      Pointer to PropSet object.
name         String which identifies the property.
num          Number of properties in vector
prop         Value or property or vector of properties

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Place the property prop in the property set, associated with the specified name. This will replace any property which may have previously inserted with the same name. All name comparisons are case sensitive. A copy of the name and property is made internal to the PropSet object.

Table of Contents , PropSet

NAME

vsy_PropSetLookup - return property parameters by name

C SPECIFICATION

void vsy_PropSetLookup (const vsy_PropSet *propset,	
                        const Vchar *name,
                        Vint *type,
                        Vint *num,
                        Vint *size)

INPUT ARGUMENTS

propset      Pointer to PropSet object.
name         Name of the desired property.

OUTPUT ARGUMENTS

type         Data type of property
             =SYS_DOUBLE             type Vdouble
             =SYS_FLOAT              type Vfloat
             =SYS_INTEGER            type Vint
             =SYS_OBJECT             type Vobject*
             =SYS_STRING             type Vchar*
num          Number of data items in property
size         Size of of data items in property

DESCRIPTION

Get property type and size parameters with the specified name. The type, num and size are all returned as zero if no property with that name has been previously inserted into the property set. The size is the result of the application of num multiplied by the sizeof operation on the data type, type. All name comparisons are case sensitive.

Table of Contents , PropSet

NAME

vsy_PropSetLookupDouble - return property parameters by name

C SPECIFICATION

void vsy_PropSetLookupDouble (const vsy_PropSet *propset,
                              const Vchar *name,
                              Vdouble dprop[]),

void vsy_PropSetLookupFloat (const vsy_PropSet *propset,
                             const Vchar *name,
                             Vfloat fprop[]),

void vsy_PropSetLookupInteger (const vsy_PropSet *propset,
                               const Vchar *name,
                               Vint iprop[]),

void vsy_PropSetLookupObject (const vsy_PropSet *propset,
                              const Vchar *name,
                              Vobject *pprop[]),

void vsy_PropSetLookupString (const vsy_PropSet *propset,
                              const Vchar *name,
                              Vchar cprop[]),

INPUT ARGUMENTS

propset      Pointer to PropSet object.
name         Name of the desired property.

OUTPUT ARGUMENTS

prop         Returned properties

DESCRIPTION

Get properties with the specified name. If the property has not been inserted then the returned properties are undefined.

Table of Contents , PropSet

NAME

vsy_PropSetRemove - remove a property from the property set

C SPECIFICATION

void vsy_PropSetRemove (vsy_PropSet *propset,
                        const Vchar *name)

INPUT ARGUMENTS

propset      Pointer to PropSet object.
name         Name of the property to be removed.

OUTPUT ARGUMENTS

None

DESCRIPTION

Remove the property with the specified name.

Remove all the properties from a PropSet object using 

     void vsy_PropSetClear (vsy_PropSet *propset)

Table of Contents , PropSet

NAME

vsy_PropSetNextIter,vsy_PropSetInitIter - process each item in the propset

C SPECIFICATION

void vsy_PropSetInitIter (vsy_PropSet *propset)

void vsy_PropSetNextIter (vsy_PropSet *propset,
                          Vchar **name)

INPUT ARGUMENTS

propset      Pointer to PropSet object.

OUTPUT ARGUMENTS

name         Name of the next property.

DESCRIPTION

Sequential access to each item in the property set may be implemented using these two functions. Initialize the iteration using vsy_PropSetInitIter. Each call of the method vsy_PropSetNextIter will return one property name from the property set. After every property has been visited in this manner, vsy_PropSetNextIter will return name as a NULL pointer until the iteration is restarted using vsy_PropSetInitIter. The properties are visited in an unspecified order.

Table of Contents

6.3 Random Numbers - Random

The Random module is used to generate sequences of floating point random numbers in the interval [0.,1.].

Instance a Random object using vsy_RandomBegin. Once a Random object is instanced, the random number seed may be set with vsy_RandomInit. Setting the random number seed is optional, a suitable one is set internally when the object is instanced. Generate and retrieve random numbers using vsy_RandomNumber. Note that the Random module does not use any operating system random number facilities. Like all other DevTools modules, all Random objects which are instanced are independent and thread-safe.

Table of Contents

6.4 Function Descriptions

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

Table of Contents , Random

NAME

*vsy_RandomBegin - create an instance of an Random object

C SPECIFICATION

vsy_Random *vsy_RandomBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a Random object. Memory is allocated for the object private data and the pointer to the data is returned. The random number seed is initialized to a positive number.

Destroy an instance of a Random object using 

     void vsy_RandomEnd (vsy_Random *random)

Return the current value of a Random object error flag using 

     Vint vsy_RandomError (vsy_Random *random)

Table of Contents , Random

NAME

vsy_RandomInit - set random number seed

C SPECIFICATION

void vsy_RandomInit (vsy_Random *random,
                     Vint seed)

INPUT ARGUMENTS

random       Pointer to Random object.
seed         Random number seed.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the random number seed. The seed should be a large positive integer for the best random number sequence. If the input seed is less than or equal to zero, the seed is set to one. This function may be called any number of times. The seed will initialize the subsequent sequence of random numbers generated by vsy_RandomNumber.

Table of Contents , Random

NAME

vsy_RandomNumber - generate random number

C SPECIFICATION

void vsy_RandomNumber (vsy_Random *random,
                       Vfloat *number)

INPUT ARGUMENTS

random       Pointer to Random object.

OUTPUT ARGUMENTS

number       Random number

DESCRIPTION

Generate and return a random number, random in the interval [0.,1.]. The internal seed is altered by this operation. Use vsy_RandomInit to set the random number seed.

Table of Contents

6.5 Data Tables - DataTable

The DataTable module holds a collection of double precision vectors as a function of an independent double precision variable. The vectors held in DataTable may be interpolated at any input value of the independent variable. The data is assumed to be piecewise linear. The user may specify the algorithm used to extrapolate the vector data for values of the independent variable outside the range of user input. The DataTable object may expand to contain an increasing number of vectors. It also supports "iterator" functions which are used to successively visit each vector stored in the data table.

Instance a DataTable object using vsy_DataTableBegin. Once a DataTable is instanced, an approximate number of double precision vectors to be stored may be defined using vsy_DataTableDef. The user also specifies in this function the length of the vectors which are to be maintained by DataTable. Each vector in the DataTable object is assumed to be the specified length. The function vsy_DataTableDef allocates an internal array for the storage of vector pointers. As vectors are inserted the DataTable module will expand its internal storage as required. The function vsy_DataTableInq returns the number of vectors which may be managed by the presently allocated storage.

Each new vector and the associated value of the independent variable are placed in the data table using vsy_DataTableInsert. The DataTable module does not copy the vector data, it only stores the pointer to the vector and the value of the associated independent variable. Two vectors may not be stored at the same value of the associated independent variable. The total number of vectors contained in the data table may be found by calling vsy_DataTableCount. A vector which is inserted with a specified value of the independent variable may be retrieved using vsy_DataTableLookup. The function vsy_DataTableClear removes all vectors from the data table. Use the function vsy_DataTableEval to interpolate or extrapolate the vector data for a given value of the independent variable. The type of interpolation and extrapolation to be performed is defined using vsy_DataTableSetParami. Use vsy_DataTableEvalGrad to compute the function gradients as well.

Each vector in the data table may be processed with an "iterator" construct. The method vsy_DataTableForEach takes a function as its argument and calls that function repeatedly, each time with a vector from the data table. The pair of methods vsy_DataTableInitIter and vsy_DataTableNextIter are used to visit each independent variable, vector pair using a loop. Call the first method before the body of the loop to prepare the DataTable object for the iteration. Within the loop body, call vsy_DataTableNextIter. It will return a double precision value of the independent variable and a pointer to the vector each time it is called. It will return zero and a NULL pointer when all of the vectors have been processed.

Table of Contents

6.6 Function Descriptions

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

Table of Contents , DataTable

NAME

*vsy_DataTableBegin - create an instance of a DataTable object

C SPECIFICATION

vsy_DataTable *vsy_DataTableBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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

Destroy an instance of a DataTable object using 

     void vsy_DataTableEnd (vsy_DataTable *datatable)

Return the current value of a DataTable object error flag using 

     Vint vsy_DataTableError (vsy_DataTable *datatable)

Table of Contents , DataTable

NAME

vsy_DataTableDef - define number of stored vectors and length

C SPECIFICATION

void vsy_DataTableDef (vsy_DataTable *datatable,
                       Vint numobj,
                       Vint length)

INPUT ARGUMENTS

datatable    Pointer to DataTable object.
numobj       Estimated number of vectors to be held.
length       Number of values in each double precision vector

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_MEMORY is generated if new storage was unable to be allocated. SYS_ERROR_VALUE is generated if an improper length is specified.

DESCRIPTION

Suggest a number of vectors of size length to be stored in the DataTable. This is used to allocate the initial array of storage which is used to hold each vector/value pair. If the number of inserted vectors is eventually greater than this initial estimate, storage space will dynamically expanded to hold the extra vectors. This function removes any previously inserted vectors.

Find the number and length of vectors which may be managed with the presently allocated storage using 

     void vsy_DataTableInq (const vsy_DataTable *datatable,
                            Vint *numobj,
                            Vint *length)

Table of Contents , DataTable

NAME

vsy_DataTableCount - get number of contained vectors

C SPECIFICATION

void vsy_DataTableCount (const vsy_DataTable *datatable,
                         Vint *num)

INPUT ARGUMENTS

datatable    Pointer to DataTable object.

OUTPUT ARGUMENTS

num          Number of vectors held the in DataTable object.

DESCRIPTION

Get the number of vectors which have been inserted.

Table of Contents , DataTable

NAME

vsy_DataTableEval - interpolate vectors at specified value

C SPECIFICATION

void vsy_DataTableEval (vsy_DataTable *datatable,
                        Vdouble value,
                        Vdouble vec[])

INPUT ARGUMENTS

datatable    Pointer to DataTable object.
value        Double precision independent variable

OUTPUT ARGUMENTS

vec          Vector data evaluated at value

ERRORS

SYS_ERROR_OPERATION is generated if no data vectors have been defined.

DESCRIPTION

Get vector of data evaluated at the specified value. The type of interpolation and extrapolation used during the evaluation is defined using vsy_DataTableSetParami.

Table of Contents , DataTable

NAME

vsy_DataTableEvalGrad - interpolate vectors and gradients at specified value

C SPECIFICATION

void vsy_DataTableEvalGrad (vsy_DataTable *datatable,
                            Vdouble value,
                            Vdouble vec[],
                            Vdouble grad[])

INPUT ARGUMENTS

datatable    Pointer to DataTable object.
value        Double precision independent variable

OUTPUT ARGUMENTS

vec          Vector data evaluated at value
grad         Gradient data evaluated at value

ERRORS

SYS_ERROR_OPERATION is generated if no data vectors have been defined.

DESCRIPTION

Get vector of data evaluated at the specified value. The type of interpolation and extrapolation used during the evaluation is defined using vsy_DataTableSetParami.

Table of Contents , DataTable

NAME

vsy_DataTableInsert - insert vector at specified value

C SPECIFICATION

void vsy_DataTableInsert (vsy_DataTable *datatable,
                          Vdouble value,
                          Vdouble *vec)

INPUT ARGUMENTS

datatable    Pointer to DataTable object.
value        Double precision independent variable
vec          Pointer to vector

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_MEMORY is generated if new storage was unable to be allocated. SYS_ERROR_OPERATION is generated if a vector has already been inserted at the specified value.

DESCRIPTION

Insert the vector vec in the DataTable object. Associate value with this new vector. The data is not copied from vec, instead the pointer value of vec is stored.

Table of Contents , DataTable

NAME

vsy_DataTableLookup - find the vector inserted at a specified value

C SPECIFICATION

void vsy_DataTableLookup (const vsy_DataTable *datatable,	
                          Vdouble value,
                          Vdouble **vec)

INPUT ARGUMENTS

datatable    Pointer to DataTable object.
value        Double precision independent variable

OUTPUT ARGUMENTS

vec          Pointer to vector associated with value

DESCRIPTION

Get a pointer to the vector associated the specified value. Returns a NULL pointer if no vector has been entered with this value.

Table of Contents , DataTable

NAME

vsy_DataTableClear - remove all vectors from the DataTable object

C SPECIFICATION

void vsy_DataTableClear (vsy_DataTable *datatable)

INPUT ARGUMENTS

datatable    Pointer to DataTable object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Remove all vectors.

Table of Contents , DataTable

NAME

vsy_DataTableForEach - call a function one time for each vector

C SPECIFICATION

void vsy_DataTableForEach (vsy_DataTable *datatable,
                           void (*func)(Vobject*))

INPUT ARGUMENTS

datatable    Pointer to DataTable object.
func         Pointer to function which is to be applied to each vector.

OUTPUT ARGUMENTS

None

DESCRIPTION

Calls the supplied function repeatedly, each time using a vector from the data table as the sole argument to this function. This is useful for deallocating a collection of vectors, prior to calling vsy_DataTableEnd. The vectors are visited in an unspecified order.

Sequential access to each vector in the data table may also be implemented using 

     void vsy_DataTableInitIter (vsy_DataTable *datatable)

This is followed by repeated calls to the method 

     void vsy_DataTableNextIter (vsy_DataTable *datatable,
                                 Vdouble *value
                                 Vdouble **vec)
Each call of the method vsy_DataTableNextIter will return a new vector from the data table, together with its associated value. These value/vec pairs are visited in ascending order of the values. After every vector has been visited in this manner, vsy_DataTableNextIter will return a value of zero and a NULL pointer until the iteration is restarted using vsy_DataTableInitIter.

Table of Contents , DataTable

NAME

vsy_DataTableSetParami - specify type of interpolation and extrapolation

C SPECIFICATION

void vsy_DataTableSetParami (vsy_DataTable *datatable,
                             Vint ptype,
                             Vint iparam)

INPUT ARGUMENTS

datatable    Pointer to DataTable object.
ptype        Type of parameter to set
             =DATATABLE_EXTRAPOLATE  Extrapolation method
             =DATATABLE_INTERPOLATE  Interpolation method
iparam       Specifies the integer value that ptype will be set to.
             =DATATABLE_LINEAR       Linear interpolation, extrapolation
             =DATATABLE_CLAMP        Clamp to extremes extrapolation
             =DATATABLE_PARABOLIC_SLOPE Parabolic slope extrapolation

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

Set data table evaluation parameters. The DATATABLE_EXTRAPOLATE parameter sets the extrapolation method used when the data is to evaluated at a value outside of the input range. The setting DATATABLE_LINEAR extrapolates linearly using the slope of the first two or last two entries which ever applies. The setting DATATABLE_PARABOLIC_SLOPE extrapolates linearly using the slope of the parabola fit through the first three or last three entries which ever applies. If only one vector is defined the evaluation is always clamped. If two vectors are defined and DATATABLE_PARABOLIC_SLOPE has been specified, then linear extrapolation is performed. The default DATATABLE_EXTRAPOLATE is DATATABLE_LINEAR.

The DATATABLE_INTERPOLATE parameter sets the interpolation method. Currently the only interpolation method implemented is DATATABLE_LINEAR. The default DATATABLE_INTERPOLATE is DATATABLE_LINEAR.

Table of Contents

6.7 Concatenated Storage - Concat

The Concat module stores a series of data records, each of arbitrary length, in an expandable, concatenated storage form. As data records are added to a Concat object, any additional required memory is allocated in relatively large blocks, decreasing the possibility of memory fragmentation due to many small memory allocations. The Concat module supports "iterator" functions which are used to successively visit each data record stored in the concatenated storage.

Instance a Concat object using vsy_ConcatBegin. Once a Concat is instanced, an approximate number of bytes to be stored may be defined using vsy_ConcatDef. The function, vsy_ConcatDef may also be used to reinitialize the Concat object. As records are added the Concat module will expand its internal storage as required. The function vsy_ConcatInq returns the number of bytes which are currently stored. Data records are added to the concatenation by calling vsy_ConcatAdd. The data record is defined by a specified number of bytes and a pointer to the start of the data. The function copies the data and concatenates it to any previously added data records. The last data concatenation pointer may be queried using vsy_ConcatRef. Call this function just after a call to vsy_ConcatAdd to determine the memory pointer at which the prior added data was copied. The total number of records contained in the concatentation may be found by calling vsy_ConcatCount. Note that there are no functions to remove a specific data record.

The pair of methods vsy_ConcatInitIter and vsy_ConcatNextIter are used to visit each data record using a loop. Call the first method before the body of the loop to prepare the Concat object for the iteration. Within the loop body, call vsy_ConcatNextIter. It will return a number of bytes and pointer to the start of the data record each time it is called. It will return zero and a NULL pointer when all of the records have been processed. All data may be deleted using vsy_ConcatClear.

Table of Contents

6.8 Function Descriptions

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

Table of Contents , Concat

NAME

*vsy_ConcatBegin - create an instance of a Concat object

C SPECIFICATION

vsy_Concat *vsy_ConcatBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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

Destroy an instance of a Concat object using 

     void vsy_ConcatEnd (vsy_Concat *concat)

Return the current value of a Concat object error flag using 

     Vint vsy_ConcatError (vsy_Concat *concat)

Table of Contents , Concat

NAME

vsy_ConcatDef - define total number of bytes to be stored

C SPECIFICATION

void vsy_ConcatDef (vsy_Concat *concat,
                    Vlong maxbytes)

INPUT ARGUMENTS

concat       Pointer to Concat object.
maxbytes     Estimated number of bytes to be held.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if an improper maxbytes is specified.

DESCRIPTION

Suggest a number of bytes, maxbytes to be stored in the Concat. If an added data record is eventually greater than this initial estimate, storage space will dynamically expand to hold the data. This function deletes any previously entered data.

Find the number of bytes presently stored using 

     void vsy_ConcatInq (const vsy_Concat *concat,
                         Vlong *maxbytes)

Table of Contents , Concat

NAME

vsy_ConcatClear - delete all data records

C SPECIFICATION

void vsy_ConcatClear (vsy_Concat *concat)

INPUT ARGUMENTS

concat       Pointer to Concat object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Clear all data from the concatenation.

Table of Contents , Concat

NAME

vsy_ConcatCount - get number of added records

C SPECIFICATION

void vsy_ConcatCount (vsy_Concat *concat,
                      Vint *num)

INPUT ARGUMENTS

concat       Pointer to Concat object.

OUTPUT ARGUMENTS

num          Number of added data records

DESCRIPTION

Get the number of data records which have been added.

Table of Contents , Concat

NAME

vsy_ConcatAdd - add a data record of arbitrary length

C SPECIFICATION

void vsy_ConcatAdd (vsy_Concat *concat,
                    Vint nbytes,
                    void *data)

INPUT ARGUMENTS

concat       Pointer to Concat object.
nbytes       Number of bytes in data
data         Pointer to data to copy to concatenation

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if an improper nbytes is specified. SYS_ERROR_MEMORY is generated if new storage was unable to be allocated.

DESCRIPTION

Copy nbytes of data from pointer, data, to concatenated storage. Use vsy_ConcatRef to determine the memory location to which the data was copied in concatenation storage after calling this function.

Table of Contents , Concat

NAME

vsy_ConcatRef - return last addition pointer

C SPECIFICATION

void vsy_ConcatRef (vsy_Concat *concat,	
                    void **data)

INPUT ARGUMENTS

concat       Pointer to Concat object.

OUTPUT ARGUMENTS

data         Pointer to last data addition address in concatention

DESCRIPTION

Return the pointer to the last memory location in concatenated storage to which the previous data record was added.

Table of Contents , Concat

NAME

vsy_ConcatNextIter,vsy_ConcatInitIter - process each record in concatenation

C SPECIFICATION

void vsy_ConcatInitIter (vsy_Concat *concat)

void vsy_ConcatNextIter (vsy_Concat *concat,
                         Vint *nbytes,
                         void **data)

INPUT ARGUMENTS

concat       Pointer to Concat object.

OUTPUT ARGUMENTS

nbytes       Number of bytes in data
data         Pointer to data in concatenation

DESCRIPTION

Sequential access to each data record in the concatenation may be implemented using these two functions. Initialize the iteration using vsy_ConcatInitIter. Each call of the method vsy_ConcatNextIter will return information for one data record in the concatenation. After every data record has been visited in this manner, vsy_ConcatNextIter will return nbytes as zero and data as a NULL pointer until the iteration is restarted using vsy_ConcatInitIter. The data records are visited in the order of addition.

Table of Contents

6.9 Linked List Storage - LinkList

The LinkList module stores a series of data records, each of fixed length, in a linked list structure. As data records are added to a LinkList object, any additional required memory is allocated in relatively large blocks, decreasing the possibility of memory fragmentation due to many small memory allocations. The linked list data organization makes the LinkList module useful for efficient management of fixed length data records which are repeatedly inserted and deleted. The LinkList module supports "iterator" functions which are used to successively visit each data record stored in the linked list.

Instance a LinkList object using vsy_LinkListBegin. Once a LinkList is instanced, specify the approximate number of records to be stored and the fixed length of each record using vsy_LinkListDef. The function, vsy_LinkListDef may also be used to reinitialize the LinkList object. As records are added the LinkList module will expand its internal storage as required. Records are keyed by an integer index. A fixed length of memory is associated with each record. Data records may be added to the linked list by calling vsy_LinkListAdd. In this case the function returns an integer key and a pointer to the memory associated with the integer key. The pointer is guaranteed to be aligned for use with all data types. Use vsy_LinkListRef to return the pointer to the memory associated with a given index. A record may be deleted using vsy_LinkListRemove. The total number of records contained in the linked list may be found by calling vsy_LinkListCount.

The pair of methods vsy_LinkListInitIter and vsy_LinkListNextIter are used to visit each data record using a loop. Call the first method before the body of the loop to prepare the LinkList object for the iteration. Within the loop body, call vsy_LinkListNextIter. It will return an integer index and pointer to the start of the data record each time it is called. It will return zero and a NULL pointer when all of the records have been processed. All data may be deleted using vsy_LinkListClear.

Table of Contents

6.10 Function Descriptions

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

Table of Contents , LinkList

NAME

*vsy_LinkListBegin - create an instance of a LinkList object

C SPECIFICATION

vsy_LinkList *vsy_LinkListBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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

Destroy an instance of a LinkList object using 

     void vsy_LinkListEnd (vsy_LinkList *linklist)

Return the current value of a LinkList object error flag using 

     Vint vsy_LinkListError (vsy_LinkList *linklist)

Table of Contents , LinkList

NAME

vsy_LinkListDef - define length of records

C SPECIFICATION

void vsy_LinkListDef (vsy_LinkList *linklist,
                      Vint len,
                      Vint nbytes)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.
len          Approximate number of records
nbytes       Length of each record in bytes

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if an improper len or nbytes is specified.

DESCRIPTION

Specify a number of records, len, and the length of each record, nbytes, to be stored in the LinkList. The number of records, len, only need be approximate. This function deletes any previously entered data.

Find the number of records currently allocated and the fixed length of each record in bytes using 

     void vsy_LinkListInq (const vsy_LinkList *linklist,
                           Vint *len,
                           Vint *nbytes)

Table of Contents , LinkList

NAME

vsy_LinkListClear - delete all data records

C SPECIFICATION

void vsy_LinkListClear (vsy_LinkList *linklist)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Clear all data from the linked list.

Table of Contents , LinkList

NAME

vsy_LinkListCount - get number of records

C SPECIFICATION

void vsy_LinkListCount (vsy_LinkList *linklist,
                        Vint *num)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.

OUTPUT ARGUMENTS

num          Number of data records

DESCRIPTION

Get the number of data records.

Table of Contents , LinkList

NAME

vsy_LinkListAdd - add a data record to linked list

C SPECIFICATION

void vsy_LinkListAdd (vsy_LinkList *linklist,
                      Vint *index,
                      void **value)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.

OUTPUT ARGUMENTS

index        Index of record
value        Pointer to memory associated with index.

ERRORS

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

DESCRIPTION

Add a record to the linked list. An index is returned as well as a pointer, value, to the memory associated with the index.

Table of Contents , LinkList

NAME

vsy_LinkListRef - return pointer given index

C SPECIFICATION

void vsy_LinkListRef (vsy_LinkList *linklist,	
                      Vint index,
                      void **value)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.
index        Index of record

OUTPUT ARGUMENTS

value        Pointer to memory associated with index.

DESCRIPTION

Return the pointer to memory associated with index. If the index has not been defined, value is set to NULL.

Table of Contents , LinkList

NAME

vsy_LinkListRemove - delete a record given index

C SPECIFICATION

void vsy_LinkListRemove (vsy_LinkList *linklist,	
                         Vint index)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.
index        Index of record

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if an improper index is specified.

DESCRIPTION

Remove the record associated with index from the linked list.

Table of Contents , LinkList

NAME

vsy_LinkListHead - return head record index and pointer

C SPECIFICATION

void vsy_LinkListHead (vsy_LinkList *linklist,
                       Vint *index,
                       void **value)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.

OUTPUT ARGUMENTS

index        Index of record
value        Pointer to memory associated with index.

DESCRIPTION

Access the data record at the head of the linked list.

Table of Contents , LinkList

NAME

vsy_LinkListNextIter,vsy_LinkListInitIter - process each record in linked list

C SPECIFICATION

void vsy_LinkListInitIter (vsy_LinkList *linklist)

void vsy_LinkListNextIter (vsy_LinkList *linklist,
                           Vint *index,
                           void **value)

INPUT ARGUMENTS

linklist     Pointer to LinkList object.

OUTPUT ARGUMENTS

index        Index of record
value        Pointer to memory associated with index.

DESCRIPTION

Access to each data record in the linked list may be implemented using these two functions. Initialize the iteration using vsy_LinkListInitIter. Each call of the method vsy_LinkListNextIter will return information for one data record in the linked list. After every data record has been visited in this manner, vsy_LinkListNextIter will return index as zero and value as a NULL pointer until the iteration is restarted using vsy_LinkListInitIter.

Table of Contents

6.11 String Utilities - StrUtil

The StrUtil module is a static module. Its main purpose is to provide utilities for wide character and UTF-8 encoded string conversion and length queries.

The StrUtil module supports the following functions.

The StrUtil module is designed to provide system independent string utilities for UTF-8 and wide character string conversion and length query. The vut_StrUtilMBCSFromUTF8 will convert UTF-8 to Multi-Byte Character Set (MBCS).

Table of Contents

6.12 Function Descriptions

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

Table of Contents , StrUtil

NAME

vut_StrUtilFromUTF8 - convert UTF-8 string to wide character

C SPECIFICATION

Vint vut_StrUtilFromUTF8 (const char *utf8buf,
                          Vint maxwidechar,
                          wchar_t* widebuf)

INPUT ARGUMENTS

utf8buf     UTF-8 encoded string
maxwidechar Maximum number of wide characters.

OUTPUT ARGUMENTS

widebuf     Wide character encoded string

DESCRIPTION

Convert a UTF-8 encoded string to a wide character string. The input parameter maxwidechar is the maximum length able to be accomodated in widebuf.

Table of Contents , StrUtil

NAME

vut_StrUtilToUTF8 - convert wide character string to UTF-8

C SPECIFICATION

Vint vut_StrUtilToUTF8 (const wchar_t *widebuf,
                        Vint maxutf8char,
                        char *utf8buf)

INPUT ARGUMENTS

widebuf     Wide character encoded string
maxutf8char Maximum number of UTF-8 characters.

OUTPUT ARGUMENTS

utf8buf     UTF-8 encoded string

DESCRIPTION

Convert a wide character encoded string to a UTF-8 character string. The input parameter maxutf8char, is the maximum length able to be accomodated in utf8buf.

Table of Contents , StrUtil

NAME

vut_StrUtilLenUTF8 - determine character length of UTF-8 string

C SPECIFICATION

Vint vut_StrUtilLenUTF8 (const char *utf8buf)

INPUT ARGUMENTS

utf8buf     UTF-8 encoded string

OUTPUT ARGUMENTS

None

DESCRIPTION

The number of UTF-8 encoded characters is returned.

Table of Contents , StrUtil

NAME

vut_StrUtilMBCSFromUTF8 - convert UTF-8 string to MBCS

C SPECIFICATION

Vint vut_StrUtilMBCSFromUTF8 (const char *utf8buf,
                             Vint maxMBCSchar,
                             Vuchar* mbcs)

INPUT ARGUMENTS

utf8buf     UTF-8 encoded string
maxMBCSchar Maximum number of MBCS characters.

OUTPUT ARGUMENTS

mbcs        MBCS string

DESCRIPTION

Convert a UTF-8 encoded string to a wide character string. The input parameter maxwidechar is the maximum length able to be accomodated in widebuf.