[Guile-commits] branch main updated: Remove the 'simple vector' concept

[Daniel Llorens]

This is an automated email from the git hooks/post-receive script.

lloda pushed a commit to branch main
in repository guile.

The following commit(s) were added to refs/heads/main by this push:
     new c2cf685  Remove the 'simple vector' concept
c2cf685 is described below

commit c2cf685b65ee652600ecd914d86e8a00e750b4da
Author: Daniel Llorens <lloda@sarc.name>
AuthorDate: Mon Aug 16 15:26:24 2021 +0200

    Remove the 'simple vector' concept
    
    * Deprecate scm_is_simple_vector.
    * libguile/vectors.c (scm_vector_elements,
      scm_vector_writable_elements): These functions take an array; reword
      to make this clear.
    * libguile/print.h: Remove reference to 'simple vector'.
    * doc/ref/api-data.texi: Remove documentation for scm_is_simple_vector.
      Remove references to 'simple vector'.
      Fix documentation for scm_vector_elements,
      scm_vector_writable_elements.
    * test-suite/tests/arrays.test:
    * test-suite/tests/vectors.test: Remove references to 'simple vector'.
---
 doc/ref/api-data.texi         | 81 ++++++++++++++++++++-----------------------
 doc/ref/srfi-modules.texi     |  6 ++--
 libguile/deprecated.c         |  9 +++++
 libguile/deprecated.h         |  1 +
 libguile/print.h              |  2 +-
 libguile/vectors.c            | 18 ++++------
 libguile/vectors.h            |  7 ++--
 test-suite/tests/arrays.test  |  2 +-
 test-suite/tests/vectors.test |  2 +-
 9 files changed, 62 insertions(+), 66 deletions(-)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index a3e6d6c..b41cffd 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 2e66baf..cf7a4b4 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 e4909df..57cb037 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 c68decf..bd0fae9 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 b9cc20a..5874753 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 40e80dd..a71f51e 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 78abc16..005999a 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 c2716ed..3bf4335 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 8bdbc89..371b518 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"