aboutsummaryrefslogtreecommitdiffstats
path: root/array.txi
blob: 7a2d85fbd9c78ae468d072469d19fbf8efb539e3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
@code{(require 'array)} or @code{(require 'srfi-63)}
@ftindex array


@defun array? obj

Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
@end defun

@noindent
@emph{Note:} Arrays are not disjoint from other Scheme types.
Vectors and possibly strings also satisfy @code{array?}.
A disjoint array predicate can be written:

@example
(define (strict-array? obj)
  (and (array? obj) (not (string? obj)) (not (vector? obj))))
@end example


@defun equal? obj1 obj2

Returns @code{#t} if @var{obj1} and @var{obj2} have the same rank and dimensions and the
corresponding elements of @var{obj1} and @var{obj2} are @code{equal?}.

@code{equal?} recursively compares the contents of pairs, vectors, strings, and
@emph{arrays}, applying @code{eqv?} on other objects such as numbers
and symbols.  A rule of thumb is that objects are generally @code{equal?} if
they print the same.  @code{equal?} may fail to terminate if its arguments are
circular data structures.

@example
(equal? 'a 'a)                             @result{}  #t
(equal? '(a) '(a))                         @result{}  #t
(equal? '(a (b) c)
        '(a (b) c))                        @result{}  #t
(equal? "abc" "abc")                       @result{}  #t
(equal? 2 2)                               @result{}  #t
(equal? (make-vector 5 'a)
        (make-vector 5 'a))                @result{}  #t
(equal? (make-array (A:fixN32b 4) 5 3)
        (make-array (A:fixN32b 4) 5 3))    @result{}  #t
(equal? (make-array '#(foo) 3 3)
        (make-array '#(foo) 3 3))          @result{}  #t
(equal? (lambda (x) x)
        (lambda (y) y))                    @result{}  @emph{unspecified}
@end example
@end defun


@defun array-rank obj

Returns the number of dimensions of @var{obj}.  If @var{obj} is not an array, 0 is
returned.
@end defun


@defun array-dimensions array

Returns a list of dimensions.

@example
(array-dimensions (make-array '#() 3 5))
   @result{} (3 5)
@end example
@end defun


@defun make-array prototype k1 @dots{}


Creates and returns an array of type @var{prototype} with dimensions @var{k1}, @dots{}
and filled with elements from @var{prototype}.  @var{prototype} must be an array, vector, or
string.  The implementation-dependent type of the returned array
will be the same as the type of @var{prototype}; except if that would be a vector
or string with rank not equal to one, in which case some variety of
array will be returned.

If the @var{prototype} has no elements, then the initial contents of the returned
array are unspecified.  Otherwise, the returned array will be filled
with the element at the origin of @var{prototype}.
@end defun


@defun create-array prototype k1 @dots{}

@code{create-array} is an alias for @code{make-array}.
@end defun


@defun make-shared-array array mapper k1 @dots{}

@code{make-shared-array} can be used to create shared subarrays of other
arrays.  The @var{mapper} is a function that translates coordinates in
the new array into coordinates in the old array.  A @var{mapper} must be
linear, and its range must stay within the bounds of the old array, but
it can be otherwise arbitrary.  A simple example:

@example
(define fred (make-array '#(#f) 8 8))
(define freds-diagonal
  (make-shared-array fred (lambda (i) (list i i)) 8))
(array-set! freds-diagonal 'foo 3)
(array-ref fred 3 3)
   @result{} FOO
(define freds-center
  (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j)))
                     2 2))
(array-ref freds-center 0 0)
   @result{} FOO
@end example
@end defun


@defun list->array rank proto list

@var{list} must be a rank-nested list consisting of all the elements, in
row-major order, of the array to be created.

@code{list->array} returns an array of rank @var{rank} and type @var{proto} consisting of all the
elements, in row-major order, of @var{list}.  When @var{rank} is 0, @var{list} is the lone
array element; not necessarily a list.

@example
(list->array 2 '#() '((1 2) (3 4)))
                @result{} #2A((1 2) (3 4))
(list->array 0 '#() 3)
                @result{} #0A 3
@end example
@end defun


@defun array->list array

Returns a rank-nested list consisting of all the elements, in
row-major order, of @var{array}.  In the case of a rank-0 array, @code{array->list} returns
the single element.

@example
(array->list #2A((ho ho ho) (ho oh oh)))
                @result{} ((ho ho ho) (ho oh oh))
(array->list #0A ho)
                @result{} ho
@end example
@end defun


@defun vector->array vect proto dim1 @dots{}

@var{vect} must be a vector of length equal to the product of exact
nonnegative integers @var{dim1}, @dots{}.

@code{vector->array} returns an array of type @var{proto} consisting of all the elements, in
row-major order, of @var{vect}.  In the case of a rank-0 array, @var{vect} has a
single element.

@example
(vector->array #(1 2 3 4) #() 2 2)
                @result{} #2A((1 2) (3 4))
(vector->array '#(3) '#())
                @result{} #0A 3
@end example
@end defun


@defun array->vector array

Returns a new vector consisting of all the elements of @var{array} in
row-major order.

@example
(array->vector #2A ((1 2)( 3 4)))
                @result{} #(1 2 3 4)
(array->vector #0A ho)
                @result{} #(ho)
@end example
@end defun


@defun array-in-bounds? array index1 @dots{}

Returns @code{#t} if its arguments would be acceptable to
@code{array-ref}.
@end defun


@defun array-ref array k1 @dots{}

Returns the (@var{k1}, @dots{}) element of @var{array}.
@end defun


@deffn {Procedure} array-set! array obj k1 @dots{}

Stores @var{obj} in the (@var{k1}, @dots{}) element of @var{array}.  The value returned
by @code{array-set!} is unspecified.
@end deffn

@noindent
These functions return a prototypical uniform-array enclosing the
optional argument (which must be of the correct type).  If the
uniform-array type is supported by the implementation, then it is
returned; defaulting to the next larger precision type; resorting
finally to vector.

@defun A:floC128b z
@defunx A:floC128b
Returns an inexact 128.bit flonum complex uniform-array prototype.
@end defun

@defun A:floC64b z
@defunx A:floC64b
Returns an inexact 64.bit flonum complex uniform-array prototype.
@end defun

@defun A:floC32b z
@defunx A:floC32b
Returns an inexact 32.bit flonum complex uniform-array prototype.
@end defun

@defun A:floC16b z
@defunx A:floC16b
Returns an inexact 16.bit flonum complex uniform-array prototype.
@end defun

@defun A:floR128b x
@defunx A:floR128b
Returns an inexact 128.bit flonum real uniform-array prototype.
@end defun

@defun A:floR64b x
@defunx A:floR64b
Returns an inexact 64.bit flonum real uniform-array prototype.
@end defun

@defun A:floR32b x
@defunx A:floR32b
Returns an inexact 32.bit flonum real uniform-array prototype.
@end defun

@defun A:floR16b x
@defunx A:floR16b
Returns an inexact 16.bit flonum real uniform-array prototype.
@end defun

@defun A:floR128d q
@defunx A:floR128d
Returns an exact 128.bit decimal flonum rational uniform-array prototype.
@end defun

@defun A:floR64d q
@defunx A:floR64d
Returns an exact 64.bit decimal flonum rational uniform-array prototype.
@end defun

@defun A:floR32d q
@defunx A:floR32d
Returns an exact 32.bit decimal flonum rational uniform-array prototype.
@end defun

@defun A:fixZ64b n
@defunx A:fixZ64b
Returns an exact binary fixnum uniform-array prototype with at least
64 bits of precision.
@end defun

@defun A:fixZ32b n
@defunx A:fixZ32b
Returns an exact binary fixnum uniform-array prototype with at least
32 bits of precision.
@end defun

@defun A:fixZ16b n
@defunx A:fixZ16b
Returns an exact binary fixnum uniform-array prototype with at least
16 bits of precision.
@end defun

@defun A:fixZ8b n
@defunx A:fixZ8b
Returns an exact binary fixnum uniform-array prototype with at least
8 bits of precision.
@end defun

@defun A:fixN64b k
@defunx A:fixN64b
Returns an exact non-negative binary fixnum uniform-array prototype with at
least 64 bits of precision.
@end defun

@defun A:fixN32b k
@defunx A:fixN32b
Returns an exact non-negative binary fixnum uniform-array prototype with at
least 32 bits of precision.
@end defun

@defun A:fixN16b k
@defunx A:fixN16b
Returns an exact non-negative binary fixnum uniform-array prototype with at
least 16 bits of precision.
@end defun

@defun A:fixN8b k
@defunx A:fixN8b
Returns an exact non-negative binary fixnum uniform-array prototype with at
least 8 bits of precision.
@end defun

@defun A:bool bool
@defunx A:bool
Returns a boolean uniform-array prototype.
@end defun