6.7.3.4 Vector Accessing from C

A vector can be read and modified from C with the functions scm_c_vector_ref and scm_c_vector_set_x, for example. In addition to these functions, there are two more ways to access vectors from C that might be more efficient in certain situations: you can restrict yourself to simple vectors and then use the very fast simple vector macros; or you can use the very general framework for accessing all kinds of arrays (see section Accessing Arrays from C), which is more verbose, but can deal efficiently with all kinds of vectors (and arrays). For vectors, you can use the scm_vector_elements and scm_vector_writable_elements functions as shortcuts.

C Function: int scm_is_simple_vector (SCM obj)

Return non-zero if obj is a simple vector, else return zero. A simple vector is a vector that can be used with the SCM_SIMPLE_* macros below.

The following functions are guaranteed to return simple vectors: scm_make_vector, scm_c_make_vector, scm_vector, scm_list_to_vector.

C Macro: size_t SCM_SIMPLE_VECTOR_LENGTH (SCM vec)

Evaluates to the length of the simple vector vec. No type checking is done.

C Macro: SCM SCM_SIMPLE_VECTOR_REF (SCM vec, size_t idx)

Evaluates to the element at position idx in the simple vector vec. No type or range checking is done.

C Macro: void SCM_SIMPLE_VECTOR_SET (SCM vec, size_t idx, SCM val)

Sets the element at position idx in the simple vector vec to val. No type or range checking is done.

C Function: const SCM * scm_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)

Acquire a handle for the vector vec and return a pointer to the elements of it. This pointer can only be used to read the elements of vec. When vec is not a vector, an error is signaled. The handle must eventually be released with scm_array_handle_release.

The variables pointed to by lenp and incp are filled with the number of elements of the vector and the increment (number of elements) between successive elements, respectively. Successive elements of vec need not be contiguous in their underlying “root vector” returned here; hence the increment is not necessarily equal to 1 and may well be negative too (see section Shared Arrays).

The following example shows the typical way to use this function. It creates a list of all elements of vec (in reverse order).

scm_t_array_handle handle;
size_t i, len;
ssize_t inc;
const SCM *elt;
SCM list;

elt = scm_vector_elements (vec, &handle, &len, &inc);
list = SCM_EOL;
for (i = 0; i < len; i++, elt += inc)
  list = scm_cons (*elt, list);
scm_array_handle_release (&handle);

C Function: SCM * scm_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)

Like scm_vector_elements but the pointer can be used to modify the vector.

The following example shows the typical way to use this function. It fills a vector with #t.

scm_t_array_handle handle;
size_t i, len;
ssize_t inc;
SCM *elt;

elt = scm_vector_writable_elements (vec, &handle, &len, &inc);
for (i = 0; i < len; i++, elt += inc)
  *elt = SCM_BOOL_T;
scm_array_handle_release (&handle);

This document was generated on April 20, 2013 using texi2html 5.0.