5. Numeric Type Collections - BitVec, DblVec, FltVec, IntDict, DblDict, IntHash, IntVHash, IntQue, IntVec

CEETRON SAM provides modules for managing collections of numeric data types. The BitVec module provides a vector of bits which are useful as an extensible set of Boolean flags. The DblVec, FltVec and IntVec are similar modules for double precision, single precision and signed integer data types. The IntDict, IntHash and IntVHash modules store integer data with keys similar to the manner in which the Dictionary and HashTable modules store objects. The IntQue module stores integer data with first-in, first-out access.

5.1. Bit Vectors - BitVec

The BitVec module is designed to hold an arbitrarily large, extensible series of bits. The module functions allow the user to set and query individual bits in the vector. Additional functions provide for various boolean operations between vectors, iterating through the vector, etc. The BitVec module is intended for managing a set of Boolean values in a compact form.

Instance a BitVec object using vsy_BitVecBegin(). Once a BitVec object is instanced, an approximate number of bits to be stored may be defined using vsy_BitVecDef(). This allocates an internal array for the storage of bit values. As bit values are set the BitVec module will adjust memory as required. The actual maximum index set or defined may be determined by calling vsy_BitVecInq(). The individual bits of a bit vector are addressed by an index which is greater than or equal to zero. The validity of the zero index may be toggled using vsy_BitVecSetParami().

Bit values are initially zero. Bit values may be set by calling vsy_BitVecSet(). A bit value may be returned for a given index using vsy_BitVecGet(). The total number of one bits contained in the bit vector may be found by calling vsy_BitVecCount(). The complement of a bit vector may be performed using vsy_BitVecComplement(). Boolean operations between two bit vectors are performed using vsy_BitVecBoolean().

The index of each one bit in the vector may be returned with an “iterator” construct. The pair of methods vsy_BitVecInitIter() and vsy_BitVecNextIter() are used to visit each one bit using a loop. Call the first method before the body of the loop to prepare the BitVec object for the iteration. Within the loop body, call vsy_BitVecNextIter(). It will return the index to the next one bit each time it is called. It will return an index of -1 when all of the one bits have been processed.

5.1.1. Function Descriptions

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

vsy_BitVec *vsy_BitVecBegin(void)

create an instance of a BitVec object

Create an instance of a BitVec object. Memory is allocated for the object private data and the pointer to the data is returned. By default a bit index of zero is valid.

Destroy an instance of a BitVec object using 

void vsy_BitVecEnd (vsy_BitVec *bitvec)

Return the current value of a BitVec object error flag using 

Vint vsy_BitVecError (vsy_BitVec *bitvec)

Make a copy of a BitVec object. The private data from the frombitvec object is copied to the BitVec object. Any previous private data in bitvec is lost. 

void vsy_BitVecCopy (vsy_BitVec *bitvec,
                     vsy_BitVec *frombitvec)

Returns:

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

void vsy_BitVecEnd(vsy_BitVec *p)

destroy an instance of a BitVec object

See vsy_BitVecBegin()

Vint vsy_BitVecError(vsy_BitVec *p)

return the current value of a BitVec object error flag

See vsy_BitVecBegin()

void vsy_BitVecDef(vsy_BitVec *p, Vint maxindex)

define initial maximum bit index

Suggest the maximum bit index to be stored in the BitVec. This is used to allocate the initial array of storage which is used to hold the bit vector. If a bit index is accessed greater than this initial estimate, storage space in dynamically expanded to hold the extra bits. This function clears any previously set bits to zero.

Find the current maximum bit index of a BitVec using 

void vsy_BitVecInq (const vsy_BitVec *bitvec,
                    Vint *maxindex)

Errors

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

Parameters:

  • p – Pointer to BitVec object.

  • maxindex – Estimated maximum bit index addressed

void vsy_BitVecInq(const vsy_BitVec *p, Vint *len)

find the current maximum bit index

See vsy_BitVecDef()

void vsy_BitVecSetParami(vsy_BitVec *p, Vint ptype, Vint iparam)

set bit vector operation parameters

Set bit vector operation parameters. The VSY_INCLUDEZERO parameter is an integer boolean value which toggles the validity of the zero bit index. The value of the zero bit is not changed by this operation. By default the zero bit index is valid.

Errors

SYS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to BitVec object.

  • ptype – Type of parameter to set 

    x=VSY_INCLUDEZERO        Validity of zero bit index, \param

  • iparam – Specifies the integer value that ptype will be set to.

void vsy_BitVecCount(const vsy_BitVec *p, Vint *num)

get number of one bits

Get the number one bits contained in the bit vector. If bit index zero is a valid index then the count will include the bit value of index zero.

Parameters:

  • p – Pointer to BitVec object.

  • num – [out] Number of one bits.

void vsy_BitVecVector(const vsy_BitVec *p, Vint vec[])

place one bit indices in a vector

Set the indices of one bits in ascending order in vec. Use vsy_BitVecCount() to determine the number of one bit indices.

Parameters:

  • p – Pointer to BitVec object.

  • vec – [out] Vector of one bit indices

void vsy_BitVecSet(vsy_BitVec *p, Vint index, Vint value)

set a bit value at an index

Set the value of a bit specified by index. The bit is set to one if value is non zero, otherwise it is set to zero. All unset bit are initially set to zero. The bit vector automatically expands the required storage to hold the values of set bits.

Return the bit value at an index using 

void vsy_BitVecGet (const vsy_BitVec *bitvec,
                    Vint index,
                    Vint *value)

Errors

  • SYS_ERROR_VALUE is generated if an improper index is specified.

  • SYS_ERROR_MEMORY is generated if bit storage was unable to be allocated.

Parameters:

  • p – Pointer to BitVec object.

  • index – Index of bit to set value

  • value – Value of bit 

    =SYS_OFF      Turn bit off (zero)
=SYS_ON       Turn bit on (one)

void vsy_BitVecGet(const vsy_BitVec *p, Vint idx, Vint *value)

get a bit value at an index

See vsy_BitVecSet()

void vsy_BitVecClear(vsy_BitVec *p)

clear all bits to zero

See vsy_BitVecBoolean()

void vsy_BitVecComplement(vsy_BitVec *p)

flip the values of all bits

See vsy_BitVecBoolean()

void vsy_BitVecBoolean(vsy_BitVec *p, Vint oper, vsy_BitVec *bitvecsrc)

bit vector operations

Perform Boolean bit operations on a bitvec object. The operations are performed bitwise. The result of the specified operation is stored in the bitvec object, the bitvecsrc object remains unchanged. The range of bit indices included in the operation is determined by the bit indices which are valid in the bitvecsrc object. The validity of the zero bit index is set using vsy_BitVecSetParami().

Clear all bits to zero in a BitVec object using 

void vsy_BitVecClear (vsy_BitVec *bitvec)

Flip the values of all bits in a BitVec object using 

void vsy_BitVecComplement (vsy_BitVec *bitvec)

Parameters:

  • p – Pointer to BitVec object.

  • oper – Boolean operation to perform 

    x=BITVEC_AND   Bitwise and of bitvecsrc and bitvec.
 =BITVEC_OR    Bitwise or of bitvecsrc and bitvec.
 =BITVEC_XOR   Bitwise xor of bitvecsrc and bitvec.
 =BITVEC_SET   Copy bitvecsrc to bitvec.

  • bitvecsrc – Pointer to source BitVec object.

void vsy_BitVecInitIter(vsy_BitVec *p)

successively visit each one bit

Sequential access to each one bit in the bit vector may be performed using vsy_BitVecInitIter() and vsy_BitVecNextIter(). Call vsy_BitVecInitIter() to initiate the iteration. Each call of the method vsy_BitVecNextIter() will return the index of the next one bit from the bit vector. After every one bit has been visited in this manner, vsy_BitVecNextIter() will return an index of -1 until the iteration is restarted using vsy_BitVecInitIter().

Parameters:

p – Pointer to BitVec object.

void vsy_BitVecNextIter(vsy_BitVec *p, Vint *index)

successively visit each one bit

See vsy_BitVecInitIter()

Parameters:

  • p – Pointer to BitVec object.

  • index – [out] Index of next one bit.

void vsy_BitVecMatch(vsy_BitVec *p, vsy_BitVec *bitvecm, Vint *flag)

check for matching objects

Check for matching BitVec objects. The order and values of the contents must be identical for a match to occur.

Parameters:

  • p – Pointer to BitVec object.

  • bitvecm – Pointer to BitVec object.

  • flag – [out] Matching flag 

    x=SYS_OFF                 Not matching
 =SYS_ON                  Matching

void vsy_BitVecCopy(vsy_BitVec *p, vsy_BitVec *fromp)

make a copy of a BitVec object

See vsy_BitVecBegin()

5.2. Real Vectors (single FltVec) - DblVec

The DblVec module is designed to hold an arbitrarily large, extensible series of double precision numbers. The FltVec module is identical to the DblVec object except that it holds a series of single precision numbers. In the documentation which follows only the DblVec functions will be described. The corresponding FltVec functions may be obtained by substituting FltVec for DblVec and Vfloat for Vdouble argument types. The module functions allow the user to set and query individual double precision numbers in a vector using an integer index key. The double precision numbers are guaranteed to be contiguous in memory with respect to the integer index key.

Instance a DblVec object using vsy_DblVecBegin(). Once a DblVec object is instanced, an approximate number of doubles to be stored may be defined using vsy_DblVecDef(). This allocates an internal array for the storage of double precision values. As double values are set the DblVec module will adjust memory as required. The actual maximum index referenced or defined may be determined by calling vsy_DblVecInq(). The individual doubles are addressed by an index which is greater than or equal to zero. The validity of the zero index may be toggled using vsy_DblVecSetParami().

Double values are initially zero. Double values may be set by calling vsy_DblVecSet(). A double value may be returned for a given index using vsy_DblVecGet(). The total number of nonzero double values contained in the vector may be found by calling vsy_DblVecCount().

The index of each nonzero double value in the vector may be returned with an “iterator” construct. The pair of methods vsy_DblVecInitIter() and vsy_DblVecNextIter() are used to visit each nonzero value using a loop. Call the first method before the body of the loop to prepare the DblVec object for the iteration. Within the loop body, call vsy_DblVecNextIter(). It will return the index to the next nonzero value each time it is called. It will return an index of -1 when all of the nonzero values have been processed.

5.2.1. Function Descriptions

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

vsy_DblVec *vsy_DblVecBegin(void)

create an instance of a DblVec object

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

Destroy an instance of a DblVec object using 

void vsy_DblVecEnd (vsy_DblVec *dblvec)

Return the current value of a DblVec object error flag using 

Vint vsy_DblVecError (vsy_DblVec *dblvec)

Make a copy of a DblVec object. The private data from the fromdblvec object is copied to the DblVec object. Any previous private data in dblvec is lost. 

void vsy_DblVecCopy (vsy_DblVec *dblvec,
                     vsy_DblVec *fromdblvec)

Returns:

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

void vsy_DblVecEnd(vsy_DblVec *p)

destroy an instance of a DblVec object

See vsy_DblVecBegin()

Vint vsy_DblVecError(vsy_DblVec *p)

return the current value of a DblVec object error

See vsy_DblVecBegin()

void vsy_DblVecDef(vsy_DblVec *p, Vint maxindex)

define initial maximum index

Suggest the maximum index to be stored in the DblVec. This is used to allocate the initial array of storage which is used to hold the vector. If an index is accessed greater than this initial estimate, storage space in dynamically expanded to hold the extra double values. This function clears any previously set values to zero.

Find the current maximum set or appended index of a DblVec using The returned value will be -1 if no values are set. 

void vsy_DblVecInq (const vsy_DblVec *dblvec,
                    Vint *maxindex)

Errors

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

Parameters:

  • p – Pointer to DblVec object.

  • maxindex – Estimated maximum index addressed

void vsy_DblVecInq(const vsy_DblVec *p, Vint *maxind)

find the current maximum set or appended index

See vsy_DblVecDef()

void vsy_DblVecSetParami(vsy_DblVec *p, Vint ptype, Vint iparam)

set double vector operation parameters

Set vector operation parameters. The VSY_INCLUDEZERO parameter is an integer boolean value which toggles the validity of the zero index. The value of index zero is not changed by this operation. By default the zero index is not valid.

Errors

SYS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to DblVec object.

  • ptype – Type of parameter to set 

    x=VSY_INCLUDEZERO        Validity of zero index, iparam

  • iparam – Specifies the integer value that ptype will be set to.

void vsy_DblVecCount(const vsy_DblVec *p, Vint *num)

get number of nonzero values

Get the number nonzero values contained in the vector. If index zero is a valid index then the count will include the value of index zero.

Parameters:

  • p – Pointer to DblVec object.

  • num – [out] Number of nonzero double values

void vsy_DblVecSet(vsy_DblVec *p, Vint index, Vdouble value)

set a double value at an index

Set the value specified by \ index. All unset values are initially set to zero. The vector automatically expands the required storage to hold the set values.

Return the value at an index using 

void vsy_DblVecGet (const vsy_DblVec *dblvec,
                    Vint index,
                    Vdouble *value)

Errors

  • SYS_ERROR_VALUE is generated if an improper index is specified.

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

Parameters:

  • p – Pointer to DblVec object.

  • index – Index of set value

  • value – Double value

void vsy_DblVecSum(vsy_DblVec *p, Vint index, Vdouble value)

sum a double value at an index

Sum value to the existing value at index.

Errors

  • SYS_ERROR_VALUE is generated if an improper index is specified.

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

Parameters:

  • p – Pointer to DblVec object.

  • index – Index of set value

  • value – Double value

void vsy_DblVecAppend(vsy_DblVec *p, Vdouble value)

append value at end of vector

Set the value at the index after the last set or appended value.

Errors

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

Parameters:

  • p – Pointer to DblVec object.

  • value – Double value

void vsy_DblVecGet(const vsy_DblVec *p, Vint idx, Vdouble *value)

get a double value at an index

See vsy_DblVecSet()

void vsy_DblVecClear(vsy_DblVec *p)

clear all doubles to zero

Reinitialize the vector of doubles. The maximum defined index is reset so that any appended values using vsy_DblVecAppend() will be placed at the starting index specified by vsy_DblVecSetParami(). The double values are effectively set to zero.

Parameters:

p – Pointer to DblVec object.

void vsy_DblVecGetPtr(vsy_DblVec *p, Vdouble **ptr)

get pointer to start of double vector

Get the memory pointer to the start of the vector of double values. The double precision numbers are guaranteed to be contiguous in memory with respect to the index key. If zero index is enabled (see vsy_DblVecSetParam()) then the pointer to the double value at index zero is returned, otherwise the pointer to the double value at index one is returned.

Parameters:

  • p – Pointer to DblVec object.

  • ptr – [out] Pointer to start of double vector

void vsy_DblVecInitIter(vsy_DblVec *p)

successively visit each nonzero value

Sequential access to each nonzero value in the vector may be performed using vsy_DblVecInitIter() and vsy_DblVecNextIter(). Call vsy_DblVecInitIter() to initiate the iteration. Each call of the method vsy_DblVecNextIter() will return the index of the next value from the vector. After every nonzero value has been visited in this manner, vsy_DblVecNextIter() will return an index of -1 until the iteration is restarted using vsy_DblVecInitIter().

Parameters:

p – Pointer to DblVec object.

void vsy_DblVecNextIter(vsy_DblVec *p, Vint *index, Vdouble *value)

successively visit each nonzero value

See vsy_DblVecInitIter()

Parameters:

  • p – Pointer to DblVec object.

  • index – [out] Index of next nonzero value

  • value – [out] Double value

void vsy_DblVecMatch(vsy_DblVec *p, vsy_DblVec *dblvecm, Vint *flag)

check for matching objects

Check for matching DblVec objects. The order and values of the contents must be identical for a match to occur.

Parameters:

  • p – Pointer to DblVec object.

  • dblvecm – Pointer to DblVec object.

  • flag – [out] Matching flag 

    x=SYS_OFF                 Not matching
 =SYS_ON                  Matching

void vsy_DblVecCopy(vsy_DblVec *p, vsy_DblVec *fromp)

make a copy of a DblVec object

See vsy_DblVecBegin()

5.3. Integer Dictionary - IntDict

The IntDict module holds a collection of integers which are each identified by name. The matching of names during object retrieval is case sensitive. The IntDict object may expand to contain increasing numbers of integers. It also supports “iterator” functions, which are used to successively visit each integer in the dictionary.

Instance an IntDict object using vsy_IntDictBegin(). Once a IntDict is instanced, an approximate number of integers to be stored may defined using vsy_IntDictDef(). As integers are inserted the IntDict module will adjust memory as required. The actual size of the allocated storage may be determined by calling vsy_IntDictInq().

Each new integer is placed in the dictionary by calling vsy_IntDictInsert(). The total number of integers contained in the dictionary may be found with vsy_IntDictCount(). The integer with a specified name may be found by calling vsy_IntDictLookup(). The method vsy_IntDictClear() removes all integers from the dictionary.

Each integer in the dictionary may be processed with an “iterator” construct. The pair of methods vsy_IntDictInitIter() and vsy_IntDictNextIter() are used to visit each name/integer pair using a loop. Call the first method before the body of the loop to prepare the IntDict object for the iteration. Within the loop body, call vsy_IntDictNextIter(). It will return the name of and the value of an integer each time it is called. It will return a NULL pointer to the name and a zero value when all of the integers have been visited. Use vsy_IntDictInitIterOrder() to visit the integers in name alphabetical order

5.3.1. Function Descriptions

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

vsy_IntDict *vsy_IntDictBegin(void)

create an instance of an IntDict object

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

Destroy an instance of a IntDict object using 

void vsy_IntDictEnd (vsy_IntDict *intdict)

Return the current value of a IntDict object error flag using 

Vint vsy_IntDictError (vsy_IntDict *intdict)

Returns:

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

void vsy_IntDictEnd(vsy_IntDict *p)

destroy an instance of a IntDict object

See vsy_IntDictBegin()

Vint vsy_IntDictError(vsy_IntDict *p)

return the current value of a IntDict object error flag

See vsy_IntDictBegin()

void vsy_IntDictDef(vsy_IntDict *p, Vint numint)

define initial size

Suggest a number of integers to be stored in the IntDict. This is used to allocate an initial array of storage which is used to hold the pointer to each stored integer. Since the name/integer pairs are stored sparsely within the IntDict module, the actual length of the internal array is larger than this supplied number. This function removes any previously entered integers.

Find the number of integers which may be managed by the currently allocated internal storage of an IntDict using 

void vsy_IntDictInq (const vsy_IntDict *intdict,
                     Vint *numint,

Errors

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

Parameters:

  • p – Pointer to IntDict object.

  • numint – Estimated number of integers to be held.

void vsy_IntDictInq(const vsy_IntDict *p, Vint *nument)

find the number of integers which may be managed

See vsy_IntDictDef()

void vsy_IntDictCount(const vsy_IntDict *p, Vint *num)

get number of contained integers

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

Parameters:

  • p – Pointer to IntDict object.

  • num – [out] Number of integers held the in IntDict object.

void vsy_IntDictInsert(vsy_IntDict *p, const Vchar *name, Vint value)

place an integer in the dictionary

Place the integer value in the dictionary, associated with the specified name. This will replace any integer which may have previously inserted with the same name. All name comparisons are case sensitive. A copy of the name is made internal to the IntDict object.

Errors

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

  • SYS_ERROR_VALUE is generated if value is zero.

Parameters:

  • p – Pointer to IntDict object.

  • name – String which identifies the integer.

  • value – Integer value, non zero

void vsy_IntDictLookup(const vsy_IntDict *p, const Vchar *name, Vint *value)

find the integer at a specified location

Get the integer value associated with the specified name. Returns a zero value if no integer with that name has been previously inserted into the dictionary. All name comparisons are case sensitive.

Parameters:

  • p – Pointer to IntDict object.

  • name – Name of the integer.

  • value – [out] Integer associated with the specified name.

void vsy_IntDictClear(vsy_IntDict *p)

remove all integers

Remove all integers

Parameters:

p – Pointer to IntDict object.

void vsy_IntDictInitIter(vsy_IntDict *p)

successively visit each integer

Each call of the method ´vsy_IntDictNextIter()´ will return one integer from the dictionary. It will also return a pointer to the name used within the dictionary. Do not deallocate this string! It is a pointer to the storage used within the IntDict object itself. After every integer has been visited in this manner, ´vsy_IntDictNextIter()´ will return a NULL name pointer and a zero value until the iteration is restarted using ´vsy_IntDictInitIter()´. If the iteration is initiated using ´vsy_IntDictInitIter()´, the integers are visited in an unspecified order. If the iteration is initiated using ´vsy_IntDictInitIterOrder()´, the integers are visited alphabetically by name.

Parameters:

p – Pointer to IntDict object.

void vsy_IntDictNextIter(vsy_IntDict *p, Vchar **name, Vint *value)

successively visit each integer

See vsy_IntDictInitIter()

Parameters:

  • p – Pointer to IntDict object.

  • name – [out] Name of the integer

  • value – [out] Integer associated with name.

void vsy_IntDictInitIterOrder(vsy_IntDict *p)

successively visit each integer

See vsy_IntDictInitIter()

5.4. Double Dictionary - DblDict

The DblDict module holds a collection of doubles which are each identified by name. The matching of names during object retrieval is case sensitive. The DblDict object may expand to contain increasing numbers of doubles. It also supports “iterator” functions, which are used to successively visit each double in the dictionary.

Instance an DblDict object using vsy_DblDictBegin(). Once a DblDict is instanced, an approximate number of doubles to be stored may defined using vsy_DblDictDef(). As doubles are inserted the DblDict module will adjust memory as required. The actual size of the allocated storage may be determined by calling vsy_DblDictInq().

Each new double is placed in the dictionary by calling vsy_DblDictInsert(). The total number of doubles contained in the dictionary may be found with vsy_DblDictCount(). The double with a specified name may be found by calling vsy_DblDictLookup(). The method vsy_DblDictClear() removes all doubles from the dictionary.

Each double in the dictionary may be processed with an “iterator” construct. The pair of methods vsy_DblDictInitIter() and vsy_DblDictNextIter() are used to visit each name/double pair using a loop. Call the first method before the body of the loop to prepare the DblDict object for the iteration. Within the loop body, call vsy_DblDictNextIter(). It will return the name of and the value of an double each time it is called. It will return a NULL pointer to the name and a zero value when all of the doubles have been visited. Use vsy_DblDictInitIterOrder() to visit the doubles in name alphabetical order

5.4.1. Function Descriptions

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

vsy_DblDict *vsy_DblDictBegin(void)

create an instance of a DblDict object

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

Destroy an instance of a DblDict object using 

void vsy_DblDictEnd (vsy_DblDict *DblDict)

Return the current value of a DblDict object error flag using 

Vint vsy_DblDictError (vsy_DblDict *DblDict)

Returns:

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

void vsy_DblDictEnd(vsy_DblDict *p)

destroy an instance of a DblDict object

See vsy_DblDictBegin()

Vint vsy_DblDictError(vsy_DblDict *p)

return the current value of a DblDict object error flag

See vsy_DblDictBegin()

void vsy_DblDictDef(vsy_DblDict *p, Vint numint)

define initial size

Suggest a number of doubles to be stored in the DblDict. This is used to allocate an initial array of storage which is used to hold the pointer to each stored double. Since the name/double pairs are stored sparsely within the DblDict module, the actual length of the internal array is larger than this supplied number. This function removes any previously entered doubles.

Find the number of doubles which may be managed by the currently allocated internal storage of an DblDict using 

void vsy_DblDictInq (const vsy_DblDict *DblDict,
                     Vint *numint,

Errors

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

Parameters:

  • p – Pointer to DblDict object.

  • numint – Estimated number of doubles to be held.

void vsy_DblDictInq(const vsy_DblDict *p, Vint *nument)

find the number of doubles which may be managed

See vsy_DblDictDef()

void vsy_DblDictCount(const vsy_DblDict *p, Vint *num)

get number of contained items

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

Parameters:

  • p – Pointer to DblDict object.

  • num – [out] Number of doubles held the in DblDict object.

void vsy_DblDictInsert(vsy_DblDict *p, const Vchar *name, Vdouble value)

place an double in the dictionary

Place the double value in the dictionary, associated with the specified name. This will replace any double which may have previously inserted with the same name. All name comparisons are case sensitive. A copy of the name is made internal to the DblDict object.

Errors

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

  • SYS_ERROR_VALUE is generated if value is zero.

Parameters:

  • p – Pointer to DblDict object.

  • name – String which identifies the double.

  • value – Double value

void vsy_DblDictLookup(const vsy_DblDict *p, const Vchar *name, Vdouble *value)

find the double at a specified location

Get the double value associated with the specified name. Returns a SYS_DOUBLE_UNDEFINED value if no double with that name has been previously inserted into the dictionary. All name comparisons are case sensitive.

Parameters:

  • p – Pointer to DblDict object.

  • name – Name of the double.

  • value – [out] Double associated with the specified name.

void vsy_DblDictClear(vsy_DblDict *p)

remove all items

Remove all items

Parameters:

p – Pointer to DblDict object.

void vsy_DblDictInitIter(vsy_DblDict *p)

successively visit each double

Each call of the method vsy_DblDictNextIter() will return one double from the dictionary. It will also return a pointer to the name used within the dictionary. Do not deallocate this string! It is a pointer to the storage used within the DblDict object itself. After every double has been visited in this manner, vsy_DblDictNextIter() will return a NULL name pointer and a SYS_DOUBLE_UNDEFINED value until the iteration is restarted using vsy_DblDictInitIter(). If the iteration is initiated using vsy_DblDictInitIter(), the doubles are visited in an unspecified order. If the iteration is initiated using vsy_DblDictInitIterOrder(), the doubles are visited alphabetically by name.

Parameters:

p – Pointer to DblDict object.

void vsy_DblDictNextIter(vsy_DblDict *p, Vchar **name, Vdouble *value)

successively visit each double

See vsy_DblDictInitIter()

Parameters:

  • p – Pointer to DblDict object.

  • name – [out] Name of the double

  • value – [out] double associated with name.

void vsy_DblDictInitIterOrder(vsy_DblDict *p)

successively visit each double sorted alphabetically by its key

See vsy_DblDictInitIter()

5.5. Integer Hashtable - IntHash

The IntHash module holds a collection of integers which are identified by integer key values. The IntHash object may expand to contain an increasing number of integers. It also supports “iterator” functions, which are used to successively visit each integer stored in the hashtable.

Instance a IntHash object using vsy_IntHashBegin(). Once a IntHash is instanced, an approximate number of integers to be stored may be defined using vsy_IntHashDef(). As integers are inserted IntHash module will expand its internal storage as required. The method vsy_IntHashInq() returns the number of integers which may be managed by the presently allocated storage.

Each new integer is placed in the hashtable using vsy_IntHashInsert(). The total number of integers contained in the hashtable may be found by calling vsy_IntHashCount(). An integer with a specified integer key may be retrieved using vsy_IntHashLookup(). The method vsy_IntHashClear() removes all integers from the hashtable. The maximum key used to store any integer may be queried using vsy_IntHashMaxKey(). All keys may be queried using vsy_IntHashAllKeys(). In this case the number of keys returned will be equal to the number of keys returned by vsy_IntHashCount().

Each integer in the hashtable may be processed with an “iterator” construct. The pair of methods vsy_IntHashInitIter() and vsy_IntHashNextIter() are used to visit each key/integer pair using a loop. Call the first method before the body of the loop to prepare the IntHash object for the iteration. Within the loop body, call vsy_IntHashNextIter(). It will return an integer key and an integer value each time it is called. It will return a zero value when all of the integers have been processed. Use vsy_IntHashInitIterOrder() to visit the integers in monotonically increasing key value.

5.5.1. Function Descriptions

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

vsy_IntHash *vsy_IntHashBegin(void)

create an instance of an IntHash object

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

Destroy an instance of a IntHash object using 

void vsy_IntHashEnd (vsy_IntHash *inthash)

Return the current value of a IntHash object error flag using 

Vint vsy_IntHashError (vsy_IntHash *inthash)

Returns:

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

void vsy_IntHashEnd(vsy_IntHash *p)

destroy an instance of an IntHash object

See vsy_IntHashBegin()

Vint vsy_IntHashError(vsy_IntHash *p)

return the current value of an IntHash object error flag

See vsy_IntHashBegin()

void vsy_IntHashDef(vsy_IntHash *p, Vint numint)

define initial length of storage array

Suggest a number of elements to be stored in the IntHash. This is used to allocate the initial array of storage which is used to hold each integer/integer pair. If the number of inserted elements is eventually greater than this initial estimate, storage space will dynamically expanded to hold the extra integers. This function removes any previously entered integers.

Find the number of integers which may be managed with the presently allocated storage using 

void vsy_IntHashInq (const vsy_IntHash *inthash,
                     Vint *numint)

Errors

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

Parameters:

  • p – Pointer to IntHash object.

  • numint – Estimated number of integers to be held.

void vsy_IntHashInq(const vsy_IntHash *p, Vint *nument)

find the number of integers which may be managed

See vsy_IntHashDef()

void vsy_IntHashCount(const vsy_IntHash *p, Vint *num)

get number of contained integers

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

Parameters:

  • p – Pointer to IntHash object.

  • num – [out] Number of integers held the in IntHash object.

void vsy_IntHashMaxKey(vsy_IntHash *p, Vint *maxkey)

get maximum key value

Get the maximum key value used to store current integers in IntHash.

Parameters:

  • p – Pointer to IntHash object.

  • maxkey – [out] Maximum key value

void vsy_IntHashAllKeys(const vsy_IntHash *p, Vint allkeys[])

get all key values

Get all key values used to store current integers in IntHash. The number of key values returned will be equal the the number of keys returned by the function vsy_IntHashCount().

Parameters:

  • p – Pointer to IntHash object.

  • allkeys – [out] Array of all keys

void vsy_IntHashInsert(vsy_IntHash *p, Vint key, Vint value)

place an integer in the hashtable

Place the integer value in the IntHash object. Associate the integer key with this new integer, and replace any integer which may have been previously associated with this same key.

Errors

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

  • SYS_ERROR_VALUE is generated if value is zero.

Parameters:

  • p – Pointer to IntHash object.

  • key – Integer key value.

  • value – Integer value, non zero

void vsy_IntHashLookup(const vsy_IntHash *p, Vint key, Vint *value)

find the integer at a specified location

Get the integer value associated the specified key. Returns a zero value if no integer has been entered with this key.

Parameters:

  • p – Pointer to IntHash object.

  • key – Integer key of the desired integer.

  • value – [out] Integer associated with key.

void vsy_IntHashClear(vsy_IntHash *p)

remove all integers

Remove all the integers.

Parameters:

p – Pointer to IntHash object.

void vsy_IntHashInitIter(vsy_IntHash *p)

successively visit each integer

Each call of the method vsy_IntHashNextIter() will return a new item from the hashtable, together with its associated key. These key/value pairs are visited in arbitrary order. After every integer has been visited in this manner, vsy_IntHashNextIter() will return a key of zero and a zero value until the iteration is restarted using vsy_IntHashInitIter() or vsy_IntHashInitIterOrder().

Parameters:

p – Pointer to IntHash object.

void vsy_IntHashInitIterOrder(vsy_IntHash *p)

successively visit each integer

See vsy_IntHashInitIter()

Parameters:

p – Pointer to IntHash object.

void vsy_IntHashNextIter(vsy_IntHash *p, Vint *key, Vint *value)

successively visit each integer

See vsy_IntHashInitIter()

Parameters:

  • p – Pointer to IntHash object.

  • key – [out] Key of integer

  • value – [out] Integer associated with key

5.6. Double Hashtable - DblHash

The DblHash module holds a collection of integers which are identified by double key values. The DblHash object may expand to contain an increasing number of integers. It also supports “iterator” functions, which are used to successively visit each integer stored in the hashtable.

Instance a DblHash object using vsy_DblHashBegin(). Once a DblHash is instanced, an approximate number of integers to be stored may be defined using vsy_DblHashDef(). As integers are inserted DblHash module will expand its internal storage as required. The method vsy_DblHashInq() returns the number of integers which may be managed by the presently allocated storage.

Each new integer is placed in the hashtable using vsy_DblHashInsert(). The total number of integers contained in the hashtable may be found by calling vsy_DblHashCount(). An integer with a specified integer key may be retrieved using vsy_DblHashLookup(). The method vsy_DblHashClear() removes all integers from the hashtable.

Each integer in the hashtable may be processed with an “iterator” construct. The pair of methods vsy_DblHashInitIter() and vsy_DblHashNextIter() are used to visit each key/integer pair using a loop. Call the first method before the body of the loop to prepare the DblHash object for the iteration. Within the loop body, call vsy_DblHashNextIter(). It will return an integer key and an integer value each time it is called. It will return a zero value when all of the integers have been processed.

5.6.1. Function Descriptions

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

vsy_DblHash *vsy_DblHashBegin(void)

create an instance of an DblHash object

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

Destroy an instance of a DblHash object using 

void vsy_DblHashEnd (vsy_DblHash *p)

Return the current value of a DblHash object error flag using 

Vint vsy_DblHashError (vsy_DblHash *p)

Returns:

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

void vsy_DblHashEnd(vsy_DblHash *p)

destroy an instance of an DblHash object

See vsy_DblHashBegin()

Vint vsy_DblHashError(vsy_DblHash *p)

return the current value of an DblHash object error flag

See vsy_DblHashBegin()

void vsy_DblHashDef(vsy_DblHash *p, Vint size)

define initial length of storage array

Suggest a number of elements to be stored in the DblHash. This is used to allocate the initial array of storage. If the number of inserted elements is eventually greater than this initial estimate, storage space will dynamically expanded to hold the extra entries. This function removes any previously entered keys.

Find the number of integers which may be managed with the presently allocated storage using 

void vsy_DblHashInq (const vsy_DblHash *p,
                      Vint *size)

Errors

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

Parameters:

  • p – Pointer to DblHash object.

  • size – number of keys to be stored

void vsy_DblHashInq(const vsy_DblHash *p, Vint *size)

find the number of integers which may be managed with the presently allocated storage

See vsy_DblHashDef()

void vsy_DblHashCount(const vsy_DblHash *p, Vint *num)

get number of contained keys

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

Parameters:

  • p – Pointer to DblHash object.

  • num – [out] Number of keys held the in DblHash object.

void vsy_DblHashInsert(vsy_DblHash *p, Vdouble key, Vint value)

place an integer in the hashtable

Place the integer a value in the DblHash object. Associate the double key with this new integer, and replace any integer which may have been previously associated with this same key.

Errors

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

  • SYS_ERROR_VALUE is generated if value is zero.

Parameters:

  • p – Pointer to DblHash object.

  • key – Double key value.

  • value – Integer value, non zero

void vsy_DblHashLookup(const vsy_DblHash *p, Vdouble key, Vint *value)

find the integer at a specified location

Get the integer value associated the specified key. Returns a zero value if no integer has been entered with this key.

Parameters:

  • p – Pointer to DblHash object.

  • key – Integer key values of the desired integer.

  • value – [out] Integer associated with key.

void vsy_DblHashRemove(vsy_DblHash *p, Vdouble key)

remove the integer at a specified location

Remove the integer value associated to the specified key, if found.

Parameters:

  • p – Pointer to DblHash object.

  • key – double key values of the desired integer.

void vsy_DblHashClear(vsy_DblHash *p)

remove all keys

Remove all the keys.

void vsy_DblHashInitIter(vsy_DblHash *p)

successively visit each key

Each call of the method vsy_DblHashNextIter() will return a new item from the hashtable, together with its associated keys. These key/value pairs are visited in arbitrary order. After every key has been visited in this manner, vsy_DblHashNextIter() will return a key of zeros and a zero value until the iteration is restarted using vsy_DblHashInitIter().

Parameters:

p – Pointer to DblHash object.

void vsy_DblHashNextIter(vsy_DblHash *p, Vdouble *key, Vint *value)

successively visit each key,value pair

See vsy_DblHashInitIter()

Parameters:

  • p – Pointer to DblHash object.

  • key – [out] Key

  • value – [out] Integer associated with key

5.7. Integer, Multiple Integer Key, Hashtable - IntVHash

The IntVHash module is similar to the IntVHash module except that the scalar integer key is generalized to an arbitrarily sized vector of integer keys.

Instance a IntVHash object using vsy_IntVHashBegin(). Once a IntVHash is instanced, define the size of the vector of integer keys and an approximate number of integers to be stored using vsy_IntVHashDef(). As integers are inserted IntVHash module will expand its internal storage as required. The method vsy_IntVHashInq() returns the number of integers defined in a vector key and the number of integer values which may be managed by the presently allocated storage.

Each new integer is placed in the hashtable using vsy_IntVHashInsert(). The total number of integers contained in the hashtable may be found by calling vsy_IntVHashCount(). An integer with a specified vector of integer keys may be retrieved using vsy_IntVHashLookup(). The method vsy_IntVHashClear() removes all integers from the hashtable.

Each integer in the hashtable may be processed with an “iterator” construct. The pair of methods vsy_IntVHashInitIter() and vsy_IntVHashNextIter() are used to visit each key-vector/integer pair using a loop. Call the first method before the body of the loop to prepare the IntVHash object for the iteration. Within the loop body, call vsy_IntVHashNextIter(). It will return an integer key and an integer value each time it is called. It will return a zero value when all of the integers have been processed.

5.7.1. Function Descriptions

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

vsy_IntVHash *vsy_IntVHashBegin(void)

create an instance of an IntVHash object

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

Destroy an instance of a IntVHash object using 

void vsy_IntVHashEnd (vsy_IntVHash *intvhash)

Return the current value of a IntVHash object error flag using 

Vint vsy_IntVHashError (vsy_IntVHash *intvhash)

Returns:

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

void vsy_IntVHashEnd(vsy_IntVHash *p)

destroy an instance of an IntVHash object

See vsy_IntVHashBegin()

Vint vsy_IntVHashError(vsy_IntVHash *p)

return the current value of an IntVHash object error flag

See vsy_IntVHashBegin()

void vsy_IntVHashDef(vsy_IntVHash *p, Vint size, Vint numint)

define initial length of storage array

Suggest a number of elements to be stored in the IntVHash. This is used to allocate the initial array of storage which is used to hold each integer/integer pair. If the number of inserted elements is eventually greater than this initial estimate, storage space will dynamically expanded to hold the extra integers. This function removes any previously entered integers.

Find the number of integers which may be managed with the presently allocated storage using 

void vsy_IntVHashInq (const vsy_IntVHash *intvhash,
                      Vint *size,
                      Vint *numint)

Errors

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

Parameters:

  • p – Pointer to IntVHash object.

  • size – Number of integers per key-vector

  • numint – Estimated number of integers to be held.

void vsy_IntVHashInq(const vsy_IntVHash *p, Vint *size, Vint *nument)

find the number of integers which may be managed with the presently allocated storage

See vsy_IntVHashDef()

void vsy_IntVHashCount(const vsy_IntVHash *p, Vint *num)

get number of contained integers

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

Parameters:

  • p – Pointer to IntVHash object.

  • num – [out] Number of integers held the in IntVHash object.

void vsy_IntVHashInsert(vsy_IntVHash *p, Vint key[], Vint value)

place an integer in the hashtable

Place the integer a value in the IntVHash object. Associate the integers key with this new integer, and replace any integer which may have been previously associated with this same key.

Errors

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

  • SYS_ERROR_VALUE is generated if value is zero.

Parameters:

  • p – Pointer to IntVHash object.

  • key – Integer key values.

  • value – Integer value, non zero

void vsy_IntVHashLookup(const vsy_IntVHash *p, Vint key[], Vint *value)

find the integer at a specified location

Get the integer value associated the specified key. Returns a zero value if no integer has been entered with this key.

Parameters:

  • p – Pointer to IntVHash object.

  • key – Integer key values of the desired integer.

  • value – [out] Integer associated with key.

void vsy_IntVHashRemove(vsy_IntVHash *p, Vint key[])

remove the integer at a specified location

Remove the integer value associated to the specified key, if found.

Parameters:

  • p – Pointer to IntVHash object.

  • key – Integer key values of the desired integer.

void vsy_IntVHashClear(vsy_IntVHash *p)

remove all integers

Remove all the integers.

void vsy_IntVHashInitIter(vsy_IntVHash *p)

successively visit each integer

Each call of the method vsy_IntVHashNextIter() will return a new item from the hashtable, together with its associated keys. These key/value pairs are visited in arbitrary order. After every integer has been visited in this manner, vsy_IntVHashNextIter() will return a key of zeros and a zero value until the iteration is restarted using vsy_IntVHashInitIter().

Parameters:

p – Pointer to IntVHash object.

void vsy_IntVHashNextIter(vsy_IntVHash *p, Vint *key, Vint *value)

successively visit each integer

See vsy_IntVHashInitIter()

Parameters:

  • p – Pointer to IntVHash object.

  • key – [out] Keys of integer

  • value – [out] Integer associated with key

5.8. Integer Queue - IntQue

The IntQue module holds a collection of integers with first-in, first-out access. The IntQue object may expand to contain an increasing number of integers.

Instance a IntQue object using vsy_IntQueBegin(). Once a IntQue is instanced, an approximate number of integers to be stored may be defined using vsy_IntQueDef(). As integers are inserted IntQue module will expand its internal storage as required. The method vsy_IntQueInq() returns the number of integers which may be managed by the presently allocated storage.

Each new integer is placed in the queue using vsy_IntQuePut(). The total number of integers contained in the queue may be found by calling vsy_IntQueCount(). The current earliest put integer may be retrieved without removing the integer from the queue using vsy_IntQueRef(), to access and remove the integer use vsy_IntQueGet(). The method vsy_IntQueClear() removes all integers from the queue.

5.8.1. Function Descriptions

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

vsy_IntQue *vsy_IntQueBegin(void)

create an instance of an IntQue object

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

Destroy an instance of a IntQue object using 

void vsy_IntQueEnd (vsy_IntQue *intque)

Return the current value of a IntQue object error flag using 

Vint vsy_IntQueError (vsy_IntQue *intque)

Returns:

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

void vsy_IntQueEnd(vsy_IntQue *p)

destroy an instance of an IntQue object

See vsy_IntQueBegin()

Vint vsy_IntQueError(vsy_IntQue *p)

return the current value of a IntQue object error flag

See vsy_IntQueBegin()

void vsy_IntQueDef(vsy_IntQue *p, Vint numint)

define suggested number of stored integers

Suggest a number of integers to be stored in the IntQue. This is used to allocate the initial array of storage. If the number of inserted integers is eventually greater than this initial estimate, storage space will dynamically expanded to hold the extra integers. This function removes any previously entered integers.

Find the number of integers which may be managed with the presently allocated storage using 

void vsy_IntQueInq (const vsy_IntQue *intque,
                    Vint *numint)

Errors

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

Parameters:

  • p – Pointer to IntQue object.

  • numint – Estimated number of integers to be held.

void vsy_IntQueInq(const vsy_IntQue *p, Vint *nument)

find the number of integers which may be managed with the presently allocated storage

See vsy_IntQueDef()

void vsy_IntQueCount(const vsy_IntQue *p, Vint *num)

get number of contained integers

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

Parameters:

  • p – Pointer to IntQue object.

  • num – [out] Number of integers held the in IntQue object.

void vsy_IntQuePut(vsy_IntQue *p, Vint value)

put an integer in the queue

Place the integer value in the IntQue object.

Errors

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

Parameters:

  • p – Pointer to IntQue object.

  • value – Integer value

void vsy_IntQueRef(const vsy_IntQue *p, Vint *value)

access earliest integer without removal

Get the earliest integer value without removing it from the queue. A zero is returned if the queue is empty.

Parameters:

  • p – Pointer to IntQue object.

  • value – [out] Integer value

void vsy_IntQueGet(vsy_IntQue *p, Vint *value)

access and remove earliest integer

Get the earliest integer value and remove it from the queue. A zero is returned if the queue is empty.

Parameters:

  • p – Pointer to IntQue object.

  • value – [out] Integer value

void vsy_IntQueClear(vsy_IntQue *p)

remove all integers

Remove all the integers.

Parameters:

p – Pointer to IntQue object.

5.9. Integer Vectors - IntVec

The IntVec module is designed to hold an arbitrarily large, extensible series of integer numbers. The module functions allow the user to set and query individual integer numbers in a vector using an integer index key. The integer numbers are guaranteed to be contiguous in memory with respect to the integer index key.

Instance a IntVec object using vsy_IntVecBegin(). Once a IntVec object is instanced, an approximate number of integers to be stored may be defined using vsy_IntVecDef(). This allocates an internal array for the storage of integer values. As integer values are set the IntVec module will adjust memory as required. The actual maximum index referenced or defined may be determined by calling vsy_IntVecInq(). The individual integers are addressed by an index which is greater than or equal to zero. The validity of the zero index may be toggled using vsy_IntVecSetParami().

Integer values are initially zero. Integer values may be set by calling vsy_IntVecSet(). A integer value may be returned for a given index using vsy_IntVecGet(). The total number of nonzero integer values contained in the vector may be found by calling vsy_IntVecCount().

The index of each nonzero integer value in the vector may be returned with an “iterator” construct. The pair of methods vsy_IntVecInitIter() and vsy_IntVecNextIter() are used to visit each nonzero value using a loop. Call the first method before the body of the loop to prepare the IntVec object for the iteration. Within the loop body, call vsy_IntVecNextIter(). It will return the index to the next nonzero value each time it is called. It will return an index of -1 when all of the nonzero values have been processed.

5.9.1. Function Descriptions

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

vsy_IntVec *vsy_IntVecBegin(void)

create an instance of an IntVec object

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

Destroy an instance of a IntVec object using 

void vsy_IntVecEnd (vsy_IntVec *intvec)

Return the current value of a IntVec object error flag using 

Vint vsy_IntVecError (vsy_IntVec *intvec)

Make a copy of a IntVec object. The private data from the fromintvec object is copied to the IntVec object. Any previous private data in intvec is lost. 

void vsy_IntVecCopy (vsy_IntVec *intvec,
                     vsy_IntVec *fromintvec)

Returns:

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

void vsy_IntVecEnd(vsy_IntVec *p)

destroy an instance of an IntVec object

See vsy_IntVecBegin()

Vint vsy_IntVecError(vsy_IntVec *p)

return the current value of a IntVec object error flag

See vsy_IntVecBegin()

void vsy_IntVecDef(vsy_IntVec *p, Vint maxindex)

define initial maximum index

Suggest the maximum index to be stored in the IntVec. This is used to allocate the initial array of storage which is used to hold the vector. If an index is accessed greater than this initial estimate, storage space in dynamically expanded to hold the extra integer values. This function clears any previously set values to zero.

Find the current maximum set or appended index of a IntVec using The returned value will be -1 if no values are set. 

void vsy_IntVecInq (const vsy_IntVec *intvec,
                    Vint *maxindex)

Errors

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

Parameters:

  • p – Pointer to IntVec object.

  • maxindex – Estimated maximum index addressed

void vsy_IntVecInq(const vsy_IntVec *p, Vint *maxind)

find the current maximum set or appended index

See vsy_IntVecDef()

void vsy_IntVecSetParami(vsy_IntVec *p, Vint ptype, Vint iparam)

set integer vector operation parameters

Set vector operation parameters. The VSY_INCLUDEZERO parameter is an integer boolean value which toggles the validity of the zero index. The value of index zero is not changed by this operation. By default the zero index is not valid.

Errors

SYS_ERROR_ENUM is generated if an improper ptype is specified.

Parameters:

  • p – Pointer to IntVec object.

  • ptype – Type of parameter to set 

    x=VSY_INCLUDEZERO        Validity of zero index, iparam

  • iparam – Specifies the integer value that ptype will be set to.

void vsy_IntVecCount(const vsy_IntVec *p, Vint *num)

get number of nonzero values

Get the number nonzero values contained in the vector. If index zero is a valid index then the count will include the value of index zero.

Parameters:

  • p – Pointer to IntVec object.

  • num – [out] Number of nonzero integer values

void vsy_IntVecSet(vsy_IntVec *p, Vint index, Vint value)

set a integer value at an index

Set the value specified by index. All unset values are initially set to zero. The vector automatically expands the required storage to hold the set values.

Return the value at an index using 

void vsy_IntVecGet (const vsy_IntVec *intvec,
                    Vint index,
                    Vint *value)

Errors

  • SYS_ERROR_VALUE is generated if an improper index is specified.

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

Parameters:

  • p – Pointer to IntVec object.

  • index – Index of set value

  • value – Integer value

void vsy_IntVecAppend(vsy_IntVec *p, Vint value)

append value at end of vector

Set the value at the index after the last set or appended value.

Errors

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

Parameters:

  • p – Pointer to IntVec object.

  • value – Integer value

void vsy_IntVecGet(const vsy_IntVec *p, Vint idx, Vint *value)

set a integer value at an index

See vsy_IntVecSet()

void vsy_IntVecClear(vsy_IntVec *p)

clear all integers to zero

Reinitialize the vector of integers. The maximum defined index is reset so that any appended values using vsy_IntVecAppend() will be placed at the starting index specified by vsy_IntVecSetParami(). The integer values are effectively set to zero.

Parameters:

p – Pointer to IntVec object.

void vsy_IntVecGetPtr(vsy_IntVec *p, Vint **ptr)

get pointer to start of integer vector

Get the memory pointer to the start of the vector of integer values. The integer numbers are guaranteed to be contiguous in memory with respect to the index key. If zero index is enabled (see vsy_IntVecSetParami()) then the pointer to the integer value at index zero is returned, otherwise the pointer to the integer value at index one is returned.

Parameters:

  • p – Pointer to IntVec object.

  • ptr – [out] Pointer to start of integer vector

void vsy_IntVecInitIter(vsy_IntVec *p)

successively visit each nonzero value

Sequential access to each nonzero value in the vector may be performed using vsy_IntVecInitIter() and vsy_IntVecNextIter(). Call vsy_IntVecInitIter() to initiate the iteration. Each call of the method vsy_IntVecNextIter() will return the index of the next value from the vector. After every nonzero value has been visited in this manner, vsy_IntVecNextIter() will return an index of -1 until the iteration is restarted using vsy_IntVecInitIter().

Parameters:

p – Pointer to IntVec object.

void vsy_IntVecNextIter(vsy_IntVec *p, Vint *index, Vint *value)

successively visit each nonzero value

See vsy_IntVecInitIter()

Parameters:

  • p – Pointer to IntVec object.

  • index – [out] Index of next nonzero value

  • value – [out] Integer value

void vsy_IntVecMatch(vsy_IntVec *p, vsy_IntVec *intvecm, Vint *flag)

check for matching objects

Check for matching IntVec objects. The order and values of the contents must be identical for a match to occur.

Parameters:

  • p – Pointer to IntVec object.

  • intvecm – Pointer to IntVec object.

  • flag – [out] Matching flag 

    x=SYS_OFF                 Not matching
 =SYS_ON                  Matching

void vsy_IntVecCopy(vsy_IntVec *p, vsy_IntVec *fromp)

make a copy of a IntVec object

See vsy_IntVecBegin()

void vsy_IntVecGetStartingIndex(vsy_IntVec *p, Vint *index)

get the starting index of a IntVec object

Retrieve the starting index of a IntVec object.

Parameters:

  • p – Pointer to IntVec object.

  • index – [out] Staring index.