diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index a3e6d6c31..b41cffdef 100644 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -6214,12 +6214,12 @@ accessed element in the list. Vectors can contain any kind of Scheme object; it is even possible to have different types of objects in the same vector. For vectors -containing vectors, you may wish to use arrays, instead. Note, too, -that vectors are the special case of one dimensional non-uniform arrays -and that most array procedures operate happily on vectors -(@pxref{Arrays}). +containing vectors, you may wish to use @ref{Arrays,arrays} instead. +Note, too, that vectors are a special case of one dimensional +non-uniform arrays and that array procedures operate happily on vectors. -Also see @ref{SRFI-43}, for a comprehensive vector library. +Also see @ref{SRFI-43}, @ref{R6RS Support}, or @ref{R7RS Support}, for +more comprehensive vector libraries. @menu * Vector Syntax:: Read syntax for vectors. @@ -6349,6 +6349,7 @@ Return the contents of position @var{k} of @var{vec}. @end lisp @end deffn +@anchor{x-scm_c_vector_ref} @deftypefn {C Function} SCM scm_c_vector_ref (SCM vec, size_t k) Return the contents of position @var{k} (a @code{size_t}) of @var{vec}. @@ -6376,6 +6377,7 @@ The value returned by @samp{vector-set!} is unspecified. @end lisp @end deffn +@anchor{x-scm_c_vector_set_x} @deftypefn {C Function} void scm_c_vector_set_x (SCM vec, size_t k, SCM obj) Store @var{obj} in position @var{k} (a @code{size_t}) of @var{vec}. @end deftypefn @@ -6447,58 +6449,48 @@ The value returned by @code{vector-move-right!} is unspecified. @subsubsection Vector Accessing from C A vector can be read and modified from C with the functions -@code{scm_c_vector_ref} and @code{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 @dfn{simple vectors} and then use the very fast -@emph{simple vector macros}; or you can use the very general framework -for accessing all kinds of arrays (@pxref{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 -@code{scm_vector_elements} and @code{scm_vector_writable_elements} -functions as shortcuts. - -@deftypefn {C Function} int scm_is_simple_vector (SCM obj) -Return non-zero if @var{obj} is a simple vector, else return zero. A -simple vector is a vector that can be used with the @code{SCM_SIMPLE_*} -macros below. - -The following functions are guaranteed to return simple vectors: -@code{scm_make_vector}, @code{scm_c_make_vector}, @code{scm_vector}, -@code{scm_list_to_vector}. -@end deftypefn +@ref{x-scm_c_vector_ref,@code{scm_c_vector_ref}} and +@ref{x-scm_c_vector_set_x,@code{scm_c_vector_set_x}}. In addition to +these functions, there are two other ways to access vectors from C that +might be more efficient in certain situations: you can use the unsafe +@emph{vector macros}; or you can use the general framework for accessing +all kinds of arrays (@pxref{Accessing Arrays from C}), which is more +verbose, but can deal efficiently with all kinds of vectors (and +arrays). For arrays of rank 1 whose backing store is a vector, you can +use the @code{scm_vector_elements} and +@code{scm_vector_writable_elements} functions as shortcuts. @deftypefn {C Macro} size_t SCM_SIMPLE_VECTOR_LENGTH (SCM vec) -Evaluates to the length of the simple vector @var{vec}. No type +Evaluates to the length of the vector @var{vec}. No type checking is done. @end deftypefn @deftypefn {C Macro} SCM SCM_SIMPLE_VECTOR_REF (SCM vec, size_t idx) -Evaluates to the element at position @var{idx} in the simple vector -@var{vec}. No type or range checking is done. +Evaluates to the element at position @var{idx} in the vector @var{vec}. +No type or range checking is done. @end deftypefn @deftypefn {C Macro} void SCM_SIMPLE_VECTOR_SET (SCM vec, size_t idx, SCM val) -Sets the element at position @var{idx} in the simple vector -@var{vec} to @var{val}. No type or range checking is done. +Sets the element at position @var{idx} in the vector @var{vec} to +@var{val}. No type or range checking is done. @end deftypefn -@deftypefn {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 @var{vec} and return a pointer to the -elements of it. This pointer can only be used to read the elements of -@var{vec}. When @var{vec} is not a vector, an error is signaled. The -handle must eventually be released with -@code{scm_array_handle_release}. +@deftypefn {C Function} {const SCM *} scm_vector_elements (SCM array, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +Acquire a @ref{Accessing Arrays from C,handle} for @var{array} and +return a read-only pointer to its elements. @var{array} must be either +a vector, or an array of rank 1 whose backing store is a vector; +otherwise an error is signaled. The handle must eventually be released +with @ref{x-scm_array_handle_release,@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 (number of +the number of elements of the array and the increment (number of elements) between successive elements, respectively. Successive -elements of @var{vec} need not be contiguous in their underlying +elements of @var{array} 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 @var{vec} (in reverse order). +creates a list of all elements of @var{array} (in reverse order). @example scm_t_array_handle handle; @@ -6507,7 +6499,7 @@ ssize_t inc; const SCM *elt; SCM list; -elt = scm_vector_elements (vec, &handle, &len, &inc); +elt = scm_vector_elements (array, &handle, &len, &inc); list = SCM_EOL; for (i = 0; i < len; i++, elt += inc) list = scm_cons (*elt, list); @@ -6516,12 +6508,12 @@ scm_array_handle_release (&handle); @end deftypefn -@deftypefn {C Function} {SCM *} scm_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) +@deftypefn {C Function} {SCM *} scm_vector_writable_elements (SCM array, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) Like @code{scm_vector_elements} but the pointer can be used to modify -the vector. +the array. The following example shows the typical way to use this function. It -fills a vector with @code{#t}. +fills an array with @code{#t}. @example scm_t_array_handle handle; @@ -6529,7 +6521,7 @@ size_t i, len; ssize_t inc; SCM *elt; -elt = scm_vector_writable_elements (vec, &handle, &len, &inc); +elt = scm_vector_writable_elements (array, &handle, &len, &inc); for (i = 0; i < len; i++, elt += inc) *elt = SCM_BOOL_T; scm_array_handle_release (&handle); @@ -8024,6 +8016,7 @@ by @var{handle} does not need to be initialized before calling this function. @end deftypefn +@anchor{x-scm_array_handle_release} @deftypefn {C Function} void scm_array_handle_release (scm_t_array_handle *handle) End the array reservation represented by @var{handle}. After a call to this function, @var{handle} might be used for another reservation. diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 2e66bafb9..cf7a4b410 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -1734,9 +1734,9 @@ indicated kind. @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} (@pxref{Vector Accessing from -C}), 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 @node SRFI-4 and Bytevectors diff --git a/libguile/deprecated.c b/libguile/deprecated.c index e4909dfc6..57cb037d2 100644 --- a/libguile/deprecated.c +++ b/libguile/deprecated.c @@ -42,6 +42,7 @@ #include "srfi-4.h" #include "strings.h" #include "symbols.h" +#include "vectors.h" #include "deprecated.h" @@ -96,6 +97,14 @@ scm_find_executable (const char *name) +int +scm_is_simple_vector (SCM obj) +{ + scm_c_issue_deprecation_warning + ("scm_is_simple_vector is deprecated. Use scm_is_vector instead."); + return SCM_I_IS_VECTOR (obj); +} + SCM scm_bitvector_p (SCM vec) { diff --git a/libguile/deprecated.h b/libguile/deprecated.h index c68decf74..bd0fae9d5 100644 --- a/libguile/deprecated.h +++ b/libguile/deprecated.h @@ -115,6 +115,7 @@ typedef struct scm_thread scm_i_thread SCM_DEPRECATED_TYPE; SCM_DEPRECATED char* scm_find_executable (const char *name); +SCM_DEPRECATED int scm_is_simple_vector (SCM obj); SCM_DEPRECATED SCM scm_bitvector_p (SCM vec); SCM_DEPRECATED SCM scm_bitvector (SCM bits); SCM_DEPRECATED SCM scm_make_bitvector (SCM len, SCM fill); diff --git a/libguile/print.h b/libguile/print.h index b9cc20a6b..587475362 100644 --- a/libguile/print.h +++ b/libguile/print.h @@ -74,7 +74,7 @@ typedef struct scm_print_state { unsigned long ceiling; /* Max size of reference stack */ SCM ref_vect; /* Stack of references used during circular reference detection; - a simple vector. */ + a vector. */ SCM highlight_objects; /* List of objects to be highlighted */ } scm_print_state; diff --git a/libguile/vectors.c b/libguile/vectors.c index 40e80ddd2..a71f51e28 100644 --- a/libguile/vectors.c +++ b/libguile/vectors.c @@ -55,21 +55,15 @@ scm_is_vector (SCM obj) return SCM_I_IS_VECTOR (obj); } -int -scm_is_simple_vector (SCM obj) -{ - return SCM_I_IS_VECTOR (obj); -} - const SCM * -scm_vector_elements (SCM vec, scm_t_array_handle *h, +scm_vector_elements (SCM array, scm_t_array_handle *h, size_t *lenp, ssize_t *incp) { - scm_array_get_handle (vec, h); + scm_array_get_handle (array, h); if (1 != scm_array_handle_rank (h)) { scm_array_handle_release (h); - scm_wrong_type_arg_msg (NULL, 0, vec, "rank 1 array of Scheme values"); + scm_wrong_type_arg_msg (NULL, 0, array, "rank 1 array of Scheme values"); } if (lenp) @@ -82,13 +76,13 @@ scm_vector_elements (SCM vec, scm_t_array_handle *h, } SCM * -scm_vector_writable_elements (SCM vec, scm_t_array_handle *h, +scm_vector_writable_elements (SCM array, scm_t_array_handle *h, size_t *lenp, ssize_t *incp) { - const SCM *ret = scm_vector_elements (vec, h, lenp, incp); + const SCM *ret = scm_vector_elements (array, h, lenp, incp); if (h->writable_elements != h->elements) - scm_wrong_type_arg_msg (NULL, 0, vec, "mutable vector"); + scm_wrong_type_arg_msg (NULL, 0, array, "mutable rank 1 array of Scheme values"); return (SCM *) ret; } diff --git a/libguile/vectors.h b/libguile/vectors.h index 78abc16f2..005999a2b 100644 --- a/libguile/vectors.h +++ b/libguile/vectors.h @@ -45,15 +45,14 @@ SCM_API SCM scm_vector_copy_partial (SCM vec, SCM start, SCM end); SCM_API SCM scm_vector_copy_x (SCM dst, SCM at, SCM src, SCM start, SCM end); SCM_API int scm_is_vector (SCM obj); -SCM_API int scm_is_simple_vector (SCM obj); SCM_API SCM scm_c_make_vector (size_t len, SCM fill); SCM_API size_t scm_c_vector_length (SCM vec); SCM_API SCM scm_c_vector_ref (SCM vec, size_t k); SCM_API void scm_c_vector_set_x (SCM vec, size_t k, SCM obj); -SCM_API const SCM *scm_vector_elements (SCM vec, +SCM_API const SCM *scm_vector_elements (SCM array, scm_t_array_handle *h, size_t *lenp, ssize_t *incp); -SCM_API SCM *scm_vector_writable_elements (SCM vec, +SCM_API SCM *scm_vector_writable_elements (SCM array, scm_t_array_handle *h, size_t *lenp, ssize_t *incp); @@ -67,7 +66,7 @@ SCM_API SCM *scm_vector_writable_elements (SCM vec, SCM_ASSERT (scm_is_vector (v) && len == scm_c_vector_length (v), v, pos, FUNC_NAME); \ } while (0) -/* Fast, non-checking accessors for simple vectors. +/* Fast, non-checking accessors */ #define SCM_SIMPLE_VECTOR_LENGTH(x) SCM_I_VECTOR_LENGTH(x) #define SCM_SIMPLE_VECTOR_REF(x,idx) ((SCM_I_VECTOR_ELTS(x))[idx]) diff --git a/test-suite/tests/arrays.test b/test-suite/tests/arrays.test index c2716ed17..3bf433582 100644 --- a/test-suite/tests/arrays.test +++ b/test-suite/tests/arrays.test @@ -419,7 +419,7 @@ (eq? a (array-contents (make-shared-array a (const '(0))))) (eq? a (array-contents (make-shared-array a (const '(0))) #t))))) - (pass-if "simple vector" + (pass-if "plain vector" (let* ((a (make-array 0 4))) (eq? a (array-contents a)))) diff --git a/test-suite/tests/vectors.test b/test-suite/tests/vectors.test index 8bdbc89bc..371b51840 100644 --- a/test-suite/tests/vectors.test +++ b/test-suite/tests/vectors.test @@ -42,7 +42,7 @@ (with-test-prefix "vector->list" - (pass-if "simple vector" + (pass-if "plain vector" (equal? '(1 2 3) (vector->list #(1 2 3)))) (pass-if "string vector 1"