NAME¶
Bigarray.Genarray - no description
Module¶
Module Bigarray.Genarray
Documentation¶
Module
Genarray
:
sig end
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 OCaml 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 32-bit floats in Fortran layout; reads and
writes in this array use the OCaml type
float .
val create :
('a, 'b) Bigarray.kind -> 'c Bigarray.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.
Genarray.create raises
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 . Raise
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) Bigarray.kind
Return the kind of the given big array.
val layout :
('a, 'b, 'c) t -> 'c Bigarray.layout
Return the layout of the given big array.
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 . Raise
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 ;
otherwise,
Invalid_argument 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 three-dimensional arrays as described below.)
val sub_left :
('a, 'b, Bigarray.c_layout) t -> int ->
int -> ('a, 'b, Bigarray.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. Raise
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, Bigarray.fortran_layout) t -> int
-> int -> ('a, 'b, Bigarray.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. Raise
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, Bigarray.c_layout) t -> int array
-> ('a, 'b, Bigarray.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. Raise
Invalid_argument if
M >= N , or if
[|i1; ... ; iM|] is
outside the bounds of
a .
val slice_right :
('a, 'b, Bigarray.fortran_layout) t -> int
array -> ('a, 'b, Bigarray.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. Raise
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) Bigarray.kind -> 'c Bigarray.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 defaults 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, 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 .
Array accesses are bounds-checked, but the bounds are determined by the initial
call to
map_file . Therefore, you should make sure no other process
modifies the mapped file while you're accessing it, or a SIGBUS signal may be
raised. This happens, for instance, if the file is shrinked.