Re: SRFI-4 in Guile 1.7

[Ludovic Courtès]

Marius Vollmer <address@hidden> writes:

> No, you can't.  The increment gives the number of _elements_ between
> the real elements of the vector in memory, not the number of _bytes_.
> Very nearly all vectors will have an increment of 1, but not all.  See
> "Shared Arrays" in the manual: shared arrays of rank one are vectors,
> but they don't need to be stored contiguously in memory.
>
> For example, the diagonal of a 3x3 matrix is a vector, and to go from
> one element of this vector to the next, you need to skip 4 elements in
> memory (one full row of the matrix plus one more).  Such a vector has
> an increment of 4.
>
> The size of an element in a uniform numeric vector can be retrieved
> with scm_array_handle_uniform_element_size, if you need it.

Thanks for the clarification.  I had not learned about shared arrays
yet.

> Maybe we could improve the manual.  Do you have a suggestion?

How about the following (patch against 1.7.2)?

diff -ubB --show-c-function 
/home/ludo/tmp/guile-1.7.2/doc/ref/api-compound.texi\~ 
/home/ludo/tmp/guile-1.7.2/doc/ref/api-compound.texi
--- /home/ludo/tmp/guile-1.7.2/doc/ref/api-compound.texi~       2005-03-06 
13:54:55.000000000 +0100
+++ /home/ludo/tmp/guile-1.7.2/doc/ref/api-compound.texi        2005-03-23 
14:16:48.000000000 +0100
@@ -885,11 +885,14 @@ handle mustr eventually be released with
 @code{scm_array_handle_release}.
 
 The variables pointed to by @var{lenp} and @var{incp} are filled with
-the number of elements of the vector and the increment between elements,
-respectively.  Note that the increment can well be negative.
+the number of elements of the vector and the increment (number of
+elements) between successive elements, respectively.  Successive
+elements of @var{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 (@pxref{Shared Arrays}).
 
 The following example shows the typical way to use this function.  It
-creates a list of all elements of @code{vec} (in reverse order).
+creates a list of all elements of @var{vec} (in reverse order).
 
 @example
 scm_t_array_handle handle;
@@ -1352,8 +1355,9 @@ Return the number of elements of @var{uv
 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, 
scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, 
scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, 
scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
-Like @code{scm_vector_elements} (which see), but returns a pointer to
-the elements of a uniform numeric vector of the indicated kind.
+Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
+returns a pointer to the elements of a uniform numeric vector of the
+indicated kind.
 @end deftypefn
 
 @deftypefn  {C Function} {void *} scm_uniform_vector_writable_elements (SCM 
vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
@@ -1369,8 +1373,9 @@ the elements of a uniform numeric vector
 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, 
scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, 
scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, 
scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
-Like @code{scm_vector_writable_elements} (which see), but returns a
-pointer to the elements of a uniform numeric vector of the indicated kind.
+Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
+C}), but returns a pointer to the elements of a uniform numeric vector
+of the indicated kind.
 @end deftypefn
 
 @deffn {Scheme Procedure} uniform-vector-read! uvec [port_or_fd [start [end]]]
@@ -1595,11 +1600,11 @@ For example,
 @end deffn
 
 @deftypefn {C Function} {const scm_t_uint32 *} scm_bitvector_elements (SCM 
vec, scm_t_array_handle *handle, size_t *offp, size_t *lenp, ssize_t *incp)
-Like @code{scm_vector_elements} (which see), but for bitvectors.  The
-variable pointed to by @var{offp} is set to the value returned by
address@hidden  See
address@hidden for how to use the returned pointer
-and the offset.
+Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
+for bitvectors.  The variable pointed to by @var{offp} is set to the
+value returned by @code{scm_array_handle_bit_elements_offset}.  See
address@hidden for how to use the returned
+pointer and the offset.
 @end deftypefn
 
 @deftypefn {C Function} {scm_t_uint32 *} scm_bitvector_writable_elements (SCM 
vec, scm_t_array_handle *handle, size_t *offp, size_t *lenp, ssize_t *incp)


Thanks,
Ludovic.