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
39 Bigarray.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
56 abstract 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
256 array 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
259 Bigarrays. Finally, Bigarrays of kind int8_unsigned_elt can also be
260 accessed as arrays of characters instead of arrays of small integers,
261 by 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
352 operations, 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
368 three-dimensional arrays.) Statically knowing the number of dimensions
369 of the array allows faster operations, and more precise static
370 type-checking.
371 Two-dimensional arrays
376 module Array2 : sig end
377 Two-dimensional arrays. The Array2 structure provides operations simi‐
380 lar to those of Bigarray.Genarray , but specialized to the case of
381 two-dimensional arrays.
382 Three-dimensional arrays
387 module Array3 : sig end
388 Three-dimensional arrays. The Array3 structure provides operations sim‐
391 ilar to those of Bigarray.Genarray , but specialized to the case of
392 three-dimensional arrays.
393 Coercions between generic Bigarrays and fixed-dimension Bigarrays
398 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
399 ray.t
400 Return the generic Bigarray corresponding to the given zero-dimensional
402 Bigarray.
403 Since 4.05.0
406 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
410 ray.t
411 Return the generic Bigarray corresponding to the given one-dimensional
413 Bigarray.
414 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
418 ray.t
419 Return the generic Bigarray corresponding to the given two-dimensional
421 Bigarray.
422 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
426 ray.t
427 Return the generic Bigarray corresponding to the given three-dimen‐
429 sional Bigarray.
430 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
434 Array0.t
435 Return the zero-dimensional Bigarray corresponding to the given generic
437 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
438 exactly zero dimension.
439 Since 4.05.0
442 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
446 Array1.t
447 Return the one-dimensional Bigarray corresponding to the given generic
449 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
450 exactly one dimension.
451 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
455 Array2.t
456 Return the two-dimensional Bigarray corresponding to the given generic
458 Bigarray. Raise Invalid_argument if the generic Bigarray does not have
459 exactly two dimensions.
460 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
464 Array3.t
465 Return the three-dimensional Bigarray corresponding to the given
467 generic Bigarray. Raise Invalid_argument if the generic Bigarray does
468 not have exactly three dimensions.
469 Re-shaping Bigarrays
474 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
475 Genarray.t
476 reshape b [|d1;...;dN|] converts the Bigarray b to a N -dimensional
479 array of dimensions d1 ... dN . The returned array and the original
480 array b share their data and have the same layout. For instance,
481 assuming that b is a one-dimensional array of dimension 12, reshape b
482 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
483 has C layout, the element (x,y) of b' corresponds to the element x * 3
484 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
485 sponds to the element x + (y - 1) * 4 of b . The returned Bigarray
486 must have exactly the same number of elements as the original Bigarray
487 b . That is, the product of the dimensions of b must be equal to i1 *
488 ... * iN . Otherwise, Invalid_argument is raised.
489 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
493 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
495 sional arrays.
496 Since 4.05.0
499 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
503 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
505 sional arrays.
506 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
510 Array2.t
511 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
513 sional arrays.
514 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
518 'b, 'c) Array3.t
519 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
521 sional arrays.
522OCamldoc 2020-02-27 Stdlib.Bigarray(3)