op_vvec_insert()
Abstract
Inserts the contents of one vector into another, existing vector.
Syntax
op_vvec_insert (target, position, source)
| Argument | Type | Description |
|---|---|---|
target |
Vvec_Vector |
value vector in which elements from the source will be inserted |
position |
unsigned int |
index number at which the insertion begins [The index number of a vector’s first element is 0.] |
source |
Vvec_Vector |
value vector whose elements are inserted in the target value vector |
Return Type
int
Completion code indicating whether the operation completed successfully.
See Table 95 “Value Vector Completion Code Symbolic Constants“ on page 33 for a list of the possible return values.
Example
/* Create destination vector. */
dest = op_vvec_create (OpC_Type_Bit);
for (i = 0; i < strlen (source_string); i++)
{
/* Convert a string of characters to a string of bits in a value vector. */
op_vvec_from_value (&temp_vec, OPC_VVEC_BYTE_ORDER_LITTLE_ENDIAN,
OPC_VVEC_BITFORMAT_ASCII_8, 8, OPC_VVEC_NATIVE_STRING, source_string);
/* insert this temporary vector into the destination vector. */
/* use OPC_VVEC_VECTOR_END to specify that the values are */
/* appended to the destination vector. */
op_vvec_insert (dest, OPC_VVEC_VECTOR_END, temp_vec);
}
Details
This procedure copies the contents of one vector, the source, into a target vector starting at a specified index number. Any existing values in the target vector are unaffected if they have a lower index number than that specified by the position argument. Values with index numbers equal to or greater than the number specified by position are moved to the end of the value vector, but not destroyed. You may, therefore, insert a vector into the middle of another vector. The data types of both vectors must be the same.
For example, if the target vector consists of {1, 2, 3} and the source vector consists of {8,9}, then inserting the source vector into the target vector at position 1 results in: {1, 8, 9, 2, 3}. (Recall that the first value is index 0.)
You may use symbolic position constants to specify that you want to insert the source vector at the beginning of the target vector (OPC_VVEC_VECTOR_START) or at the end of the target vector (OPC_VVEC_VECTOR_END).
The source vector remains unaffected by this procedure.
Purpose
Provides a way to copy the contents of one vector into another vector without overwriting the target vector’s contents. Instead, the target vector’s contents are moved to make room for the new values.
Errors
- Recoverable Error: Value vector is invalid.
- Recoverable Error: Value types stored in argument value vectors do not match.
- Recoverable Error: Insufficient memory to perform insert.
Reference
- Use the KP op_vvec_remove() to create a new vector consisting of elements removed from another vector
- Use the KP op_vvec_size_get() to determine the number of elements in a vector
- Use the KP op_vvec_type_get() to determine the data type of a vector