Re: propose deprecation of generalized-vector-*

[Daniel Llorens <daniel.llorens@bluewin.ch>]

[-- Attachment #1: Type: text/plain, Size: 3041 bytes --]


On Jan 21, 2013, at 17:11, Andy Wingo wrote:

> Hi,
> 
> Sorry for the long delay.
> 
> Deprecating the generalized-vector functions sounds mostly sensible to
> me, and the proposed semantics of array-length sound fine.  Attached is
> a first patch in that direction.

The changes look good to me. The patch attached applies over yours and is to document this function and a couple others in the manual.

> However, before going further, some thoughts.
> 
> Firstly, array-set! has a different interface from
> generalized-vector-set!; a shame to change already sensible uses of
> generalized-vector-set!.  But I am OK with that.

It's worse from C where one has to build a list explicitly. Maybe we should have scm_array_ref_1, scm_array_ref_2, etc. as it is done for some other functions taking rest lists. I can write a patch for that. But the argument order can't be helped.

> I think it's a useful simplification, mentally, to be able to treat
> generic one-dimensional indexed sequences as vectors instead of arrays.
> The feedback that you get from documentation and the editor is nicer
> when you don't have to deal with variable arity.  Though I like removing
> needless code, it seems to me that this abstraction does have some minor
> benefit.

I think this is a good argument for including the rank in a type system or for doing static analysis on rank, because the rank of arrays can often be determined statically. The compiler should know and this knowledge would help in debugging. But this is true for rank 2 or higher, not only for rank 1.

As an interface, I prefer uniformity. My inclination whenever I use arrays is to use only the array- functions and forget about the vector- functions.

> I always wondered why vector-ref and vector-set! didn't do what
> generalized-vector-ref and generalized-vector-set! did.  I mean, they
> are primitive generics.  Might it make sense to allow vector-ref to
> operate as generalized-vector-ref did?  I really don't know, myself...

I think this is fair for type polymorphism. It makes sense to let vector- work on uniform vectors because the implementation should be identical.

It's different for arrays because even for the 1D case you need a stride and an indirection (and in the current Guile, also bounds).

That is, I think that the main distinction is not between rank=1 and rank!=1 objects, but between ‘container’ and ‘views’ (if this makes sense). This is why generalized-vector- was bad. It was an if x, do X, if y, do Y kind of abstraction.

> Finally, if we are doing this, then we should also deprecate the
> pseudo-polymorphic uniform-vector-ref set of functions as well.

If vector-set / -ref / -length works on these, they are not needed, I agree. Some of the uniform-vector functions are still needed because they handle the element type.

So we would have array- / typed-array- functions for ‘views’ of any rank, and vector- / uniform-vector- functions for ‘containers’ of rank 1.

Does this make sense?



[-- Attachment #2: 0001-Array-documentation-fixes.patch --]
[-- Type: application/octet-stream, Size: 2993 bytes --]

From b096700697eeeefed31e4025ec5e30b85b7e1d13 Mon Sep 17 00:00:00 2001
From: Daniel Llorens <daniel.llorens@bluewin.ch>
Date: Tue, 22 Jan 2013 13:01:14 +0100
Subject: [PATCH] Array documentation fixes

* libguile/generalized-arrays.c: Fix wording of docstring for array-length.
* doc/ref/api-compund.texi:
  - Document scm_array_type(), scm_array_ref(), array-length,
    scm_array_length(), scm_c_array_length().
  - Fix wording of documentation for array-in-bounds?
---
 doc/ref/api-compound.texi     |   11 ++++++++++-
 libguile/generalized-arrays.c |    5 ++---
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 9cd5468..b32cc91 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -1392,6 +1392,7 @@ as elements in the list.
 @end deffn
 
 @deffn {Scheme Procedure} array-type array
+@deffnx {C Function} scm_array_type (array)
 Return the type of @var{array}.  This is the `vectag' used for
 printing @var{array} (or @code{#t} for ordinary arrays) and can be
 used with @code{make-typed-array} to create an array of the same kind
@@ -1399,6 +1400,7 @@ as @var{array}.
 @end deffn
 
 @deffn {Scheme Procedure} array-ref array idx @dots{}
+@deffnx {C Function} scm_array_ref (array, idxlist)
 Return the element at @code{(idx @dots{})} in @var{array}.
 
 @example
@@ -1409,7 +1411,7 @@ Return the element at @code{(idx @dots{})} in @var{array}.
 
 @deffn {Scheme Procedure} array-in-bounds? array idx @dots{}
 @deffnx {C Function} scm_array_in_bounds_p (array, idxlist)
-Return @code{#t} if the given index would be acceptable to
+Return @code{#t} if the given indices would be acceptable to
 @code{array-ref}.
 
 @example
@@ -1450,6 +1452,13 @@ For example,
 @end example
 @end deffn
 
+@deffn {Scheme Procedure} array-length array
+@deffnx {C Function} scm_array_length (array)
+@deffnx {C Function} size_t scm_c_array_length (array)
+Return the length of an array: its first dimension. It is an error to
+ask for the length of an array of rank 0.
+@end deffn
+
 @deffn {Scheme Procedure} array-rank array
 @deffnx {C Function} scm_array_rank (array)
 Return the rank of @var{array}.
diff --git a/libguile/generalized-arrays.c b/libguile/generalized-arrays.c
index 706779e..f2e17e9 100644
--- a/libguile/generalized-arrays.c
+++ b/libguile/generalized-arrays.c
@@ -127,9 +127,8 @@ scm_c_array_length (SCM array)
 
 SCM_DEFINE (scm_array_length, "array-length", 1, 0, 0,
            (SCM array),
-	    "Return the length of an array: the dimension of its first\n"
-            "dimension.  It is an error to ask for the length of an\n"
-            "array of rank 0.")
+	    "Return the length of an array: its first dimension.\n"
+            "It is an error to ask for the length of an array of rank 0.")
 #define FUNC_NAME s_scm_array_rank
 {
   return scm_from_size_t (scm_c_array_length (array));
-- 
1.7.9.5