8.3.5 Vector views

In addition to creating vectors from slices of blocks it is also possible to slice vectors and create vector views. For example, a subvector of another vector can be described with a view, or two views can be made which provide access to the even and odd elements of a vector.

A vector view is a temporary object, stored on the stack, which can be used to operate on a subset of vector elements. Vector views can be defined for both constant and non-constant vectors, using separate types that preserve constness. A vector view has the type gsl_vector_view and a constant vector view has the type gsl_vector_const_view. In both cases the elements of the view can be accessed as a gsl_vector using the vector component of the view object. A pointer to a vector of type gsl_vector * or const gsl_vector * can be obtained by taking the address of this component with the & operator.

When using this pointer it is important to ensure that the view itself remains in scope—the simplest way to do so is by always writing the pointer as &view.vector, and never storing this value in another variable.

Function: gsl_vector_view gsl_vector_subvector (gsl_vector * v, size_t offset, size_t n)

Function: gsl_vector_const_view gsl_vector_const_subvector (const gsl_vector * v, size_t offset, size_t n)

These functions return a vector view of a subvector of another vector v. The start of the new vector is offset by offset elements from the start of the original vector. The new vector has n elements. Mathematically, the i-th element of the new vector v' is given by,

v'(i) = v->data[(offset + i)*v->stride]

where the index i runs from 0 to n-1.

The data pointer of the returned vector struct is set to null if the combined parameters (offset,n) overrun the end of the original vector.

The new vector is only a view of the block underlying the original vector, v. The block containing the elements of v is not owned by the new vector. When the view goes out of scope the original vector v and its block will continue to exist. The original memory can only be deallocated by freeing the original vector. Of course, the original vector should not be deallocated while the view is still in use.

The function gsl_vector_const_subvector is equivalent to gsl_vector_subvector but can be used for vectors which are declared const.

Function: gsl_vector_view gsl_vector_subvector_with_stride (gsl_vector * v, size_t offset, size_t stride, size_t n)

Function: gsl_vector_const_view gsl_vector_const_subvector_with_stride (const gsl_vector * v, size_t offset, size_t stride, size_t n)

These functions return a vector view of a subvector of another vector v with an additional stride argument. The subvector is formed in the same way as for gsl_vector_subvector but the new vector has n elements with a step-size of stride from one element to the next in the original vector. Mathematically, the i-th element of the new vector v' is given by,

v'(i) = v->data[(offset + i*stride)*v->stride]

where the index i runs from 0 to n-1.

Note that subvector views give direct access to the underlying elements of the original vector. For example, the following code will zero the even elements of the vector v of length n, while leaving the odd elements untouched,

gsl_vector_view v_even = gsl_vector_subvector_with_stride (v, 0, 2, n/2); gsl_vector_set_zero (&v_even.vector);

A vector view can be passed to any subroutine which takes a vector argument just as a directly allocated vector would be, using &view.vector. For example, the following code computes the norm of the odd elements of v using the BLAS routine DNRM2,

gsl_vector_view v_odd = gsl_vector_subvector_with_stride (v, 1, 2, n/2); double r = gsl_blas_dnrm2 (&v_odd.vector);

The function gsl_vector_const_subvector_with_stride is equivalent to gsl_vector_subvector_with_stride but can be used for vectors which are declared const.

Function: gsl_vector_view gsl_vector_complex_real (gsl_vector_complex * v)

Function: gsl_vector_const_view gsl_vector_complex_const_real (const gsl_vector_complex * v)

These functions return a vector view of the real parts of the complex vector v.

The function gsl_vector_complex_const_real is equivalent to gsl_vector_complex_real but can be used for vectors which are declared const.

Function: gsl_vector_view gsl_vector_complex_imag (gsl_vector_complex * v)

Function: gsl_vector_const_view gsl_vector_complex_const_imag (const gsl_vector_complex * v)

These functions return a vector view of the imaginary parts of the complex vector v.

The function gsl_vector_complex_const_imag is equivalent to gsl_vector_complex_imag but can be used for vectors which are declared const.

Function: gsl_vector_view gsl_vector_view_array (double * base, size_t n)

Function: gsl_vector_const_view gsl_vector_const_view_array (const double * base, size_t n)

These functions return a vector view of an array. The start of the new vector is given by base and has n elements. Mathematically, the i-th element of the new vector v' is given by,

v'(i) = base[i]

where the index i runs from 0 to n-1.

The array containing the elements of v is not owned by the new vector view. When the view goes out of scope the original array will continue to exist. The original memory can only be deallocated by freeing the original pointer base. Of course, the original array should not be deallocated while the view is still in use.

The function gsl_vector_const_view_array is equivalent to gsl_vector_view_array but can be used for arrays which are declared const.

Function: gsl_vector_view gsl_vector_view_array_with_stride (double * base, size_t stride, size_t n)

Function: gsl_vector_const_view gsl_vector_const_view_array_with_stride (const double * base, size_t stride, size_t n)

These functions return a vector view of an array base with an additional stride argument. The subvector is formed in the same way as for gsl_vector_view_array but the new vector has n elements with a step-size of stride from one element to the next in the original array. Mathematically, the i-th element of the new vector v' is given by,

v'(i) = base[i*stride]

where the index i runs from 0 to n-1.

Note that the view gives direct access to the underlying elements of the original array. A vector view can be passed to any subroutine which takes a vector argument just as a directly allocated vector would be, using &view.vector.

The function gsl_vector_const_view_array_with_stride is equivalent to gsl_vector_view_array_with_stride but can be used for arrays which are declared const.