Module BatBigarray.Genarray

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:

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.

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.

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.

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;

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.

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.

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.

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.

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,

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.