Next: , Previous: , Up: Miscellaneous Topics   [Contents][Index]

### 6.2 Ordinary and Sparse Vectors

A vector handle refers to an ordinary or sparse vector.

Data type: qsmm_vec_t

This is a type for a vector handle. It is a pointer, so variables of this type can be `NULL`. The function `qsmm_get_actor_choice_sig_prob_vec` returns the handle of a vector holding the probabilities of emitting output signals by an actor. The function `qsmm_vec_clone` returns the handle of a newly allocated copy of a vector. After using the copy, free its handle by the function `qsmm_vec_destroy`.

Use the following function to get the number of accessible vector elements.

Function: size_t qsmm_get_vec_npos (qsmm_vec_t vec)

This function returns the number of accessible elements in a vector vec. For an ordinary vector, that number might be equal to the length of a vector segment containing elements with set values. For a sparse vector, that number is equal to the number of elements with set values. Normally, it is the number of non-zero elements in the sparse vector.

Use the following function to get the value of an element of a vector.

Function: int qsmm_get_vec_elm_by_pos_d (qsmm_vec_t vec, size_t pos, size_t *idx_p, double *val_p)

This function retrieves the index and value of an element of a vector vec by the access position of this element. The argument pos specifies that access position. It must be less than the number of accessible elements in the vector. If idx_p is not `NULL`, the function sets *idx_p to the index of this element. If val_p is not `NULL`, the function sets *val_p to the value of this element.

On success, the function returns a non-negative value. If the access position is greater than or equal to a value returned by the function `qsmm_get_vec_npos`, the function `qsmm_get_vec_elm_by_pos_d` returns negative error code `QSMM_ERR_INVAL`.

Use the following function to get the access position of an element of a vector by the index of this element.

Function: int qsmm_get_vec_pos_by_idx_v2 (qsmm_vec_t vec, int rez1, size_t idx, size_t *pos_p)

This function retrieves the access position of an element of a vector vec by the index of this element. The argument idx specifies that index. If pos_p is not `NULL`, the function sets *pos_p to that access position. It is less than the number of accessible vector elements returned by the function `qsmm_get_vec_npos`. The argument rez1 is for future use and must be equal to 0.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

`QSMM_ERR_INVAL`

The argument idx is greater than or equal to the number of vector dimensions.

`QSMM_ERR_NOTFOUND`

No such access position for a valid idx—the element at index idx is zero.

For example, to get the value of an element of a vector `vec` at index `idx`, you can use a block of code like this:

```int rc;
double val=0;  // element value
size_t pos=0;  // element access position
if ((rc=qsmm_get_vec_pos_by_idx_v2(vec,0,idx,&pos))>=0) {
rc=qsmm_get_vec_elm_by_pos_d(vec,pos,0,&val);
assert(rc>=0);
}
else assert(rc==QSMM_ERR_NOTFOUND);
```

Use the following function to create a copy of a vector.

Function: int qsmm_vec_clone (qsmm_vec_t vec_src, qsmm_vec_t *vec_dst_p)

This function creates a copy of a vector vec_src and stores the handle of this copy in *vec_dst_p. The copy might occupy less memory compared to the original vector because the function might only copy a segment of an ordinary vector containing elements with set values.

The function returns a non-negative value on success or a negative error code on failure in creating a copy of a vector. Currently, the function can return the following error codes.

`QSMM_ERR_INVAL`

The argument vec_dst_p is `NULL`.

`QSMM_ERR_NOMEM`

There was not enough memory to create a copy of vec_src.

Use the following function to destroy a copy of a vector created by the function `qsmm_vec_clone`.

Function: void qsmm_vec_destroy (qsmm_vec_t vec)

This function destroys a vector specified by a handle vec. You must not use the vector handle after destroying the vector. If vec is `NULL`, the function has no effect.

An application program may only destroy vectors it created by the function `qsmm_vec_clone`. If the application program destroys a vector with a handle returned by the function `qsmm_get_actor_choice_sig_prob_vec`, a memory error occurs later.

Next: , Previous: , Up: Miscellaneous Topics   [Contents][Index]