module Genarray:sig
..end
Generic arrays (of arbitrarily many dimensions)
type('a, 'b, 'c)
t =('a, 'b, 'c) Bigarray.Genarray.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:
'a
, is the OCaml type for accessing array
elements (float
, int
, int32
, int64
, nativeint
);'b
, is the actual kind of array elements
(float32_elt
, float64_elt
, int8_signed_elt
, int8_unsigned_elt
,
etc);'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 32-bit floats
in Fortran layout; reads and writes in this array use the
OCaml type float
.
val create : ('a, 'b) BatBigarray.kind ->
'c BatBigarray.layout -> 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 32-bit 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.
Invalid_argument
if the number of dimensions
is not in the range 1 to 16 inclusive, or if one of the dimensions
is negative.val num_dims : ('a, 'b, 'c) t -> int
Return the number of dimensions of the given big array.
val dims : ('a, 'b, 'c) t -> int array
Genarray.dims a
returns all dimensions of the big array a
,
as an array of integers of length Genarray.num_dims a
.
val 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
.
Invalid_argument
if n
is less than 0 or greater or equal than
Genarray.num_dims a
.val kind : ('a, 'b, 'c) t -> ('a, 'b) BatBigarray.kind
Return the kind of the given big array.
val layout : ('a, 'b, 'c) t -> 'c BatBigarray.layout
Return the layout of the given big array.
val change_layout : ('a, 'b, 'c) t ->
'd BatBigarray.layout -> ('a, 'b, 'd) t
Genarray.change_layout a layout
returns a bigarray with the
specified layout
, sharing the data with a
(and hence having
the same dimensions as a
). No copying of elements is involved: the
new array and the original array share the same storage space.
The dimensions are reversed, such that get v [| a; b |]
in
C layout becomes get v [| b+1; a+1 |]
in Fortran layout.
val size_in_bytes : ('a, 'b, 'c) t -> int
size_in_bytes a
is the number of elements in a
multiplied
by a
's BatBigarray.kind_size_in_bytes
.
val 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
.
Invalid_argument
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 three-dimensional arrays
as described below.)val 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
;
Invalid_argument
otherwise.
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 three-dimensional arrays
as described below.)val sub_left : ('a, 'b, BatBigarray.c_layout) t ->
int -> int -> ('a, 'b, BatBigarray.c_layout) t
Extract a sub-array of the given big array by restricting the
first (left-most) 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 sub-array and the original array share the same
storage space. In other terms, the element at coordinates
[|i1; ...; iN|]
of the sub-array 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.
Invalid_argument
if ofs
and len
do not designate
a valid sub-array of a
, that is, if ofs < 0
, or len < 0
,
or ofs + len > Genarray.nth_dim a 0
.val sub_right : ('a, 'b, BatBigarray.fortran_layout) t ->
int -> int -> ('a, 'b, BatBigarray.fortran_layout) t
Extract a sub-array of the given big array by restricting the
last (right-most) 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 sub-array and the original array share the same
storage space. In other terms, the element at coordinates
[|i1; ...; iN|]
of the sub-array 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.
Invalid_argument
if ofs
and len
do not designate
a valid sub-array of a
, that is, if ofs < 1
, or len < 0
,
or ofs + len > Genarray.nth_dim a (Genarray.num_dims a - 1)
.val slice_left : ('a, 'b, BatBigarray.c_layout) t ->
int array -> ('a, 'b, BatBigarray.c_layout) t
Extract a sub-array of lower dimension from the given big array
by fixing one or several of the first (left-most) 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(N-M)|]
in the slice is identical to the element
at coordinates [|i1; ...; iM; j1; ...; j(N-M)|]
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.
Invalid_argument
if M >= N
, or if [|i1; ... ; iM|]
is outside the bounds of a
.val slice_right : ('a, 'b, BatBigarray.fortran_layout) t ->
int array -> ('a, 'b, BatBigarray.fortran_layout) t
Extract a sub-array of lower dimension from the given big array
by fixing one or several of the last (right-most) 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(N-M)|]
in the slice is identical to the element
at coordinates [|j1; ...; j(N-M); 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.
Invalid_argument
if M >= N
, or if [|i1; ... ; iM|]
is outside the bounds of a
.val blit : ('a, 'b, 'c) t ->
('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 sub-array of src
to a sub-array of dst
can be achieved by applying Genarray.blit
to sub-array or slices of src
and dst
.
val 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 sub-array
or a slice of a
.
val map_file : Unix.file_descr ->
?pos:int64 ->
('a, 'b) BatBigarray.kind ->
'c BatBigarray.layout ->
bool -> 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). The optional pos
parameter
is the byte offset in the file of the data being mapped;
it default to 0 (map from the beginning of the file).
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
copy-on-write 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 sub-arrays as determined by the non-major dimensions,
Failure
otherwise.
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
.val iter : ('a -> unit) -> ('a, 'b, 'c) t -> unit
iter f a
applies function f
in turn to all
the elements of a
.
val iteri : ((int, [ `Read ]) BatArray.Cap.t -> 'a -> unit) ->
('a, 'b, 'c) t -> unit
Same as BatBigarray.Genarray.iter
, but the function is applied to the index of
the element as the first argument, and the element itself as
the second argument.
val modify : ('a -> 'a) -> ('a, 'b, 'c) t -> unit
modify f a
changes each element x
in a
to f x
in-place.
val modifyi : ((int, [ `Read ]) BatArray.Cap.t -> 'a -> 'a) ->
('a, 'b, 'c) t -> unit
Same as BatBigarray.Genarray.modify
, but the function is applied to the index of
the coordinates as the first argument, and the element itself
as the second argument.
val enum : ('a, 'b, 'c) t -> 'a BatEnum.t
enum e
returns an enumeration on the elements of e
.
The order of enumeration is unspecified.
val map : ('a -> 'b) ->
('b, 'c) Bigarray.kind ->
('a, 'd, 'e) t -> ('b, 'c, 'e) t
map f kind a
applies function f
to all the elements of a
,
and builds a Bigarray.t
of kind kind
with the results
returned by f
.
val mapi : ((int, [ `Read ]) BatArray.Cap.t -> 'a -> 'b) ->
('b, 'c) Bigarray.kind ->
('a, 'd, 'e) t -> ('b, 'c, 'e) t
Same as BatBigarray.Genarray.map
, but the function is applied to the index of the
coordinates as the first argument, and the element itself as the
second argument.