Title

Array Notation

Authors

Aubrey Jaffer and Radey Shouman

Status

This SRFI is currently in ``draft'' status. To see an explanation of each status that a SRFI can hold, see here. It will remain in draft status until 2005/01/26, or as amended. To provide input on this SRFI, please mailto:srfi-58@srfi.schemers.org. See instructions here to subscribe to the list. You can access previous messages via the archive of the mailing list.

Abstract

SRFI-47 provides both uniform-typed and heterogeneous multidimensional arrays which subsume Scheme vectors and strings. The notation presented here builds upon Common-Lisp array sytnax to represent heterogeneous and uniform-typed arrays.

Issues

Rationale

SRFI-47, "Array", incorporates all the uniform vector types from SFRI-4 "Homogeneous numeric vector datatypes", and adds a uniform boolean array type and complex types composed of two IEEE 32.bit or two 64.bit floating-point numbers. Multi-dimensional arrays subsume homogeneous vectors as the one-dimensional case, obviating the need for SRFI-4.

Implementations are required to accept all of the type denotations. Those which the platform supports will have platform-dependent representations; the others will be represented as the next larger uniform-type implemented; defaulting to vector if there are none. All implementations must support the character array type, the rank-1 character arrays being strings.

This arrangement has platforms supporting uniform array types using them, with less capable platforms using vectors; both from the same source code.

Specification

Syntax

A syntax for arrays is the list-decomposition of an array with a prefix according to the type of the array. The case of characters is not significant in the prefix characters.

By list-decomposition is meant rank nestings of lists of the elements where the most nested list has length equal to the last dimension of the array and at top level has length equal to the first dimension of the array.

Rank 1 character arrays which are not subarrays are writen as Scheme strings; display treats rank-1 character arrays which are not subarrays identically with strings.

Rank 1 heterogeneous arrays which are not subarrays write and display as Scheme vectors.

original
prototype
procedure

prototype
procedure
exactness element type original
prefix
(rank = n)

prefix
(rank = n)
vectorvector any #nA #nA
ac64 A:complex-64inexactIEEE 64.bit floating point complex#nAc64#nA:complex-64
ac32 A:complex-32inexactIEEE 32.bit floating point complex#nAc32#nA:complex-32
ar64 A:real-64 inexactIEEE 64.bit floating point real #nAr64#nA:real-64
ar32 A:real-32 inexactIEEE 32.bit floating point real #nAr32#nA:real-32
as64 A:integer-64exact 64.bit integer #nAs64#nA:integer-64
as32 A:integer-32exact 32.bit integer #nAs32#nA:integer-32
as16 A:integer-16exact 16.bit integer #nAs16#nA:integer-16
as8 A:integer-8 exact 8.bit integer #nAs8 #nA:integer-8
au64 A:integer+64exact 64.bit nonnegative integer #nAu64#nA:integer+64
au32 A:integer+32exact 32.bit nonnegative integer #nAu32#nA:integer+32
au16 A:integer+16exact 16.bit nonnegative integer #nAu16#nA:integer+16
au8 A:integer+8 exact 8.bit nonnegative integer #nAu8 #nA:integer+8
stringstring char #nA\ #nA:char
at1 A:boolean boolean #nAt #nA:boolean

A two-by-three array of nonnegative 16.bit integers is written:

#2A:integer+16((0 1 2) (3 5 4))
Note that this is the external representation of an array, not an expression evaluating to a array. Like vector constants, array constants must be quoted:
'#2a:INTEGER+16((0 1 2) (3 5 4))
               ==> #2A:integer+16((0 1 2) (3 5 4))

Semantics

This array could have been created by (make-array (A:integer+16) 2 3).

(array-dimensions '#2A:integer+16((0 1 2) (3 5 4))) ==> (2 3)

Literal array constants are immutable objects. It is an error to attempt to store a new value into a location that is denoted by an immutable object.

The following equivalences will be defined to alias SRFI-47 names to the new ones. SRFI-47 should be amended or replaced to make these be the array-prototype-procedures:

(define A:complex-64 ac64)
(define A:complex-32 ac32)
(define A:real-64    ar64)
(define A:real-32    ar32)
(define A:integer-64 as64)
(define A:integer-32 as32)
(define A:integer-16 as16)
(define A:integer-8  as8)
(define A:integer+64 au64)
(define A:integer+32 au32)
(define A:integer+16 au16)
(define A:integer+8  au8)
(define A:boolean    at1)

Having the array-prototype-procedure names match the array prefixes reduces the memory load for users.

Implementation

The following code from the SCM implementation ("Init5d9.scm") implements both the original and new array read-syntax. read:sharp is called from read when a #\# is read. Its first argument is the character after #\#; the second argument is the input port; the third argument is the procedure to call for recursive reading.

list->uniform-array converts the list-decomposition returned by read into the uniform array of the specified type (or the next larger compatible type).

(define (read:sharp c port read)
  (case c
    ((#\a #\A) (read:array 1 port read))
    ((#\0 #\1 #\2 #\3 #\4 #\5 #\6 #\7 #\8 #\9)
     (let* ((num (read:try-number port c))
            (c (peek-char port)))
       (cond ((memv c '(#\a #\A))
              (read-char port)
              (read:array num port read))
             (else (error "syntax? #" num c)))))
    (else (error "unknown # object" c))))

(define (read:array rank port reader)   ;ignore reader
  (define (bomb pc wid)
    (error (string-append "array syntax? #"
                          (number->string rank)
                          "A" (string pc)
                          (if wid (number->string wid) ""))))
  (list->uniform-array
   rank
   (case (char-downcase (peek-char port))
     ((#\:)
      (read-char port)
      (let ((typ (read port)))
        (case typ
          ((complex-64) +64.0i)
          ((complex-32) +32.0i)
          ((real-64)     64.0)
          ((real-32)     32.0)
          ((integer-64) -64)
          ((integer-32) -32)
          ((integer-16) -16)
          ((integer-8)   -8)
          ((integer+64)  64)
          ((integer+32)  32)
          ((integer+16)  16)
          ((integer+8)    8)
          ((boolean)     #t))))
     ((#\\) (read-char port) #\a)
     ((#\t) (read-char port) #t)
     ((#\c #\r)
      (let* ((pc (read-char port))
             (wid (read:try-number port)))
        (case wid
          ((64 32) (case pc
                     ((#\c) (* +i wid))
                     (else (exact->inexact wid))))
          (else (bomb pc wid)))))
     ((#\s #\u)
      (let* ((pc (read-char port))
             (wid (read:try-number port)))
        (case (or wid (peek-char port))
          ((32 16 8) (case pc
                       ((#\s) (- wid))
                       (else wid)))
          (else (bomb pc wid)))))
     (else #f))
   (read port)))

(define (read:try-number port . ic)
  (define chr0 (char->integer #\0))
  (let loop ((arg (and (not (null? ic)) (- (char->integer (car ic)) chr0))))
    (let ((c (peek-char port)))
      (cond ((eof-object? c) #f)
            ((char-numeric? c)
             (loop (+ (* 10 (or arg 0))
                      (- (char->integer (read-char port)) chr0))))
            (else arg)))))

Copyright

Copyright (C) Aubrey Jaffer (2004, 2005). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Scheme Request For Implementation process or editors, except as needed for the purpose of developing SRFIs in which case the procedures for copyrights defined in the SRFI process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the authors or their successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Editor: David Van Horn
Last modified: Fri Nov 26 10:49:37 EST 2004