Status

This SRFI is currently in draft status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-163@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.

• Received: 2018/10/30
• 60-day deadline: 2018/12/31
• Draft #1 published: 2018/11/1
• Draft #2 published: 2018/11/4

Abstract

This is a specification of a reader form (literals) for multi-dimensional arrays. It is an extension of the Common Lisp array reader syntax to handle non-zero lower bounds, optional explicit bounds, and optional uniform element types (compatible with SRFI 4). It can be used in conjunction with SRFI 25, SRFI 122, or SRFI 164. These extensions were implemented in Guile (except the handling of rank-0 arrays), and later in Kawa.

There is a non-normative discussing of output formatting, and a suggested format-array procedure.

Issues

Should the rank be optional if the bounds are specified? It is in SRFI 58.

Should format-array be here?

The output of format-array starts out with "╔" (Unicode BOX DRAWINGS DOUBLE DOWN AND RIGHT) if there is space, and otherwise it starts with "#". The former is prettier, but the latter makes it easier to actually parse the output. It might be nice (as a future or implementation extension) to be able to use the pretty box representation in a program, or otherwise execute it, and that is easier if the initial character is "#".

Rationale

It is desirable to have a read and write syntax for multi-dimensional arrays. Basing it on the Common Lisp syntax makes sense, and is what has been done by all known existing implementations. However, Common Lisp arrays do not support non-zero lower bounds, and Common Lisp's handling of specialized (uniform) arrays is very different from that of known Scheme implementations. Various Scheme extensions have been proposed. SRFI 58 is one proposal, but it does not handle non-zero lower bounds, and its type-specifier syntax is verbose and stylistically incompatible with the literals proposed for uniform vectors in SRFI 4.

This specification is basically that of Guile. However, Guile requires the single element of rank-0 arrays to be enclosed in parentheses. While this may slightly enhance readability, it is somewhat inconsistent in that otherwise the nesting of parentheses (of atom-valued arrays) is equal to the rank. It is also inconsistent with Common Lisp and SRFI 58. So this specification (and the Kawa implementation) diverge from Guile in this respect.

Specification

Reader syntax

An array literal starts with # followed by its rank, followed by a tag that describes the underlying vector (by default a), optionally followed by information about its shape, and finally followed by the cells, organized into dimensions using parentheses.

For example, #2a((11 12 13) (21 22 23)) is a rank-2 array (a matrix) whose upper index bounds (shape) is #(2 3). It could be pretty-printed (using the non-normative format-array helper function below):

╔#2a:2:3═╗
║11│12│13║
╟──┼──┼──╢
║21│22│23║
╚══╧══╧══╝

The vectag specifies the type of the elements of the array. These are the same tags as SRFI 4. For example #2u32((10 11) (20 21)) is a 2x2 array of 32-bit unsigned integers.

Following the vectag you can optionally include information about the shape: For each dimension you can optionally specify the lower bounds (after the character @), followed by the length of the dimension (after the character ":"). The shape information is required if a lower bound is non-zero, or any length is zero. If any array-bound is specified, there must be exactly rank of them.

The datum contains the elements in a nested-list format: a rank-1 array uses a single list, a rank-2 array uses a list of lists, and so on. The elements are in lexicographic order.

The array-literal-header must be terminated by a delimiter. This is trivially the case for rank-1 and above (since the left parenthesis of a list is a delimiter). For rank-0 arrays, a single space before datum is recommended style, even if the datum starts with a delimiter. (Compatibility note: Common Lisp does not require a space after #0a.)

A uniform u32 array of rank 2 with index ranges 2..3 and 3..4:

#2u32@2@3((1 2) (2 3))

Rank 0 arrays:

#0a sym
#0f32 237.0

Empty arrays:

#2a:0:2()
#2a:2:0(() ())
#3a:2:0:3(() ())
#3a:2:3:0((() () ()) (() () ()))

Output (non-normative)

When an array is printed with the write function, the result should be an array-literal. For a rank-0 arrays (only), a single space should be printed before the datum. In an implementation where vector is a subtype of array, rank-1 arrays with zero lower bound may be printed as vectors.

Printing with display may format the array in the same way as write (except using display for each element), or in some more readable way, perhaps by using the format-array procedure.

The format-array utility procedure (non-normative)

(format-array value [port] [element-format])

Implementation

This syntax is implemented in Guile (except for the handling of rank-0 arrays), and Kawa.

Kawa provides format-array (though it is implemented in Java): The format-array is a Scheme wrapper around the print method of the gnu.kawa.functions.ArrayPrint class.

Acknowledgements

Copyright

Copyright (C) Per Bothner 2018

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.