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

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

Table of Contents

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.

Begin and end an instance of an object, return object error flag

*vsy_BitVecBegin         - create an instance of a BitVec object
vsy_BitVecEnd            - destroy an instance of a BitVec object
vsy_BitVecError          - return BitVec object error flag
vsy_BitVecCopy           - copy a BitVec

Set and query bits

vsy_BitVecBoolean        - perform Boolean operations between vectors
vsy_BitVecClear          - clear all bits to zero
vsy_BitVecComplement     - flip the value of all bits
vsy_BitVecCount          - get number of one bits
vsy_BitVecDef            - define initial maximum bit index
          Inq            - inquire current maximum bit index
vsy_BitVecMatch          - check for matching objects
vsy_BitVecInitIter       - prepare to successively visit each one bit
vsy_BitVecNextIter       - return the index of the next one bit
vsy_BitVecSet            - set a bit value at an index
          Get            - get a bit value at an index
vsy_BitVecSetParami      - set bit vector operation parameters
vsy_BitVecVector         - place one bit indices in a vector

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.

Table of Contents

5.2 Function Descriptions

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

Table of Contents , BitVec

NAME

*vsy_BitVecBegin - create an instance of an BitVec object

C SPECIFICATION

vsy_BitVec *vsy_BitVecBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , BitVec

NAME

vsy_BitVecBoolean,vsy_BitVecClear,vsy_BitVecComplement - bit vector operations

C SPECIFICATION

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

void vsy_BitVecClear (vsy_BitVec *bitvec)

void vsy_BitVecComplement (vsy_BitVec *bitvec)

INPUT ARGUMENTS

bitvec       Pointer to BitVec object.
oper         Boolean operation to perform
             =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.

OUTPUT ARGUMENTS

None

DESCRIPTION

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)

Table of Contents , BitVec

NAME

vsy_BitVecCount - get number of one bits

C SPECIFICATION

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

INPUT ARGUMENTS

bitvec       Pointer to BitVec object.

OUTPUT ARGUMENTS

num          Number of one bits.

DESCRIPTION

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.

Table of Contents , BitVec

NAME

vsy_BitVecDef - define initial maximum bit index

C SPECIFICATION

void vsy_BitVecDef (vsy_BitVec *bitvec,
                    Vint maxindex)

INPUT ARGUMENTS

bitvec       Pointer to BitVec object.
maxindex     Estimated maximum bit index addressed

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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)

                                                                           

Table of Contents , BitVec

NAME

vsy_BitVecMatch - check for matching objects

C SPECIFICATION

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

INPUT ARGUMENTS

bitvec       Pointer to BitVec object.
bitvecm      Pointer to BitVec object.

OUTPUT ARGUMENTS

flag         Matching flag
             =SYS_OFF                 Not matching
             =SYS_ON                  Matching

DESCRIPTION

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

Table of Contents , BitVec

NAME

vsy_BitVecNextIter,vsy_BitVecInitIter - successively visit each one bit

C SPECIFICATION

void vsy_BitVecInitIter (vsy_BitVec *bitvec)

void vsy_BitVecNextIter (vsy_BitVec *bitvec,
                         Vint *index)

INPUT ARGUMENTS

bitvec       Pointer to BitVec object.

OUTPUT ARGUMENTS

index        Index of next one bit.

DESCRIPTION

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.

Table of Contents , BitVec

NAME

vsy_BitVecSet - set a bit value at an index

C SPECIFICATION

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

INPUT ARGUMENTS

bitvec       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)

OUTPUT ARGUMENTS

None

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.

DESCRIPTION

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)

Table of Contents , BitVec

NAME

vsy_BitVecSetParami - set bit vector operation parameters

C SPECIFICATION

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

INPUT ARGUMENTS

bitvec       Pointer to BitVec object.
ptype        Type of parameter to set
             =VSY_INCLUDEZERO        Validity of zero bit index, iparam
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

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.

Table of Contents , BitVec

NAME

vsy_BitVecVector - place one bit indices in a vector

C SPECIFICATION

void vsy_BitVecVector (vsy_BitVec *bitvec,
                       Vint vec[])

INPUT ARGUMENTS

bitvec       Pointer to BitVec object.

OUTPUT ARGUMENTS

vec          Vector of one bit indices

DESCRIPTION

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

Table of Contents

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

Begin and end an instance of an object, return object error flag

*vsy_DblVecBegin         - create an instance of a DblVec object
vsy_DblVecEnd            - destroy an instance of a DblVec object
vsy_DblVecError          - return DblVec object error flag
vsy_DblVecCopy           - copy a DblVec

Set and query values

vsy_DblVecAppend         - append value at end of vector
vsy_DblVecClear          - clear all doubles to zero
vsy_DblVecCount          - get number of nonzero doubles
vsy_DblVecDef            - define initial maximum index
          Inq            - inquire current maximum index
vsy_DblVecGetPtr         - get pointer to start of double vector
vsy_DblVecMatch          - check for matching objects
vsy_DblVecInitIter       - prepare to successively visit each nonzero
vsy_DblVecNextIter       - return the index of the next nonzero
vsy_DblVecSet            - set a double value at an index
          Get            - get a double value at an index
vsy_DblVecSum            - sum a double value at an index
vsy_DblVecSetParami      - set double vector operation parameters

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.

Table of Contents

5.4 Function Descriptions

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

Table of Contents , DblVec

NAME

*vsy_DblVecBegin - create an instance of an DblVec object

C SPECIFICATION

vsy_DblVec *vsy_DblVecBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , DblVec

NAME

vsy_DblVecCount - get number of nonzero values

C SPECIFICATION

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

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.

OUTPUT ARGUMENTS

num          Number of nonzero double values

DESCRIPTION

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.

Table of Contents , DblVec

NAME

vsy_DblVecDef - define initial maximum index

C SPECIFICATION

void vsy_DblVecDef (vsy_DblVec *dblvec,
                    Vint maxindex)

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.
maxindex     Estimated maximum index addressed

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

DESCRIPTION

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)

Table of Contents , DblVec

NAME

vsy_DblVecAppend - append value at end of vector

C SPECIFICATION

void vsy_DblVecAppend (vsy_DblVec *dblvec,
                       Vdouble value)

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.
value        Double value

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

DESCRIPTION

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

Table of Contents , DblVec

NAME

vsy_DblVecClear - clear all doubles to zero

C SPECIFICATION

void vsy_DblVecClear (vsy_DblVec *dblvec)

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.

OUTPUT ARGUMENTS

None

DESCRIPTION

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.

Table of Contents , DblVec

NAME

vsy_DblVecGetPtr - get pointer to start of double vector

C SPECIFICATION

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

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.

OUTPUT ARGUMENTS

ptr          Pointer to start of double vector

DESCRIPTION

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_DblVecSetParami) then the pointer to the double value at index zero is returned, otherwise the pointer to the double value at index one is returned.

Table of Contents , DblVec

NAME

vsy_DblVecMatch - check for matching objects

C SPECIFICATION

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

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.
dblvecm      Pointer to DblVec object.

OUTPUT ARGUMENTS

flag         Matching flag
             =SYS_OFF                 Not matching
             =SYS_ON                  Matching

DESCRIPTION

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

Table of Contents , DblVec

NAME

vsy_DblVecNextIter,vsy_DblVecInitIter - successively visit each nonzero value

C SPECIFICATION

void vsy_DblVecInitIter (vsy_DblVec *dblvec)

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

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.

OUTPUT ARGUMENTS

index        Index of next nonzero value
value        Double value

DESCRIPTION

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.

Table of Contents , DblVec

NAME

vsy_DblVecSet - set a double value at an index

C SPECIFICATION

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

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.
index        Index of set value
value        Double value

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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)

Table of Contents , DblVec

NAME

vsy_DblVecSum - sum a double value at an index

C SPECIFICATION

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

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.
index        Index of set value
value        Double value

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Sum value to the existing value at index.

Table of Contents , DblVec

NAME

vsy_DblVecSetParami - set double vector operation parameters

C SPECIFICATION

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

INPUT ARGUMENTS

dblvec       Pointer to DblVec object.
ptype        Type of parameter to set
             =VSY_INCLUDEZERO        Validity of zero index, iparam
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper ptype is specified.

DESCRIPTION

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.

Table of Contents

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

Begin and end an instance of an object, return object error flag

*vsy_IntDictBegin    - create an instance of a IntDict object
vsy_IntDictEnd       - destroy an instance of a IntDict object
vsy_IntDictError     - return IntDict object error flag

Set and query elements

vsy_IntDictDef       - suggest number of items
           Inq       - get current storage capacity
vsy_IntDictCount     - get number of contained integers
vsy_IntDictInsert    - place integer in the dictionary
vsy_IntDictLookup    - find integer with the specified name
vsy_IntDictClear     - remove all integers
vsy_IntDictInitIter  - prepare to successively visit each integer
vsy_IntDictInitIterOrder - alphabetically by name, visit each integer
vsy_IntDictNextIter  - return the next integer in the sequence

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

Table of Contents

5.6 Function Descriptions

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

Table of Contents , IntDict

NAME

*vsy_IntDictBegin - create an instance of an IntDict object

C SPECIFICATION

vsy_IntDict *vsy_IntDictBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , IntDict

NAME

vsy_IntDictDef - define initial size

C SPECIFICATION

void vsy_IntDictDef (vsy_IntDict *intdict,
                     Vint numint)

INPUT ARGUMENTS

intdict      Pointer to IntDict object.
numint       Estimated number of integers 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 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 a IntDict using

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

Table of Contents , IntDict

NAME

vsy_IntDictCount - get number of contained integers

C SPECIFICATION

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

INPUT ARGUMENTS

intdict      Pointer to IntDict object.

OUTPUT ARGUMENTS

num          Number of integers held the in IntDict object.

DESCRIPTION

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

Table of Contents , IntDict

NAME

vsy_IntDictInsert - place an integer in the dictionary

C SPECIFICATION

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

INPUT ARGUMENTS

intdict      Pointer to IntDict object.
name         String which identifies the integer.
value        Integer value, non zero

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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.

Table of Contents , IntDict

NAME

vsy_IntDictLookup - find the integer at a specified location

C SPECIFICATION

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

INPUT ARGUMENTS

intdict      Pointer to IntDict object.
name         Name of the integer.

OUTPUT ARGUMENTS

value        Integer associated with the specified name.

DESCRIPTION

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.

Table of Contents , IntDict

NAME

vsy_IntDictClear - remove all integers

C SPECIFICATION

void vsy_IntDictClear (vsy_IntDict *intdict)

INPUT ARGUMENTS

intdict      Pointer to IntDict object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Remove all integers

Table of Contents , IntDict

NAME

vsy_IntDictInitIter,vsy_IntDictNextIter - successively visit each integer

C SPECIFICATION

void vsy_IntDictInitIter (vsy_IntDict *intdict)

void vsy_IntDictInitIterOrder (vsy_IntDict *intdict)

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

INPUT ARGUMENTS

intdict      Pointer to IntDict object.

OUTPUT ARGUMENTS

name         Name of the integer
value        Integer associated with name.

DESCRIPTION

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.

Table of Contents

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

Begin and end an instance of an object, return object error flag

*vsy_IntHashBegin    - create an instance of a IntHash object
vsy_IntHashEnd       - destroy an instance of a IntHash object
vsy_IntHashError     - return IntHash object error flag

Set and query elements

vsy_IntHashDef       - define suggested number of stored items
           Inq       - get current storage capacity
vsy_IntHashCount     - get number of contained integers
vsy_IntHashMaxKey    - get maximum key value
vsy_IntHashAllKeys   - get all key values
vsy_IntHashInsert    - place integer at specified location
vsy_IntHashLookup    - find integer at specified location
vsy_IntHashClear     - remove all integers
vsy_IntHashInitIter  - prepare to successively visit each integer
vsy_IntHashInitIterOrder - monotonically increasing integer key
vsy_IntHashNextIter  - return the next integer in the sequence

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.

Table of Contents

5.8 Function Descriptions

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

Table of Contents , IntHash

NAME

*vsy_IntHashBegin - create an instance of a IntHash object

C SPECIFICATION

vsy_IntHash *vsy_IntHashBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an 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)

Table of Contents , IntHash

NAME

vsy_IntHashDef - define initial length of storage array

C SPECIFICATION

void vsy_IntHashDef (vsy_IntHash *inthash,
                     Vint numint)

INPUT ARGUMENTS

inthash      Pointer to IntHash object.
numint       Estimated number of integers 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 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)

Table of Contents , IntHash

NAME

vsy_IntHashCount - get number of contained integers

C SPECIFICATION

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

INPUT ARGUMENTS

inthash      Pointer to IntHash object.

OUTPUT ARGUMENTS

num          Number of integers held the in IntHash object.

DESCRIPTION

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

Table of Contents , IntHash

NAME

vsy_IntHashMaxKey - get maximum key value

C SPECIFICATION

void vsy_IntHashMaxKey (vsy_IntHash *inthash,
                        Vint *maxkey)

INPUT ARGUMENTS

inthash      Pointer to IntHash object.

OUTPUT ARGUMENTS

maxkey       Maximum key value

DESCRIPTION

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

Table of Contents , IntHash

NAME

vsy_IntHashAllKeys - get all key values

C SPECIFICATION

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

INPUT ARGUMENTS

inthash      Pointer to IntHash object.

OUTPUT ARGUMENTS

allkeys      Array of all keys

DESCRIPTION

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.

Table of Contents , IntHash

NAME

vsy_IntHashInsert - place an integer in the hashtable

C SPECIFICATION

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

INPUT ARGUMENTS

inthash      Pointer to IntHash object.
key          Integer key value. 
value        Integer value, non zero

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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.

Table of Contents , IntHash

NAME

vsy_IntHashLookup - find the integer at a specified location

C SPECIFICATION

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

INPUT ARGUMENTS

inthash      Pointer to IntHash object.
key          Integer key of the desired integer.

OUTPUT ARGUMENTS

value        Integer associated with key.

DESCRIPTION

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

Table of Contents , IntHash

NAME

vsy_IntHashClear - remove all integers

C SPECIFICATION

void vsy_IntHashClear (vsy_IntHash *inthash)

INPUT ARGUMENTS

inthash      Pointer to IntHash object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Remove all the integers.

Table of Contents , IntHash

NAME

vsy_IntHashInitIter,vsy_IntHashNextIter - successively visit each integer

C SPECIFICATION

void vsy_IntHashInitIter (vsy_IntHash *inthash)

vsy_IntHashInitIterOrder (vsy_IntHash *inthash)

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

INPUT ARGUMENTS

inthash      Pointer to IntHash object.

OUTPUT ARGUMENTS

key          Key of integer
value        Integer associated with key

DESCRIPTION

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.

Table of Contents

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

Begin and end an instance of an object, return object error flag

*vsy_IntVHashBegin    - create an instance of a IntVHash object
vsy_IntVHashEnd       - destroy an instance of a IntVHash object
vsy_IntVHashError     - return IntVHash object error flag

Set and query elements

vsy_IntVHashDef       - define suggested number of stored items
            Inq       - get current storage capacity
vsy_IntVHashCount     - get number of contained integers
vsy_IntVHashInsert    - place integer at specified location
vsy_IntVHashLookup    - find integer at specified location
vsy_IntVHashClear     - remove all integers
vsy_IntVHashInitIter  - prepare to successively visit each integer
vsy_IntVHashNextIter  - return the next integer in the sequence

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.

Table of Contents

5.10 Function Descriptions

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

Table of Contents , IntVHash

NAME

*vsy_IntVHashBegin - create an instance of a IntVHash object

C SPECIFICATION

vsy_IntVHash *vsy_IntVHashBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an 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)

Table of Contents , IntVHash

NAME

vsy_IntVHashDef - define initial length of storage array

C SPECIFICATION

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

INPUT ARGUMENTS

intvhash     Pointer to IntVHash object.
size         Number of integers per key-vector
numint       Estimated number of integers 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 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)

Table of Contents , IntVHash

NAME

vsy_IntVHashCount - get number of contained integers

C SPECIFICATION

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

INPUT ARGUMENTS

intvhash     Pointer to IntVHash object.

OUTPUT ARGUMENTS

num          Number of integers held the in IntVHash object.

DESCRIPTION

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

Table of Contents , IntVHash

NAME

vsy_IntVHashInsert - place an integer in the hashtable

C SPECIFICATION

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

INPUT ARGUMENTS

intvhash     Pointer to IntVHash object.
key          Integer key values. 
value        Integer value, non zero

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Place the integer 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.

Table of Contents , IntVHash

NAME

vsy_IntVHashLookup - find the integer at a specified location

C SPECIFICATION

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

INPUT ARGUMENTS

intvhash     Pointer to IntVHash object.
key          Integer key values of the desired integer.

OUTPUT ARGUMENTS

value        Integer associated with key.

DESCRIPTION

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

Table of Contents , IntVHash

NAME

vsy_IntVHashClear - remove all integers

C SPECIFICATION

void vsy_IntVHashClear (vsy_IntVHash *intvhash)

INPUT ARGUMENTS

intvhash     Pointer to IntVHash object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Remove all the integers.

Table of Contents , IntVHash

NAME

vsy_IntVHashInitIter,vsy_IntVHashNextIter - successively visit each integer

C SPECIFICATION

void vsy_IntVHashInitIter (vsy_IntVHash *intvhash)

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

INPUT ARGUMENTS

intvhash     Pointer to IntVHash object.

OUTPUT ARGUMENTS

key          Keys of integer
value        Integer associated with key

DESCRIPTION

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.

Table of Contents

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

Begin and end an instance of an object, return object error flag

*vsy_IntQueBegin    - create an instance of a IntQue object
vsy_IntQueEnd       - destroy an instance of a IntQue object
vsy_IntQueError     - return IntQue object error flag

Set and query elements

vsy_IntQueDef       - define suggested number of stored integers
          Inq       - get current storage capacity
vsy_IntQueClear     - remove all integers
vsy_IntQueCount     - get number of contained integers
vsy_IntQueGet       - access and remove earliest integer
vsy_IntQuePut       - put integer in queue
vsy_IntQueRef       - access earliest integer without removal

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.

Table of Contents

5.12 Function Descriptions

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

Table of Contents , IntQue

NAME

*vsy_IntQueBegin - create an instance of a IntQue object

C SPECIFICATION

vsy_IntQue *vsy_IntQueBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an 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)

Table of Contents , IntQue

NAME

vsy_IntQueDef - define suggested number of stored integers

C SPECIFICATION

void vsy_IntQueDef (vsy_IntQue *intque,
                    Vint numint)

INPUT ARGUMENTS

intque       Pointer to IntQue object.
numint       Estimated number of integers 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 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)

Table of Contents , IntQue

NAME

vsy_IntQueCount - get number of contained integers

C SPECIFICATION

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

INPUT ARGUMENTS

intque       Pointer to IntQue object.

OUTPUT ARGUMENTS

num          Number of integers held the in IntQue object.

DESCRIPTION

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

Table of Contents , IntQue

NAME

vsy_IntQuePut - put an integer in the queue

C SPECIFICATION

void vsy_IntQueInsert (vsy_IntQue *intque,
                       Vint value)

INPUT ARGUMENTS

intque       Pointer to IntQue object.
value        Integer value

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Place the integer value in the IntQue object.

Table of Contents , IntQue

NAME

vsy_IntQueRef - access earliest integer without removal

C SPECIFICATION

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

INPUT ARGUMENTS

intque       Pointer to IntQue object.

OUTPUT ARGUMENTS

value        Integer value

DESCRIPTION

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

Table of Contents , IntQue

NAME

vsy_IntQueGet - access and remove earliest integer

C SPECIFICATION

void vsy_IntQueGet (vsy_IntQue *intque,
                    Vint *value)

INPUT ARGUMENTS

intque       Pointer to IntQue object.

OUTPUT ARGUMENTS

value        Integer value

DESCRIPTION

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

Table of Contents , IntQue

NAME

vsy_IntQueClear - remove all integers

C SPECIFICATION

void vsy_IntQueClear (vsy_IntQue *intque)

INPUT ARGUMENTS

intque       Pointer to IntQue object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Remove all the integers.

Table of Contents

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

Begin and end an instance of an object, return object error flag

*vsy_IntVecBegin         - create an instance of a IntVec object
vsy_IntVecEnd            - destroy an instance of a IntVec object
vsy_IntVecError          - return IntVec object error flag
vsy_IntVecCopy           - copy a IntVec

Set and query values

vsy_IntVecAppend         - append value at end of vector
vsy_IntVecClear          - clear all integers to zero
vsy_IntVecCount          - get number of nonzero integers
vsy_IntVecDef            - define initial maximum index
          Inq            - inquire current maximum index
vsy_IntVecGetPtr         - get pointer to start of integer vector
vsy_IntVecMatch          - check for matching objects
vsy_IntVecInitIter       - prepare to successively visit each nonzero
vsy_IntVecNextIter       - return the index of the next nonzero
vsy_IntVecSet            - set a integer value at an index
          Get            - get a integer value at an index
vsy_IntVecSetParami      - set integer vector operation parameters

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.

Table of Contents

5.14 Function Descriptions

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

Table of Contents , IntVec

NAME

*vsy_IntVecBegin - create an instance of an IntVec object

C SPECIFICATION

vsy_IntVec *vsy_IntVecBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)

Table of Contents , IntVec

NAME

vsy_IntVecCount - get number of nonzero values

C SPECIFICATION

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

INPUT ARGUMENTS

intvec       Pointer to IntVec object.

OUTPUT ARGUMENTS

num          Number of nonzero integer values

DESCRIPTION

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.

Table of Contents , IntVec

NAME

vsy_IntVecDef - define initial maximum index

C SPECIFICATION

void vsy_IntVecDef (vsy_IntVec *intvec,
                    Vint maxindex)

INPUT ARGUMENTS

intvec       Pointer to IntVec object.
maxindex     Estimated maximum index addressed

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

DESCRIPTION

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)

Table of Contents , IntVec

NAME

vsy_IntVecAppend - append value at end of vector

C SPECIFICATION

void vsy_IntVecAppend (vsy_IntVec *intvec,
                       Vint value)

INPUT ARGUMENTS

intvec       Pointer to IntVec object.
value        Integer value

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_MEMORY is generated if storage was unable to be allocated.

DESCRIPTION

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

Table of Contents , IntVec

NAME

vsy_IntVecClear - clear all integers to zero

C SPECIFICATION

void vsy_IntVecClear (vsy_IntVec *intvec)

INPUT ARGUMENTS

intvec       Pointer to IntVec object.

OUTPUT ARGUMENTS

None

DESCRIPTION

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.

Table of Contents , IntVec

NAME

vsy_IntVecGetPtr - get pointer to start of integer vector

C SPECIFICATION

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

INPUT ARGUMENTS

intvec       Pointer to IntVec object.

OUTPUT ARGUMENTS

ptr          Pointer to start of integer vector

DESCRIPTION

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.

Table of Contents , IntVec

NAME

vsy_IntVecMatch - check for matching objects

C SPECIFICATION

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

INPUT ARGUMENTS

intvec       Pointer to IntVec object.
intvecm      Pointer to IntVec object.

OUTPUT ARGUMENTS

flag         Matching flag
             =SYS_OFF                 Not matching
             =SYS_ON                  Matching

DESCRIPTION

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

Table of Contents , IntVec

NAME

vsy_IntVecNextIter,vsy_IntVecInitIter - successively visit each nonzero value

C SPECIFICATION

void vsy_IntVecInitIter (vsy_IntVec *intvec)

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

INPUT ARGUMENTS

intvec       Pointer to IntVec object.

OUTPUT ARGUMENTS

index        Index of next nonzero value
value        Integer value

DESCRIPTION

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.

Table of Contents , IntVec

NAME

vsy_IntVecSet - set a integer value at an index

C SPECIFICATION

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

INPUT ARGUMENTS

intvec       Pointer to IntVec object.
index        Index of set value
value        Integer value

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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)

Table of Contents , IntVec

NAME

vsy_IntVecSetParami - set integer vector operation parameters

C SPECIFICATION

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

INPUT ARGUMENTS

intvec       Pointer to IntVec object.
ptype        Type of parameter to set
             =VSY_INCLUDEZERO        Validity of zero index, iparam
iparam       Specifies the integer value that ptype will be set to.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper ptype is specified.

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

5.1 Bit Vectors - BitVec

5.2 Function Descriptions

NAME

C SPECIFICATION

ARGUMENTS

FUNCTION RETURN VALUE

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

ERRORS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

ERRORS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

ERRORS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

5.3 Real Vectors (single FltVec) - DblVec

5.4 Function Descriptions

NAME

C SPECIFICATION

ARGUMENTS

FUNCTION RETURN VALUE

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

ERRORS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

ERRORS

DESCRIPTION

NAME

C SPECIFICATION

INPUT ARGUMENTS

OUTPUT ARGUMENTS

DESCRIPTION

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