1Bigarray(3) OCamldoc Bigarray(3)
2
6 Bigarray - Large, multi-dimensional, numerical arrays.
7
9 Module Bigarray
10
12 Module Bigarray
13 : sig end
14 Large, multi-dimensional, numerical arrays.
17 This module implements multi-dimensional arrays of integers and float‐
19 ing-point numbers, thereafter referred to as 'big arrays'. The imple‐
20 mentation allows efficient sharing of large numerical arrays between
21 OCaml code and C or Fortran numerical libraries.
22 Concerning the naming conventions, users of this module are encouraged
24 to do open Bigarray in their source, then refer to array types and
25 operations via short dot notation, e.g. Array1.t or Array2.sub .
26 Big arrays support all the OCaml ad-hoc polymorphic operations:
28 -comparisons ( = , <> , <= , etc, as well as Pervasives.compare );
30 -hashing (module Hash );
32 -and structured input-output (the functions from the Marshal module, as
34 well as Pervasives.output_value and Pervasives.input_value ).
35 === Element kinds ===
44 === Big arrays can contain elements of the following kinds: - IEEE sin‐
47 gle precision (32 bits) floating-point numbers (Bigarray.float32_elt),
48 - IEEE double precision (64 bits) floating-point numbers (Bigar‐
49 ray.float64_elt), - IEEE single precision (2 * 32 bits) floating-point
50 complex numbers (Bigarray.complex32_elt), - IEEE double precision (2 *
51 64 bits) floating-point complex numbers (Bigarray.complex64_elt), -
52 8-bit integers (signed or unsigned) (Bigarray.int8_signed_elt or Bigar‐
53 ray.int8_unsigned_elt), - 16-bit integers (signed or unsigned) (Bigar‐
54 ray.int16_signed_elt or Bigarray.int16_unsigned_elt), - OCaml integers
55 (signed, 31 bits on 32-bit architectures, 63 bits on 64-bit architec‐
56 tures) (Bigarray.int_elt), - 32-bit signed integers (Bigar‐
57 ray.int32_elt), - 64-bit signed integers (Bigarray.int64_elt), - plat‐
58 form-native signed integers (32 bits on 32-bit architectures, 64 bits
59 on 64-bit architectures) (Bigarray.nativeint_elt). Each element kind
60 is represented at the type level by one of the *_elt types defined
61 below (defined with a single constructor instead of abstract types for
62 technical injectivity reasons). ===
63 type float32_elt =
66 | Float32_elt
67 type float64_elt =
72 | Float64_elt
73 type int8_signed_elt =
78 | Int8_signed_elt
79 type int8_unsigned_elt =
84 | Int8_unsigned_elt
85 type int16_signed_elt =
90 | Int16_signed_elt
91 type int16_unsigned_elt =
96 | Int16_unsigned_elt
97 type int32_elt =
102 | Int32_elt
103 type int64_elt =
108 | Int64_elt
109 type int_elt =
114 | Int_elt
115 type nativeint_elt =
120 | Nativeint_elt
121 type complex32_elt =
126 | Complex32_elt
127 type complex64_elt =
132 | Complex64_elt
133 type ('a, 'b) kind =
138 | Float32 : (float, float32_elt) kind
139 | Float64 : (float, float64_elt) kind
140 | Int8_signed : (int, int8_signed_elt) kind
141 | Int8_unsigned : (int, int8_unsigned_elt) kind
142 | Int16_signed : (int, int16_signed_elt) kind
143 | Int16_unsigned : (int, int16_unsigned_elt) kind
144 | Int32 : (int32, int32_elt) kind
145 | Int64 : (int64, int64_elt) kind
146 | Int : (int, int_elt) kind
147 | Nativeint : (nativeint, nativeint_elt) kind
148 | Complex32 : (Complex.t, complex32_elt) kind
149 | Complex64 : (Complex.t, complex64_elt) kind
150 | Char : (char, int8_unsigned_elt) kind
151 To each element kind is associated an OCaml type, which is the type of
154 OCaml values that can be stored in the big array or read back from it.
155 This type is not necessarily the same as the type of the array elements
156 proper: for instance, a big array whose elements are of kind
157 float32_elt contains 32-bit single precision floats, but reading or
158 writing one of its elements from OCaml uses the OCaml type float ,
159 which is 64-bit double precision floats.
160 The GADT type ('a, 'b) kind captures this association of an OCaml type
162 'a for values read or written in the big array, and of an element kind
163 'b which represents the actual contents of the big array. Its construc‐
164 tors list all possible associations of OCaml types with element kinds,
165 and are re-exported below for backward-compatibility reasons.
166 Using a generalized algebraic datatype (GADT) here allows to write
168 well-typed polymorphic functions whose return type depend on the argu‐
169 ment type, such as:
170 let zero : type a b. (a, b) kind -> a = function | Float32 -> 0.0 |
173 Complex32 -> Complex.zero | Float64 -> 0.0 | Complex64 -> Complex.zero
174 | Int8_signed -> 0 | Int8_unsigned -> 0 | Int16_signed -> 0 |
175 Int16_unsigned -> 0 | Int32 -> 0l | Int64 -> 0L | Int -> 0 | Nativeint
176 -> 0n | Char -> '\000'
177 val float32 : (float, float32_elt) kind
182 See Bigarray.char .
184 val float64 : (float, float64_elt) kind
188 See Bigarray.char .
190 val complex32 : (Complex.t, complex32_elt) kind
194 See Bigarray.char .
196 val complex64 : (Complex.t, complex64_elt) kind
200 See Bigarray.char .
202 val int8_signed : (int, int8_signed_elt) kind
206 See Bigarray.char .
208 val int8_unsigned : (int, int8_unsigned_elt) kind
212 See Bigarray.char .
214 val int16_signed : (int, int16_signed_elt) kind
218 See Bigarray.char .
220 val int16_unsigned : (int, int16_unsigned_elt) kind
224 See Bigarray.char .
226 val int : (int, int_elt) kind
230 See Bigarray.char .
232 val int32 : (int32, int32_elt) kind
236 See Bigarray.char .
238 val int64 : (int64, int64_elt) kind
242 See Bigarray.char .
244 val nativeint : (nativeint, nativeint_elt) kind
248 See Bigarray.char .
250 val char : (char, int8_unsigned_elt) kind
254 As shown by the types of the values above, big arrays of kind
256 float32_elt and float64_elt are accessed using the OCaml type float .
257 Big arrays of complex kinds complex32_elt , complex64_elt are accessed
258 with the OCaml type Complex.t . Big arrays of integer kinds are
259 accessed using the smallest OCaml integer type large enough to repre‐
260 sent the array elements: int for 8- and 16-bit integer bigarrays, as
261 well as OCaml-integer bigarrays; int32 for 32-bit integer bigarrays;
262 int64 for 64-bit integer bigarrays; and nativeint for platform-native
263 integer bigarrays. Finally, big arrays of kind int8_unsigned_elt can
264 also be accessed as arrays of characters instead of arrays of small
265 integers, by using the kind value char instead of int8_unsigned .
266 val kind_size_in_bytes : ('a, 'b) kind -> int
270 kind_size_in_bytes k is the number of bytes used to store an element of
273 type k .
274 Since 4.03.0
277 === Array layouts ===
282 type c_layout =
285 | C_layout_typ
286 See Bigarray.fortran_layout .
289 type fortran_layout =
292 | Fortran_layout_typ
293 To facilitate interoperability with existing C and Fortran code, this
296 library supports two different memory layouts for big arrays, one com‐
297 patible with the C conventions, the other compatible with the Fortran
298 conventions.
299 In the C-style layout, array indices start at 0, and multi-dimensional
301 arrays are laid out in row-major format. That is, for a two-dimen‐
302 sional array, all elements of row 0 are contiguous in memory, followed
303 by all elements of row 1, etc. In other terms, the array elements at
304 (x,y) and (x, y+1) are adjacent in memory.
305 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
307 sional arrays are laid out in column-major format. That is, for a
308 two-dimensional array, all elements of column 0 are contiguous in mem‐
309 ory, followed by all elements of column 1, etc. In other terms, the
310 array elements at (x,y) and (x+1, y) are adjacent in memory.
311 Each layout style is identified at the type level by the phantom types
313 Bigarray.c_layout and Bigarray.fortran_layout respectively.
314 === Supported layouts The GADT type 'a layout represents one of the two
319 supported memory layouts: C-style or Fortran-style. Its constructors
320 are re-exported as values below for backward-compatibility reasons. ===
321 type 'a layout =
324 | C_layout : c_layout layout
325 | Fortran_layout : fortran_layout layout
326 val c_layout : c_layout layout
332 val fortran_layout : fortran_layout layout
337 === Generic arrays (of arbitrarily many dimensions) ===
343 module Genarray : sig end
346 === Zero-dimensional arrays ===
353 module Array0 : sig end
356 Zero-dimensional arrays. The Array0 structure provides operations simi‐
359 lar to those of Bigarray.Genarray , but specialized to the case of
360 zero-dimensional arrays that only contain a single scalar value. Stat‐
361 ically knowing the number of dimensions of the array allows faster
362 operations, and more precise static type-checking.
363 Since 4.05.0
366 === One-dimensional arrays ===
371 module Array1 : sig end
374 One-dimensional arrays. The Array1 structure provides operations simi‐
377 lar to those of Bigarray.Genarray , but specialized to the case of
378 one-dimensional arrays. (The Bigarray.Array2 and Bigarray.Array3
379 structures below provide operations specialized for two- and
380 three-dimensional arrays.) Statically knowing the number of dimensions
381 of the array allows faster operations, and more precise static
382 type-checking.
383 === Two-dimensional arrays ===
388 module Array2 : sig end
391 Two-dimensional arrays. The Array2 structure provides operations simi‐
394 lar to those of Bigarray.Genarray , but specialized to the case of
395 two-dimensional arrays.
396 === Three-dimensional arrays ===
401 module Array3 : sig end
404 Three-dimensional arrays. The Array3 structure provides operations sim‐
407 ilar to those of Bigarray.Genarray , but specialized to the case of
408 three-dimensional arrays.
409 === Coercions between generic big arrays and fixed-dimension big arrays
414 ===
415 val genarray_of_array0 : ('a, 'b, 'c) Array0.t -> ('a, 'b, 'c) Genar‐
418 ray.t
419 Return the generic big array corresponding to the given zero-dimen‐
421 sional big array.
422 Since 4.05.0
425 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
429 ray.t
430 Return the generic big array corresponding to the given one-dimensional
432 big array.
433 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
437 ray.t
438 Return the generic big array corresponding to the given two-dimensional
440 big array.
441 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
445 ray.t
446 Return the generic big array corresponding to the given three-dimen‐
448 sional big array.
449 val array0_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
453 Array0.t
454 Return the zero-dimensional big array corresponding to the given
456 generic big array. Raise Invalid_argument if the generic big array
457 does not have exactly zero dimension.
458 Since 4.05.0
461 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
465 Array1.t
466 Return the one-dimensional big array corresponding to the given generic
468 big array. Raise Invalid_argument if the generic big array does not
469 have exactly one dimension.
470 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
474 Array2.t
475 Return the two-dimensional big array corresponding to the given generic
477 big array. Raise Invalid_argument if the generic big array does not
478 have exactly two dimensions.
479 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
483 Array3.t
484 Return the three-dimensional big array corresponding to the given
486 generic big array. Raise Invalid_argument if the generic big array
487 does not have exactly three dimensions.
488 === Re-shaping big arrays ===
493 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
496 Genarray.t
497 reshape b [|d1;...;dN|] converts the big array b to a N -dimensional
500 array of dimensions d1 ... dN . The returned array and the original
501 array b share their data and have the same layout. For instance,
502 assuming that b is a one-dimensional array of dimension 12, reshape b
503 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
504 has C layout, the element (x,y) of b' corresponds to the element x * 3
505 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
506 sponds to the element x + (y - 1) * 4 of b . The returned big array
507 must have exactly the same number of elements as the original big array
508 b . That is, the product of the dimensions of b must be equal to i1 *
509 ... * iN . Otherwise, Invalid_argument is raised.
510 val reshape_0 : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c) Array0.t
514 Specialized version of Bigarray.reshape for reshaping to zero-dimen‐
516 sional arrays.
517 Since 4.05.0
520 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
524 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
526 sional arrays.
527 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
531 Array2.t
532 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
534 sional arrays.
535 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
539 'b, 'c) Array3.t
540 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
542 sional arrays.
5432018-04-14 source: Bigarray(3)