1Stdlib.Bigarray(3) OCaml library Stdlib.Bigarray(3)
2
6 Stdlib.Bigarray - no description
7
9 Module Stdlib.Bigarray
10
12 Module Bigarray
13 : (module Stdlib__Bigarray)
14 Element kinds
24 Bigarrays can contain elements of the following kinds:
25 -IEEE single precision (32 bits) floating-point numbers ( Bigar‐
27 ray.float32_elt ),
28 -IEEE double precision (64 bits) floating-point numbers ( Bigar‐
30 ray.float64_elt ),
31 -IEEE single precision (2 * 32 bits) floating-point complex numbers (
33 Bigarray.complex32_elt ),
34 -IEEE double precision (2 * 64 bits) floating-point complex numbers (
36 Bigarray.complex64_elt ),
37 -8-bit integers (signed or unsigned) ( Bigarray.int8_signed_elt or Bi‐
39 garray.int8_unsigned_elt ),
40 -16-bit integers (signed or unsigned) ( Bigarray.int16_signed_elt or
42 Bigarray.int16_unsigned_elt ),
43 -OCaml integers (signed, 31 bits on 32-bit architectures, 63 bits on
45 64-bit architectures) ( Bigarray.int_elt ),
46 -32-bit signed integers ( Bigarray.int32_elt ),
48 -64-bit signed integers ( Bigarray.int64_elt ),
50 -platform-native signed integers (32 bits on 32-bit architectures, 64
52 bits on 64-bit architectures) ( Bigarray.nativeint_elt ).
53 Each element kind is represented at the type level by one of the *_elt
55 types defined below (defined with a single constructor instead of ab‐
56 stract types for technical injectivity reasons).
57 type float32_elt =
59 | Float32_elt
60 type float64_elt =
65 | Float64_elt
66 type int8_signed_elt =
71 | Int8_signed_elt
72 type int8_unsigned_elt =
77 | Int8_unsigned_elt
78 type int16_signed_elt =
83 | Int16_signed_elt
84 type int16_unsigned_elt =
89 | Int16_unsigned_elt
90 type int32_elt =
95 | Int32_elt
96 type int64_elt =
101 | Int64_elt
102 type int_elt =
107 | Int_elt
108 type nativeint_elt =
113 | Nativeint_elt
114 type complex32_elt =
119 | Complex32_elt
120 type complex64_elt =
125 | Complex64_elt
126 type ('a, 'b) kind =
131 | Float32 : (float, float32_elt) kind
132 | Float64 : (float, float64_elt) kind
133 | Int8_signed : (int, int8_signed_elt) kind
134 | Int8_unsigned : (int, int8_unsigned_elt) kind
135 | Int16_signed : (int, int16_signed_elt) kind
136 | Int16_unsigned : (int, int16_unsigned_elt) kind
137 | Int32 : (int32, int32_elt) kind
138 | Int64 : (int64, int64_elt) kind
139 | Int : (int, int_elt) kind
140 | Nativeint : (nativeint, nativeint_elt) kind
141 | Complex32 : (Complex.t, complex32_elt) kind
142 | Complex64 : (Complex.t, complex64_elt) kind
143 | Char : (char, int8_unsigned_elt) kind
144 To each element kind is associated an OCaml type, which is the type of
147 OCaml values that can be stored in the Bigarray or read back from it.
148 This type is not necessarily the same as the type of the array elements
149 proper: for instance, a Bigarray whose elements are of kind float32_elt
150 contains 32-bit single precision floats, but reading or writing one of
151 its elements from OCaml uses the OCaml type float , which is 64-bit
152 double precision floats.
153 The GADT type ('a, 'b) kind captures this association of an OCaml type
155 'a for values read or written in the Bigarray, and of an element kind
156 'b which represents the actual contents of the Bigarray. Its construc‐
157 tors list all possible associations of OCaml types with element kinds,
158 and are re-exported below for backward-compatibility reasons.
159 Using a generalized algebraic datatype (GADT) here allows writing
161 well-typed polymorphic functions whose return type depend on the argu‐
162 ment type, such as:
163 let zero : type a b. (a, b) kind -> a = function
166 | Float32 -> 0.0 | Complex32 -> Complex.zero
167 | Float64 -> 0.0 | Complex64 -> Complex.zero
168 | Int8_signed -> 0 | Int8_unsigned -> 0
169 | Int16_signed -> 0 | Int16_unsigned -> 0
170 | Int32 -> 0l | Int64 -> 0L
171 | Int -> 0 | Nativeint -> 0n
172 | Char -> '\000'
173 val float32 : (float, float32_elt) kind
178 See Bigarray.char .
180 val float64 : (float, float64_elt) kind
184 See Bigarray.char .
186 val complex32 : (Complex.t, complex32_elt) kind
190 See Bigarray.char .
192 val complex64 : (Complex.t, complex64_elt) kind
196 See Bigarray.char .
198 val int8_signed : (int, int8_signed_elt) kind
202 See Bigarray.char .
204 val int8_unsigned : (int, int8_unsigned_elt) kind
208 See Bigarray.char .
210 val int16_signed : (int, int16_signed_elt) kind
214 See Bigarray.char .
216 val int16_unsigned : (int, int16_unsigned_elt) kind
220 See Bigarray.char .
222 val int : (int, int_elt) kind
226 See Bigarray.char .
228 val int32 : (int32, int32_elt) kind
232 See Bigarray.char .
234 val int64 : (int64, int64_elt) kind
238 See Bigarray.char .
240 val nativeint : (nativeint, nativeint_elt) kind
244 See Bigarray.char .
246 val char : (char, int8_unsigned_elt) kind
250 As shown by the types of the values above, Bigarrays of kind
252 float32_elt and float64_elt are accessed using the OCaml type float .
253 Bigarrays of complex kinds complex32_elt , complex64_elt are accessed
254 with the OCaml type Complex.t . Bigarrays of integer kinds are accessed
255 using the smallest OCaml integer type large enough to represent the ar‐
256 ray elements: int for 8- and 16-bit integer Bigarrays, as well as
257 OCaml-integer Bigarrays; int32 for 32-bit integer Bigarrays; int64 for
258 64-bit integer Bigarrays; and nativeint for platform-native integer Bi‐
259 garrays. Finally, Bigarrays of kind int8_unsigned_elt can also be ac‐
260 cessed as arrays of characters instead of arrays of small integers, by
261 using the kind value char instead of int8_unsigned .
262 val kind_size_in_bytes : ('a, 'b) kind -> int
266 kind_size_in_bytes k is the number of bytes used to store an element of
269 type k .
270 Since 4.03.0
273 Array layouts
278 type c_layout =
279 | C_layout_typ
280 See Bigarray.fortran_layout .
283 type fortran_layout =
286 | Fortran_layout_typ
287 To facilitate interoperability with existing C and Fortran code, this
290 library supports two different memory layouts for Bigarrays, one com‐
291 patible with the C conventions, the other compatible with the Fortran
292 conventions.
293 In the C-style layout, array indices start at 0, and multi-dimensional
295 arrays are laid out in row-major format. That is, for a two-dimen‐
296 sional array, all elements of row 0 are contiguous in memory, followed
297 by all elements of row 1, etc. In other terms, the array elements at
298 (x,y) and (x, y+1) are adjacent in memory.
299 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
301 sional arrays are laid out in column-major format. That is, for a
302 two-dimensional array, all elements of column 0 are contiguous in mem‐
303 ory, followed by all elements of column 1, etc. In other terms, the
304 array elements at (x,y) and (x+1, y) are adjacent in memory.
305 Each layout style is identified at the type level by the phantom types
307 Bigarray.c_layout and Bigarray.fortran_layout respectively.
308 Supported layouts
313 The GADT type 'a layout represents one of the two supported memory lay‐
314 outs: C-style or Fortran-style. Its constructors are re-exported as
315 values below for backward-compatibility reasons.
316 type 'a layout =
318 | C_layout : c_layout layout
319 | Fortran_layout : fortran_layout layout
320 val c_layout : c_layout layout
326 val fortran_layout : fortran_layout layout
331 Generic arrays (of arbitrarily many dimensions)
337 module Genarray : sig end
338 Zero-dimensional arrays
345 module Array0 : sig end
346 Zero-dimensional arrays. The Array0 structure provides operations simi‐
349 lar to those of Bigarray.Genarray , but specialized to the case of
350 zero-dimensional arrays that only contain a single scalar value. Stat‐
351 ically knowing the number of dimensions of the array allows faster op‐
352 erations, and more precise static type-checking.
353 Since 4.05.0
356 One-dimensional arrays
361 module Array1 : sig end
362 One-dimensional arrays. The Array1 structure provides operations simi‐
365 lar to those of Bigarray.Genarray , but specialized to the case of
366 one-dimensional arrays. (The Bigarray.Array2 and Bigarray.Array3
367 structures below provide operations specialized for two- and three-di‐
368 mensional arrays.) Statically knowing the number of dimensions of the
369 array allows faster operations, and more precise static type-checking.
370 Two-dimensional arrays
375 module Array2 : sig end
376 Two-dimensional arrays. The Array2 structure provides operations simi‐
379 lar to those of Bigarray.Genarray , but specialized to the case of
380 two-dimensional arrays.
381 Three-dimensional arrays
386 module Array3 : sig end
387 Three-dimensional arrays. The Array3 structure provides operations sim‐
390 ilar to those of Bigarray.Genarray , but specialized to the case of
391 three-dimensional arrays.
392 Coercions between generic Bigarrays and fixed-dimension Bigarrays
397 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
398 ray.t
399 Return the generic Bigarray corresponding to the given zero-dimensional
401 Bigarray.
402 Since 4.05.0
405 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
409 ray.t
410 Return the generic Bigarray corresponding to the given one-dimensional
412 Bigarray.
413 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
417 ray.t
418 Return the generic Bigarray corresponding to the given two-dimensional
420 Bigarray.
421 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
425 ray.t
426 Return the generic Bigarray corresponding to the given three-dimen‐
428 sional Bigarray.
429 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
433 ray0.t
434 Return the zero-dimensional Bigarray corresponding to the given generic
436 Bigarray.
437 Since 4.05.0
440 Raises Invalid_argument if the generic Bigarray does not have exactly
443 zero dimension.
444 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
448 ray1.t
449 Return the one-dimensional Bigarray corresponding to the given generic
451 Bigarray.
452 Raises Invalid_argument if the generic Bigarray does not have exactly
455 one dimension.
456 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
460 ray2.t
461 Return the two-dimensional Bigarray corresponding to the given generic
463 Bigarray.
464 Raises Invalid_argument if the generic Bigarray does not have exactly
467 two dimensions.
468 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Ar‐
472 ray3.t
473 Return the three-dimensional Bigarray corresponding to the given
475 generic Bigarray.
476 Raises Invalid_argument if the generic Bigarray does not have exactly
479 three dimensions.
480 Re-shaping Bigarrays
485 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
486 Genarray.t
487 reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional ar‐
490 ray of dimensions d1 ... dN . The returned array and the original ar‐
491 ray b share their data and have the same layout. For instance, assum‐
492 ing that b is a one-dimensional array of dimension 12, reshape b
493 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
494 has C layout, the element (x,y) of b' corresponds to the element x * 3
495 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
496 sponds to the element x + (y - 1) * 4 of b . The returned Bigarray
497 must have exactly the same number of elements as the original Bigarray
498 b . That is, the product of the dimensions of b must be equal to i1 *
499 ... * iN . Otherwise, Invalid_argument is raised.
500 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
504 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
506 sional arrays.
507 Since 4.05.0
510 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
514 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
516 sional arrays.
517 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
521 Array2.t
522 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
524 sional arrays.
525 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
529 'b, 'c) Array3.t
530 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
532 sional arrays.
533OCamldoc 2022-07-22 Stdlib.Bigarray(3)