Chapter 28 
The bigarray library 

The bigarray library implements large, multidimensional, numerical
arrays. These arrays are called ``big arrays'' to distinguish them
from the standard Caml arrays described in section 19.2.
The main differences between ``big arrays'' and standard Caml arrays
are as follows:

Big arrays are not limited in size, unlike Caml arrays
(float array are limited to 2097151 elements on a 32bit platform,
other array types to 4194303 elements).
 Big arrays are multidimensional. Any number of dimensions
between 1 and 16 is supported. In contrast, Caml arrays are
monodimensional and require encoding multidimensional arrays as
arrays of arrays.
 Big arrays can only contain integers and floatingpoint
numbers, while Caml arrays can contain arbitrary Caml data types.
However, big arrays provide more spaceefficient storage of integer
and floatingpoint elements, in particular because they support
``small'' types such as singleprecision floats and 8 and 16bit
integers, in addition to the standard Caml types of doubleprecision
floats and 32 and 64bit integers.
 The memory layout of big arrays is entirely compatible with that
of arrays in C and Fortran, allowing large arrays to be passed back
and forth between Caml code and C / Fortran code with no data copying
at all.
 Big arrays support interesting highlevel operations that normal
arrays do not provide efficiently, such as extracting subarrays and
``slicing'' a multidimensional array along certain dimensions, all
without any copying.
Programs that use the bigarray library must be linked as follows:
nmlc other options bigarray.cma other files
28.1 
Module Bigarray: large, multidimensional, numerical arrays 

This module implements multidimensional arrays of integers and
floatingpoint numbers, thereafter referred to as ``big arrays''.
The implementation allows efficient sharing of large numerical
arrays between Caml code and C or Fortran numerical libraries.
Concerning the naming conventions, users of this module are encouraged
to do open Bigarray
in their source, then refer to array types and
operations via short dot notation, e.g. Array1.t
or Array2.sub
.
Big arrays support all the Caml adhoc polymorphic operations:
comparisons (=
, <>
, <=
, etc, as well as compare
);
hashing (module Hash
);
and structured inputoutput (output_value
and input_value
,
as well as the functions from the Marshal
module).
type float32_elt
type float64_elt
type int8_signed_elt
type int8_unsigned_elt
type int16_signed_elt
type int16_unsigned_elt
type int_elt
type int32_elt
type int64_elt
type nativeint_elt
Big arrays can contain elements of the following kinds:
IEEE single precision (32 bits) floatingpoint numbers;
IEEE double precision (64 bits) floatingpoint numbers;
8bit integers (signed or unsigned);
16bit integers (signed or unsigned);
Caml integers (signed, 31 bits on 32bit architectures,
63 bits on 64bit architectures);
32bit signed integers;
64bit signed integers;
platformnative signed integers (32 bits on 32bit architectures,
64 bits on 64bit architectures).
Each element kind is represented at the type level by one
of the abstract types defined above.
type ('a, 'b) kind
To each element kind is associated a Caml type, which is
the type of Caml values that can be stored in the big array
or read back from it. This type is not necessarily the same
as the type of the array elements proper: for instance,
a big array whose elements are of kind float32_elt
contains
32bit single precision floats, but reading or writing one of
its elements from Caml uses the Caml type float
, which is
64bit double precision floats.
The abstract type ('a, 'b) kind
captures this association
of a Caml type 'a
for values read or written in the big array,
and of an element kind 'b
which represents the actual contents
of the big array. The following predefined values of type
kind
list all possible associations of Caml types with
element kinds:
val float32: (float, float32_elt) kind
val float64: (float, float64_elt) kind
val int8_signed: (int, int8_signed_elt) kind
val int8_unsigned: (int, int8_unsigned_elt) kind
val int16_signed: (int, int16_signed_elt) kind
val int16_unsigned: (int, int16_unsigned_elt) kind
val int: (int, int_elt) kind
val int32: (int32, int32_elt) kind
val int64: (int64, int64_elt) kind
val nativeint: (nativeint, nativeint_elt) kind
val char: (char, int8_unsigned_elt) kind
As shown by the types of the values above,
big arrays of kind float32_elt
and float64_elt
are
accessed using the Caml type float
. Big arrays of
integer kinds are accessed using the smallest Caml integer
type large enough to represent the array elements:
int
for 8 and 16bit integer bigarrays, as well as Camlinteger
bigarrays; int32
for 32bit integer bigarrays; int64
for 64bit integer bigarrays; and nativeint
for
platformnative integer bigarrays. Finally, big arrays of
kind int8_unsigned_elt
can also be accessed as arrays of
characters instead of arrays of small integers, by using
the kind value char
instead of int8_unsigned
.
type c_layout
type fortran_layout
To facilitate interoperability with existing C and Fortran code,
this library supports two different memory layouts for big arrays,
one compatible with the C conventions,
the other compatible with the Fortran conventions.
In the Cstyle layout, array indices start at 0, and
multidimensional arrays are laid out in rowmajor format.
That is, for a twodimensional array, all elements of
row 0 are contiguous in memory, followed by all elements of
row 1, etc. In other terms, the array elements at (x,y)
and (x, y+1)
are adjacent in memory.
In the Fortranstyle layout, array indices start at 1, and
multidimensional arrays are laid out in columnmajor format.
That is, for a twodimensional array, all elements of
column 0 are contiguous in memory, followed by all elements of
column 1, etc. In other terms, the array elements at (x,y)
and (x+1, y)
are adjacent in memory.
Each layout style is identified at the type level by the
abstract types c_layout
and fortran_layout
respectively.
type 'a layout
The type 'a layout
represents one of the two supported
memory layouts: Cstyle if 'a
is c_layout
, Fortranstyle
if 'a
is fortran_layout
.
val c_layout: c_layout layout
val fortran_layout: fortran_layout layout
The abstract values c_layout
and fortran_layout
represent
the two supported layouts at the level of values.
Generic arrays (of arbitrarily many dimensions) 

module Genarray: sig
type ('a, 'b, 'c) t
The type Genarray.t
is the type of big arrays with variable
numbers of dimensions. Any number of dimensions between 1 and 16
is supported.
The three type parameters to Genarray.t
identify the array element
kind and layout, as follows:
the first parameter, 'a
, is the Caml type for accessing array
elements (float
, int
, int32
, int64
, nativeint
);
the second parameter, 'b
, is the actual kind of array elements
(float32_elt
, float64_elt
, int8_signed_elt
, int8_unsigned_elt
,
etc);
the third parameter, 'c
, identifies the array layout
(c_layout
or fortran_layout
).
For instance, (float, float32_elt, fortran_layout) Genarray.t
is the type of generic big arrays containing 32bit floats
in Fortran layout; reads and writes in this array use the
Caml type float
.
external create:
kind:('a, 'b) kind > layout:'c layout > dims:int array > ('a, 'b, 'c) t
Genarray.create kind layout dimensions
returns a new big array
whose element kind is determined by the parameter kind
(one of
float32
, float64
, int8_signed
, etc) and whose layout is
determined by the parameter layout
(one of c_layout
or
fortran_layout
). The dimensions
parameter is an array of
integers that indicate the size of the big array in each dimension.
The length of dimensions
determines the number of dimensions
of the bigarray.
For instance, Genarray.create int32 c_layout [4;6;8]
returns a fresh big array of 32bit integers, in C layout,
having three dimensions, the three dimensions being 4, 6 and 8
respectively.
Big arrays returned by Genarray.create
are not initialized:
the initial values of array elements is unspecified.
Genarray.create
raises Invalid_arg
if the number of dimensions
is not in the range 1 to 16 inclusive, or if one of the dimensions
is negative.
external num_dims: ('a, 'b, 'c) t > int
Return the number of dimensions of the given big array.
external nth_dim: ('a, 'b, 'c) t > int > int
Genarray.nth_dim a n
returns the n
th dimension of the
big array a
. The first dimension corresponds to n = 0
;
the second dimension corresponds to n = 1
; the last dimension,
to n = Genarray.num_dims a  1
.
Raise Invalid_arg
if n
is less than 0 or greater or equal than
Genarray.num_dims a
.
external get: ('a, 'b, 'c) t > int array > 'a
Read an element of a generic big array.
Genarray.get a [i1; ...; iN]
returns the element of a
whose coordinates are i1
in the first dimension, i2
in
the second dimension, ..., iN
in the N
th dimension.
If a
has C layout, the coordinates must be greater or equal than 0
and strictly less than the corresponding dimensions of a
.
If a
has Fortran layout, the coordinates must be greater or equal
than 1 and less or equal than the corresponding dimensions of a
.
Raise Invalid_arg
if the array a
does not have exactly N
dimensions, or if the coordinates are outside the array bounds.
If N > 3
, alternate syntax is provided: you can write
a.{i1, i2, ..., iN}
instead of Genarray.get a [i1; ...; iN]
.
(The syntax a.{...}
with one, two or three coordinates is
reserved for accessing one, two and threedimensional arrays
as described below.)
external set: ('a, 'b, 'c) t > int array > 'a > unit
Assign an element of a generic big array.
Genarray.set a [i1; ...; iN] v
stores the value v
in the
element of a
whose coordinates are i1
in the first dimension,
i2
in the second dimension, ..., iN
in the N
th dimension.
The array a
must have exactly N
dimensions, and all coordinates
must lie inside the array bounds, as described for Genarray.get
;
otherwise, Invalid_arg
is raised.
If N > 3
, alternate syntax is provided: you can write
a.{i1, i2, ..., iN} < v
instead of
Genarray.set a [i1; ...; iN] v
.
(The syntax a.{...} < v
with one, two or three coordinates is
reserved for updating one, two and threedimensional arrays
as described below.)
external sub_left:
('a, 'b, c_layout) t > pos:int > len:int > ('a, 'b, c_layout) t
Extract a subarray of the given big array by restricting the
first (leftmost) dimension. Genarray.sub_left a ofs len
returns a big array with the same number of dimensions as a
,
and the same dimensions as a
, except the first dimension,
which corresponds to the interval [ofs ... ofs + len  1]
of the first dimension of a
. No copying of elements is
involved: the subarray and the original array share the same
storage space. In other terms, the element at coordinates
[i1; ...; iN]
of the subarray is identical to the
element at coordinates [i1+ofs; ...; iN]
of the original
array a
.
Genarray.sub_left
applies only to big arrays in C layout.
Raise Invalid_arg
if ofs
and len
do not designate
a valid subarray of a
, that is, if ofs < 0
, or len < 0
,
or ofs + len > Genarray.nth_dim a 0
.
external sub_right:
('a, 'b, fortran_layout) t >
pos:int > len:int > ('a, 'b, fortran_layout) t
Extract a subarray of the given big array by restricting the
last (rightmost) dimension. Genarray.sub_right a ofs len
returns a big array with the same number of dimensions as a
,
and the same dimensions as a
, except the last dimension,
which corresponds to the interval [ofs ... ofs + len  1]
of the last dimension of a
. No copying of elements is
involved: the subarray and the original array share the same
storage space. In other terms, the element at coordinates
[i1; ...; iN]
of the subarray is identical to the
element at coordinates [i1; ...; iN+ofs]
of the original
array a
.
Genarray.sub_right
applies only to big arrays in Fortran layout.
Raise Invalid_arg
if ofs
and len
do not designate
a valid subarray of a
, that is, if ofs < 1
, or len < 0
,
or ofs + len > Genarray.nth_dim a (Genarray.num_dims a  1)
.
external slice_left:
('a, 'b, c_layout) t > int array > ('a, 'b, c_layout) t
Extract a subarray of lower dimension from the given big array
by fixing one or several of the first (leftmost) coordinates.
Genarray.slice_left a [i1; ... ; iM]
returns the ``slice''
of a
obtained by setting the first M
coordinates to
i1
, ..., iM
. If a
has N
dimensions, the slice has
dimension N  M
, and the element at coordinates
[j1; ...; j(NM)]
in the slice is identical to the element
at coordinates [i1; ...; iM; j1; ...; j(NM)]
in the original
array a
. No copying of elements is involved: the slice and
the original array share the same storage space.
Genarray.slice_left
applies only to big arrays in C layout.
Raise Invalid_arg
if M >= N
, or if [i1; ... ; iM]
is outside the bounds of a
.
external slice_right:
('a, 'b, fortran_layout) t > int array > ('a, 'b, fortran_layout) t
Extract a subarray of lower dimension from the given big array
by fixing one or several of the last (rightmost) coordinates.
Genarray.slice_right a [i1; ... ; iM]
returns the ``slice''
of a
obtained by setting the last M
coordinates to
i1
, ..., iM
. If a
has N
dimensions, the slice has
dimension N  M
, and the element at coordinates
[j1; ...; j(NM)]
in the slice is identical to the element
at coordinates [j1; ...; j(NM); i1; ...; iM]
in the original
array a
. No copying of elements is involved: the slice and
the original array share the same storage space.
Genarray.slice_right
applies only to big arrays in Fortran layout.
Raise Invalid_arg
if M >= N
, or if [i1; ... ; iM]
is outside the bounds of a
.
external blit: src:('a, 'b, 'c) t > dst:('a, 'b, 'c) t > unit
Copy all elements of a big array in another big array.
Genarray.blit src dst
copies all elements of src
into
dst
. Both arrays src
and dst
must have the same number of
dimensions and equal dimensions. Copying a subarray of src
to a subarray of dst
can be achieved by applying Genarray.blit
to subarray or slices of src
and dst
.
external fill: ('a, 'b, 'c) t > 'a > unit
Set all elements of a big array to a given value.
Genarray.fill a v
stores the value v
in all elements of
the big array a
. Setting only some elements of a
to v
can be achieved by applying Genarray.fill
to a subarray
or a slice of a
.
external map_file:
Unix.file_descr > kind:('a, 'b) kind > layout:'c layout >
shared:bool > dims:int array > ('a, 'b, 'c) t
Memory mapping of a file as a big array.
Genarray.map_file fd kind layout shared dims
returns a big array of kind kind
, layout layout
,
and dimensions as specified in dims
. The data contained in
this big array are the contents of the file referred to by
the file descriptor fd
(as opened previously with
Unix.openfile
, for example). If shared
is true
,
all modifications performed on the array are reflected in
the file. This requires that fd
be opened with write permissions.
If shared
is false
, modifications performed on the array
are done in memory only, using copyonwrite of the modified
pages; the underlying file is not affected.
Genarray.map_file
is much more efficient than reading
the whole file in a big array, modifying that big array,
and writing it afterwards.
To adjust automatically the dimensions of the big array to
the actual size of the file, the major dimension (that is,
the first dimension for an array with C layout, and the last
dimension for an array with Fortran layout) can be given as
1
. Genarray.map_file
then determines the major dimension
from the size of the file. The file must contain an integral
number of subarrays as determined by the nonmajor dimensions,
otherwise Failure
is raised.
If all dimensions of the big array are given, the file size is
matched against the size of the big array. If the file is larger
than the big array, only the initial portion of the file is
mapped to the big array. If the file is smaller than the big
array, the file is automatically grown to the size of the big array.
This requires write permissions on fd
.
end
The Array1
structure provides operations similar to those of
Genarray
, but specialized to the case of onedimensional arrays.
(The Array2
and Array3
structures below provide operations
specialized for two and threedimensional arrays.)
Statically knowing the number of dimensions of the array allows
faster operations, and more precise static typechecking.
module Array1: sig
type ('a, 'b, 'c) t
The type of onedimensional big arrays whose elements have
Caml type 'a
, representation kind 'b
, and memory layout 'c
.
val create:
kind:('a, 'b) kind > layout:'c layout > dim:int > ('a, 'b, 'c) t
Array1.create kind layout dim
returns a new bigarray of
one dimension, whose size is dim
. kind
and layout
determine the array element kind and the array layout
as described for Genarray.create
.
val dim: ('a, 'b, 'c) t > int
Return the size (dimension) of the given onedimensional
big array.
external get: ('a, 'b, 'c) t > int > 'a
Array1.get a x
, or alternatively a.{x}
,
returns the element of a
at index x
.
x
must be greater or equal than 0
and strictly less than
Array1.dim a
if a
has C layout. If a
has Fortran layout,
x
must be greater or equal than 1
and less or equal than
Array1.dim a
. Otherwise, Invalid_arg
is raised.
external set: ('a, 'b, 'c) t > int > 'a > unit
Array1.set a x v
, also written a.{x} < v
,
stores the value v
at index x
in a
.
x
must be inside the bounds of a
as described in Array1.get
;
otherwise, Invalid_arg
is raised.
external sub: ('a, 'b, 'c) t > pos:int > len:int > ('a, 'b, 'c) t
Extract a subarray of the given onedimensional big array.
See Genarray.sub_left
for more details.
external blit: src:('a, 'b, 'c) t > dst:('a, 'b, 'c) t > unit
Copy the first big array to the second big array.
See Genarray.blit
for more details.
external fill: ('a, 'b, 'c) t > 'a > unit
Fill the given big array with the given value.
See Genarray.fill
for more details.
val of_array:
kind:('a, 'b) kind > layout:'c layout > 'a array > ('a, 'b, 'c) t
Build a onedimensional big array initialized from the
given array.
val map_file: Unix.file_descr > kind:('a, 'b) kind > layout:'c layout >
shared:bool > dim:int > ('a, 'b, 'c) t
Memory mapping of a file as a onedimensional big array.
See Genarray.map_file
for more details.
end
The Array2
structure provides operations similar to those of
Genarray
, but specialized to the case of twodimensional arrays.
module Array2: sig
type ('a, 'b, 'c) t
The type of twodimensional big arrays whose elements have
Caml type 'a
, representation kind 'b
, and memory layout 'c
.
val create:
kind:('a, 'b) kind >
layout:'c layout > dim1:int > dim2:int > ('a, 'b, 'c) t
Array2.create kind layout dim1 dim2
returns a new bigarray of
two dimension, whose size is dim1
in the first dimension
and dim2
in the second dimension. kind
and layout
determine the array element kind and the array layout
as described for Genarray.create
.
val dim1: ('a, 'b, 'c) t > int
Return the first dimension of the given twodimensional
big array.
val dim2: ('a, 'b, 'c) t > int
Return the second dimension of the given twodimensional
big array.
external get: ('a, 'b, 'c) t > int > int > 'a
Array2.get a x y
, also written a.{x,y}
,
returns the element of a
at coordinates (x
, y
).
x
and y
must be within the bounds
of a
, as described for Genarray.get
; otherwise, Invalid_arg
is raised.
external set: ('a, 'b, 'c) t > int > int > 'a > unit
Array2.set a x y v
, or alternatively a.{x,y} < v
,
stores the value v
at coordinates (x
, y
) in a
.
x
and y
must be within the bounds of a
,
as described for Genarray.set
;
otherwise, Invalid_arg
is raised.
external sub_left:
('a, 'b, c_layout) t > pos:int > len:int > ('a, 'b, c_layout) t
Extract a twodimensional subarray of the given twodimensional
big array by restricting the first dimension.
See Genarray.sub_left
for more details. Array2.sub_left
applies only to arrays with C layout.
external sub_right:
('a, 'b, fortran_layout) t >
pos:int > len:int > ('a, 'b, fortran_layout) t
Extract a twodimensional subarray of the given twodimensional
big array by restricting the second dimension.
See Genarray.sub_right
for more details. Array2.sub_right
applies only to arrays with Fortran layout.
val slice_left:
('a, 'b, c_layout) t > x:int > ('a, 'b, c_layout) Array1.t
Extract a row (onedimensional slice) of the given twodimensional
big array. The integer parameter is the index of the row to
extract. See Genarray.slice_left
for more details.
Array2.slice_left
applies only to arrays with C layout.
val slice_right:
('a, 'b, fortran_layout) t > y:int > ('a, 'b, fortran_layout) Array1.t
Extract a column (onedimensional slice) of the given
twodimensional big array. The integer parameter is the
index of the column to extract. See Genarray.slice_right
for
more details. Array2.slice_right
applies only to arrays
with Fortran layout.
external blit: src:('a, 'b, 'c) t > dst:('a, 'b, 'c) t > unit
Copy the first big array to the second big array.
See Genarray.blit
for more details.
external fill: ('a, 'b, 'c) t > 'a > unit
Fill the given big array with the given value.
See Genarray.fill
for more details.
val of_array:
kind:('a, 'b) kind > layout:'c layout > 'a array array > ('a, 'b, 'c) t
Build a twodimensional big array initialized from the
given array of arrays.
val map_file: Unix.file_descr > kind:('a, 'b) kind > layout:'c layout >
shared:bool > dim1:int > dim2:int > ('a, 'b, 'c) t
Memory mapping of a file as a twodimensional big array.
See Genarray.map_file
for more details.
end
The Array3
structure provides operations similar to those of
Genarray
, but specialized to the case of threedimensional arrays.
module Array3: sig
type ('a, 'b, 'c) t
The type of threedimensional big arrays whose elements have
Caml type 'a
, representation kind 'b
, and memory layout 'c
.
val create:
kind:('a, 'b) kind > layout:'c layout >
dim1:int > dim2:int > dim3:int > ('a, 'b, 'c) t
Array3.create kind layout dim1 dim2 dim3
returns a new bigarray of
three dimension, whose size is dim1
in the first dimension,
dim2
in the second dimension, and dim3
in the third.
kind
and layout
determine the array element kind and
the array layout as described for Genarray.create
.
val dim1: ('a, 'b, 'c) t > int
Return the first dimension of the given threedimensional
big array.
val dim2: ('a, 'b, 'c) t > int
Return the second dimension of the given threedimensional
big array.
val dim3: ('a, 'b, 'c) t > int
Return the third dimension of the given threedimensional
big array.
external get: ('a, 'b, 'c) t > int > int > int > 'a
Array3.get a x y z
, also written a.{x,y,z}
,
returns the element of a
at coordinates (x
, y
, z
).
x
, y
and z
must be within the bounds of a
,
as described for Genarray.get
; otherwise, Invalid_arg
is raised.
external set: ('a, 'b, 'c) t > int > int > int > 'a > unit
Array3.set a x y v
, or alternatively a.{x,y,z} < v
,
stores the value v
at coordinates (x
, y
, z
) in a
.
x
, y
and z
must be within the bounds of a
,
as described for Genarray.set
;
otherwise, Invalid_arg
is raised.
external sub_left:
('a, 'b, c_layout) t > pos:int > len:int > ('a, 'b, c_layout) t
Extract a threedimensional subarray of the given
threedimensional big array by restricting the first dimension.
See Genarray.sub_left
for more details. Array3.sub_left
applies only to arrays with C layout.
external sub_right:
('a, 'b, fortran_layout) t >
pos:int > len:int > ('a, 'b, fortran_layout) t
Extract a threedimensional subarray of the given
threedimensional big array by restricting the second dimension.
See Genarray.sub_right
for more details. Array3.sub_right
applies only to arrays with Fortran layout.
val slice_left_1:
('a, 'b, c_layout) t > x:int > y:int > ('a, 'b, c_layout) Array1.t
Extract a onedimensional slice of the given threedimensional
big array by fixing the first two coordinates.
The integer parameters are the coordinates of the slice to
extract. See Genarray.slice_left
for more details.
Array3.slice_left_1
applies only to arrays with C layout.
val slice_right_1:
('a, 'b, fortran_layout) t > y:int > z:int >
('a, 'b, fortran_layout) Array1.t
Extract a onedimensional slice of the given threedimensional
big array by fixing the last two coordinates.
The integer parameters are the coordinates of the slice to
extract. See Genarray.slice_right
for more details.
Array3.slice_right_1
applies only to arrays with Fortran
layout.
val slice_left_2:
('a, 'b, c_layout) t > x:int > ('a, 'b, c_layout) Array2.t
Extract a twodimensional slice of the given threedimensional
big array by fixing the first coordinate.
The integer parameter is the first coordinate of the slice to
extract. See Genarray.slice_left
for more details.
Array3.slice_left_2
applies only to arrays with C layout.
val slice_right_2:
('a, 'b, fortran_layout) t > z:int > ('a, 'b, fortran_layout) Array2.t
Extract a twodimensional slice of the given
threedimensional big array by fixing the last coordinate.
The integer parameter is the coordinate of the slice
to extract. See Genarray.slice_right
for more details.
Array3.slice_right_2
applies only to arrays with Fortran
layout.
external blit: src:('a, 'b, 'c) t > dst:('a, 'b, 'c) t > unit
Copy the first big array to the second big array.
See Genarray.blit
for more details.
external fill: ('a, 'b, 'c) t > 'a > unit
Fill the given big array with the given value.
See Genarray.fill
for more details.
val of_array:
kind:('a, 'b) kind > layout:'c layout >
'a array array array > ('a, 'b, 'c) t
Build a threedimensional big array initialized from the
given array of arrays of arrays.
val map_file: Unix.file_descr > kind:('a, 'b) kind > layout:'c layout >
shared:bool > dim1:int > dim2:int > dim3:int > ('a, 'b, 'c) t
Memory mapping of a file as a threedimensional big array.
See Genarray.map_file
for more details.
end
Coercions between generic big arrays and fixeddimension big arrays 

val genarray_of_array1: ('a, 'b, 'c) Array1.t > ('a, 'b, 'c) Genarray.t
val genarray_of_array2: ('a, 'b, 'c) Array2.t > ('a, 'b, 'c) Genarray.t
val genarray_of_array3: ('a, 'b, 'c) Array3.t > ('a, 'b, 'c) Genarray.t
Return the generic big array corresponding to the given
onedimensional, twodimensional or threedimensional big array.
val array1_of_genarray: ('a, 'b, 'c) Genarray.t > ('a, 'b, 'c) Array1.t
Return the onedimensional big array corresponding to the given
generic big array. Raise Invalid_arg
if the generic big array
does not have exactly one dimension.
val array2_of_genarray: ('a, 'b, 'c) Genarray.t > ('a, 'b, 'c) Array2.t
Return the twodimensional big array corresponding to the given
generic big array. Raise Invalid_arg
if the generic big array
does not have exactly two dimensions.
val array3_of_genarray: ('a, 'b, 'c) Genarray.t > ('a, 'b, 'c) Array3.t
Return the threedimensional big array corresponding to the given
generic big array. Raise Invalid_arg
if the generic big array
does not have exactly three dimensions.
val reshape:
('a, 'b, 'c) Genarray.t > dims:int array > ('a, 'b, 'c) Genarray.t
reshape b [d1;...;dN]
converts the big array b
to a
N
dimensional array of dimensions d1
...dN
. The returned
array and the original array b
share their data
and have the same layout. For instance, assuming that b
is a onedimensional array of dimension 12, reshape b [3;4]
returns a twodimensional array b'
of dimensions 3 and 4.
If b
has C layout, the element (x,y)
of b'
corresponds
to the element x * 3 + y
of b
. If b
has Fortran layout,
the element (x,y)
of b'
corresponds to the element
x + (y  1) * 4
of b
.
The returned big array must have exactly the same number of
elements as the original big array b
. That is, the product
of the dimensions of b
must be equal to i1 * ... * iN
.
Otherwise, Invalid_arg
is raised.
val reshape_1:
('a, 'b, 'c) Genarray.t > dim:int > ('a, 'b, 'c) Array1.t
Specialized version of reshape
for reshaping to onedimensional
arrays.
val reshape_2:
('a, 'b, 'c) Genarray.t > dim1:int > dim2:int > ('a, 'b, 'c) Array2.t
Specialized version of reshape
for reshaping to twodimensional
arrays.
val reshape_3:
('a, 'b, 'c) Genarray.t > dim1:int > dim2:int > dim3:int >
('a, 'b, 'c) Array3.t
Specialized version of reshape
for reshaping to threedimensional
arrays.
28.2 
Big arrays in the CamlC interface 

C stub code that interface C or Fortran code with Caml code, as
described in chapter 17, can exploit big arrays as
follows.
The include file <caml/bigarray.h> must be included in the C stub
file. It declares the functions, constants and macros discussed
below.
28.2.2 
Accessing a Caml bigarray from C or Fortran 

If v is a Caml value representing a big array, the expression
Data_bigarray_val(v) returns a pointer to the data part of the array.
This pointer is of type void * and can be cast to the appropriate C
type for the array (e.g. double [], char [][10], etc).
Various characteristics of the Caml big array can be consulted from C
as follows:
C expression 
Returns 
Bigarray_val(v)>num_dims 
number of dimensions 
Bigarray_val(v)>dim[i[i] 
ith dimension 
Bigarray_val(v)>flags & BIGARRAY_KIND_MASK 
kind of array elements 
The kind of array elements is one of the following constants:
Constant 
Element kind 
BIGARRAY_FLOAT32 
32bit singleprecision floats 
BIGARRAY_FLOAT64 
64bit doubleprecision floats 
BIGARRAY_SINT8 
8bit signed integers 
BIGARRAY_UINT8 
8bit unsigned integers 
BIGARRAY_SINT16 
16bit signed integers 
BIGARRAY_UINT16 
16bit unsigned integers 
BIGARRAY_INT32 
32bit signed integers 
BIGARRAY_INT64 
64bit signed integers 
BIGARRAY_CAML_INT 
31 or 63bit signed integers 
BIGARRAY_NATIVE_INT 
32 or 64bit (platformnative) integers 
The following example shows the passing of a twodimensional big array
to a C function and a Fortran function.
extern void my_c_function(double * data, int dimx, int dimy);
extern void my_fortran_function_(double * data, int * dimx, int * dimy);
value caml_stub(value bigarray)
{
int dimx = Bigarray_val(bigarray)>dim[0];
int dimy = Bigarray_val(bigarray)>dim[1];
/* C passes scalar parameters by value */
my_c_function(Data_bigarray_val(bigarray), dimx, dimy);
/* Fortran passes all parameters by reference */
my_fortran_function_(Data_bigarray_val(bigarray), &dimx, &dimy);
return Val_unit;
}
28.2.3 
Wrapping a C or Fortran array as a Caml big array 

A pointer p to an alreadyallocated C or Fortran array can be
wrapped and returned to Caml as a big array using the alloc_bigarray
or alloc_bigarray_dims functions.

alloc_bigarray(kind  layout, numdims, p, dims)
Return a Caml big array wrapping the data pointed to by p.
kind is the kind of array elements (one of the BIGARRAY_
kind constants above). layout is BIGARRAY_C_LAYOUT for an
array with C layout and BIGARRAY_FORTRAN_LAYOUT for an array with
Fortran layout. numdims is the number of dimensions in the
array. dims is an array of numdims long integers, giving
the sizes of the array in each dimension.
 alloc_bigarray_dims(kind  layout, numdims,
p, (long) dim_{1}, (long) dim_{2}, ..., (long) dim_{numdims})
Same as alloc_bigarray, but the sizes of the array in each dimension
are listed as extra arguments in the function call, rather than being
passed as an array.
The following example illustrates how staticallyallocated C and
Fortran arrays can be made available to Caml.
extern long my_c_array[100][200];
extern float my_fortran_array_[300][400];
value caml_get_c_array(value unit)
{
long dims[2];
dims[0] = 100; dims[1] = 200;
return alloc_bigarray(BIGARRAY_NATIVEINT  BIGARRAY_C_LAYOUT,
2, my_c_array, dims);
}
value caml_get_fortran_array(value unit)
{
return alloc_bigarray_dims(BIGARRAY_FLOAT32  BIGARRAY_FORTRAN_LAYOUT,
2, my_fortran_array_, 300L, 400L);
}