guile-newra/docs/newra.texi

@c -*-texinfo-*-
@c %**start of header
@setfilename newra.info
@documentencoding UTF-8
@settitle newra — An alternative array library for Guile 3
@c %**end of header
@c last [ma112]

@set VERSION 1
@set UPDATED 2021 October 7

@copying
@code{newra} (version @value{VERSION}, updated @value{UPDATED})

(c) lloda 2017--2021

@smalldisplay
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@end smalldisplay
@end copying

@dircategory Guile libraries
@direntry
* newra: (newra.info).  Array library for Guile meant to replace the built-in array facility.
@end direntry

@include my-bib-macros.texi
@mybibuselist{Sources}

@titlepage
@title newra
@subtitle version @value{VERSION}, updated @value{UPDATED}
@author lloda
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex
@node Top
@top @code{newra}

@insertcopying

@code{newra} is a pure Scheme replacement for the built-in C-based array facility in Guile 3.0.

This document uses ‘array’ to refer both to the old built-in array type and to the new type introduced in @code{newra}. The distinction is made as necessary.

@menu
* Introduction::    Why Guile arrays need replacing.
* Basic use::       Arrays as data structures.
* High level::      Guile as an array language.
* Hazards::         User beware.
* Reference::       Systematic list of types and functions.
* Cheatsheet::      Asking for directions
* @mybibnode{}::    It's been done before.
* Indices::         Or try the search function.
@end menu

@end ifnottex

@iftex
@shortcontents
@end iftex

@c ------------------------------------------------
@node Introduction
@chapter Introduction
@c ------------------------------------------------

@cindex bounds
A multidimensional array is a container (or rather a container view) whose elements can be looked up using a multi-index (i₀, i₁, ...). Each of the indices i₀, i₁, ... has constant bounds [l₀, h₀], [l₁, h₁], ... independent of the values of the other indices, so the array is ‘rectangular’. The number of indices in the multi-index is the @dfn{rank} of the array, and the list ([l₀ h₀] [l₁ h₁] ... [lᵣ₋₁ hᵣ₋₁]) is the @dfn{shape} of the array. We speak of a rank-@math{r} array or of an @math{r}-array.

This is a 2-array with bounds [0, 2] on both axes:
@verbatim
┌───────┬───────┬───────┐
│A(0, 0)│A(0, 1)│A(0, 2)│
├───────┼───────┼───────┤
│A(1, 0)│A(1, 1)│A(1, 2)│
├───────┼───────┼───────┤
│A(2, 0)│A(2, 1)│A(2, 2)│
└───────┴───────┴───────┘
@end verbatim

This is a 3-array with bounds [0, 1] on axis 0, [2, 5] on axis 1, bounds [-2, 0] on axis 2:@footnote{
@verbatim
(import (newra))
(define element (lambda i (format #f "A(~{~a~^, ~})" i)))
(define (ti k) (ra-transpose (ra-iota) k))
(ra-format (ra-map! (make-ra #f 3 3)  element (ti 0) (ti 1)) #:prefix? #f)
(ra-format (ra-map! (make-ra #f 2 '(2 5) '(-2 0))  element (ti 0) (ti 1) (ti 2)) #:prefix? #f)
@end verbatim
}
@verbatim
║───────────┬───────────┬──────────║───────────┬───────────┬──────────║
║A(0, 2, -2)│A(0, 2, -1)│A(0, 2, 0)║A(1, 2, -2)│A(1, 2, -1)│A(1, 2, 0)║
║───────────┼───────────┼──────────║───────────┼───────────┼──────────║
║A(0, 3, -2)│A(0, 3, -1)│A(0, 3, 0)║A(1, 3, -2)│A(1, 3, -1)│A(1, 3, 0)║
║───────────┼───────────┼──────────║───────────┼───────────┼──────────║
║A(0, 4, -2)│A(0, 4, -1)│A(0, 4, 0)║A(1, 4, -2)│A(1, 4, -1)│A(1, 4, 0)║
║───────────┼───────────┼──────────║───────────┼───────────┼──────────║
║A(0, 5, -2)│A(0, 5, -1)│A(0, 5, 0)║A(1, 5, -2)│A(1, 5, -1)│A(1, 5, 0)║
║───────────┴───────────┴──────────║───────────┴───────────┴──────────║
@end verbatim

Sometimes we deal with multidimensional @emph{expressions} where the elements aren't stored anywhere, but are computed on demand when the expression is looked up. In this general sense, an ‘array’ is just a function of integers with a rectangular domain. Such an array would be immutable.

Arrays (in the form of @dfn{matrices}, @dfn{vectors}, or @dfn{tensors}) are very common objects in math and programming, and it is very useful to be able to manipulate arrays as individual entities rather than as aggregates — that is one of the main purposes of @code{newra}.

The rest of this section discusses the motivation for @code{newra} in more detail. To start using the library, please jump ahead to @ref{Low level}.

@menu
* Rank polymorphism::
* Rank extension::
* The pieces of an array::
* Built-in Guile arrays::
@end menu

@c ------------------------------------------------
@node Rank polymorphism
@section Rank polymorphism
@c ------------------------------------------------

@cindex rank polymorphism
@dfn{Rank polymorphism} is the ability to treat an array of rank @math{r} as an array of lower rank where the elements are themselves arrays.

@cindex cell
@cindex frame
Think of a matrix A, a 2-array with lengths (l₀, l₁) where the elements A(i₀, i₁) are numbers. If we consider the subarrays (rows) A(0, ...), A(1, ...), ..., A(l₀-1, ...) as individual elements, then we have a new view of A as a 1-array of length l₀ with those rows as elements. We say that the rows A(i₀)≡A(i₀, ...) are the 1-@dfn{cells} of A, and the numbers A(i₀, i₁) are 0-cells of A. For an array of arbitrary rank @math{r} the (@math{r}-1)-cells of A are called its @dfn{items}. The prefix of the shape (l₀, l₁, ... lₙ₋₁₋ₖ) that is not taken up by the k-cell is called the (r-k)-@dfn{frame}.

@multitable @columnfractions .4 .1 .4
@item
@verbatim
┌───────┬───────┬───────┐
│A(0, 0)│A(0, 1)│A(0, 2)│
├───────┼───────┼───────┤
│A(1, 0)│A(1, 1)│A(1, 2)│
├───────┼───────┼───────┤
│A(2, 0)│A(2, 1)│A(2, 2)│
└───────┴───────┴───────┘
@end verbatim
@tab
≡
@tab
@verbatim
────
A(0)
────
A(1)
────
A(2)
────
@end verbatim
@end multitable

An obvious way to store an array in linearly addressed memory is to place its items one after another. So we would store a 3-array as

@quotation
A: [A(0), A(1), ...]
@end quotation

and the items of A(i₀), etc. are in turn stored in the same way, so

@quotation
A: [A(0): [A(0, 0), A(0, 1) ...], ...]
@end quotation

and the same for the items of A(i₀, i₁), etc.

@quotation
A: [[A(0, 0): [A(0, 0, 0), A(0, 0, 1) ...], A(0, 1): [A(0, 1, 0), A(0, 1, 1) ...]], ...]
@end quotation

@cindex order, row-major
@cindex order, C
This way to lay out an array in memory is called @dfn{row-major order} or @dfn{C-order}, since it's the default order for built-in arrays in C. A row-major array A with lengths (l₀, l₁, ... lᵣ₋₁) can be looked up like this:

@anchor{x-steps}
@quotation
A(i₀, i₁, ...) = (storage-of-A) [(((i₀l₁ + i₁)l₂ + i₂)l₃ + ...)+iᵣ₋₁] = (storage-of-A) [o + s₀·i₀ + s₁·i₁ +  ...]
@end quotation

where the numbers (s₀, s₁, ...) are called the @dfn{steps}@footnote{Cf. @url{https://en.wikipedia.org/wiki/Dope_vector, @dfn{dope vector}}}. Note that the ‘linear’ or ‘raveled’ address [o + s₀·i₀ + s₁·i₁ +  ...] is an affine function of (i₀, i₁, ...). If we represent an array as a tuple

@quotation
A ≡ ((storage-of-A), o, (s₀, s₁, ...))
@end quotation

then any affine transformation of the indices can be achieved simply by modifying the numbers (o, (s₀, s₁, ...)), with no need to touch the storage. This includes very common operations such as: @ref{x-ra-transpose,transposing} axes, @ref{x-ra-reverse,reversing} the order along an axis, most cases of @ref{Slicing,slicing}, and sometimes even reshaping or tiling the array.

A basic example is obtaining the i₀-th item of A:

@quotation
A(i₀) ≡ ((storage-of-A), o+s₀·i₀, (s₁, ...))
@end quotation

Note that we can iterate over these items by simply bumping the pointer o+s₀·i₀. This means that iterating over (k>0)-cells doesn't have to cost any more than iterating over 0-cells (@ref{x-ra-slice-for-each,@code{ra-slice-for-each}}). Rank polymorphism isn't just a high level property of arrays; it is enabled and supported by the way they are laid out in memory.

@c ------------------------------------------------
@node Rank extension
@section Rank extension
@c ------------------------------------------------

Rank extension is the mechanism that allows @code{R+S} to be defined even when @code{R}, @code{S} may have different ranks. The idea is an interpolation of the following basic cases.

Suppose first that @code{R} and @code{S} have the same rank. We require that the shapes be the same. Then the shape of @code{R+S} will be the same as the shape of either @code{R} or @code{S} and the elements of @code{R+S} will be

@quotation
@code{(R+S)(i₀ i₁ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ᵣ₋₁₎) + S(i₀ i₁ ... i₍ᵣ₋₁₎)}
@end quotation

where @code{r} is the rank of @code{R}.

Now suppose that @code{S} has rank 0. The shape of @code{R+S} is the same as the shape of @code{R} and the elements of @code{R+S} will be

@quotation
@code{(R+S)(i₀ i₁ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ᵣ₋₁₎) + S()}.
@end quotation

The two rules above are supported by all primitive array languages. But suppose that @code{S} has rank @code{s}, where @code{0<s<r}. Looking at the expressions above, it seems natural to define @code{R+S} by

@quotation
@code{(R+S)(i₀ i₁ ... i₍ₛ₋₁₎ ... i₍ᵣ₋₁₎) = R(i₀ i₁ ... i₍ₛ₋₁₎ ... i₍ᵣ₋₁₎) + S(i₀ i₁ ... i₍ₛ₋₁₎)}.
@end quotation

That is, after we run out of indices in @code{S}, we simply repeat the elements. We have aligned the shapes so:

@quotation
@verbatim
[n₀ n₁ ... n₍ₛ₋₁₎ ... n₍ᵣ₋₁₎]
[n₀ n₁ ... n₍ₛ₋₁₎]
@end verbatim
@end quotation

@cindex shape agreement, prefix
@cindex shape agreement, suffix
@c @cindex J
@cindex Numpy
This rank extension rule is used by the J language @mybibcite{J S} and is known as @dfn{prefix agreement}. The opposite rule of @dfn{suffix agreement} is used, for example, in Numpy @mybibcite{num17}.

As you can verify, the prefix agreement rule is distributive. Therefore it can be applied to nested expressions or to expressions with any number of arguments. It is applied systematically throughout @code{newra}, even in assignments. For example,

@example
@verbatim
(define a (make-ra-root #(3 5 9)))
(define b (make-ra #f 3 2))
(ra-copy! b a) ; copy each aᵢ on each bᵢ
@end verbatim
@result{} @code{#%2:3:2((3 3) (5 5) (9 9))}
@end example

@example
@verbatim
(define a (make-ra 0 3))
(define b (ra-reshape (ra-iota 6 1) 0 3 2))
(ra-map! a + a b) ; sum the rows of b
@end verbatim
@result{} @code{#%1:3(3 7 11)}
@end example

@cindex Numpy
@cindex broadcasting, singleton, newaxis
A weakness of prefix agreement is that the axes you want to match aren't always the prefix axes. Other array systems (e.g. @mybibcite{num17}) offer a feature similar to rank extension called ‘broadcasting’ that is a bit more flexible. For example an array of shape [A B 1 D] will match an array of shape [A B C D] for any value of C. The process of broadcasting consists in inserting so-called ‘singleton dimensions’ (axes with length one) to align the axes that one wishes to match. One may think of rank extension as a particular case of broadcasting where the singleton dimensions are added to the end of the shorter shapes automatically.

A drawback of singleton broadcasting is that it muddles the distinction between a scalar and a vector of length 1. Sometimes, an axis of length 1 is no more than that, and if 2≠3 is a size error, it isn't obvious why 1≠2 shouldn't be. For this reason @code{newra}'s support for explicit broadcasting is based on @ref{x-dead-axes,dead axes}.

@example
@verbatim
(define a (ra-i 5 3))
(define b (make-ra 0 3))
(let ((b1 (ra-transpose b 1))) ; align axis 0 of b with axis 1 of a
  (ra-map! b1 + b1 a) ; sum the columns of a
  b)
@end verbatim
@result{} b = @code{#%1:5(30 35 40)}
@end example

@c ------------------------------------------------
@node The pieces of an array
@section The pieces of an array
@c ------------------------------------------------

An @code{newra} array is an aggregate of the following pieces:

@cindex rank
@cindex dim vector
@cindex root vector
@itemize
@item A @dfn{root vector}, or root for short.
This can be a Scheme vector, as well as one of several other vector-like types.
@item A @dfn{zero}.
An arbitary integer.
@item A @dfn{dim vector}.
Each dim consists of a length (@dfn{len}), a lower bound (@dfn{lo}), and a @dfn{step}. The length of the dim vector is the @dfn{rank} of the array.
@end itemize

Together, the dim vector and the zero define an affine function of array indices @code{i₀, i₁, ..} that produces an index into the root. Thus, the array is a multidimensional view of the root.

For example, the following pieces

@itemize
@item root: v = @code{#(1 2 3 4 5 6 7)}
@item zero: 1
@item dims: @code{#(#<<dim> len: 2 lo: 0 step: 2> #<<dim> len: 2 lo: 0 step: 1>)}
@end itemize

define an array A(i₀, i₁) = v(1 + 2·i₀ + 1·i₁), 0≤i₀<2, 0≤i₁<2, that is A = [[2 3] [4 5]].

In @code{newra} code,

@example
@verbatim
(make-ra-root (vector 1 2 3 4 5 6 7) 1 (vector (make-dim 2 0 2) (make-dim 2 0 1)))
@end verbatim
@result{} @code{#%2:2:2((2 3) (4 5))}
@end example

The default print style means @code{#%RANK:LEN₀:LEN₁(...)} (@ref{Writing and reading}).

It's unusual to need to specify the dims directly. More commonly, one creates an array of whatever size

@example
@verbatim
> (define a (make-ra #f 3 4))
> a
@end verbatim
@result{} @code{#%2:3:4((#f #f #f #f) (#f #f #f #f) (#f #f #f #f))}
@end example

which automatically creates a root of the required size, so that all the array elements are distinct. Then one operates on the array without making reference to the underlying root,

@example
@verbatim
> (ra-set! a 99 2 2)
@end verbatim
@result{} @code{#%2:3:4((#f #f #f #f) (#f #f 99 #f) (#f #f #f #f))}
@end example

Still, since the array is just a view of the root, any changes on the array are reflected there as well

@example
@verbatim
> (ra-root a)
@end verbatim
@result{} @code{#(#f #f #f #f #f #f #f #f #f #f 99 #f)}
@end example

and the other way around,

@example
@verbatim
> (define b (make-ra-root (vector 'x) 0 (vector (make-dim 3 0 0) (make-dim 2 0 0))))
> b
@end verbatim
@result{} @code{#%2:3:2((x x) (x x) (x x))}

@verbatim
> (vector-set! (ra-root b) 0 'Z)
> b
@end verbatim
@result{} @code{#%2:3:2((Z Z) (Z Z) (Z Z))}
@end example

@cindex shared root
@cindex new array
It is often important to know whether an operation on an array returns a different view of its argument, or instead it allocates a new root which can be modified without affecting the original argument. When we say that a function `creates a new array', we mean that it allocates a new root.

Generally a given function will always do one or the other, e.g. the result of @ref{x-ra-tile, @code{ra-tile}} always shares the root of its argument, while @ref{x-ra-copy, @code{ra-copy}} always creates a new array. Some functions, like @ref{x-ra-ravel, @code{ra-ravel}} or @ref{x-ra-from, @code{ra-from}}, may do either, depending on their arguments. For example, the result of

@example
@verbatim
(ra-ravel (ra-iota 3 4))
@end verbatim
@result{} @code{#%1d:12(0 1 2 3 4 5 6 7 8 9 10 11)}
@end example

shares the root of @code{(ra-iota 3 4)}, but

@example
@verbatim
(ra-ravel (ra-transpose (ra-iota 3 4) 1 0))
@end verbatim
@result{} @code{#%1:12(0 4 8 1 5 9 2 6 10 3 7 11)}
@end example

doesn't.

@c ------------------------------------------------
@node Built-in Guile arrays
@section Built-in Guile arrays
@c ------------------------------------------------

Dense multidimensional arrays work similarly in every language that offers them, and built-in Guile arrays are no different — they also have a root (@code{shared-array-root}), a zero (computable from @code{shared-array-offset} and @code{array-shape}), and a dim vector (@code{array-shape}, @code{shared-array-increments}). Functionally, they are entirely equivalent to the objects offered by @code{newra}. Why replace them?

@cindex libguile
Built-in Guile arrays are implemented in C, as part of libguile. As a Guile type they have their own low-level type tag, and all the basic array operations are C stubs, even the most basic functions such as @code{array-ref} or @code{array-rank}. Obtaining any of the components of the array requires calling into C. There are several problems with this.

First, the built-in library offers a single function to manipulate array dims, @code{make-shared-array}. Although this is a sufficient interface, it is excessively generic, and also very cumbersome and inefficient. The array dims cannot be manipulated directly from Scheme, so any alternative interface written in Scheme is forced to go through @code{make-shared-array}.

Second, the C stubs create a barrier to optimization by the Scheme compiler. The main loop of an operation such as @code{(array-map! c + a b)} has to be implemented in C (for the reasons given above) and then it has to call back to Scheme on each iteration in order to apply @code{+}. Since the Scheme compiler doesn't have any special support for @code{array-map!}, it doesn't know what the types of the arguments are, etc. and those checks and dispatches are repeated over and over. @footnote{Guile (before v1.8) used to offer dedicated operations to sum arrays, etc. but obviously that isn't any kind of solution.}

Third, some of the the larger functions of the array interface, such as @code{array-map!}, etc. are not interruptible. This is especially inconvenient when operating on large arrays.

These problems are solved if the built-in type is replaced with a new type defined in Scheme.

@c ------------------------------------------------
@node Low level
@chapter Low level
@c ------------------------------------------------

@menu
* Creating and accessing arrays::
* Special arrays::
* Writing and reading::
* Iteration::
* Slicing::
* Reshaping::
* Concatenation::
* Transposition::
* Other operations on arrays::
* Automatic result arrays::
* Foreign interface::
* Compatibility with old Guile arrays::
@end menu

@c ------------------------------------------------
@node Creating and accessing arrays
@section Creating and accessing arrays
@c ------------------------------------------------

An array can be created anew (@ref{x-make-ra-new, @code{make-ra-new}}, @ref{x-make-ra, @code{make-ra}}, @ref{x-make-typed-ra, @code{make-typed-ra}}), or over an existing root (@ref{x-make-ra-root, @code{make-ra-root}}).

@ref{x-make-ra, @code{make-ra}} or @ref{x-make-typed-ra, @code{make-typed-ra}} take array lengths and use row-major order by default.

@example
@verbatim
(make-ra 99 2 3)
@end verbatim
@result{} #%2:3:2((9 9) (9 9) (9 9))
@end example

@example
@verbatim
(make-typed-ra 'f64 99 2 3)
@end verbatim
@result{} #%2f64:3:2((9.0 9.0) (9.0 9.0) (9.0 9.0))
@end example

@ref{x-make-ra-new, @code{make-ra-new}} takes an array type, a fill value, and a dim vector. @ref{x-c-dims, @code{c-dims}} can be used to create a row-major dim vector.

@example
@verbatim
(make-ra-new #t 'x (vector (make-dim 3 0 2) (make-dim 2 0 1))) ; more simply
(make-ra-new #t 'x (c-dims 3 2))
@end verbatim
@result{} #%2:3:2((x x) (x x) (x x))
@end example

@example
@verbatim
(make-ra-new 'f32 0.0 (c-dims 3 2))
@end verbatim
@result{} #%2f32:3:2((0.0 0.0) (0.0 0.0) (0.0 0.0))
@end example

@ref{x-make-ra-root, @code{make-ra-root}} takes the type from the root vector.

@example
@verbatim
(make-ra-root (vector 1 2 3 4 5 6) (c-dims 3 2))
@end verbatim
@result{} #%2:3:2((1 2) (3 4) (5 6))
@end example

@code{newra} arrays are applicative; to look up or assign an element of an array, use it as a function of the indices.

@example
@verbatim
(define a (make-ra #f 3 2))
(set! (a 0 0) 9)
(set! (a 1 1) 3)
@end verbatim
@result{} #%2:3:4((9 #f) (#f 3) (#f #f))
@verbatim
(a 0 0)
@end verbatim
@result{} 9
@end example

@cindex prefix slice
If you give fewer indices than the rank, you get a prefix slice. This slice shares the root of the original array.

@example
@verbatim
(a 1)
@end verbatim
@result{} #%1:2(#f 3)
@verbatim
(set! ((a 1) 0) 'b)
@end verbatim
@result{} #%1:2(b 3)
@verbatim
a
@end verbatim
@result{} #%2:3:4((9 #f) (b 3) (#f #f))
@end example

You can also access arrays in the more usual way with the functions @ref{x-ra-ref, @code{ra-ref}} and @ref{x-ra-set!, @code{ra-set!}}. See @ref{Slicing} for additional options.

@c ------------------------------------------------
@node Special arrays
@section Special arrays
@c ------------------------------------------------

Any type that is usable as the root of an old built-in Guile array is also usable as root of a @code{newra} array. These include

@itemize
@item vectors (e.g. @code{(vector 3)})
@item SRFI-4 typed vectors (e.g. @code{(c64vector 1 2+0i)})
@item strings (e.g. @code{"hello"})
@item bitvectors (e.g. @code{(bitvector #f #t #f #t)})
@end itemize

@code{newra} supports an additional root vector type, @code{<aseq>}, representing an unbounded arithmetic sequence.

@cindex @code{make-aseq}
@anchor{x-none}
@deffn @w{Function} make-aseq [org [inc]]

Create an arithmetic sequence [@code{org, org+inc, org+2·inc, ...}]. The default values of @code{org} and @code{inc} are respectively 0 and 1. For example:

@example
@verbatim
(make-ra-root (make-aseq 0 3) (vector (make-dim 10)) 0)
@end verbatim
@result{} #%1d:10(0 3 6 9 12 15 18 21 24 27)
@end example

(The example above can be written @code{(@ref{x-ra-iota, ra-iota} 10 0 3)}).
@end deffn

@cindex @code{d}
@code{aseq} roots are immutable. The type tag of @code{aseq} roots is @code{d}. Arrays with integer-valued @code{aseq} roots have a few special uses; one of them is as arguments in @ref{Slicing, slicing}.

@cindex infinite axes
@cindex unbounded axes
To make @code{<aseq>} even more useful, @code{newra} supports unbounded axes.

@example
@verbatim
(ra-ref (make-ra-root (make-aseq) (vector (make-dim #f)) 0) #e1e12) ; or more simply
(ra-ref (ra-iota) #e1e12)
@end verbatim
@result{} 1000000000000
@end example

These are treated especially when used in iteration, in that they match axes of any finite length (@ref{x-ra-map!, @code{ra-map!}}). Effectively this lets one use @code{(@ref{x-ra-transpose, @code{ra-transpose}} (ra-iota) k)} as a placeholder for the index over axis @code{k}.

@example
@verbatim
(ra-map! (make-ra 0 3) + (ra-iota 3) (ra-iota))
@end verbatim
@result{} #1%3(0 2 4)
@end example

@cindex dead axes
@anchor{x-dead-axes}
@code{newra} also supports `dead axes', which are axes with step 0 and undefined length. These axes can match axes of any length and can exist on arrays of any type, not only on arrays of type @code{d}, because effectively only one position (the lower bound) is ever accessed.

@cindex singleton axis
Dead axes operate essentially as ‘singleton axes’ do in other array languages. The main diference is that the ability to match any finite length is explicit; an axis with length 1 will still fail to match an axis with length 2 (say).

Some functions work by creating axes with step 0, usually with defined lengths.

@example
@verbatim
(define A (make-ra-root #(1 2 3) (c-dims 3)))
(ra-tile A 0 2 2)
@end verbatim
@result{} #%3d:2:2:3(((0 1 2) (0 1 2)) ((0 1 2) (0 1 2)))
@verbatim
(ra-dims (ra-tile A 0 2 2))
@end verbatim
@result{} #(#<<dim> len: 2 lo: 0 step: 0> #<<dim> len: 2 lo: 0 step: 0> #<<dim> len: 3 lo: 0 step: 1>)
@end example

@c ------------------------------------------------
@node Writing and reading
@section Writing and reading
@c ------------------------------------------------

The read syntax for arrays is @url{https://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html,the same} as for built-in Guile arrays, except that @code{#%} is used instead of @code{#}. Full dimensions are printed by default, even when they are not required to read an array.

@example
@verbatim
(call-with-input-string "#%1(2 2 2)" read)
@end verbatim
@result{} @code{#%1:3(2 2 2)}
@end example

@example
@verbatim
(call-with-input-string "#%1:3(2 2 2)" read)
@end verbatim
@result{} @code{#%1:3(2 2 2)}
@end example

Dead axes print as @code{d}, and unbounded (not dead) axes print as @code{f}. These cannot be read back.

@example
@verbatim
(display (ra-transpose (ra-copy (ra-iota 3)) 1))
@end verbatim
@result{} @code{#%2:d:3((0 1 2))}
@end example

Arrays with root of type @code{d} cannot be read back either.

@example
@verbatim
(define s (format #f "~a" (ra-i 2 3)))
s
@end verbatim
@result{} @code{"#%2d:2:3((0 1 2) (3 4 5))"}
@end example

@example
@verbatim
(call-with-input-string s read)
@end verbatim
@result{} error: cannot make array of type d
@end example

Truncated output is not supported yet.

@example
@verbatim
(format #f "~@y" (ra-i 2 3))
@end verbatim
@result{} @code{"#%2d:2:3((0 1 2) (3 4 5))"} ; ok, but we didn't need to truncate
@end example

@example
@verbatim
(format #f "~@y" (ra-i 99 99))
@end verbatim
@result{} @code{"#" ; ouch}
@end example

The function @ref{x-ra-format, @code{ra-format}} can be used to pretty print arrays. This type of output cannot be read back, either.

@example
@verbatim
(ra-format (list->ra 2 '((1 hello) ("try" 2) (never 3.14))) #:fmt "~s")
@end verbatim
@result{}
@verbatim
#%2:3:2─────┐
│    1│hello│
├─────┼─────┤
│"try"│    2│
├─────┼─────┤
│never│ 3.14│
└─────┴─────┘
@end verbatim
@end example

The writing mode can be configured with the following parameter.

@cindex @code{*ra-print*}
@anchor{x-star-ra-print-star}
@deffn @w{Parameter} *ra-print* (lambda (array port) ...)

Set the default printer for arrays. This parameter is available from @code{(newra print)}.

@cindex @code{box}
@cindex @code{box-compact}
@cindex @code{default}
The parameter can be set to a function @code{(lambda (array port) ...)} or to one of the values @code{#f}, @code{'default}, @code{'box} or @code{'box-compact}.

For example
@example
@verbatim
(import (newra print))
(*ra-print* (lambda (ra o) (ra-print ra o #:dims? #f)))
(ra-i 2 3)
@end verbatim
@result {}
@verbatim
$1 = #%2d((0 1 2) (3 4 5))
@end verbatim
@end example

or

@example
@verbatim
(*ra-print* (lambda (ra o) (newline o) (ra-format ra o)))
; (*ra-print* 'box) ; same thing
(ra-i 2 3)
@end verbatim
@result {}
@verbatim
$1 =
#%2d:2:3
│0│1│2│
├─┼─┼─┤
│3│4│5│
└─┴─┴─┘
@end verbatim
@end example

The default printer can be reset with @code{(*ra-print* #f)} or @code{(*ra-print* 'default)}.
@end deffn

@cindex SRFI-163
By default, rank-0 arrays are printed like the built-in Guile arrays, with extra parentheses around the content. In the read syntax specified in @mybibcite{SRFI-163}, those parentheses are not used. The following parameter allows one to choose either behavior for both the printer and the reader.

@cindex @code{*ra-parenthesized-rank-zero*}
@anchor{x-star-ra-parenthesized-rank-zero-star}
@deffn @w{Parameter} *ra-parenthesized-rank-zero* boolean

Control read syntax of rank-0 arrays. This parameter is available from @code{(newra print)} or @code{(newra read)}.

If @code{(*ra-parenthesized-rank-zero*)} is true, the read syntax for rank-0 arrays is

@display
@code{#%0TYPE(item)}
@end display

If it is @code{#f}, it is

@display
@code{#%0TYPE item}
@end display

with @code{TYPE} being optional in either case. Note that these are not compatible:

@example
@verbatim
(ra-ref (parameterize ((*ra-parenthesized-rank-zero* #t))
          (call-with-input-string "#%0(a)" read)))
@end verbatim
@result{} @code{a}
@verbatim
(ra-ref (parameterize ((*ra-parenthesized-rank-zero* #f))
          (call-with-input-string "#%0(a)" read)))
@end verbatim
@result{} @code{(a)}
@verbatim
(ra-ref (parameterize ((*ra-parenthesized-rank-zero* #f))
          (call-with-input-string "#%0 a" read)))
@end verbatim
@result{} @code{a}
@end example

In the last example, the space is necessary (unlike in @mybibcite{SRFI-163}) since the array type tag is optional in Guile.

@example
@verbatim
(parameterize ((*ra-parenthesized-rank-zero* #f))
  (call-with-input-string "#%0a" read))
@end verbatim
@result{} Wrong type (expecting character): #<eof>
@end example

The printer always uses a space in this mode:

@example
@verbatim
(parameterize ((*ra-parenthesized-rank-zero* #f))
 (display (make-ra '(a))))
@end verbatim
@result{} @code{#%0 (a)}
@end example

Note that setting this parameter to @code{#f} still doesn't make the array read syntax fully compatible with that of @mybibcite{SRFI-163}, since the type tag @code{a} is reserved (in Guile) for character arrays.

The default value of this parameter is @code{#t}.

@end deffn

@c ------------------------------------------------
@node Iteration
@section Iteration
@c ------------------------------------------------

The basic array iteration operations in @code{newra} all operate by effect. This gives you control of how the result is allocated. If one of the arguments is designated as destination, as is the case with @ref{x-ra-map!, @code{ra-map!}}, then that is the result of the whole iteration. For example:

@example
@verbatim
(ra-map! (make-ra #f 3) - (ra-iota 3 1))
@end verbatim
@result{} #%1:3(-1 -2 -3)
@end example

It is common to need the indices of the elements during array iteration. @code{newra} iteration operations do not keep track of those indices@footnote{An exception is @ref{x-ra-index-map!, @code{ra-index-map!}}, where passing the indices is the purpose.} because that has a cost. You need to pass the indices you need as arguments, but it's easy to do so by using an unbounded index vector together with @ref{x-ra-transpose, @code{ra-transpose}}.

@example
@verbatim
(define i0 (ra-iota))
(define i1 (ra-transpose (ra-iota) 1))
(ra-map! (make-ra #f 2 2) list (list->ra 2 '((A B) (C D))) i0 i1)
@end verbatim
@result{} #%2:2:2(((A 0 0) (B 0 1)) ((C 1 0) (D 1 1)))
@end example

One can iterate not only over the whole array, but also over any @code{n}-frame (the first @code{n} axes of an array), using @ref{x-ra-slice-for-each, @code{ra-slice-for-each}}. In this case the operation takes array slices as arguments, even when they are of rank 0; this allows writing to any of the arguments. When there are several arrays involved, all the frames must match.

In the following example, @code{xys} is of rank 2, @code{angle} is of rank 1, and their first axes have the same length.

@example
@verbatim
(ra-slice-for-each 1
  (lambda (xy angle)
; inside the op, xy is rank 1, angle is rank 0
    (ra-set! angle (atan (ra-ref xy 1) (ra-ref xy 0))))
  xys angles)
@end verbatim
@end example

@cindex prefix matching
The iteration procedures in @code{newra} all perform rank extension of their arguments through prefix matching (see @ref{Rank extension}). In the following example, the shapes of the arguments are (5 5), (5) and (@code{#f} 5), and the common prefixes all match.

@example
@verbatim
(ra-map! (make-ra 5 5) * (ra-iota 5 1) (ra-transpose (ra-iota 5 1) 1))
@end verbatim
@result{} @code{#%2:5:5((1 2 3 4 5) (2 4 6 8 10) (3 6 9 12 15) (4 8 12 16 20) (5 10 15 20 25))}
@end example

Another example using @ref{x-ra-copy!, @code{ra-copy!}},

@example
@verbatim
(ra-copy! (list->ra 2 '((a b) (p q) (x y)))
          (list->ra 1 '(1 2 3)))
@end verbatim
@result{} @code{#%2:3:2((1 1) (2 2) (3 3))}
@end example

@c ------------------------------------------------
@node Slicing
@section Slicing
@c ------------------------------------------------

Slicing refers to the operation of taking a partial view of an array (e.g. a row or a column out of a matrix) through modification of the dim vector. This can be done with creative uses of @ref{x-ra-ravel, @code{ra-ravel}}, @ref{x-ra-reshape, @code{ra-reshape}} and @ref{x-ra-transpose, @code{ra-transpose}}, and of course by direct modification of the dim vector, but the facilities described in this section are usually a lot clearer.

@cindex prefix slice
The simplest form of slicing uses @ref{x-ra-slice, ra-slice} to produce ‘prefix slices’.

@example
@verbatim
(define a (list->ra 3 '(((a b) (x y)) ((A B) (X Y)))))
@end verbatim
@result{} @code{#%3:2:2:2(((a b) (x y)) ((A B) (X Y)))}
@verbatim
(ra-slice a 0 1 0)
@end verbatim
@result{} @code{#%0(x)}
@verbatim
(ra-slice a 0 1)
@end verbatim
@result{} @code{#%1:2(x y)}
@verbatim
(ra-slice a 0)
@end verbatim
@result{} @code{#%2:2:2((a b) (x y))}
@verbatim
(ra-slice a)
@end verbatim
@result{} @code{#%3:2:2:2(((a b) (x y)) ((A B) (X Y)))}
@end example

The prefix slice always shares the root of the source array, so it can be used to modify the source array.

@example
@verbatim
(ra-fill! (ra-slice a 1 0) '99)
@end verbatim
@result{} @code{#%1:2(99 99)}
@verbatim
a
@end verbatim
@result{} @code{#%3:2:2:2(((a b) (x y)) ((99 99) (X Y)))}
@end example

The variant @ref{x-ra-cell, @code{ra-cell}} is identical to @code{ra-slice} except that it returns an element (and not a rank 0 array) when the full set of indices is given.

@example
@verbatim
(ra-slice a 0 1 0)
@end verbatim
@result{} @code{x}
@end example

@code{ra-cell} is a @ref{Rank polymorphism, rank-polymorphic} generalization of the basic element lookup function @ref{x-ra-ref, @code{ra-ref}}, which requires the full set of indices.

@example
@verbatim
(ra-ref a 0 1 0) ; same as ra-cell
@end verbatim
@result{} @code{x}
@verbatim
(ra-ref a 0 1)
@end verbatim
@result{} @code{"<unnamed port>":...: Throw to key `bad-number-of-indices' with args `(3 2)'.}
@end example

Both @code{ra-cell} and @code{ra-slice} (and @code{ra-ref}) take scalar indices as arguments. The more powerful function @ref{x-ra-from, @code{ra-from}} is able to handle arrays of indices.

@cindex @code{@{}, from
@quotation
@verbatim
(ra-from a i₀ ...) ⇒ b
@end verbatim
@end quotation

Each of the @code{i₀...} is either 1. an integer; 2. an array of integers; 3. the special value @code{#t}. Integer arguments contain indices into the respective axis of @code{a}. @code{#t} for @code{iₖ} is a shortcut for ‘the whole of axis @code{k}’@footnote{Note that this is not the same as @code{(let ((d (vector-ref (ra-dims a) k))) (ra-iota (dim-len d) (dim-lo d)))}, because the lower bound of @code{(ra-iota ...)} (@emph{not} its content) is 0, not @code{(dim-lo d)}, so the corresponding lower bound on the result array would also be 0, while @code{#t} preserves the lower bound of @code{a}.}. The result @code{b} has rank equal to the sum of all the ranks of the @code{i₀...}, and is defined as

@quotation
@verbatim
(ra-ref b j₀ ...) = (ra-ref a (ra-ref i₀ j₀ ...) ...)
@end verbatim
@end quotation

In other words, @code{ra-from} produces the outer product of the indices @code{i₀...} with operator @code{a} (if one thinks of @code{(a i₀ ...)} as @code{(ra-ref a i₀ ...)}).

If all of the @code{i...} are integers or arrays of type @code{d} (such as those produced by @code{ra-iota} or @code{ra-i}) then the result of @code{ra-from} shares the root of @code{a}. Otherwise @code{newra} cannot tell whether the indices are an arithmetic sequence, so the result has to be copied to a new root. For example:

@example
@verbatim
(define a (list->ra 2 '((a b c) (d e f))))
@end verbatim
@result{} @code{#%2:2:3((a b c) (d e f))}
@verbatim
(ra-from a 0 #t) ; row 0, will share root
@end verbatim
@result{} @code{#%1:3(a b c)}
@verbatim
(ra-from a #t 1) ; column 1, will share root
@end verbatim
@result{} @code{#%1:2(b e)}
@verbatim
(ra-from a #t (make-ra-root #(2 0))) ; cols 2 & 0, won't share root
@end verbatim
@result{} @code{#%2:2:2((c a) (f d))}
@verbatim
(ra-from a #t (ra-iota 2 2 -2)) ; cols 2 & 0, will share root
@end verbatim
@result{} @code{#%2:2:2((c a) (f d))}
@end example

One may give fewer @code{i} than the rank of @code{a}. The missing arguments are taken as @code{#t} (see @ref{Rank polymorphism}).

@example
@verbatim
(ra-from a 0) ; row 0, same as (ra-from a 0 #t)
@end verbatim
@result{} @code{#%1d:3(0 1 2)}
@end example

@cindex @code{ldots}
When used as an argument to @code{ra-from} (or @code{ra-amend!}), the special object @code{(@ref{x-ldots, ldots} n)} stands for @code{n} times @code{#t}. @code{(ldots)} alone will expand to fill the rank of the array argument, so the indices that come after are pushed to the last axes.

@example
@verbatim
(ra-from A 0 (ldots 1) 1) ; same as (ra-from A 0 #t 1)
(ra-from B 0 (ldots 2) 1) ; same as (ra-from B 0 #t #t 1)
(ra-from C 0 (ldots) 1) ; same as (ra-from C 1 (ldots (- (ra-rank C) 2)) 1)
@end verbatim
@end example

For instance:
@example
@verbatim
(ra-i 4 3 2)
@end verbatim
@result{} #%3d:4:3:2(((0 1) (2 3) (4 5)) ((6 7) (8 9) (10 11)) ((12 13) (14 15) (16 17)) ((18 19) (20 21) (22 23)))
@verbatim
(ra-from (ra-i 4 3 2) (ldots) 1) ; select second element on last axis
@end verbatim
@result{} #%2d:4:3((1 3 5) (7 9 11) (13 15 17) (19 21 23))
@end example

When it is known that the result of @code{ra-from} will share the root with its argument, that can be used to modify the original array. For example:

@example
@verbatim
(ra-fill! (ra-from a 1) x)
@end verbatim
@result{} @code{#%2:3((a b c) (x x x)}
@verbatim
a
@end verbatim
@result{} @code{#%2:3((a b c) (x x x))}
@end example

@ref{x-ra-amend!, @code{ra-amend!}} handles the general case:

@example
@verbatim
(define a (list->ra 2 '((a b c) (d e f))))
(ra-amend! a 'Y #t (make-ra-root #(2 0)))
@end verbatim
@result{} @code{#%2:3((Y b Y) (Y e Y))}
@verbatim
a
@end verbatim
@result{} @code{#%2:3((Y b Y) (Y e Y))}
@end example
while on the other hand
@example
@verbatim
(define a (list->ra 2 '((a b c) (d e f))))
(ra-fill! (ra-from a #t (make-ra-root #(2 0))) 'Y)
@end verbatim
@result{} @code{#%2:3((Y Y) (Y Y))}
@verbatim
a
@end verbatim
@result{} @code{#%2:3((a b c) (d e f))}
@end example

@c ------------------------------------------------
@node Reshaping
@section Reshaping
@c ------------------------------------------------

@cindex APL
@cindex @code{,}, ravel
@cindex @code{⍴}, reshape
To match APL ρ, @code{newra} offers three separate functions.

@ref{x-ra-reshape, @code{ra-reshape}} and @ref{x-ra-ravel, @code{ra-ravel}} are in a way the inverse of each other. @code{ra-reshape} folds an axis into (potentially) many, while @code{ra-ravel} makes a block of axes into a single axis. Neither is able to increase the size of the array (although @code{ra-reshape} can @emph{reduce} it). For that purpose @ref{x-ra-tile, @code{ra-tile}} is provided.

@example
@verbatim
(ra-dimensions (ra-i 2 3 4))
@end verbatim
@result{} (2 3 4)
@verbatim
; insert new axis of size 5 before axis 0
(ra-dimensions (ra-tile (ra-i 2 3 4) 0 5))
@end verbatim
@result{} (5 2 3 4)
@verbatim
; collapse axes 0 and 1
(ra-dimensions (ra-ravel (ra-tile (ra-i 2 3 4) 0 5) 2))
@end verbatim
@result{} (10 3 4)
@verbatim
; reshape axis 0 into two axes with shape [3 3]
(ra-dimensions (ra-reshape (ra-ravel (ra-tile (ra-i 2 3 4) 0 5) 2) 0 3 3))
@end verbatim
@result{} (3 3 3 4)
@end example

@code{ra-reshape} and @code{ra-tile} always reuse the root of the argument. On the other hand @code{ra-ravel} may not be able to, depending on the storage order of the array — this is one of the reasons to have three different functions instead of only one. You can check in advance whether @code{ra-ravel} will reuse the root with the function @ref{x-ra-order-c?, @code{ra-order-c?}}.

@c ------------------------------------------------
@node Concatenation
@section Concatenation
@c ------------------------------------------------

@cindex concatenation
@code{newra} offers two concatenation operations: @ref{x-ra-cat, @code{ra-cat}} (prefix cat) and @ref{x-ra-scat, @code{ra-scat}} (suffix cat).

For @code{ra-cat}, the arguments are prefix-matched, and the concatenation axis is counted from the left. E.g. for three arrays @var{r}, @var{s}, @var{t} with shapes

@example
@verbatim
(r₀ r₁ r₂ r₃)
(s₀ s₁ s₂ s₃ s₄ s₅)
(t₀ t₁)
@end verbatim
@end example

Then @code{(define val (ra-cat #t 1 r s t))} will prefix-match these to (it is an error if any of @code{r₀=s₀=t₀}, @code{r₂=s₂}, or @code{r₃=s₃} don't hold)

@example
@verbatim
(s₀ |r₁| s₂ s₃ s₄ s₅)
(s₀ |s₁| s₂ s₃ s₄ s₅)
(s₀ |t₁| s₂ s₃ s₄ s₅)
@end verbatim
@end example

and then concatenate them along axis 1 into an array of shape @code{(s₀ (r₁+s1+t₁) s₂ s₃ s₄ s₅)}.

For @code{ra-scat}, the arguments are suffix-matched, and the concatenation axis is counted from the right. For example

@example
@verbatim
(define r (ra-i 2 3 2))
(define s (list->ra 1 '(a b)))
(ra-scat #t 1 r s)
@end verbatim
@end example

the axes are aligned as

@example
@verbatim
(r₀ r₁ r₂)
      (s₀)
@end verbatim
@end example

and suffix-matched (s₀ and r₂ must match)

@example
@verbatim
(r₀ |r₁| r₂)
(r₀ | 1| r₂)
@end verbatim
@end example

for a result

@example
@verbatim
(ra-scat #t 1 r s)
@end verbatim
@result{} @code{#%3(((0 1) (2 3) (4 5) (a b)) ((6 7) (8 9) (10 11) (a b)))}
@end example

Note that the rank extension of @code{s} on the concatenation axis yields a length of 1 (and not @code{r₀}). It can be useful to think of the axis argument of @code{ra-scat} as indicating cell rank, so the code above means `concatenate 1-cells'.

For both @code{ra-cat} and @code{ra-scat}, axes other than the concatenation axis must match across all of the arguments.

@example
@verbatim
(ra-cat #t 0 (ra-i 3 2) (ra-i 2))
@end verbatim
@result{} @code{#%2:4:2((0 1) (2 3) (4 5) (0 0) (1 1))}
@end example

@example
@verbatim
(ra-scat #t 1 (ra-i 3 2) (ra-i 2))
@end verbatim
@result{} @code{#%2:4:2((0 1) (2 3) (4 5) (0 1))}
@end example

In particular, it is not enough for the lengths to be the same; both bounds must match.

@example
@verbatim
(ra-cat #t 0 (make-ra 'a '(1 1) '(1 4))
             (make-ra 'b '(2 2) '(1 4)))
@end verbatim
@result{} @code{#%2:2@@1:4((a a a a) (b b b b))} ; axes 1 match, axes 0 don't need to
@end example

@example
@verbatim
(ra-cat #t 1 (make-ra 'a '(1 1) '(1 4))
             (make-ra 'b '(2 2) '(1 4)))
@end verbatim
@result{} error ; axes 0 don't match
@end example

Here @ref{x-ra-reshape,@code{ra-reshape}} is used to move axis 0 of the second argument into agreement.@footnote{An example of how using lower bounds other than 0 is generally worthless trouble, not least for the library author.}

@example
@verbatim
(ra-cat #t 1 (make-ra 'a '(1 1) '(1 4))
             (ra-reshape (make-ra 'b '(2 2) '(1 4)) 0 '(1 1)))
@end verbatim
@result{} @code{#%2@@1:1:8((a a a a b b b b))}
@end example

On the concatenation axis, only lengths matter; for both @code{ra-cat} and @code{ra-scat}, the lower bound is 0 in the result, and the lower bounds of the arguments are ignored.

@example
@verbatim
(define a (make-ra 'a '(1 2) '(2 3)))
(define b (make-ra 'b '(1 2)))
(define c (make-ra 'c '(1 2) '(-1 0)))
(ra-format (ra-cat #t 1 a b c))
@end verbatim
@result{}
@verbatim
#%2@1:2:5─┐
│a│a│b│c│c│
├─┼─┼─┼─┼─┤
│a│a│b│c│c│
└─┴─┴─┴─┴─┘
@end verbatim
@end example

Both @code{ra-cat} and @code{ra-scat} accept a negative concatenation axis. That will rank-extend all the arguments to the left (@code{ra-cat}) or to the right (@code{ra-scat}) before concatenating on the leftmost (@code{ra-cat}) or rightmost (@code{ra-scat}) axis. In the same way, one may give a concatenation axis which is beyond the rank of the argument with the highest rank. Consider

@example
@verbatim
(define abc (list->ra 1 #(a b c)))
(ra-cat #t -1 (ra-i 3) abc)
@end verbatim
@result{} @code{#%2:2:3((0 1 2) (a b c))}
@end example
@example
@verbatim
(ra-cat #t 0 (ra-i 3) abc)
@end verbatim
@result{} @code{#%1:6(0 1 2 a b c)}
@end example
@example
@verbatim
(ra-cat #t 1 (ra-i 3) abc)
@end verbatim
@result{} @code{#%2:3:2((0 a) (1 b) (2 c))}
@end example

vs

@example
@verbatim
(ra-scat #t -1 (ra-i 3) abc)
@end verbatim
@result{} @code{#%2:3:2((0 a) (1 b) (2 c))}
@end example
@example
@verbatim
(ra-scat #t 0 (ra-i 3) abc)
@end verbatim
@result{} @code{#%1:6(0 1 2 a b c)}
@end example
@example
@verbatim
(ra-scat #t 1 (ra-i 3) abc)
@end verbatim
@result{} @code{#%2:2:3((0 1 2) (a b c))}
@end example

Cf J append (,) stitch (,.).

@c ------------------------------------------------
@node Transposition
@section Transposition
@c ------------------------------------------------

@cindex @code{⍉}, transpose
@cindex transpose

@ref{x-ra-transpose, @code{ra-transpose}} takes a source array and one axis argument for each of the dimensions of the source array. The values of the arguments are the corresponding axes of the result array.

@example
@verbatim
(ra-dimensions (ra-transpose (ra-i 10 20 30) 2 0 1))
@end verbatim
@result{} @code{'(20 30 10)}
@end example

That is, axis 0 in the source array is mapped to axis 2 in the destination array, axis 1 to axis 0, and axis 2 to axis 1. The result array always shares the root of the source array.

As you'd expect

@example
@verbatim
(ra-transpose (ra-i 2 3) 1 0)
@end verbatim
@result{} @code{#%2d:3:2((0 3) (1 4) (2 5))}
@end example

One can map more than one axis of the source array to the same axis of the destination array. In that case the step of the destination axis becomes the sum of the steps of all the source axes. The classic example is

@cindex diagonal
@example
@verbatim
(define A (ra-copy #t (ra-i 3 3)))
(ra-fill! (ra-transpose A 0 0) 'x)
A
@end verbatim
@result{} @code{#%2:3:3((x 1 2) (3 x 5) (6 7 x))}
@end example

If one doesn't give values for all of the source axes, the missing axes are sent beyond the highest one that was given. These are equivalent:

@example
@verbatim
(ra-transpose (ra-i 2 3 4) 1 0 2)
(ra-transpose (ra-i 2 3 4) 1 0) ; fill with (+ 1 (max 1 0))
@end verbatim
@end example

as are these:

@example
@verbatim
(ra-transpose (ra-i 2 3) 1) ; fill with (+ 1 (max 1))
(ra-transpose (ra-i 2 3) 1 2)
@end verbatim
@end example

Note that in the last example there is no source axis for destination axis 0. Destination axes not mentioned in the axis argument list become @ref{x-dead-axes,dead axes}. The rank of the result array is always just large enough to fit all the destination axes.

@example
@verbatim
(ra-dimensions (ra-transpose (ra-i 2 3) 1))
@end verbatim
@result{} (#f 2 3)
@end example

In particular, @code{(ra-transpose A)} is equivalent to @code{(ra-transpose A 0 1 ... (- (ra-rank A) 1))} (which is of course the same array as @code{A}).

@cindex outer product
This ability of @code{ra-transpose} can be exploited to compute `outer products'. In the following example the shape @code{[2 2]} of @code{A} matches with the two leading dead axes of @code{(ra-transpose B 2)}:

@example
@verbatim
                 A : [2 2]
(ra-transpose B 2) : [f f 2 2]
@end verbatim
@end example

@cindex prefix matching
The trailing axes then match through @ref{Rank extension,prefix matching}.

@example
@verbatim
(define A (list->ra 2 '((a b) (c d))))
(define B (ra-i 2 2))
(ra-format (ra-map! (make-ra #f 2 2 2 2)
             (lambda i (format #f "~{~a~}" i))
             A (ra-transpose B 2)))
@end verbatim
@result{}
@verbatim
#%4:2:2:2:2═╗
║a0│a1║b0│b1║
║──┼──║──┼──║
║a2│a3║b2│b3║
╠═════╬═════╣
║c0│c1║d0│d1║
║──┼──║──┼──║
║c2│c3║d2│d3║
╚═════╩═════╝
@end verbatim
@end example

@cindex index placeholder
Another use is the creation of ‘index placeholders’, e.g.
@example
@verbatim
(define (tensor-index i) (ra-transpose (ra-iota) i))
(ra-format (ra-map! (make-ra #f 3 4) list (tensor-index 0) (tensor-index 1)))
@end verbatim
@result{}
@verbatim
#%2:3:4─────┬─────┬─────┐
│(0 0)│(0 1)│(0 2)│(0 3)│
├─────┼─────┼─────┼─────┤
│(1 0)│(1 1)│(1 2)│(1 3)│
├─────┼─────┼─────┼─────┤
│(2 0)│(2 1)│(2 2)│(2 3)│
└─────┴─────┴─────┴─────┘
@end verbatim
@end example

@cindex ⍋
@cindex grade
The function @ref{x-ra-untranspose, @code{ra-untranspose}} takes its axis arguments the other way from @code{ra-transpose}; the value of each argument is the axis of the original array and the position in the argument list is the axis of the result array. This is less flexible than @code{ra-transpose}, but can be used to reverse an application of @code{ra-transpose} without having to sort (‘grade’) the original axis arguments.

@example
@verbatim
(define a (ra-i 2 3 4))
(ra-equal? a (ra-untranspose (ra-transpose a 2 0 1) 2 0 1))
@end verbatim
@result{} @code{#t}
@end example

@c @cindex @code{none}
@c @anchor{x-none}
@c @deffn @w{Special objects} {none}
@c For example...

@c @example
@c @verbatim
@c For example
@c @end verbatim
@c @end example

@c @end deffn

@c ------------------------------------------------
@node Other operations on arrays
@section Other operations on arrays
@c ------------------------------------------------

@c ------------------------------------------------
@node Automatic result arrays
@section Automatic result arrays
@c ------------------------------------------------

Most of the functions of @code{newra} do not create arrays, but instead they expect result arrays to be passed as arguments. This means that they must have been allocated before. However, there are a few functions, such as @ref{x-ra-copy, @code{ra-copy}} or @ref{x-ra-map, @code{ra-map}}, that do create a result array. The type and shape of that result array is deduced from the source arguments, as follows.

@itemize
@item The default type of the result array is the type of the first of the source arguments. If that type is @code{'d}, however, the default type of the result array is @code{#t}. Usually, a function will allow this default to be overriden with an explicit argument. If that argument is required, then @code{#f} will select the default.
@item The rank of the result array will be the rank of the source argument with the largest rank. On each dimension, the lower bound and the length of the result will match those of the source arguments, with the precision that if any of those is finite, then it will be finite in the result as well. (If there is only one source argument, as is the case for @code{ra-copy}, then it follows that that is the shape of the result.)
@end itemize

For example:

@example
@verbatim
(ra-map #t *
  ; shape '((0 1))
  (ra-iota 2 1)
  ; shape '((#f #f) (1 3))
  (ra-transpose (make-ra 9 '(1 3)) 1))
@end verbatim
@result{}
@verbatim
; shape of result is '((0 1) (1 3))
#%2:2@1:3((9 9 9) (18 18 18)
@end verbatim
@end example

@c ------------------------------------------------
@node Foreign interface
@section Foreign interface
@c ------------------------------------------------

One of the major reasons to use arrays instead of other Scheme data structures is that they let one pass a large amount of data through a C interface very efficiently. The data doesn't need to be copied — one only needs to pass a pointer to the data, plus the lengths and the steps in some order. C doesn't have a standard consolidated array type, so the particulars are variable. In any case, the required items can be obtained trivially from a @code{newra} array object.

For example:

TODO

@c ------------------------------------------------
@node Compatibility with old Guile arrays
@section Compatibility with old Guile arrays
@c ------------------------------------------------

The functions @ref{x-ra->array, @code{ra->array}} and @ref{x-array->ra, @code{array->ra}} are provided to convert to and from @code{newra} arrays and built-in Guile arrays. It is an error to use @code{ra->array} on arrays whose root isn't supported by the built-in arrays, or that have an unbounded axis. Except in those two cases, the conversion is transparent both ways, and the result always shares the root of the argument.

@example
@verbatim
(define a (make-array 'o 2 3))
(define b (array->ra a))
(ra-set! b 'x 1 1)
(array-set! a 'y 0 2)
a
@end verbatim
@result{} @code{#2((o o y) (o x o))}
@verbatim
b
@end verbatim
@result{}  @code{#%2((o o y) (o x o))}
@end example

@code{<aseq>}-root arrays must be type converted before using @code{ra->array}.

@example
@verbatim
(ra->array (ra-copy #t (ra-i 2 3)))
@end verbatim
@result{} #2((0 1 2) (3 4 5))
@end example

On dead axes, lengths can be set to 1 (with @ref{x-ra-singletonize, @code{ra-singletonize}}) to allow conversion with @code{ra->array} or to other array systems that do singleton broadcasting.

@example
@verbatim
(define a (ra-transpose (ra-i 2 3) 1 3))
a
@end verbatim
@result{} @code{#%4d:d:2:d:3((((0 1 2)) ((3 4 5))))}
@verbatim
(ra-singletonize a)
@end verbatim
@result{} @code{#%4d:1:2:1:3((((0 1 2)) ((3 4 5))))}
@end example

One important difference between the built-in array functions and @code{newra} is that bounds matching in @code{newra} is strict: finite bounds must be identical for axes to match, while for @code{array-map!}, @code{array-for-each}, @code{array-copy!}, etc. the iteration range is the intersection of the ranges of the arguments@footnote{I decided against this approach for @code{newra} because in my experience it results in errors going undetected much more often than it saves any work.}. @code{newra} provides @ref{x-ra-clip, @code{ra-clip}} to match ranges easily.

@example
@verbatim
(define a (make-ra-root (vector 'a 'b 'c 'd 'e 'f 'g))) ; range is 0..6
(define b (ra-reshape (ra-iota 4) 0 '(2 5))) ; range is 2..5
(ra-copy! a b)
@end verbatim
@result{} @code{Throw to key `mismatched-lens' with args `(7 4 at-dim 0)'.}
@verbatim
(ra-copy! (ra-clip a b) b)
a
@end verbatim
@result{} @code{#%1:7(a b 0 1 2 3 g)}
@c Cf. using built-in arrays @c Looks like a Guile bug to me :-/
@c @verbatim
@c (define a (vector 'a 'b 'c 'd 'e 'f 'g)))
@c (define b #1@2:4(0 1 2 3))
@c (array-copy! b a)
@c a
@c @end verbatim
@c @result{} @code{#(0 1 2 3 e f g)}
@end example

@c ------------------------------------------------
@node High level
@chapter High level
@c ------------------------------------------------

NOTE This section is about a facility that hasn't been implemented yet.

In array languages such as APL, scalar operations are implicitly extended to work on arrays, so one can just write (the equivalent of) @code{(+ A B)} instead of @code{(ra-map! (make-ra ...) + A B)}. The basic @code{newra} iteration operations such as @code{ra-map!} already perform rank extension of their arguments (so @code{A} or @code{B} can have a different rank from the result, as long as the prefix axes match). We still need ways to:

@itemize
@item associate an operation to the ranks of their arguments, so that the right frame of iteration can be chosen.
@item compute the shape and type of the result (if any).
@item handle scalar (non-array) arguments.
@end itemize

@menu
* Verbs::
* Reductions::
@end menu

@c ------------------------------------------------
@node Verbs
@section Verbs
@c ------------------------------------------------

@c ------------------------------------------------
@node Reductions
@section Reductions
@c ------------------------------------------------

@c ------------------------------------------------
@node Hazards
@chapter Hazards
@c ------------------------------------------------

@menu
* Differences with...::
* Common mistakes::
* Performance pitfalls::
@end menu

@c ------------------------------------------------
@node Differences with...
@section Differences with...
@c ------------------------------------------------

If you come to @code{newra} from another array language or library, you may want to be aware of some of these differences. See also the @ref{Cheatsheet}.

Differences with built-in Guile arrays:
@itemize
@item @code{newra} map operations are rank-extending but require exact agreement of bounds, unlike operations on built-in arrays, which require exact rank agreement but admit overlapping bounds.
@end itemize

@cindex APL
Differences with APL:
@itemize
@item The default lower bound (base index) in @code{newra} is 0, as in @code{⎕io←0}. The lower bound isn't global, but it may be different per axis.
@item @code{newra} arrays of size 1 are not equivalent to scalars and always retain their rank. For example, @code{(make-ra 99)}, @code{(make-ra 99 1)} and @code{(make-ra 99 1 1)} are all different from each other and from the scalar @code{99}, while in APL @code{99}, @code{(1 ⍴ 99)}, and @code{(1 1 ⍴ 99)} are all the same thing.
@item When a function takes multiple arguments, the meaning with multiple arguments is an extension of the meaning with a single argument. This contrasts with APL where the monadic and dyadic versions of a verb usually have a related but independent definition. For example @code{(ra-transpose a)}≡@code{(ra-transpose a 0)}≡@code{(ra-transpose a 0 1)}, but (assuming @code{a} is of rank 2) @code{⍉a}≡@code{2 1⍉a}. Please check the documentation for each function.
@end itemize

@cindex Fortran
Differences with Fortran:
@itemize
@item The default lower bound (base index) in @code{newra} is 0, not 1. Like in Fortran, the lower bound may be different for each axis of each array.
@item Unlike Fortran, the default element order in arrays is row-major, or ‘last index changes fastest’. It's possible to define and manipulate arrays in any other order, including Fortran's default. However, some functions (such as @code{ra-ravel}) only support row-major order.
@item @code{newra} uses prefix matching for rank extension on arguments on any rank, while Fortran only performs rank extension on scalar arguments.
@end itemize

@cindex Python
@cindex NumPy
Differences with NumPy:
@itemize
@item @code{newra} uses prefix matching for rank extension, while Numpy uses suffix matching. For example: FIXME.
@item @code{newra} doesn't use singleton broadcasting. Axes of length 1 only match axes of length 1. For example, @code{(ra-map! (make-ra 0 2) + (make-ra 90 1) (make-ra 7 2))} is an error because the shapes (2), (1), (2) don't agree.
@end itemize

@cindex Octave
@cindex Matlab
Differences with Octave:
@itemize
@item The default lower bound (base index) in @code{newra} is 0, not 1. Lower bounds may be 1 on a particular array (or particular axes of an array), but not globally.
@item In Octave, any array of rank ≤ 2 is implicity a matrix (an array of rank 2). This isn't true in @code{newra}, so, for example, an array of rank 1 isn't equivalent to an array of rank 2 with a single row (a ‘row vector’).
@item Unlike Octave, the default element order in arrays is row-major, or ‘last index changes fastest’. It's possible to define and manipulate arrays in any other order, including Octave's default. However, some functions (such as @code{ra-ravel}) only support row-major order.
@item @code{newra} uses prefix matching for rank extension on arguments on any rank, while Octave only performs rank extension on scalar arguments.
@end itemize

@c ------------------------------------------------
@node Common mistakes
@section Common mistakes
@c ------------------------------------------------

@c ------------------------------------------------
@node Performance pitfalls
@section Performance pitfalls
@c ------------------------------------------------

@c ------------------------------------------------
@node Reference
@chapter Reference
@c ------------------------------------------------

@cindex @code{array->ra}
@anchor{x-array->ra}
@deffn @w{Function} array->ra a

Convert built-in Guile array @var{a} (anything that satisfies @code{array?}) into a (@code{newra)} array.

This function doesn't create a copy of the array, but reuses the root (@code{shared-array-root}) of @var{a}, that is, @code{(eq? (ra-root (array->ra a)) (shared-array-root a))} is @code{#t}.

@example
@verbatim
(define a (make-array 'x 2 2))
(define b (array->ra v))
b
@end verbatim
@result{} @code{#%2:2:2((x x) (x x))}
@verbatim
(ra-fill! b 'y)
a
@end verbatim
@result{} @code{#2((y y) (y y))}
@end example

See also: @ref{x-ra->array,@code{ra->array}}.

@end deffn

@cindex @code{c-dims}
@anchor{x-c-dims}
@deffn @w{Function} c-dims bounds ...

@cindex packed array
Create dims for row-major order array (packed elements, last dimension changing fastest).

Each of the bounds may be a pair of bounds (@var{lo} @var{hi}) or a single length @var{len}, which implies zero @var{lo}.
@example
@verbatim
(c-dims 2 3)
@end verbatim
@result{} @code{#(#<<dim> len: 2 lo: 0 step: 3> #<<dim> len: 3 lo: 0 step: 1>)}
@end example
@end deffn

@cindex @code{ldots}
@anchor{x-ldots}
@deffn @w{Function} ldots [n] ...

Placeholder for @var{n} full axes, used as argument to @code{ra-from} or @code{ra-amend!}. Without @var{n}, expand to fill the rank of the argument @var{a} of @ref{x-ra-from,@code{ra-from}} or @ref{x-ra-amend!,@code{ra-amend!}}.
@end deffn

@cindex @code{make-ra}
@anchor{x-make-ra}
@deffn @w{Function} make-ra val bounds ... @result{} a

Create an array of type @code{#t} with the given @var{bounds}, filled with @var{val}.

@example
@verbatim
(make-ra 0 '(2 3) 4)
@end verbatim
@result{} @code{#%2@@2:2:4((0 0 0 0) (0 0 0 0))}
@end example

See also: @ref{x-make-typed-ra,@code{make-typed-ra}}, @ref{x-make-ra-new,@code{ra-make-ra-new}}, @ref{x-ra-shape,@code{ra-shape}}.

@end deffn

@cindex @code{make-ra-new}
@anchor{x-make-ra-new}
@deffn @w{Function} make-ra-new type value dims
Create an array over a new root of the given @var{type} and size (according to @var{dims}), and fill it with @var{value}.
@example
@verbatim
(make-ra-new 'u8 0 (c-dims 3 2))
@end verbatim
@result{} #%2u8:3:2((0 0) (0 0) (0 0))
@end example
@end deffn

@cindex @code{make-ra-root}
@anchor{x-make-ra-root}
@deffn @w{Function} make-ra-root root [dims [zero]]
Create an array over the given @var{root}.
@example
@verbatim
(make-ra-root (vector 1 2 3))
@end verbatim
@result{} #%1d:3(1 2 3)
@end example

@example
@verbatim
(make-ra-root (vector 1 2 3) (vector (make-dim 2)))
@end verbatim
@result{} #%1d:2(1 2)
@end example

@example
@verbatim
(make-ra-root (vector 1 2 3) (vector (make-dim 2)) 1)
@end verbatim
@result{} #%1d:2(2 3)
@end example
@end deffn

@cindex @code{make-typed-ra}
@anchor{x-make-typed-ra}
@deffn @w{Function} make-typed-ra type val bounds ... @result{} a

Same as @ref{x-make-ra,@code{make-ra}}, except that the result has the specified @var{type}.

See also: @ref{x-make-ra,@code{make-ra}}, @ref{x-make-ra-root,@code{ra-make-ra-root}}.

@end deffn

@cindex intersection
@cindex @code{ra-clip}
@anchor{x-ra-clip}
@deffn @w{Function} ra-clip a b @result{} c
Slice @var{a} to the intersection of the bounds of @var{a} and @var{b}. If @var{a} and @var{b} have different ranks, only the common prefix of @var{a} is sliced.

@example
@verbatim
(define f (make-ra "   " '(-4 4) '(-5 3)))
(define a (make-ra " A " '(-3 0) '(-4 1)))
(define b (make-ra " B " '(-1 3) '(-1 2)))
(ra-fill! (ra-clip a b) " x ")
(ra-copy! (ra-clip f b) (ra-clip b f))
(ra-copy! (ra-clip f a) (ra-clip a f))
(ra-format f)
@end verbatim
@result{}
@verbatim
#%2@-4:9@-5:9───┬───┬───┬───┬───┬───┐
│   │   │   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ x │ x │ x │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ x │ x │ x │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │   │   │
└───┴───┴───┴───┴───┴───┴───┴───┴───┘
@end verbatim
@verbatim
(ra-fill! (ra-clip f (ra-clip a b)) " o ")
(ra-format f)
@end verbatim
@result{}
@verbatim
#%2@-4:9@-5:9───┬───┬───┬───┬───┬───┐
│   │   │   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ A │ A │ A │   │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ o │ o │ o │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │ A │ A │ A │ o │ o │ o │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │ B │ B │ B │ B │   │
├───┼───┼───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │   │   │
└───┴───┴───┴───┴───┴───┴───┴───┴───┘
@end verbatim
@end example

The result of @code{ra-clip} always shares the root of its first argument @var{a}.

See also: @ref{Slicing}, @ref{Compatibility with old Guile arrays}.
@end deffn

@cindex @code{ra-dimensions}
@anchor{x-ra-dimensions}
@deffn @w{Function} ra-dimensions a

Return the dimensions of @var{a} as a list, like @ref{x-ra-shape,@code{ra-shape}}, but the dimensions that have lower bound zero are represented by their length alone, instead of a two-element list @code{(lo hi)}. This is a convenience for the common case when lower bounds are zero.

@example
@verbatim
(ra-dimensions (make-ra 0 '(2 3) 4))
@end verbatim
@result{} @code{((2 3) 4)}
@verbatim
(ra-shape (make-ra 0 '(2 3) 4))
@end verbatim
@result{} @code{((2 3) (0 3))}
@end example

See also: @ref{x-ra-shape,@code{ra-shape}}, @ref{x-make-ra,@code{make-ra}}.

@end deffn

@cindex @code{ra-format}
@anchor{x-ra-format}
@deffn @w{Function} ra-format ra port #:fmt #:prefix?
@deffnx @w{Function} ra-format ra #f #:fmt #:prefix? @result{} sc

Pretty print array @var{ra}.

Each element @var{x} of @var{ra} is converted to a string using @code{(fmt x)}, or @code{(format #f fmt x)}@footnote{@url{https://www.gnu.org/software/guile/manual/html_node/Formatted-Output.html,@code{(ice-9 format)}}} if @var{fmt} is a string. @var{fmt} defauts to @code{"~a"}. Elements that are arrays are formatted using @code{ra-format} recursively.

If @var{port} is @code{#f}, nothing is printed; instead, the function returns a rank-2 character array @var{sc} with the result of the printing. Otherwise the array is printed to @var{port} and the function returns unspecified values. The default for @var{port} is @code{#t}, which works as @code{current-output-port}.

If @var{prefix?} is true, the array print prefix @ref{x-ra-print-prefix,@code{ra-print-prefix}} is printed over the first line of the printout if the rank of @var{ra} is 2 or greater, else it is printed on a separate line above the printout.

If @var{compact?} is true, the separators for the rank-0 cells are replaced by spaces and the separators for the rank-1 cells are omitted. This results in a more compact output at the cost of some clarity.

This function handles arrays of rank up to 8, or up to 10 in compact mode. The even dimensions (counting from the last one) are arranged horizontally, while the odd dimensions are arranged vertically. The dimensions are separated visually using @url{https://unicode.org/charts/nameslist/n_2500.html,box-drawing characters}. This might look better or worse depending on the font.

A 0-array:
@example
@verbatim
(ra-format (make-ra 'element))
@end verbatim
@result{}
@verbatim
#%0
element
@end verbatim
@end example

A 1-array:
@example
@verbatim
(ra-format (ra-i 4))
@end verbatim
@result{}
@verbatim
#%1d:4
│0│1│2│3│
@end verbatim
@end example

Compare with the 2-array
@example
@verbatim
(ra-format (ra-i 1 4))
@end verbatim
@result{}
@verbatim
#%2d:1:4┐
│0│1│2│3│
└─┴─┴─┴─┘
@end verbatim
@end example

Another 2-array:
@example
@verbatim
(ra-format (ra-i 3 4) #:prefix? #f)
@end verbatim
@result{}
@verbatim
┌─┬─┬──┬──┐
│0│1│ 2│ 3│
├─┼─┼──┼──┤
│4│5│ 6│ 7│
├─┼─┼──┼──┤
│8│9│10│11│
└─┴─┴──┴──┘
@end verbatim
@end example

A 5-array:
@example
@verbatim
(ra-format (ra-i 2 2 3 2 4) #:prefix? #f)
@end verbatim
@result{}
@verbatim
┃═══════════╦═══════════╦═══════════┃═══════════╦═══════════╦═══════════┃
┃ 0│ 1│ 2│ 3║ 8│ 9│10│11║16│17│18│19┃48│49│50│51║56│57│58│59║64│65│66│67┃
┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃
┃ 4│ 5│ 6│ 7║12│13│14│15║20│21│22│23┃52│53│54│55║60│61│62│63║68│69│70│71┃
┃═══════════╬═══════════╬═══════════┃═══════════╬═══════════╬═══════════┃
┃24│25│26│27║32│33│34│35║40│41│42│43┃72│73│74│75║80│81│82│83║88│89│90│91┃
┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃──┼──┼──┼──║──┼──┼──┼──║──┼──┼──┼──┃
┃28│29│30│31║36│37│38│39║44│45│46│47┃76│77│78│79║84│85│86│87║92│93│94│95┃
┃═══════════╩═══════════╩═══════════┃═══════════╩═══════════╩═══════════┃
@end verbatim
@end example

The same 5-array in compact mode:
@example
@verbatim
(ra-format (ra-i 2 2 3 2 4) #:prefix? #f #:compact? #t)
@end verbatim
@result{}
@verbatim
║───────────┬───────────┬───────────║───────────┬───────────┬───────────║
║ 0  1  2  3│ 8  9 10 11│16 17 18 19║48 49 50 51│56 57 58 59│64 65 66 67║
║ 4  5  6  7│12 13 14 15│20 21 22 23║52 53 54 55│60 61 62 63│68 69 70 71║
║───────────┼───────────┼───────────║───────────┼───────────┼───────────║
║24 25 26 27│32 33 34 35│40 41 42 43║72 73 74 75│80 81 82 83│88 89 90 91║
║28 29 30 31│36 37 38 39│44 45 46 47║76 77 78 79│84 85 86 87│92 93 94 95║
║───────────┴───────────┴───────────║───────────┴───────────┴───────────║
@end verbatim
@end example

@cindex SRFI-163
A nested array (example from @mybibcite{SRFI-163}):

@example
@verbatim
(ra-format (call-with-input-string "#%2@1:2@1:3((#%2((1 2) (3 4)) 9 #%2((3 4) (5 6)))
                                    (#%(42 43) #%2((8 7 6)) #%2((90 91) (100 101))))))"
                                   read))
@end verbatim
@result{}
@verbatim
#%2@1:2@1:3─────┬─────────┐
│#%2:2:2│      9│  #%2:2:2│
││1│2│  │       │  │3│4│  │
│├─┼─┤  │       │  ├─┼─┤  │
││3│4│  │       │  │5│6│  │
│└─┴─┘  │       │  └─┴─┘  │
├───────┼───────┼─────────┤
│#%1:2  │#%2:1:3│#%2:2:2─┐│
││42│43│││8│7│6│││ 90│ 91││
│       │└─┴─┴─┘│├───┼───┤│
│       │       ││100│101││
│       │       │└───┴───┘│
└───────┴───────┴─────────┘
@end verbatim
@end example

Looking at the return value when @var{port} is @code{#f}:
@example
@verbatim
(ra-format (ra-format (ra-i 2 3) #f #:prefix? #f) #:prefix? #f)
@end verbatim
@result{}
@verbatim
┌─┬─┬─┬─┬─┬─┬─┐
│┌│─│┬│─│┬│─│┐│
├─┼─┼─┼─┼─┼─┼─┤
│││0│││1│││2│││
├─┼─┼─┼─┼─┼─┼─┤
│├│─│┼│─│┼│─│┤│
├─┼─┼─┼─┼─┼─┼─┤
│││3│││4│││5│││
├─┼─┼─┼─┼─┼─┼─┤
│└│─│┴│─│┴│─│┘│
└─┴─┴─┴─┴─┴─┴─┘
@end verbatim
@end example

Using a custom element formatter:
@example
@verbatim
(ra-format (ra-map! (make-ra #f 4 4) sqrt (ra-reshape (ra-iota 20 -10) 0 4 4))
           #:fmt (lambda (x) (format #f (cond ((real? x) "~4,2f")
                                              ((complex? x) "~4,2i")
                                              (else "~a"))
                                     x)))
@end verbatim
@result{}
@verbatim
#%2:4:4────┬──────────┬──────────┬──────────┐
│0.00+3.16i│0.00+3.00i│0.00+2.83i│0.00+2.65i│
├──────────┼──────────┼──────────┼──────────┤
│0.00+2.45i│0.00+2.24i│0.00+2.00i│0.00+1.73i│
├──────────┼──────────┼──────────┼──────────┤
│0.00+1.41i│0.00+1.00i│      0.00│      1.00│
├──────────┼──────────┼──────────┼──────────┤
│      1.41│      1.73│      2.00│      2.24│
└──────────┴──────────┴──────────┴──────────┘
@end verbatim
@end example

If any of the lengths of @var{ra} is 0, only the prefix is printed.

This function doesn't handle large arrays in any particular way. User beware!

See also: @ref{x-ra-print,@code{ra-print}}, @ref{x-star-ra-print-star, @code{*ra-print*}}.

@end deffn

@cindex @code{ra-i}
@anchor{x-ra-i}
@deffn @w{Function} ra-i bounds ...

Create multidimensional index array with the given bounds.

The root is of type @code{d}. The first upper bound that isn't @code{#f} may be @code{#t}; this creates an unbounded axis.

@example
@verbatim
(ra-i 2 3 4)
@end verbatim
@result{} #%3d:2:3:4(((0 1 2 3) (4 5 6 7) (8 9 10 11)) ((12 13 14 15) (16 17 18 19) (20 21 22 23)))
@end example

See also: @ref{x-ra-iota,@code{ra-iota}}, @ref{x-ra-index-map!,@code{ra-index-map!}}. @footnote{Cf. @code{array-index} from @mybibcite{SRFI-164}.}

@end deffn

@cindex @code{ra-iota}
@anchor{x-ra-iota}
@deffn @w{Function} ra-iota len [lo [step]]
@deffnx @w{Function} ra-iota

Create rank-1 index array. The root is of type @code{d}. @var{lo} defaults to 0 and @var{step} to 1.

@example
@verbatim
(ra-iota 4 3 -1)
@end verbatim
@result{} #%1d:4(3 2 1 0)
@end example

@code{(ra-iota)} is unbounded both ways, e.g.

@example
@verbatim
(ra-shape (ra-iota))
@end verbatim
@result{} @code{((#f #f))}
@verbatim
((ra-iota) -100000000000)
@end verbatim
@result{} -100000000000
@end example

See also: @ref{x-ra-i,@code{ra-i}}.

@end deffn

@cindex @code{ra-cat}
@anchor{x-ra-cat}
@deffn @w{Function} ra-cat type i a ...  @result{} b

Concatenate arrays @var{a} ... along axis @var{i}. The arguments are prefix-matched and rank extended before concatenation. All axes must match, other than the concatenation axis.

This function always produces a new array, of the type given. If @var{type} is @code{#f} then the type of the first @var{a} is used, unless that is @code{d}, in which case @code{#t} is used. The lower bound in the concatenation axis of the result is 0; the lower bounds of the arguments in the concatenation axis are ignored.

@example
@verbatim
(ra-cat #f 1 #%1(a b) #%2((0 1) (2 3)))
@end verbatim
@result{} #%2((a 0 1) (b 2 3))
@end example

See also: @ref{x-ra-scat,@code{ra-scat}}, @ref{x-ra-tile,@code{ra-tile}},  @ref{Concatenation}.

@end deffn

@cindex @code{ra-print}
@anchor{x-ra-print}
@deffn @w{Function} ra-print ra [port]

Print an array to @var{port}. @var{port} defaults to @code{(current-output-port)}.

This is the default array printer. The result is meant to be back-readable, although some special arrays are not supported yet.

See also: @ref{x-ra-format,@code{ra-format}}, @ref{x-star-ra-print-star,@code{*ra-print*}}, @ref{x-star-ra-parenthesized-rank-zero-star, @code{*ra-parenthesized-rank-zero*}}.
@end deffn


@cindex @code{print prefix}
@cindex @code{ra-print-prefix}
@anchor{x-ra-print-prefix}
@deffn @w{Function} ra-print-prefix ra port #:dims?

Return the print prefix for array @var{ra}. This is a string that details the type, rank, and (optionally) the dimensions of @var{ra}, and is part of the default read syntax for arrays. This is the same syntax as that of the @url{https://www.gnu.org/software/guile/manual/html_node/Array-Syntax.html,the built in Guile arrays}, except that @var{dims?} defaults to true and @code{#%} is used instead of @code{#}.

This function is provided by the module @code{(newra print)}.

@example
@verbatim
(call-with-output-string (cut ra-print-prefix (make-ra 4 '(3 4) '(2 3)) <>))
@end verbatim
@result{} @code{"#%2@@3:2@@2:2"}
@end example

@example
@verbatim
(call-with-output-string (cut ra-print-prefix (make-ra 4 '(3 4) '(2 3)) <> #:dims? #t))
@end verbatim
@result{} @code{"#%2@@3@@2"}
@end example

See also: @ref{x-ra-format,@code{ra-format}}, @ref{Writing and reading}.

@end deffn

@cindex @code{ra-ravel}
@anchor{x-ra-ravel}
@deffn @w{Function} ra-ravel a [n [org]] @result{} b
Ravel axes [@var{org} ... @var{org}+@var{n}) of array @var{a} in row-major order. @var{n} defaults to the rank of @var{a} and @var{org} defaults to 0.

For example:
@example
@verbatim
(ra-ravel (ra-i 2 3))
@end verbatim
@result{} #%1d:6(0 1 2 3 4 5)
@end example

Consider this 3-array:

@example
@verbatim
(ra-format (ra-i 2 3 4))
@end verbatim
@result{}
@verbatim
#%3d:2:3:4║──┬──┬──┬──║
║0│1│ 2│ 3║12│13│14│15║
║─┼─┼──┼──║──┼──┼──┼──║
║4│5│ 6│ 7║16│17│18│19║
║─┼─┼──┼──║──┼──┼──┼──║
║8│9│10│11║20│21│22│23║
║─┴─┴──┴──║──┴──┴──┴──║
@end verbatim
@end example

Ravel axes 0..1:

@example
@verbatim
(ra-format (ra-ravel (ra-i 2 3 4) 2)) ; or (ra-ravel ... 2 0)
@end verbatim
@result{}
@verbatim
#%2d:6:4─┬──┐
│ 0│ 1│ 2│ 3│
├──┼──┼──┼──┤
│ 4│ 5│ 6│ 7│
├──┼──┼──┼──┤
│ 8│ 9│10│11│
├──┼──┼──┼──┤
│12│13│14│15│
├──┼──┼──┼──┤
│16│17│18│19│
├──┼──┼──┼──┤
│20│21│22│23│
└──┴──┴──┴──┘
@end verbatim
@end example

Ravel axes 1..2:

@example
@verbatim
(ra-format (ra-ravel (ra-i 2 3 4) 2 1))
@end verbatim
@result{}
@verbatim
@end verbatim
#%2d:2:12┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
│ 0│ 1│ 2│ 3│ 4│ 5│ 6│ 7│ 8│ 9│10│11│
├──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┼──┤
│12│13│14│15│16│17│18│19│20│21│22│23│
└──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
@end example

To ravel other combinations of axes, use @ref{Transposition}.

@cindex packed array
The full ravel of an array doesn't necessarily result in a rank-1 `packed' array, that is, one where the step is 1. If that is required, one can use @code{(ra-ravel (ra-copy ra))}. @footnote{This works because @ref{x-ra-order-c?, @code{ra-order-c?}} is always true for the result of @code{ra-copy}. Note that the ravel operation in @code{(ra-ravel (ra-copy ra))} is free, while it might not be in @code{(ra-copy (ra-ravel ra))}, so it is preferable, in principle, to copy first.}.

See also: @ref{x-ra-reshape,@code{ra-reshape}}, @ref{x-ra-tile,@code{ra-tile}}, @ref{Reshaping}.

@end deffn

@cindex @code{ra-reshape}
@anchor{x-ra-reshape}
@deffn @w{Function} ra-reshape a k bounds ... @result{} b
Reshape axis @var{k} of array @var{a} to @var{bounds}.

Each of the bounds may be an integer (a length) or a pair of integers (lower and upper bounds).
@example
@verbatim
(define a (ra-i 4 3))
(ra-format a)
@end verbatim
@result{}
@verbatim
#%2d:4:3┐
│0│ 1│ 2│
├─┼──┼──┤
│3│ 4│ 5│
├─┼──┼──┤
│6│ 7│ 8│
├─┼──┼──┤
│9│10│11│
└─┴──┴──┘
@end verbatim
@verbatim
(ra-format (ra-reshape a 0 2 2))
@end verbatim
@result{}
@verbatim
#%3d:2:2:3─┬──║
║0│1│2║6│ 7│ 8║
║─┼─┼─║─┼──┼──║
║3│4│5║9│10│11║
║─┴─┴─║─┴──┴──║
@end verbatim
@end example

The result of @code{ra-reshape} always shares the root of @var{a}.

It is an error if the product of the lengths in @var{bounds} exceeds the length of axis @var{k} of @var{a}. For example

@example
@verbatim
(ra-reshape (ra-i 8 2) 0 2 3)
@end verbatim
@result{} @code{#%3d:2:3:2(((0 1) (2 3) (4 5)) ((6 7) (8 9) (10 11))} ; ok, 8 can be reshaped into 2·3
@verbatim
(ra-reshape (ra-i 8 2) 0 4 3)
@end verbatim
@result{} error ; 8 cannot be reshaped into 4·3
@end example

@cindex bounds
@code{ra-reshape} may be used to change either of the bounds of an axis, not only its length. For example

@example
@verbatim
(ra-format (ra-i 2 3))
@end verbatim
@result {}
@verbatim
#%2d:2:3
│0│1│2│
├─┼─┼─┤
│3│4│5│
└─┴─┴─┘
@end verbatim
@end example

@example
@verbatim
(ra-format (ra-reshape (ra-i 2 3) 0 '(1 2)))
@end verbatim
@result {}
@verbatim
#%2d@1:2:3
│0│1│2│
├─┼─┼─┤
│3│4│5│
└─┴─┴─┘
@end verbatim
@end example

See also: @ref{x-ra-ravel,@code{ra-ravel}}, @ref{x-ra-tile,@code{ra-tile}}, @ref{Reshaping}.

@end deffn

@cindex @code{⌽}, reverse
@cindex @code{ra-reverse}
@anchor{x-ra-reverse}
@deffn @w{Function} ra-reverse a axes ... @result{} b
Reverse the given @var{axes} of @var{a}.

@example
@verbatim
(ra-reverse (ra-i 2 3) 0 1)
@end verbatim
@result{} #%1d:2:3((5 4 3) (2 1 0))
@end example

The reversed array shares the root of @var{a}.

See also: @ref{x-ra-rotate,@code{ra-rotate}}, @ref{x-ra-rotate,@code{ra-rotate!}}.

@end deffn

@cindex @code{⌽}, rotate
@cindex @code{⊖}, rowel
@cindex @code{ra-rotate}
@anchor{x-ra-rotate}
@deffn @w{Function} ra-rotate n a @result{} b
(FIXME: not implemented) Rotate the first axis of @var{a} toward the lower indices (‘to the left’) @var{n} times. @var{n} may be any integer. The result has the type of @var{a}, unless that type is @code{d}, in which case the result is of type @code{#t}.

This function always returns a new array.

Example:
@example
@verbatim
(ra-rotate 1 (ra-i 3 2))
@end verbatim
@result{} #%1:3:2((2 3) (4 5) (0 1))
@end example

See also: @ref{x-ra-rotate!,@code{ra-rotate!}}, @ref{x-ra-reverse,@code{ra-reverse}}.

@end deffn

@cindex rotate!
@cindex @code{ra-rotate!}
@anchor{x-ra-rotate!}
@deffn @w{Function} ra-rotate! n a @result{} a
Rotate in place the first axis of @var{a} to the left @var{n} times. @var{n} may be any integer. @var{a} must be writable. This function returns @var{a}.

Example:
@example
@verbatim
(define a (ra-copy #t (ra-i 3 2)))
(ra-rotate! 1 a)
a
@end verbatim
@result{} #%1:3:2((2 3) (4 5) (0 1))
@end example

See also: @ref{x-ra-rotate,@code{ra-rotate}}, @ref{x-ra-reverse,@code{ra-reverse}}.

@end deffn

@cindex @code{ra-scat}
@anchor{x-ra-scat}
@deffn @w{Function} ra-scat type i a ... @result{} b

Concatenate @var{i}-items of arrays @var{a} ... . The arguments are suffix-matched and rank extended before concatenation. All axes must match, other than the concatenation axis.

This function always produces a new array, of the type given. If @var{type} is @code{#f} then the type of the first @var{a} is used, unless that is @code{d}, in which case @code{#t} is used. The lower bound in the concatenation axis of the result is 0; the lower bounds of the arguments in the concatenation axis are ignored.

@example
@verbatim
(ra-scat #t 1 #%2((0 1) (2 3)) #%(a b))
@end verbatim
@result{} #%2((0 1) (2 3) (a b))
@end example

See also: @ref{x-ra-cat,@code{ra-cat}}, @ref{x-ra-tile,@code{ra-tile}}, @ref{Concatenation}.

@end deffn

@cindex @code{ra-shape}
@anchor{x-ra-shape}
@deffn @w{Function} ra-shape a @result{} s

Return the shape (a list of two-element lists, each containing the lower and upper bound of each axis) of array @var{a}.

@example
@verbatim
(ra-shape (make-ra 0 '(2 3) 4))
@end verbatim
@result{} @code{((2 3) (0 3))}
@end example

See also: @ref{x-ra-dimensions,@code{ra-dimensions}}, @ref{x-make-ra,@code{make-ra}}.

@end deffn

@cindex @code{ra-tile}
@anchor{x-ra-tile}
@deffn @w{Function} ra-tile a k bounds ... @result{} b
Replicate array @var{a} by inserting axes of @var{bounds} ... before axis @var{k}. If @var{t} is the shape of @var{a}, the shape of the result will be

@example
@verbatim
[t₀ ... tₖ₋₁ s₀ ... tₖ ...]
@end verbatim
@end example

Each of the bounds may be an integer (a length) or a pair of integers (lower and upper bounds).

@example
@verbatim
(define a (ra-i 3 4))
(ra-format a)
@end verbatim
@result{}
@verbatim
#%2d:3:4──┐
│0│1│ 2│ 3│
├─┼─┼──┼──┤
│4│5│ 6│ 7│
├─┼─┼──┼──┤
│8│9│10│11│
└─┴─┴──┴──┘
@end verbatim
@end example

@example
@verbatim
(ra-format (ra-tile a 0 2))
@end verbatim
@result{}
@verbatim
#%3d:2:3:4║─┬─┬──┬──║
║0│1│ 2│ 3║0│1│ 2│ 3║
║─┼─┼──┼──║─┼─┼──┼──║
║4│5│ 6│ 7║4│5│ 6│ 7║
║─┼─┼──┼──║─┼─┼──┼──║
║8│9│10│11║8│9│10│11║
║─┴─┴──┴──║─┴─┴──┴──║
@end verbatim
@end example

@example
@verbatim
(ra-format (ra-tile a 1 2))
@end verbatim
@result{}
@verbatim
#%3d:3:2:4┬─┬─┬─║─┬─┬──┬──║
║0│1│2│3║4│5│6│7║8│9│10│11║
║─┼─┼─┼─║─┼─┼─┼─║─┼─┼──┼──║
║0│1│2│3║4│5│6│7║8│9│10│11║
║─┴─┴─┴─║─┴─┴─┴─║─┴─┴──┴──║
@end verbatim
@end example

@example
@verbatim
(ra-format (ra-tile a 2 2))
@end verbatim
@result{}
@verbatim
#%3d:3:4:2─┬──║
║0│0║4│4║ 8│ 8║
║─┼─║─┼─║──┼──║
║1│1║5│5║ 9│ 9║
║─┼─║─┼─║──┼──║
║2│2║6│6║10│10║
║─┼─║─┼─║──┼──║
║3│3║7│7║11│11║
║─┴─║─┴─║──┴──║
@end verbatim
@end example

Either @var{len} or @var{hi} being @code{#f} creates @ref{x-dead-axes,dead axes}.
@example
@verbatim
(define a (ra-tile (ra-i 2 2) 0 #f #f))
(define b (ra-transpose (ra-i 2 2) 2)) ; same thing
@end verbatim
@result{} @code{#%4d:d:d:2:2((((0 1) (2 3))))}
@end example

The tiled array shares the root of @var{a}.

See also: @ref{x-ra-ravel,@code{ra-ravel}}, @ref{x-ra-reshape,@code{ra-reshape}}, @ref{Reshaping}.

@end deffn

@cindex @code{ra-transpose}
@anchor{x-ra-transpose}
@deffn @w{Function} ra-transpose a axes ... @result{} b
Transpose each axis 0, 1, ... of @var{a} to matching destination @var{axes}.

@example
@verbatim
(ra-transpose (ra-i 2 3) 1 0)
@end verbatim
@result{} #%1d:3:2((0 3) (1 4) (2 5))
@end example

The transposed array shares the root of @var{a}.

See also: @ref{x-ra-untranspose,@code{ra-untranspose}}, @ref{Transposition}.

@end deffn

@cindex @code{ra-untranspose}
@anchor{x-ra-untranspose}
@deffn @w{Function} ra-untranspose a axes ... @result{} b
Transpose @var{axes} of @var{a} to matching destination axes 0, 1, ...

@example
@verbatim
(ra-untranspose (ra-transpose (ra-i 2 3 4) 2 1 0) 2 1 0)
@end verbatim
@result{} @code{#%3d:2:3:4(((0 1 2 3) (4 5 6 7) (8 9 10 11)) ((12 13 14 15) (16 17 18 19) (20 21 22 23)))}
@end example

but

@example
@verbatim
(ra-transpose (ra-transpose (ra-i 2 3 4) 2 1 0) 2 1 0)
@end verbatim
@result{} @code{#%3d:4:2:3(((0 4 8) (12 16 20)) ((1 5 9) (13 17 21)) ((2 6 10) (14 18 22)) ((3 7 11) (15 19 23)))}
@end example

The transposed array shares the root of @var{a}.

See also: @ref{x-ra-transpose,@code{ra-transpose}}, @ref{Transposition}.

@end deffn

@cindex @code{ra-index-map!}
@anchor{x-ra-index-map!}
@deffn @w{Function} ra-index-map! a op @result{} a
Iterate over array @var{a} in unspecified order, assigning to each element the result of @code{(op i₀ ...)}, where @code{i₀ ...} are the indices of that element.

For example:

@example
@verbatim
(ra-index-map! (make-ra #t 3 4) -)
(ra-map! (make-ra #t 3 4) - (ra-iota) (ra-transpose (ra-iota) 1)) ; same thing
@end verbatim
@result{} @code{#%2:3:4((0 -1 -2 -3) (1 0 -1 -2) (2 1 0 -1))}
@end example

See also: @ref{x-ra-map!,@code{ra-map!}}, @ref{Iteration}.

@end deffn

@cindex @code{ra-slice-for-each}
@anchor{x-ra-slice-for-each}
@deffn @w{Function} ra-slice-for-each k op a ...
Iterate over the @var{k}-frames of arrays @var{a} ..., applying @var{op} to the respective slices. The arguments @var{a} ... must have matching shapes over their @var{k}-frames.

Note that it isn't necessary for arguments @var{a} to have rank ≥ @var{k}. Arguments with rank < @var{k} are rank-extended and the corresponding arguments are 0-cells. For example:

@example
@verbatim
(ra-slice-for-each 1
  (lambda (a b) (display (list (a) (b))))
  (make-ra-root #(a b))
  (ra-i 2 3))
@end verbatim
@result{} @code{(a #%1d:3(0 1 2))(b #%1d:3(3 4 5))}
@end example

@example
@verbatim
(ra-slice-for-each 2
  (lambda (a b) (display (list (a) (b))))
  (make-ra-root #(a b))
  (ra-i 2 3))
@end verbatim
@result{} @code{(a 0)(a 1)(a 2)(b 3)(b 4)(b 5)}
@end example

See also: @ref{x-ra-map!,@code{ra-map!}}, @ref{x-ra-for-each,@code{ra-for-each}}, @ref{Iteration}.

@end deffn

@cindex @code{ra-map!}
@anchor{x-ra-map!}
@deffn @w{Function} ra-map! dst op a ... @result{} dst
Iterate over arrays @var{dst} @var{a} ... applying @var{op} to the respective elements in @var{a}, and storing the result in the respective element of @var{dst}. The arguments must have matching shapes and the type of @var{dst} must be compatible with the results of @var{op}.

This is equivalent to
@verbatim
(apply ra-slice-for-each
       (rank dst)
       (lambda (dst . a)
         (ra-set! dst (apply op (map ra-ref a))))
       dst a)
@end verbatim

See also: @ref{x-ra-map,@code{ra-map}}, @ref{x-ra-for-each,@code{ra-for-each}}, @ref{x-ra-slice-for-each,@code{ra-slice-for-each}}, @ref{Iteration}.

@end deffn

@cindex @code{ra-map}
@anchor{x-ra-map}
@deffn @w{Function} ra-map type op a0 a ... @result{} dst
Same as @ref{x-ra-map!,@code{ra-map!}}, but create the result array from the arguments. Unlike @code{ra-map!}, this function requires at least one source argument.

The type of @var{dst} is @var{type} unless that is @code{#f}, in which case the type of @var{a0} is used,  unless that is @code{'d}, in which case the @code{#f} is used. For the computation of the shape of @var{dst} see @ref{Automatic result arrays}.

@example
@verbatim
(ra-format (ra-map 'f64 + (ra-iota 3 1) (ra-i 3 4)))
@end verbatim
@result{}
@verbatim
#%2f64:3:4┬────┬────┐
│ 1.0│ 2.0│ 3.0│ 4.0│
├────┼────┼────┼────┤
│ 6.0│ 7.0│ 8.0│ 9.0│
├────┼────┼────┼────┤
│11.0│12.0│13.0│14.0│
└────┴────┴────┴────┘
@end verbatim
@end example

See also: @ref{x-ra-map!,@code{ra-map!}}, @ref{x-ra-copy,@code{ra-copy}}.

@end deffn

@cindex @code{ra-copy!}
@anchor{x-ra-copy!}
@deffn @w{Function} ra-copy! dst src @result{} dst
Copy @var{src} to @var{dst}. The arguments must have matching shapes and be of compatible types.

For valid arguments, this is equivalent to any one of
@verbatim
(ra-map! dst identity src)
(ra-amend! dst src)
@end verbatim

See also @ref{x-ra-copy,@code{ra-copy}} @ref{x-ra-amend!,@code{ra-amend!}} @ref{x-ra-set!,@code{ra-set!}} @ref{x-ra-map!,@code{ra-map!}}.

@end deffn

@cindex @code{ra-copy}
@anchor{x-ra-copy}
@deffn @w{Function} ra-copy src @result{} dst
@deffnx @w{Function} ra-copy type src @result{} dst
Create a new array of type @var{type} and copy @var{src} into it. If @var{type} is @code{#f} or isn't given, use the type of @var{src}, unless that type is @code{d}, in which case the result is of type @code{#t}.

See also @ref{x-ra-copy!,@code{ra-copy!}} @ref{x-ra-amend!,@code{ra-amend!}} @ref{x-ra-set!,@code{ra-set!}}.
@end deffn

@cindex @code{ra-swap!}
@anchor{x-ra-swap!}
@deffn @w{Function} ra-swap! a b @result{} a
Swap the contents of @var{a} and @var{b}. The swap is executed in unspecified order, so the effect on @var{a} and @var{b} is undefined if @var{a} and @var{b} share storage.

@example
@verbatim
(ra-swap! (make-ra 2 3) (make-typed-ra 'f64 -1 3))
@end verbatim
@result{}
@verbatim
#%1:3(-1.0 -1.0 -1.0)
@end verbatim
@end example

See also @ref{x-ra-swap-in-order!,@code{ra-swap-in-order!}} @ref{x-ra-copy!,@code{ra-copy!}}.
@end deffn

@cindex @code{ra-swap-in-order!}
@anchor{x-ra-swap-in-order!}
@deffn @w{Function} ra-swap-in-order! a b @result{} a
Swap the contents of @var{a} and @var{b}. The swap is executed in row-major order.
@end deffn

@cindex @code{ra-fill!}
@anchor{x-ra-fill!}
@deffn @w{Function} ra-fill! dst value @result{} dst
Assign @var{value} to each element of @var{dst}. The arguments must be of compatible types.

This is equivalent to any one of
@example
@verbatim
(ra-map! dst (const value))
(ra-copy! dst (make-ra value))
(ra-amend! dst (make-ra value))
(ra-amend! dst value) ; as long as value isn't an array
@end verbatim
@end example

Compare

@example
@verbatim
(ra-fill! (make-ra #f 2 2) (make-ra 'x))
@end verbatim
@result{} #%2:2:2((#%0(x) #%0(x)) (#%0(x) #%0(x)))
@verbatim
(ra-amend! (make-ra #f 2 2) 'x)
@end verbatim
@result{} #%2:2:2((x x) (x x))
@verbatim
(ra-amend! (make-ra #f 2 2) (make-ra 'x))
@end verbatim
@result{} #%2:2:2((x x) (x x))
@verbatim
(ra-amend! (make-ra #f 2 2) (make-ra (make-ra 'x)))
@end verbatim
@result{} #%2:2:2((#%0(x) #%0(x)) (#%0(x) #%0(x)))
@end example

See also: @ref{x-ra-set!,@code{ra-set!}}, @ref{x-ra-copy!,@code{ra-copy!}}, @ref{x-ra-amend!,@code{ra-amend!}}.

@end deffn

@cindex packed array
@cindex @code{ra-order-c?}
@anchor{x-ra-order-c?}
@deffn @w{Function} ra-order-c? a [n [org]]
Check whether axes [@var{org} ... @var{org}+@var{n}) of @var{a} are in row-major order. By default, check that the whole array is in row-major order, and additionally that the step on the last axis is 1 (i.e. the array is ‘packed’).

@code{(ra-order-c? a n org)} implies @code{(eq? (ra-root a) (ra-root (@ref{x-ra-ravel, @code{ra-ravel}} a n org)))}. Note that the stronger condition @code{(ra-order-c? a)} is not necessary for @code{(eq? (ra-root a) (ra-root (ra-ravel a)))} to hold.

@end deffn

@cindex @code{ra-ref}
@anchor{x-ra-ref}
@deffn @w{Function} ra-ref a i ...

Look up array element. It is an error if the number of @var{i ...} doesn't match the rank of @var{a}.

See also: @ref{x-ra-cell,@code{ra-cell}}, @ref{x-ra-slice,@code{ra-slice}}, @ref{x-ra-from,@code{ra-from}}, @ref{x-ra-set!,@code{ra-set!}}.

@end deffn

@cindex @code{ra-set!}
@anchor{x-ra-set!}
@deffn @w{Function} ra-set! a o i ...

Assign array element. It is an error if the number of @var{i ...} doesn't match the rank of @var{a}.

See also: @ref{x-ra-amend!,@code{ra-amend!}}, @ref{x-ra-ref,@code{ra-ref}}.

@end deffn

@cindex @code{ra-slice}
@anchor{x-ra-slice}
@deffn @w{Function} ra-slice a i ...

Look up array cell.

This function returns a view of @var{a} with rank @var{k} equal to the rank of @var{a} minus the number of @var{i ...}, even if that is 0.

It is an error if the number of @var{i ...} exceeds the rank of @var{a}.

See also: @ref{x-ra-cell,@code{ra-cell}}, @ref{x-ra-ref,@code{ra-ref}}, @ref{x-ra-from,@code{ra-from}}, @ref{Slicing}.
@end deffn

@cindex @code{ra-cell}
@anchor{x-ra-cell}
@deffn @w{Function} ra-cell a i ...

Look up array cell.

Let @var{k} be the rank of @var{a} minus the number of @var{i ...}. If @var{k} is zero, return the array element at @var{i ...}, like @ref{x-ra-ref,@code{ra-ref}}; else return a @var{k}-view of @var{a}, like @ref{x-ra-slice,@code{ra-slice}}.

It is an error if the number of @var{i ...} exceeds the rank of @var{a}.

@example
@verbatim
(define a (ra-copy (ra-i 3 2)))
(ra-cell a 0)
(ra-slice a 0) ; same thing
@end verbatim
@result{} @code{#%1(0 1 2)}
@verbatim
(ra-slice a 0 1)
@end verbatim
@result{} @code{#%0(4)}
@verbatim
(ra-cell a 0 1)
(ra-ref a 0 1) ; same thing
@end verbatim
@result{} @code{4}
@end example

See also: @ref{x-ra-slice,@code{ra-slice}}, @ref{x-ra-ref,@code{ra-ref}}, @ref{x-ra-from,@code{ra-from}}, @ref{Slicing}.

@end deffn

@cindex @code{ra-equal?}
@anchor{x-ra-equal?}
@deffn @w{Function} ra-equal? a ... → boolean

Return @code{#t} if the arrays @var{a} ... have the same shapes and types and their
corresponding elements are all @code{equal?} to each other, or @code{#f} otherwise.

Note that this function isn't rank extending; the shapes of the arguments must be the same, not just match. Here's a rank-extending version:

@example
@verbatim
(import (ice-9 control))
(define (ra-equal?* . a) (let/ec exit (apply ra-for-each (lambda a (unless (apply equal? a) (exit #f))) a) #t))
@end verbatim
@end example

See also: @ref{x-ra-for-each,@code{ra-for-each}}, @ref{x-ra-fold,@code{ra-fold}}, @ref{x-ra-every,@code{ra-every}}, @ref{x-ra-any,@code{ra-any}}.

@end deffn

@cindex @code{ra-for-each}
@anchor{x-ra-for-each}
@deffn @w{Function} ra-for-each op a ...

See also: @ref{x-ra-slice-for-each, @code{ra-slice-for-each}}, @ref{x-ra-map!,@code{ra-map}}, @ref{Iteration}.

@end deffn

@cindex @code{ra-fold}
@anchor{x-ra-fold}
@deffn @w{Function} ra-fold op knil a ...

See also: @ref{x-ra-every,@code{ra-every}}, @ref{x-ra-any,@code{ra-any}}, @ref{Iteration}.

@end deffn

@cindex @code{ra-every}
@anchor{x-ra-every}
@deffn @w{Function} ra-every pred? a ...

See also: @ref{x-ra-fold,@code{ra-fold}}, @ref{x-ra-any,@code{ra-any}}.

@end deffn

@cindex @code{ra-any}
@anchor{x-ra-any}
@deffn @w{Function} ra-any pred? a ...

See also: @ref{x-ra-fold,@code{ra-fold}}, @ref{x-ra-every,@code{ra-every}}.

@end deffn

@cindex @code{ra-from}
@anchor{x-ra-from}
@deffn @w{Function} ra-from a i ... → b

Outer product slice of @var{a} by indices @var{i} ...

The shape of @var{b} is the concatenation of the shapes of @var{i}... and the
contents are obtained by looking up in each dimension of @var{a} by the indices @var{i},
that is

@example
@verbatim
b(j₀₀ j₀₁ ... j₁₀ j₁₁ ...) = a(i₀(j₀₀ j₀₁ ...) i₁(j₁₀ j₁₁ ...) ...)
@end verbatim
@end example

where @var{i} : @var{i₀} @var{i₁} ... The special value @code{#t} is understood as the full range of @var{a} on that axis.

Additionally, if each of the @var{i} ... is one of
@itemize
@item @code{#t}
@item an array of type @code{d}
@item an array of rank 0
@item an integer
@end itemize
then the result @var{b} shares the root of @var{a}. In all other cases a new root is allocated for the result. For example

@example
@verbatim
(define a (list->ra 2 '((1 2 3) (a b c))))
(define b (ra-from a #t (ra-iota 3 2 -1))) ; same as (ra-reverse a 1)
b
@end verbatim
@result {} @code{#%2:2:3((3 2 1) (c b a))}
@verbatim
(eq? (ra-root a) (ra-root b))
@end verbatim
@result {} @code{#t}
@verbatim
(define c (ra-from a #t (list->ra 1 '(2 1 0))))
b
@end verbatim
@result {} @code{#%2:2:3((3 2 1) (c b a))}
@verbatim
(eq? (ra-root a) (ra-root c))
@end verbatim
@result {} @code{#f}
@end example

Unbounded indices aren't treated especially, so they are only valid if the relevant axis of @var{ra} is itself unbounded.

@example
@verbatim
(ra-i #t 4)
@end verbatim
@result {}
@verbatim
#%2d:f:4──┐
│0│1│ 2│ 3│
├─┼─┼──┼──┤
│4│5│ 6│ 7│
├─┼─┼──┼──┤
│8│9│10│11│
...........
@end verbatim
@verbatim
(ra-from (ra-i #t 4) (ra-iota #f 0 2))
@end verbatim
@result {}
@verbatim
#%2d:f:4─┬──┐
│ 0│ 1│ 2│ 3│
├──┼──┼──┼──┤
│ 8│ 9│10│11│
├──┼──┼──┼──┤
│16│17│18│19│
.............
@end verbatim
@end example

@i{If the result would have rank 0, then an array element is returned, and not a 0-rank view of @var{a}. Use @ref{x-ra-amend!,@code{ra-amend!}} to assign to cells of an array regardless of whether they are of 0-rank or higher.}

The type of @var{b} is the same as that of @var{a}, with the only exception that if the type of @var{a} is @code{d} and the root of @var{b} cannot be shared with the root of @var{a}, then the type of @var{b} is @code{#t}.

See also: @ref{x-ra-cell,@code{ra-cell}}, @ref{x-ra-ref,@code{ra-ref}}, @ref{x-ra-slice,@code{ra-slice}}, @ref{x-ra-amend!,@code{ra-amend!}}, @ref{Slicing}.@footnote{Cf. @code{array-index-ref} from @mybibcite{SRFI-164}.}

@end deffn

@cindex @code{ra-from-copy}
@anchor{x-ra-from-copy}
@deffn @w{Function} ra-from-copy a i ... @result{} b

Like @code{ra-from}, but always return a newly allocated array. This is equivalent to @code{(ra-copy (ra-from a i ...))}, but it doesn't incur a second copy in case @code{ra-from} already allocates a new array.

See also: @ref{x-ra-from,@code{ra-from}}.

@end deffn

@cindex @code{ra-amend!}
@anchor{x-ra-amend!}
@deffn @w{Function} ra-amend! a c i ... → a
Copy @var{c} to the outer product slice of @var{a} by indices @var{i} ...

@example
@verbatim
a(i₀(j₀₀ j₀₁ ...) i₁(j₁₀ j₁₁ ...) ...) ← c(j₀₀ j₀₁ ... j₁₀ j₁₁ ...)
@end verbatim
@end example

where @var{i} : @var{i₀} @var{i₁} ...

This is equivalent to @code{(ra-copy! (ra-from a i ...) c)} if @code{(ra-from a i ...)} would
return a shared ra of @var{a}, but it also works in other cases, as long as @var{a} is
writable. @var{i} may take any of the special values accepted by @code{ra-from}.

@example
@verbatim
(define a (list->ra 1 '(1 2 3)))
(define x 1)
(define y (array->ra #(1)))
(ra-amend! a 9 x) ; modifies a
(ra-amend! a (array->ra #0(9)) x) ; same thing
(ra-copy! (ra-from a x) (array->ra #0(9))) ; modifies a
(ra-amend! a 9 y) ; modifies a
(ra-copy! (ra-from a y) (array->ra #0(9))) ; (ra-from a y) is a new array, so a is NOT modified
(ra-amend! (array->ra #(2 3 4)) 9 1) ; error, (array->ra #(2 3 4)) is not mutable
@end verbatim
@end example

If @var{i} contains repeated indices or the steps of @var{a} make it so that the same elements of @var{a}
are referenced more than once, then the value that ends up in @var{a} may correspond to any of the
indices that match those elements. @code{newra} will @emph{not} check that each element of @var{a} is represented uniquely in its root vector.

@example
@verbatim
(ra-amend! a (array->ra #(6 7 8)) (ra-tile (array->ra #0(1)) 0 3))
@end verbatim
@result{} #%1:3(1 8 3) ; do not rely on 8 ending up there
@end example

This function returns the modified array @var{a}.

See also: @ref{x-ra-from,@code{ra-from}}, @ref{x-ra-copy!,@code{ra-copy!}} @ref{x-ra-cell,@code{ra-cell}} @ref{x-ra-ref,@code{ra-ref}} @ref{x-ra-slice,@code{ra-slice}} @ref{x-ra-set!,@code{ra-set!}}.

@end deffn


@cindex @code{ra->array}
@anchor{x-ra->array}
@deffn @w{Function} ra->array a

Convert (@code{newra}) array @var{a} into built-in Guile array.

This function does not create a copy of the array, but reuses the root (@code{ra-root}) of @var{a}, that is, @code{(eq? (ra-root a) (shared-array-root (ra->array a)))} is @code{#t}.

Not all arrays can be converted into built-in Guile arrays. For example, type @code{d} arrays, or arrays with unbounded axes, are not convertible.

@example
@verbatim
(ra->array (ra-i 3)) ; error, type d not convertible
(ra->array (ra-copy (ra-i 3))) ; ok, (ra-copy (ra-i 3)) has type #t
(ra->array (ra-transpose (ra-i 2 3) 1)) ; error, not convertible
(ra->array (ra-singletonize (ra-transpose (ra-i 2 3) 1))) ; ok
@end verbatim
@end example

See also: @ref{x-array->ra,@code{array->ra}}, @ref{x-ra-singletonize,@code{ra-singletonize}}, @ref{x-ra-copy!,@code{ra-copy!}}.

@end deffn

@cindex @code{ra-singletonize}
@anchor{x-ra-singletonize}
@deffn @w{Function} ra-singletonize a

Return an array with the same root and dimensions as @var{a}, except that dead axes (axes with step 0 and undefined length) have their length set to 1.

@example
@verbatim
(ra-dimensions (ra-transpose (ra-i 2 3) 1))
@end verbatim
@result{} (#f 2 3)
@verbatim
(ra-dimensions (ra-singletonize (ra-transpose (ra-i 2 3) 1)))
@end verbatim
@result{} (1 2 3)
@verbatim
(ra-dimensions (ra-singletonize (ra-tile (ra-i 2 3) 0 4)))
@end verbatim
@result{} (4 2 3) ; no change
@end example

@end deffn

@c ------------------------------------------------
@node Cheatsheet
@chapter Cheatsheet
@c ------------------------------------------------

@c ------------------------------------------------
@node @mybibnode{}
@chapter Sources
@c ------------------------------------------------

@multitable @columnfractions .1 .9

@item @mybibitem{Abr70} @tab Philip S. Abrams. An APL machine. Technical report SLAC-114 UC-32 (MISC), Stanford Linear Accelerator Center, Stanford University, Stanford, CA, USA, February 1970.
@item @mybibitem{Ber87} @tab Robert Bernecky. An introduction to function rank. ACM SIGAPL APL Quote Quad, 18(2):39–43, December 1987.
@item @mybibitem{bli17} @tab The Blitz++ meta-template library. @url{http://blitz.sourceforge.net}, November 2017.
@item @mybibitem{Cha86} @tab Gregory J. Chaitin. Physics in APL2, June 1986.
@item @mybibitem{FI68}  @tab Adin D. Falkoff and Kenneth Eugene Iverson. APL\360 User’s manual. IBM Thomas J. Watson Research Center, August 1968.
@item @mybibitem{FI73}  @tab Adin D. Falkoff and Kenneth Eugene Iverson. The design of APL. IBM Journal of Research and Development, 17(4):5–14, July 1973.
@item @mybibitem{FI78}  @tab Adin D. Falkoff and Kenneth Eugene Iverson. The evolution of APL. ACM SIGAPL APL, 9(1):30– 44, 1978.
@item @mybibitem{J S}   @tab J Primer. J Software, @url{https://www.jsoftware.com/help/primer/contents.htm}, November 2017.
@item @mybibitem{Mat}   @tab MathWorks. MATLAB documentation, @url{https://www.mathworks.com/help/matlab/}, November 2017.
@item @mybibitem{num17} @tab NumPy. @url{http://www.numpy.org}, November 2017.
@item @mybibitem{Ric08} @tab Henry Rich. J for C programmers, February 2008.
@item @mybibitem{SSM14} @tab Justin Slepak, Olin Shivers, and Panagiotis Manolios. An array-oriented language with static rank polymorphism. In Z. Shao, editor, ESOP 2014, LNCS 8410, pages 27–46, 2014.
@item @mybibitem{Vel01} @tab Todd Veldhuizen. Blitz++ user’s guide, February 2001.
@item @mybibitem{Wad90} @tab Philip Wadler. Deforestation: transforming programs to eliminate trees. Theoretical Computer Science, 73(2): 231--248, June 1990. @url{https://doi.org/10.1016/0304-3975%2890%2990147-A}
@item @mybibitem{SRFI-4} @tab Marc Feeley. SRFI-4: Homogeneous numeric vector datatypes, May 1999. @url{https://srfi.schemers.org/srfi-4/srfi-4.html}
@item @mybibitem{SRFI-25} @tab Jussi Piitulainen. SRFI-25: Multi-dimensional array primitives, May 2002. @url{https://srfi.schemers.org/srfi-25/srfi-25.html}
@item @mybibitem{SRFI-122} @tab Bradley J. Lucier. SRFI-122: Nonempty intervals and generalized arrays, December 2016. @url{https://srfi.schemers.org/srfi-122/srfi-122.html}
@item @mybibitem{SRFI-160} @tab John Cowan and Shiro Kawai. SRFI-160: Homogeneous numeric vector libraries, November 2020. @url{https://srfi.schemers.org/srfi-160/srfi-160.html}
@item @mybibitem{SRFI-163} @tab Per Bothner. SRFI-163: Enhanced array literals, January 2019. @url{https://srfi.schemers.org/srfi-163/srfi-163.html}
@item @mybibitem{SRFI-164} @tab Per Bothner. SRFI-164: Enhanced multi-dimensional arrays, August  2019. @url{https://srfi.schemers.org/srfi-164/srfi-164.html}
@end multitable

@c ------------------------------------------------
@node Indices
@unnumbered Indices
@c ------------------------------------------------

@c @node Concept Index
@c @unnumbered Concept Index
@printindex cp
@c @node Function Index
@c @unnumbered Function Index
@c @printindex fn

@c \nocite{JLangReference,FalkoffIverson1968,Abrams1970,FalkoffIverson1973,FalkoffIverson1978,APLexamples1,ArraysCowan,KonaTheLanguage,blitz++2001}

@bye