1.0.23.17: new function: SIMPLE-ARRAY-VECTOR

 * For users to extract the underlying vector from a multidimensional
   array. Warn about implementation-detail nature of this.

 * Add Miscellaneuous Extensions section to Beyond ANSI chapter in the
   manual.

diff --git a/NEWS b/NEWS
index 1e2de05..ea6743c 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,6 @@
 ;;;; -*- coding: utf-8; -*-
+  * new feature: SIMPLE-ARRAY-VECTOR provides access to the underlying
+    data vector of an multidimensional SIMPLE-ARRAY.
   * optimization: faster generic arithmetic dispatch on x86 and x86-64.
   * bug fix: lexical type declarations are now correctly reported by
     SB-CLTL2. (reported by Larry D'Anna)

diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo
index 78aa623..c2937d5 100644 (file)
--- a/doc/manual/beyond-ansi.texinfo
+++ b/doc/manual/beyond-ansi.texinfo
@@ -7,14 +7,15 @@ ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
 it still has quite a few.  @xref{Contributed Modules}.
 
 @menu
-* Garbage Collection::          
-* Metaobject Protocol::         
-* Support For Unix::            
-* Customization Hooks for Users::  
-* Tools To Help Developers::    
-* Resolution of Name Conflicts::  
-* Stale Extensions::            
-* Efficiency Hacks::            
+* Garbage Collection::
+* Metaobject Protocol::
+* Support For Unix::
+* Customization Hooks for Users::
+* Tools To Help Developers::
+* Resolution of Name Conflicts::
+* Miscellaneous Extensions::
+* Stale Extensions::
+* Efficiency Hacks::
 @end menu
 
 @node  Garbage Collection
@@ -43,7 +44,7 @@ with AMOP; present exceptions to this (as distinct from current bugs)
 are:
 
 @itemize
-  
+
 @item
 @findex compute-effective-method
 @findex sb-mop:compute-effective-method
@@ -67,7 +68,7 @@ the standardized classes before @code{t} appearing in the class
 precedence list of @code{generic-function} and
 @code{standard-generic-function}, as required by section 1.4.4.5 of the
 ANSI specification.
-  
+
 @item
 @findex ensure-generic-function
 @findex generic-function-declarations
@@ -261,7 +262,7 @@ between classes and proper names and between lists of the form
 @vindex *posix-argv*
 
 The UNIX command line can be read from the variable
-@code{sb-ext:*posix-argv*}. 
+@code{sb-ext:*posix-argv*}.
 
 @node Querying the process environment
 @subsection Querying the process environment
@@ -375,6 +376,12 @@ the @code{sb-ext:resolve-conflict} restart should be invoked with one
 argument, which should be a member of the list returned by the condition
 accessor @code{sb-ext:name-conflict-symbols}.
 
+@node    Miscellaneous Extensions
+@comment  node-name,  next,  previous,  up
+@section Miscellaneous Extensions
+
+@include fun-sb-ext-simple-array-vector.texinfo
+
 @node Stale Extensions
 @comment  node-name,  next,  previous,  up
 @section Stale Extensions
@@ -431,5 +438,5 @@ to it. This is appropriate for functions like @code{sqrt}, but
 is @emph{not} appropriate for functions like @code{aref},
 which can change their return values when the underlying data are
 changed.
-@c <!-- FIXME: This declaration does not seem to be supported in the 
+@c <!-- FIXME: This declaration does not seem to be supported in the
 @c      current compiler. -->

diff --git a/package-data-list.lisp-expr b/package-data-list.lisp-expr
index 1accc16..42eea42 100644 (file)
--- a/package-data-list.lisp-expr
+++ b/package-data-list.lisp-expr
@@ -675,6 +675,9 @@ like *STACK-TOP-HINT* and unsupported stuff like *TRACED-FUN-LIST*."
                ;; are assertions" default
                "TRULY-THE"
 
+               ;; Misc. array and vector tools.
+               "SIMPLE-ARRAY-VECTOR"
+
                ;; This is something which must exist inside any Common
                ;; Lisp implementation, and which someone writing a
                ;; customized toplevel might well want. It seems perverse

diff --git a/src/code/array.lisp b/src/code/array.lisp
index 7c2790e..b1239ca 100644 (file)
--- a/src/code/array.lisp
+++ b/src/code/array.lisp
@@ -1083,6 +1083,31 @@ of specialized arrays is supported."
       (setf (%array-dimension array 0) dimensions))
   (setf (%array-displaced-p array) displacedp)
   array)
+
+;;; User visible extension
+(declaim (ftype (function (simple-array) (values (simple-array * (*)) &optional))
+                simple-array-vector))
+(defun simple-array-vector (array)
+  "Returns the one-dimensional SIMPLE-ARRAY corresponding to ARRAY.
+
+The ARRAY must be a SIMPLE-ARRAY. If ARRAY is multidimensional, returns the
+underlying one-dimensional SIMPLE-ARRAY which shares storage with ARRAY.
+Otherwise returns ARRAY.
+
+Currently in SBCL a multidimensional SIMPLE-ARRAY has an underlying
+one-dimensional SIMPLE-ARRAY, which holds the data in row major order. This
+function provides access to that vector.
+
+Important note: the underlying vector is an implementation detail. Even though
+this function exposes it, changes in the implementation may cause this
+function to be removed without further warning."
+  ;; KLUDGE: Without TRULY-THE the system is not smart enough to figure out that
+  ;; (1) SIMPLE-ARRAY without ARRAY-HEADER-P is a vector (2) the data vector of
+  ;; a SIMPLE-ARRAY is a vector.
+  (truly-the (simple-array * (*))
+             (if (array-header-p array)
+                 (%array-data-vector array)
+                 array)))
 \f
 ;;;; used by SORT
 

diff --git a/tests/array.pure.lisp b/tests/array.pure.lisp
index 30be86a..0994d49 100644 (file)
--- a/tests/array.pure.lisp
+++ b/tests/array.pure.lisp
@@ -236,3 +236,13 @@
       (error (e)
         (assert (eql 12 (type-error-datum e)))
         (assert (equal '(integer 0 3) (type-error-expected-type e)))))))
+
+(with-test (:name simple-array-vector)
+  (let ((vec (vector 1 2 3)))
+    (assert (eq vec (sb-ext:simple-array-vector vec)))
+    (assert (equalp (vector 1 2 3 4)
+                    (sb-ext:simple-array-vector
+                     (make-array '(2 2) :initial-contents '((1 2) (3 4))))))
+    (assert (eq 'fixnum (array-element-type
+                         (sb-ext:simple-array-vector (make-array '(3 4 5)
+                                                                 :element-type 'fixnum)))))))

diff --git a/version.lisp-expr b/version.lisp-expr
index 4c46e9c..ef774c5 100644 (file)
--- a/version.lisp-expr
+++ b/version.lisp-expr
@@ -17,4 +17,4 @@
 ;;; checkins which aren't released. (And occasionally for internal
 ;;; versions, especially for internal versions off the main CVS
 ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"1.0.23.16"
+"1.0.23.17"