.TH "Bigarray.Genarray" 3o source: 2019-01-25 OCamldoc "OCaml library"
.SH NAME
Bigarray.Genarray \- no description
.SH Module
Module   Bigarray.Genarray
.SH Documentation
.sp
Module
.BI "Genarray"
 : 
.B sig  end

.sp

.sp

.sp
.sp
.I type 
.B ('a, 'b, 'c)
.I t 

.sp
The type 
.B Genarray\&.t
is the type of big arrays with variable
numbers of dimensions\&.  Any number of dimensions between 0 and 16
is supported\&.
.sp
The three type parameters to 
.B Genarray\&.t
identify the array element
kind and layout, as follows:
.sp
\-the first parameter, 
.B \&'a
, is the OCaml type for accessing array
elements (
.B float
, 
.B int
, 
.B int32
, 
.B int64
, 
.B nativeint
);
.sp
\-the second parameter, 
.B \&'b
, is the actual kind of array elements
(
.B float32_elt
, 
.B float64_elt
, 
.B int8_signed_elt
, 
.B int8_unsigned_elt
,
etc);
.sp
\-the third parameter, 
.B \&'c
, identifies the array layout
(
.B c_layout
or 
.B fortran_layout
)\&.

For instance, 
.B (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 
.B float
\&.

.sp

.I val create 
: 
.B ('a, 'b) Bigarray.kind ->
.B   'c Bigarray.layout -> int array -> ('a, 'b, 'c) t
.sp

.B Genarray\&.create kind layout dimensions
returns a new big array
whose element kind is determined by the parameter 
.B kind
(one of
.B float32
, 
.B float64
, 
.B int8_signed
, etc) and whose layout is
determined by the parameter 
.B layout
(one of 
.B c_layout
or
.B fortran_layout
)\&.  The 
.B dimensions
parameter is an array of
integers that indicate the size of the big array in each dimension\&.
The length of 
.B dimensions
determines the number of dimensions
of the bigarray\&.
.sp
For instance, 
.B 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\&.
.sp
Big arrays returned by 
.B Genarray\&.create
are not initialized:
the initial values of array elements is unspecified\&.
.sp

.B Genarray\&.create
raises 
.B Invalid_argument
if the number of dimensions
is not in the range 0 to 16 inclusive, or if one of the dimensions
is negative\&.

.sp

.I val num_dims 
: 
.B ('a, 'b, 'c) t -> int
.sp
Return the number of dimensions of the given big array\&.

.sp

.I val dims 
: 
.B ('a, 'b, 'c) t -> int array
.sp

.B Genarray\&.dims a
returns all dimensions of the big array 
.B a
,
as an array of integers of length 
.B Genarray\&.num_dims a
\&.

.sp

.I val nth_dim 
: 
.B ('a, 'b, 'c) t -> int -> int
.sp

.B Genarray\&.nth_dim a n
returns the 
.B n
\-th dimension of the
big array 
.B a
\&.  The first dimension corresponds to 
.B n = 0
;
the second dimension corresponds to 
.B n = 1
; the last dimension,
to 
.B n = Genarray\&.num_dims a \- 1
\&.
Raise 
.B Invalid_argument
if 
.B n
is less than 0 or greater or equal than
.B Genarray\&.num_dims a
\&.

.sp

.I val kind 
: 
.B ('a, 'b, 'c) t -> ('a, 'b) Bigarray.kind
.sp
Return the kind of the given big array\&.

.sp

.I val layout 
: 
.B ('a, 'b, 'c) t -> 'c Bigarray.layout
.sp
Return the layout of the given big array\&.

.sp

.I val change_layout 
: 
.B ('a, 'b, 'c) t ->
.B   'd Bigarray.layout -> ('a, 'b, 'd) t
.sp

.B Genarray\&.change_layout a layout
returns a bigarray with the
specified 
.B layout
, sharing the data with 
.B a
(and hence having
the same dimensions as 
.B 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 
.B get v [| a; b |]
in
C layout becomes 
.B get v [| b+1; a+1 |]
in Fortran layout\&.

.sp
.B "Since"
4.04.0

.sp

.I val size_in_bytes 
: 
.B ('a, 'b, 'c) t -> int
.sp

.B size_in_bytes a
is the number of elements in 
.B a
multiplied
by 
.B a
\&'s 
.B Bigarray\&.kind_size_in_bytes
\&.

.sp
.B "Since"
4.03.0

.sp

.I val get 
: 
.B ('a, 'b, 'c) t -> int array -> 'a
.sp
Read an element of a generic big array\&.
.B Genarray\&.get a [|i1; \&.\&.\&.; iN|]
returns the element of 
.B a
whose coordinates are 
.B i1
in the first dimension, 
.B i2
in
the second dimension, \&.\&.\&., 
.B iN
in the 
.B N
\-th dimension\&.
.sp
If 
.B a
has C layout, the coordinates must be greater or equal than 0
and strictly less than the corresponding dimensions of 
.B a
\&.
If 
.B a
has Fortran layout, the coordinates must be greater or equal
than 1 and less or equal than the corresponding dimensions of 
.B a
\&.
Raise 
.B Invalid_argument
if the array 
.B a
does not have exactly 
.B N
dimensions, or if the coordinates are outside the array bounds\&.
.sp
If 
.B N > 3
, alternate syntax is provided: you can write
.B a\&.{i1, i2, \&.\&.\&., iN}
instead of 
.B Genarray\&.get a [|i1; \&.\&.\&.; iN|]
\&.
(The syntax 
.B a\&.{\&.\&.\&.}
with one, two or three coordinates is
reserved for accessing one\-, two\- and three\-dimensional arrays
as described below\&.)

.sp

.I val set 
: 
.B ('a, 'b, 'c) t -> int array -> 'a -> unit
.sp
Assign an element of a generic big array\&.
.B Genarray\&.set a [|i1; \&.\&.\&.; iN|] v
stores the value 
.B v
in the
element of 
.B a
whose coordinates are 
.B i1
in the first dimension,
.B i2
in the second dimension, \&.\&.\&., 
.B iN
in the 
.B N
\-th dimension\&.
.sp
The array 
.B a
must have exactly 
.B N
dimensions, and all coordinates
must lie inside the array bounds, as described for 
.B Genarray\&.get
;
otherwise, 
.B Invalid_argument
is raised\&.
.sp
If 
.B N > 3
, alternate syntax is provided: you can write
.B a\&.{i1, i2, \&.\&.\&., iN} <\- v
instead of
.B Genarray\&.set a [|i1; \&.\&.\&.; iN|] v
\&.
(The syntax 
.B a\&.{\&.\&.\&.} <\- v
with one, two or three coordinates is
reserved for updating one\-, two\- and three\-dimensional arrays
as described below\&.)

.sp

.I val sub_left 
: 
.B ('a, 'b, Bigarray.c_layout) t ->
.B   int -> int -> ('a, 'b, Bigarray.c_layout) t
.sp
Extract a sub\-array of the given big array by restricting the
first (left\-most) dimension\&.  
.B Genarray\&.sub_left a ofs len
returns a big array with the same number of dimensions as 
.B a
,
and the same dimensions as 
.B a
, except the first dimension,
which corresponds to the interval 
.B [ofs \&.\&.\&. ofs + len \- 1]
of the first dimension of 
.B 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
.B [|i1; \&.\&.\&.; iN|]
of the sub\-array is identical to the
element at coordinates 
.B [|i1+ofs; \&.\&.\&.; iN|]
of the original
array 
.B a
\&.
.sp

.B Genarray\&.sub_left
applies only to big arrays in C layout\&.
Raise 
.B Invalid_argument
if 
.B ofs
and 
.B len
do not designate
a valid sub\-array of 
.B a
, that is, if 
.B ofs < 0
, or 
.B len < 0
,
or 
.B ofs + len > Genarray\&.nth_dim a 0
\&.

.sp

.I val sub_right 
: 
.B ('a, 'b, Bigarray.fortran_layout) t ->
.B   int -> int -> ('a, 'b, Bigarray.fortran_layout) t
.sp
Extract a sub\-array of the given big array by restricting the
last (right\-most) dimension\&.  
.B Genarray\&.sub_right a ofs len
returns a big array with the same number of dimensions as 
.B a
,
and the same dimensions as 
.B a
, except the last dimension,
which corresponds to the interval 
.B [ofs \&.\&.\&. ofs + len \- 1]
of the last dimension of 
.B 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
.B [|i1; \&.\&.\&.; iN|]
of the sub\-array is identical to the
element at coordinates 
.B [|i1; \&.\&.\&.; iN+ofs|]
of the original
array 
.B a
\&.
.sp

.B Genarray\&.sub_right
applies only to big arrays in Fortran layout\&.
Raise 
.B Invalid_argument
if 
.B ofs
and 
.B len
do not designate
a valid sub\-array of 
.B a
, that is, if 
.B ofs < 1
, or 
.B len < 0
,
or 
.B ofs + len > Genarray\&.nth_dim a (Genarray\&.num_dims a \- 1)
\&.

.sp

.I val slice_left 
: 
.B ('a, 'b, Bigarray.c_layout) t ->
.B   int array -> ('a, 'b, Bigarray.c_layout) t
.sp
Extract a sub\-array of lower dimension from the given big array
by fixing one or several of the first (left\-most) coordinates\&.
.B Genarray\&.slice_left a [|i1; \&.\&.\&. ; iM|]
returns the \&'slice\&'
of 
.B a
obtained by setting the first 
.B M
coordinates to
.B i1
, \&.\&.\&., 
.B iM
\&.  If 
.B a
has 
.B N
dimensions, the slice has
dimension 
.B N \- M
, and the element at coordinates
.B [|j1; \&.\&.\&.; j(N\-M)|]
in the slice is identical to the element
at coordinates 
.B [|i1; \&.\&.\&.; iM; j1; \&.\&.\&.; j(N\-M)|]
in the original
array 
.B a
\&.  No copying of elements is involved: the slice and
the original array share the same storage space\&.
.sp

.B Genarray\&.slice_left
applies only to big arrays in C layout\&.
Raise 
.B Invalid_argument
if 
.B M >= N
, or if 
.B [|i1; \&.\&.\&. ; iM|]
is outside the bounds of 
.B a
\&.

.sp

.I val slice_right 
: 
.B ('a, 'b, Bigarray.fortran_layout) t ->
.B   int array -> ('a, 'b, Bigarray.fortran_layout) t
.sp
Extract a sub\-array of lower dimension from the given big array
by fixing one or several of the last (right\-most) coordinates\&.
.B Genarray\&.slice_right a [|i1; \&.\&.\&. ; iM|]
returns the \&'slice\&'
of 
.B a
obtained by setting the last 
.B M
coordinates to
.B i1
, \&.\&.\&., 
.B iM
\&.  If 
.B a
has 
.B N
dimensions, the slice has
dimension 
.B N \- M
, and the element at coordinates
.B [|j1; \&.\&.\&.; j(N\-M)|]
in the slice is identical to the element
at coordinates 
.B [|j1; \&.\&.\&.; j(N\-M); i1; \&.\&.\&.; iM|]
in the original
array 
.B a
\&.  No copying of elements is involved: the slice and
the original array share the same storage space\&.
.sp

.B Genarray\&.slice_right
applies only to big arrays in Fortran layout\&.
Raise 
.B Invalid_argument
if 
.B M >= N
, or if 
.B [|i1; \&.\&.\&. ; iM|]
is outside the bounds of 
.B a
\&.

.sp

.I val blit 
: 
.B ('a, 'b, 'c) t -> ('a, 'b, 'c) t -> unit
.sp
Copy all elements of a big array in another big array\&.
.B Genarray\&.blit src dst
copies all elements of 
.B src
into
.B dst
\&.  Both arrays 
.B src
and 
.B dst
must have the same number of
dimensions and equal dimensions\&.  Copying a sub\-array of 
.B src
to a sub\-array of 
.B dst
can be achieved by applying 
.B Genarray\&.blit
to sub\-array or slices of 
.B src
and 
.B dst
\&.

.sp

.I val fill 
: 
.B ('a, 'b, 'c) t -> 'a -> unit
.sp
Set all elements of a big array to a given value\&.
.B Genarray\&.fill a v
stores the value 
.B v
in all elements of
the big array 
.B a
\&.  Setting only some elements of 
.B a
to 
.B v
can be achieved by applying 
.B Genarray\&.fill
to a sub\-array
or a slice of 
.B a
\&.

.sp

.I val map_file 
: 
.B Unix.file_descr ->
.B   ?pos:int64 ->
.B   ('a, 'b) Bigarray.kind ->
.B   'c Bigarray.layout -> bool -> int array -> ('a, 'b, 'c) t
.sp
Memory mapping of a file as a big array\&.
.B Genarray\&.map_file fd kind layout shared dims
returns a big array of kind 
.B kind
, layout 
.B layout
,
and dimensions as specified in 
.B dims
\&.  The data contained in
this big array are the contents of the file referred to by
the file descriptor 
.B fd
(as opened previously with
.B Unix\&.openfile
, for example)\&.  The optional 
.B 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)\&.
.sp
If 
.B shared
is 
.B true
, all modifications performed on the array
are reflected in the file\&.  This requires that 
.B fd
be opened
with write permissions\&.  If 
.B shared
is 
.B 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\&.
.sp

.B Genarray\&.map_file
is much more efficient than reading
the whole file in a big array, modifying that big array,
and writing it afterwards\&.
.sp
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
.B \-1
\&.  
.B 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 
.B Failure
is raised\&.
.sp
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 
.B fd
\&.
.sp
Array accesses are bounds\-checked, but the bounds are determined by
the initial call to 
.B 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 shrunk\&.
.sp
This function raises 
.B Sys_error
in the case of any errors from the
underlying system calls\&.  
.B Invalid_argument
or 
.B Failure
may be
raised in cases where argument validation fails\&.

.sp