6.10 Pointwise Operations

procedure
( array-map f)→(Array R)
f:(-> R)
(array-map farr0)→(Array R)
f:(A-> R)
arr0:(Array A)
(array-map farr0arr1arrs...)→(Array R)
f:(ABTs... -> R)
arr0:(Array A)
arr1:(Array B)
arrs:(Array Ts)

Composes f with the given arrays’ procedures. When the arrays’ shapes do not match, they are broadcast to the same shape first. If broadcasting fails, array-map raises an error.

Examples:

> (array-map (λ: ([x: String])(string-append x"!"))
(array #[#["Hello""I"]#["Am""Shouting"]]))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes String))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[#["Hello!" "I!"] #["Am!" "Shouting!"]])

> (array-map string-append
(array #[#["Hello""I"]#["Am""Shouting"]])
(array "!"))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes String))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[#["Hello!" "I!"] #["Am!" "Shouting!"]])
> (array-map + (index-array #(333))(array 2))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Fixnum))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array

#[#[#[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]]])
> (array-map + (index-array #(22))(index-array #(33)))

array-shape-broadcast: incompatible array shapes

(array-broadcasting #t): '#(2 2), '#(3 3)

Typed Racket can often derive fairly precise element types for the resulting array:

> (array-map * (array #[-4.3-1.2-0.2])(array -2.81))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Nonnegative-Flonum))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[12.083 3.372 0.562])

How precise the result type is depends on the type of f. Preserving precise result types for lifted arithmetic operators is the main reason most pointwise operations are macro wrappers for array-map .

Unlike map , array-map can map a zero-argument function:

> (array-map (λ ()"Whoa, Nelly!"))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes String))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array "Whoa, Nelly!")

If the resulting zero-dimensional array is used in a pointwise operation with other arrays, it will be broadcast to their shape:

> (array-map + (array #[123])(array-map (λ ()-10)))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Fixnum))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[-9 -8 -7])

When explicitly instantiating array-map ’s types using inst , instantiate R (the return type’s element type) first, then the arguments’ element types in order.

syntax
( inline-array-map farrs...)

Like array-map , but possibly faster. Inlining a map operation can allow Typed Racket’s optimizer to replace f with something unchecked and type-specific (for example, replace * with unsafe-fl* ), at the expense of code size.

syntax
( array+ arrs...)

syntax
( array* arrs...)

syntax
( array- arr0arrs...)

syntax
( array/ arr0arrs...)

syntax
( array-min arr0arrs...)

syntax
( array-max arr0arrs...)

Equivalent to mapping arithmetic operators over arrays. Note that because (array-map f) returns sensible answers, so do (array+ ) and (array* ).

Examples:

> (array+ (array #[#[0.01.0]#[2.03.0]])(array 200))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Flonum))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[#[200.0 201.0] #[202.0 203.0]])
> (array+ )

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Zero))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array 0)
> (array* )

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes One))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array 1)
> (array/ (array #[21/2]))

- : #(struct:Array

(Indexes

Index

(Boxof Boolean)

(-> Void)

(-> Indexes Positive-Exact-Rational))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[1/2 2])

syntax
( array-scale arrx)

Equivalent to (array* arr(array x)), but faster.

syntax
( array-abs arr)

syntax
( array-sqr arr)

syntax
( array-sqrt arr)

syntax
( array-conjugate arr)

Equivalent to (array-map farr), where f is respectively abs , sqr , sqrt , or conjugate .

syntax
( array-real-part arr)

syntax
( array-imag-part arr)

syntax
( array-make-rectangular arr0arr1)

syntax
( array-magnitude arr)

syntax
( array-angle arr)

syntax
( array-make-polar arr0arr1)

Conversions to and from complex numbers, lifted to operate on arrays.

syntax
( array< arr0arr1arrs...)

syntax
( array<= arr0arr1arrs...)

syntax
( array> arr0arr1arrs...)

syntax
( array>= arr0arr1arrs...)

syntax
( array= arr0arr1arrs...)

Equivalent to (array-map farr0arr1arrs... ), where f is respectively < , <= , > , >= , or = .

syntax
( array-not arr)

syntax
( array-and arr...)

syntax
( array-or arr...)

syntax
( array-if cond-arrtrue-arrfalse-err)

Boolean operators lifted to operate on arrays.

When given nonstrict arrays, the short-cutting behavior of array-and , array-or and array-if can keep their elements from being referred to (and thus computed). However, these macros cannot be used to distinguish base and inductive cases in a recursive function, because the array arguments are eagerly evaluated. For example, this function never returns, even when array-strictness is #f:

(: array-factorial((Array Integer )-> (Array Integer )))
(define (array-factorialarr)
(array-if (array<= arr(array 0))
(array 1)
(array* arr(array-factorial(array- arr(array 1))))))

6.10.1Broadcasting🔗 i

parameter
( array-broadcasting )→(U Boolean 'permissive)
(array-broadcasting broadcasting)→void?
broadcasting:(U Boolean 'permissive)

Determines the rules used when broadcasting arrays for pointwise operations. See Broadcasting Control.

procedure
( array-shape-broadcast dss[broadcasting])→Indexes
dss:(Listof Indexes )
broadcasting:(U Boolean 'permissive)=(array-broadcasting )

Determines the shape of the resulting array if some number of arrays with shapes dss were broadcast for a pointwise operation using the given broadcasting rules. If broadcasting fails, array-shape-broadcast raises an error.

Examples:

> (array-shape-broadcast '())

- : Indexes

'#()
> (array-shape-broadcast (list (vector )((inst vector Index )10)))

- : Indexes

'#(10)

> (array-shape-broadcast (list ((inst vector Index )2)
((inst vector Index )10)))

array-shape-broadcast: incompatible array shapes

(array-broadcasting #t): '#(2), '#(10)

> (array-shape-broadcast (list ((inst vector Index )2)
((inst vector Index )10))
'permissive)

- : Indexes

'#(10)

procedure
( array-broadcast arrds)→(Array A)
arr:(Array A)
ds:Indexes

Returns an array with shape ds made by inserting new axes and repeating rows. This is used for both (array-broadcasting #t) and (array-broadcasting 'permissive).

Examples:

> (array-broadcast (array 10)((inst vector Index )10))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes Positive-Byte))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[10 10 10 10 10 10 10 10 10 10])
> (array-broadcast (array #[01])#())

array-broadcast: cannot broadcast to a lower-dimensional

shape; given (array #[0 1]) and '#()
> (array-broadcast (array #[01])((inst vector Index )5))

- : #(struct:Array

(Indexes Index (Boxof Boolean) (-> Void) (-> Indexes (U One Zero)))

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:56:13 prop:equal+hash>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:55:13 prop:custom-write>

#<syntax:build/user/8.18/pkgs/math-lib/math/private/array/typed-array-struct.rkt:54:13 prop:custom-print-quotable>)

(array #[0 1 0 1 0])

When array-strictness is #f, array-broadcast always returns a nonstrict array.

When array-strictness is #t, array-broadcast returns a strict array when arr is nonstrict and the result has more elements than arr.

top ← prev up next →