1Bigarray(3) OCaml library 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
20 implementation allows efficient sharing of large numerical arrays
21 between Caml 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 Caml ad-hoc polymorphic operations:
28 -comparisons ( = , <> , <= , etc, as well as Pervasives.compare );
30 -hashing (module Hash );
32 -and structured input-output ( Pervasives.output_value and Perva‐
34 sives.input_value , as well as the functions from the Marshal module).
35 === Element kinds ===
45 === Big arrays can contain elements of the following kinds: - IEEE sin‐
48 gle precision (32 bits) floating-point numbers (Bigarray.float32_elt),
49 - IEEE double precision (64 bits) floating-point numbers (Bigar‐
50 ray.float64_elt), - IEEE single precision (2 * 32 bits) floating-point
51 complex numbers (Bigarray.complex32_elt), - IEEE double precision (2 *
52 64 bits) floating-point complex numbers (Bigarray.complex64_elt), -
53 8-bit integers (signed or unsigned) (Bigarray.int8_signed_elt or Bigar‐
54 ray.int8_unsigned_elt), - 16-bit integers (signed or unsigned) (Bigar‐
55 ray.int16_signed_elt or Bigarray.int16_unsigned_elt), - Caml integers
56 (signed, 31 bits on 32-bit architectures, 63 bits on 64-bit architec‐
57 tures) (Bigarray.int_elt), - 32-bit signed integer (Bigar‐
58 ray.int32_elt), - 64-bit signed integers (Bigarray.int64_elt), - plat‐
59 form-native signed integers (32 bits on 32-bit architectures, 64 bits
60 on 64-bit architectures) (Bigarray.nativeint_elt). Each element kind
61 is represented at the type level by one of the abstract types defined
62 below. ===
63 type float32_elt
66 type float64_elt
71 type complex32_elt
76 type complex64_elt
81 type int8_signed_elt
86 type int8_unsigned_elt
91 type int16_signed_elt
96 type int16_unsigned_elt
101 type int_elt
106 type int32_elt
111 type int64_elt
116 type nativeint_elt
121 type ('a, 'b) kind
126 To each element kind is associated a Caml type, which is the type of
129 Caml values that can be stored in the big array or read back from it.
130 This type is not necessarily the same as the type of the array elements
131 proper: for instance, a big array whose elements are of kind
132 float32_elt contains 32-bit single precision floats, but reading or
133 writing one of its elements from Caml uses the Caml type float , which
134 is 64-bit double precision floats.
135 The abstract type ('a, 'b) kind captures this association of a Caml
137 type 'a for values read or written in the big array, and of an element
138 kind 'b which represents the actual contents of the big array. The
139 following predefined values of type kind list all possible associations
140 of Caml types with element kinds:
141 val float32 : (float, float32_elt) kind
146 See Bigarray.char .
148 val float64 : (float, float64_elt) kind
153 See Bigarray.char .
155 val complex32 : (Complex.t, complex32_elt) kind
160 See Bigarray.char .
162 val complex64 : (Complex.t, complex64_elt) kind
167 See Bigarray.char .
169 val int8_signed : (int, int8_signed_elt) kind
174 See Bigarray.char .
176 val int8_unsigned : (int, int8_unsigned_elt) kind
181 See Bigarray.char .
183 val int16_signed : (int, int16_signed_elt) kind
188 See Bigarray.char .
190 val int16_unsigned : (int, int16_unsigned_elt) kind
195 See Bigarray.char .
197 val int : (int, int_elt) kind
202 See Bigarray.char .
204 val int32 : (int32, int32_elt) kind
209 See Bigarray.char .
211 val int64 : (int64, int64_elt) kind
216 See Bigarray.char .
218 val nativeint : (nativeint, nativeint_elt) kind
223 See Bigarray.char .
225 val char : (char, int8_unsigned_elt) kind
230 As shown by the types of the values above, big arrays of kind
232 float32_elt and float64_elt are accessed using the Caml type float .
233 Big arrays of complex kinds complex32_elt , complex64_elt are accessed
234 with the Caml type Complex.t . Big arrays of integer kinds are
235 accessed using the smallest Caml integer type large enough to represent
236 the array elements: int for 8- and 16-bit integer bigarrays, as well as
237 Caml-integer bigarrays; int32 for 32-bit integer bigarrays; int64 for
238 64-bit integer bigarrays; and nativeint for platform-native integer
239 bigarrays. Finally, big arrays of kind int8_unsigned_elt can also be
240 accessed as arrays of characters instead of arrays of small integers,
241 by using the kind value char instead of int8_unsigned .
242 === Array layouts ===
248 type c_layout
251 See Bigarray.fortran_layout .
254 type fortran_layout
258 To facilitate interoperability with existing C and Fortran code, this
261 library supports two different memory layouts for big arrays, one com‐
262 patible with the C conventions, the other compatible with the Fortran
263 conventions.
264 In the C-style layout, array indices start at 0, and multi-dimensional
266 arrays are laid out in row-major format. That is, for a two-dimen‐
267 sional array, all elements of row 0 are contiguous in memory, followed
268 by all elements of row 1, etc. In other terms, the array elements at
269 (x,y) and (x, y+1) are adjacent in memory.
270 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
272 sional arrays are laid out in column-major format. That is, for a
273 two-dimensional array, all elements of column 0 are contiguous in mem‐
274 ory, followed by all elements of column 1, etc. In other terms, the
275 array elements at (x,y) and (x+1, y) are adjacent in memory.
276 Each layout style is identified at the type level by the abstract types
278 Bigarray.c_layout and fortran_layout respectively.
279 type 'a layout
283 The type 'a layout represents one of the two supported memory layouts:
286 C-style if 'a is Bigarray.c_layout , Fortran-style if 'a is Bigar‐
287 ray.fortran_layout .
288 === Supported layouts The abstract values c_layout and fortran_layout
294 represent the two supported layouts at the level of values. ===
295 val c_layout : c_layout layout
298 val fortran_layout : fortran_layout layout
303 === Generic arrays (of arbitrarily many dimensions) ===
309 module Genarray : sig end
312 === One-dimensional arrays ===
319 module Array1 : sig end
322 One-dimensional arrays. The Array1 structure provides operations simi‐
325 lar to those of Bigarray.Genarray , but specialized to the case of
326 one-dimensional arrays. (The Array2 and Array3 structures below pro‐
327 vide operations specialized for two- and three-dimensional arrays.)
328 Statically knowing the number of dimensions of the array allows faster
329 operations, and more precise static type-checking.
330 === Two-dimensional arrays ===
336 module Array2 : sig end
339 Two-dimensional arrays. The Array2 structure provides operations simi‐
342 lar to those of Bigarray.Genarray , but specialized to the case of
343 two-dimensional arrays.
344 === Three-dimensional arrays ===
350 module Array3 : sig end
353 Three-dimensional arrays. The Array3 structure provides operations sim‐
356 ilar to those of Bigarray.Genarray , but specialized to the case of
357 three-dimensional arrays.
358 === Coercions between generic big arrays and fixed-dimension big arrays
364 ===
365 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
368 ray.t
369 Return the generic big array corresponding to the given one-dimensional
371 big array.
372 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
377 ray.t
378 Return the generic big array corresponding to the given two-dimensional
380 big array.
381 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
386 ray.t
387 Return the generic big array corresponding to the given three-dimen‐
389 sional big array.
390 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
395 Array1.t
396 Return the one-dimensional big array corresponding to the given generic
398 big array. Raise Invalid_argument if the generic big array does not
399 have exactly one dimension.
400 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
405 Array2.t
406 Return the two-dimensional big array corresponding to the given generic
408 big array. Raise Invalid_argument if the generic big array does not
409 have exactly two dimensions.
410 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
415 Array3.t
416 Return the three-dimensional big array corresponding to the given
418 generic big array. Raise Invalid_argument if the generic big array
419 does not have exactly three dimensions.
420 === Re-shaping big arrays ===
426 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
429 Genarray.t
430 reshape b [|d1;...;dN|] converts the big array b to a N -dimensional
433 array of dimensions d1 ... dN . The returned array and the original
434 array b share their data and have the same layout. For instance,
435 assuming that b is a one-dimensional array of dimension 12, reshape b
436 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
437 has C layout, the element (x,y) of b' corresponds to the element x * 3
438 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
439 sponds to the element x + (y - 1) * 4 of b . The returned big array
440 must have exactly the same number of elements as the original big array
441 b . That is, the product of the dimensions of b must be equal to i1 *
442 ... * iN . Otherwise, Invalid_argument is raised.
443 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
448 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
450 sional arrays.
451 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
456 Array2.t
457 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
459 sional arrays.
460 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
465 'b, 'c) Array3.t
466 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
468 sional arrays.
469OCamldoc 2017-03-22 Bigarray(3)