## table of contents

- buster 4.05.0-11

Bigarray.Genarray(3o) | OCamldoc | Bigarray.Genarray(3o) |

# 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 0 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 0 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 change_layout* : **('a, 'b, 'c) t ->** **'d
Bigarray.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.

**Since** 4.04.0

*val size_in_bytes* : **('a, 'b, 'c) t -> int**

**size_in_bytes a** is the number of elements in **a**
multiplied by **a** 's **Bigarray.kind_size_in_bytes** .

**Since** 4.03.0

*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
shrunk.

This function raises **Sys_error** in the case of any errors
from the underlying system calls. **Invalid_argument** or **Failure**
may be raised in cases where argument validation fails.

source: | 2019-01-25 |