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‐
49 gle precision (32 bits) floating-point numbers (Bigarray.float32_elt),
50 - IEEE double precision (64 bits) floating-point numbers (Bigar‐
51 ray.float64_elt), - IEEE single precision (2 * 32 bits) floating-point
52 complex numbers (Bigarray.complex32_elt), - IEEE double precision (2 *
53 64 bits) floating-point complex numbers (Bigarray.complex64_elt), -
54 8-bit integers (signed or unsigned) (Bigarray.int8_signed_elt or Bigar‐
55 ray.int8_unsigned_elt), - 16-bit integers (signed or unsigned) (Bigar‐
56 ray.int16_signed_elt or Bigarray.int16_unsigned_elt), - Caml integers
57 (signed, 31 bits on 32-bit architectures, 63 bits on 64-bit architec‐
58 tures) (Bigarray.int_elt), - 32-bit signed integer (Bigar‐
59 ray.int32_elt), - 64-bit signed integers (Bigarray.int64_elt), - plat‐
60 form-native signed integers (32 bits on 32-bit architectures, 64 bits
61 on 64-bit architectures) (Bigarray.nativeint_elt). Each element kind
62 is represented at the type level by one of the abstract types defined
63 below. ===
64 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
250 See Bigarray.fortran_layout .
253 type fortran_layout
257 To facilitate interoperability with existing C and Fortran code, this
260 library supports two different memory layouts for big arrays, one com‐
261 patible with the C conventions, the other compatible with the Fortran
262 conventions.
263 In the C-style layout, array indices start at 0, and multi-dimensional
265 arrays are laid out in row-major format. That is, for a two-dimen‐
266 sional array, all elements of row 0 are contiguous in memory, followed
267 by all elements of row 1, etc. In other terms, the array elements at
268 (x,y) and (x, y+1) are adjacent in memory.
269 In the Fortran-style layout, array indices start at 1, and multi-dimen‐
271 sional arrays are laid out in column-major format. That is, for a two-
272 dimensional array, all elements of column 0 are contiguous in memory,
273 followed by all elements of column 1, etc. In other terms, the array
274 elements at (x,y) and (x+1, y) are adjacent in memory.
275 Each layout style is identified at the type level by the abstract types
277 Bigarray.c_layout and fortran_layout respectively.
278 type 'a layout
282 The type 'a layout represents one of the two supported memory layouts:
285 C-style if 'a is Bigarray.c_layout , Fortran-style if 'a is Bigar‐
286 ray.fortran_layout .
287 === Supported layouts The abstract values c_layout and fortran_layout
293 represent the two supported layouts at the level of values. ===
294 val c_layout : c_layout layout
297 val fortran_layout : fortran_layout layout
302 === Generic arrays (of arbitrarily many dimensions) ===
308 module Genarray : sig end
310 === One-dimensional arrays ===
317 module Array1 : sig end
319 One-dimensional arrays. The Array1 structure provides operations simi‐
322 lar to those of Bigarray.Genarray , but specialized to the case of one-
323 dimensional arrays. (The Array2 and Array3 structures below provide
324 operations specialized for two- and three-dimensional arrays.) Stati‐
325 cally knowing the number of dimensions of the array allows faster oper‐
326 ations, and more precise static type-checking.
327 === Two-dimensional arrays ===
333 module Array2 : sig end
335 Two-dimensional arrays. The Array2 structure provides operations simi‐
338 lar to those of Bigarray.Genarray , but specialized to the case of two-
339 dimensional arrays.
340 === Three-dimensional arrays ===
346 module Array3 : sig end
348 Three-dimensional arrays. The Array3 structure provides operations sim‐
351 ilar to those of Bigarray.Genarray , but specialized to the case of
352 three-dimensional arrays.
353 === Coercions between generic big arrays and fixed-dimension big arrays
359 ===
360 val genarray_of_array1 : ('a, 'b, 'c) Array1.t -> ('a, 'b, 'c) Genar‐
363 ray.t
364 Return the generic big array corresponding to the given one-dimensional
366 big array.
367 val genarray_of_array2 : ('a, 'b, 'c) Array2.t -> ('a, 'b, 'c) Genar‐
372 ray.t
373 Return the generic big array corresponding to the given two-dimensional
375 big array.
376 val genarray_of_array3 : ('a, 'b, 'c) Array3.t -> ('a, 'b, 'c) Genar‐
381 ray.t
382 Return the generic big array corresponding to the given three-dimen‐
384 sional big array.
385 val array1_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
390 Array1.t
391 Return the one-dimensional big array corresponding to the given generic
393 big array. Raise Invalid_arg if the generic big array does not have
394 exactly one dimension.
395 val array2_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
400 Array2.t
401 Return the two-dimensional big array corresponding to the given generic
403 big array. Raise Invalid_arg if the generic big array does not have
404 exactly two dimensions.
405 val array3_of_genarray : ('a, 'b, 'c) Genarray.t -> ('a, 'b, 'c)
410 Array3.t
411 Return the three-dimensional big array corresponding to the given
413 generic big array. Raise Invalid_arg if the generic big array does not
414 have exactly three dimensions.
415 === Re-shaping big arrays ===
421 val reshape : ('a, 'b, 'c) Genarray.t -> int array -> ('a, 'b, 'c)
424 Genarray.t
425 reshape b [|d1;...;dN|] converts the big array b to a N -dimensional
428 array of dimensions d1 ... dN . The returned array and the original
429 array b share their data and have the same layout. For instance,
430 assuming that b is a one-dimensional array of dimension 12, reshape b
431 [|3;4|] returns a two-dimensional array b' of dimensions 3 and 4. If b
432 has C layout, the element (x,y) of b' corresponds to the element x * 3
433 + y of b . If b has Fortran layout, the element (x,y) of b' corre‐
434 sponds to the element x + (y - 1) * 4 of b . The returned big array
435 must have exactly the same number of elements as the original big array
436 b . That is, the product of the dimensions of b must be equal to i1 *
437 ... * iN . Otherwise, Invalid_arg is raised.
438 val reshape_1 : ('a, 'b, 'c) Genarray.t -> int -> ('a, 'b, 'c) Array1.t
443 Specialized version of Bigarray.reshape for reshaping to one-dimen‐
445 sional arrays.
446 val reshape_2 : ('a, 'b, 'c) Genarray.t -> int -> int -> ('a, 'b, 'c)
451 Array2.t
452 Specialized version of Bigarray.reshape for reshaping to two-dimen‐
454 sional arrays.
455 val reshape_3 : ('a, 'b, 'c) Genarray.t -> int -> int -> int -> ('a,
460 'b, 'c) Array3.t
461 Specialized version of Bigarray.reshape for reshaping to three-dimen‐
463 sional arrays.
464OCamldoc 2007-05-24 Bigarray(3)