op_vvec_remove()
Abstract
Removes data elements from an existing vector and returns a new vector containing those elements.
Syntax
op_vvec_remove (source, position, count)
| Argument | Type | Description |
|---|---|---|
source |
Vvec_Vector |
value vector from which elements will be removed [This vector must be an existing vector. Values from this vector will be removed and placed into a new value vector, which is the return value of this procedure.] |
position |
unsigned int |
index number of the first element to be removed from the source |
count |
unsigned int |
number of elements to be removed |
Return Type
Vvec_Vector
Value vector that consists of the elements removed from the source vector.
Example
/* apply 16-bit chunks of a bit value vector on an esys interface. */
for (i = 0; i < (op_vvec_size_get (src_vector) / 16); i++)
{
head = op_vvec_remove (vvec, OPC_VVEC_VECTOR_START, 16);
/* Schedule values on the esys vector interface at 100 ns intervals. */
op_esys_interface_vector_set (intf_id, op_sim_time() + (i * 1e-7), head, 0);
/* done with this value vector. */
op_vvec_destroy (head);
}
/* source vector's data has been send to the esys interface. */
op_vvec_destroy (src_vector);
Details
This procedure allows you to remove specific elements from one vector and create a new vector containing just those elements. The source vector loses both the values and the index positions that were removed. Therefore, the source vector size plus the new vector size equals the size of the original source vector.
For example, if op_vvec_remove() is applied to the vector {1, 2, 3, 4, 5} with a position argument of 1 and a count of 2, the following vectors result:
Original vector: {1, 4, 5}
New vector: {2, 3}
(Recall that the first position in a vector has an index of 0.)
The new value vector is the return value of op_vvec_remove(). It is possible to remove all values of the source vector, thereby leaving a vector of size zero. If the position argument is greater than the last index number in the vector, an empty vector is returned. If the count argument causes the procedure to reach or exceed the end of the vector, all values in the vector from position to the end appear in the new vector.
Both the source vector and the new vector must be eventually destroyed. Even if it is left at size zero, the source vector is never destroyed as a result of this procedure.
Purpose
Provides a mechanism to move specific elements of one vector into another vector.
Errors
- Recoverable Error: Value vector is invalid.
- Recoverable Error: Insufficient memory to perform remove.
Reference
- Use the KP op_vvec_create() to create a new vector
- Use the KP op_vvec_destroy() to deallocate memory assigned to a vector
- Use the KP op_vvec_insert() to place elements from one vector into another