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

### 6.2 Ordinary and Sparse Vectors

In QSMM, an ordinary or sparse vector is referred to by a vector handle.

Data type: qsmm_vec_t

This is a type for a vector handle. It is a pointer, so variables of this type can have the `NULL` value. The handle of a vector, which holds probabilities of emitting output signals by an actor, is returned by the function `qsmm_get_actor_choice_sig_prob_vec`. The handle of a newly allocated vector, which is a copy of the other vector, is returned by the function `qsmm_vec_clone`. After using the copy, its handle should be freed by the function `qsmm_vec_destroy`.

To get the number of accessible vector elements, the following function can be used.

Function: int qsmm_get_vec_npos (qsmm_vec_t vec)

This function returns the number of accessible elements of vector vec. The returned value is always non-negative. For an ordinary vector, this number might be equal to the length of a segment of elements, which values were set for the vector. For a sparse vector, this number is equal to the number of elements, which values were set for the vector. Normally, it is the number of non-zero elements in the sparse vector.

To get the value of an element of a vector, the following function can be used.

Function: int qsmm_get_vec_elm_by_pos (qsmm_vec_t vec, int pos, double *valp)

This function sets *valp to a value of an element of vector vec at position pos. If valp is `NULL`, then *valp will not be set. The value of pos must be non-negative and less than the number of accessible vector elements.

On success, the function returns a non-negative index of an element of the vector that corresponds to position pos. If pos is negative or is greater than or equal to a value returned by the function `qsmm_get_vec_npos` for the vector, then negative error code `QSMM_ERR_NOTFOUND` will be returned.

To get a position of an element of a vector by its index, the following function can be used.

Function: int qsmm_get_vec_pos_by_idx (qsmm_vec_t vec, int idx)

This function returns the position of an element of vector vec at index idx. The position is a non-negative number less than the number of accessible vector elements returned by the function `qsmm_get_vec_npos` for the vector.

On success, the function returns a non-negative position of an element of the vector that corresponds to index idx. If there is no such position, then negative error code `QSMM_ERR_NOTFOUND` will be returned. When idx is non-negative and is less than the number of vector dimensions, this means that the value of the element at index idx is 0.

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

```int rc;
double val=0;  // value of the element
if ((rc=qsmm_get_vec_pos_by_idx(vec,idx))>=0)
qsmm_get_vec_elm_by_pos(vec,rc,&val);
```

To create a copy of a vector, the following function can be used.

Function: int qsmm_vec_clone (qsmm_vec_t src, qsmm_vec_t *dst_p)

This function creates a copy of vector src and stores its newly allocated vector handle in *dst_p. The copy might occupy a lesser amount of memory than the original because, for an ordinary vector, there might be copied only a segment of elements, which values were set for the vector.

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

`QSMM_ERR_INVAL`

Argument dst_p is `NULL`.

`QSMM_ERR_NOMEM`

There was not enough memory to create a copy of the vector.

To destroy a copy of a vector created using a call to `qsmm_vec_clone`, the following function can be used.

Function: void qsmm_vec_destroy (qsmm_vec_t vec)

This function destroys a vector specified by handle vec. After vector destruction, the vector handle must not be used. If vec is `NULL`, then the function will have no effect.

An application program is only allowed to destroy vectors created by the function `qsmm_vec_clone`. If the application program destroys a vector, which handle was returned by the function `qsmm_get_actor_choice_sig_prob_vec`, then a segmentation fault will occur later.

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