.TH "ArrayLabels" 3o source: 2019-01-25 OCamldoc "OCaml library"
.SH NAME
ArrayLabels \- Array operations.
.SH Module
Module   ArrayLabels
.SH Documentation
.sp
Module
.BI "ArrayLabels"
 : 
.B sig  end

.sp
Array operations\&.

.sp

.sp
.sp

.I val length 
: 
.B 'a array -> int
.sp
Return the length (number of elements) of the given array\&.

.sp

.I val get 
: 
.B 'a array -> int -> 'a
.sp

.B Array\&.get a n
returns the element number 
.B n
of array 
.B a
\&.
The first element has number 0\&.
The last element has number 
.B Array\&.length a \- 1
\&.
You can also write 
.B a\&.(n)
instead of 
.B Array\&.get a n
\&.
.sp
Raise 
.B Invalid_argument "index out of bounds"
if 
.B n
is outside the range 0 to 
.B (Array\&.length a \- 1)
\&.

.sp

.I val set 
: 
.B 'a array -> int -> 'a -> unit
.sp

.B Array\&.set a n x
modifies array 
.B a
in place, replacing
element number 
.B n
with 
.B x
\&.
You can also write 
.B a\&.(n) <\- x
instead of 
.B Array\&.set a n x
\&.
.sp
Raise 
.B Invalid_argument "index out of bounds"
if 
.B n
is outside the range 0 to 
.B Array\&.length a \- 1
\&.

.sp

.I val make 
: 
.B int -> 'a -> 'a array
.sp

.B Array\&.make n x
returns a fresh array of length 
.B n
,
initialized with 
.B x
\&.
All the elements of this new array are initially
physically equal to 
.B x
(in the sense of the 
.B ==
predicate)\&.
Consequently, if 
.B x
is mutable, it is shared among all elements
of the array, and modifying 
.B x
through one of the array entries
will modify all other entries at the same time\&.
.sp
Raise 
.B Invalid_argument
if 
.B n < 0
or 
.B n > Sys\&.max_array_length
\&.
If the value of 
.B x
is a floating\-point number, then the maximum
size is only 
.B Sys\&.max_array_length / 2
\&.

.sp

.I val create 
: 
.B int -> 'a -> 'a array
.sp
.B "Deprecated."

.B Array\&.create
is an alias for 
.B Array\&.make
\&.

.sp

.I val init 
: 
.B int -> f:(int -> 'a) -> 'a array
.sp

.B Array\&.init n f
returns a fresh array of length 
.B n
,
with element number 
.B i
initialized to the result of 
.B f i
\&.
In other terms, 
.B Array\&.init n f
tabulates the results of 
.B f
applied to the integers 
.B 0
to 
.B n\-1
\&.
.sp
Raise 
.B Invalid_argument
if 
.B n < 0
or 
.B n > Sys\&.max_array_length
\&.
If the return type of 
.B f
is 
.B float
, then the maximum
size is only 
.B Sys\&.max_array_length / 2
\&.

.sp

.I val make_matrix 
: 
.B dimx:int -> dimy:int -> 'a -> 'a array array
.sp

.B Array\&.make_matrix dimx dimy e
returns a two\-dimensional array
(an array of arrays) with first dimension 
.B dimx
and
second dimension 
.B dimy
\&. All the elements of this new matrix
are initially physically equal to 
.B e
\&.
The element (
.B x,y
) of a matrix 
.B m
is accessed
with the notation 
.B m\&.(x)\&.(y)
\&.
.sp
Raise 
.B Invalid_argument
if 
.B dimx
or 
.B dimy
is negative or
greater than 
.B Sys\&.max_array_length
\&.
If the value of 
.B e
is a floating\-point number, then the maximum
size is only 
.B Sys\&.max_array_length / 2
\&.

.sp

.I val create_matrix 
: 
.B dimx:int -> dimy:int -> 'a -> 'a array array
.sp
.B "Deprecated."

.B Array\&.create_matrix
is an alias for
.B Array\&.make_matrix
\&.

.sp

.I val append 
: 
.B 'a array -> 'a array -> 'a array
.sp

.B Array\&.append v1 v2
returns a fresh array containing the
concatenation of the arrays 
.B v1
and 
.B v2
\&.

.sp

.I val concat 
: 
.B 'a array list -> 'a array
.sp
Same as 
.B Array\&.append
, but concatenates a list of arrays\&.

.sp

.I val sub 
: 
.B 'a array -> pos:int -> len:int -> 'a array
.sp

.B Array\&.sub a start len
returns a fresh array of length 
.B len
,
containing the elements number 
.B start
to 
.B start + len \- 1
of array 
.B a
\&.
.sp
Raise 
.B Invalid_argument "Array\&.sub"
if 
.B start
and 
.B len
do not
designate a valid subarray of 
.B a
; that is, if
.B start < 0
, or 
.B len < 0
, or 
.B start + len > Array\&.length a
\&.

.sp

.I val copy 
: 
.B 'a array -> 'a array
.sp

.B Array\&.copy a
returns a copy of 
.B a
, that is, a fresh array
containing the same elements as 
.B a
\&.

.sp

.I val fill 
: 
.B 'a array -> pos:int -> len:int -> 'a -> unit
.sp

.B Array\&.fill a ofs len x
modifies the array 
.B a
in place,
storing 
.B x
in elements number 
.B ofs
to 
.B ofs + len \- 1
\&.
.sp
Raise 
.B Invalid_argument "Array\&.fill"
if 
.B ofs
and 
.B len
do not
designate a valid subarray of 
.B a
\&.

.sp

.I val blit 
: 
.B src:'a array -> src_pos:int -> dst:'a array -> dst_pos:int -> len:int -> unit
.sp

.B Array\&.blit v1 o1 v2 o2 len
copies 
.B len
elements
from array 
.B v1
, starting at element number 
.B o1
, to array 
.B v2
,
starting at element number 
.B o2
\&. It works correctly even if
.B v1
and 
.B v2
are the same array, and the source and
destination chunks overlap\&.
.sp
Raise 
.B Invalid_argument "Array\&.blit"
if 
.B o1
and 
.B len
do not
designate a valid subarray of 
.B v1
, or if 
.B o2
and 
.B len
do not
designate a valid subarray of 
.B v2
\&.

.sp

.I val to_list 
: 
.B 'a array -> 'a list
.sp

.B Array\&.to_list a
returns the list of all the elements of 
.B a
\&.

.sp

.I val of_list 
: 
.B 'a list -> 'a array
.sp

.B Array\&.of_list l
returns a fresh array containing the elements
of 
.B l
\&.

.sp

.I val iter 
: 
.B f:('a -> unit) -> 'a array -> unit
.sp

.B Array\&.iter f a
applies function 
.B f
in turn to all
the elements of 
.B a
\&.  It is equivalent to
.B f a\&.(0); f a\&.(1); \&.\&.\&.; f a\&.(Array\&.length a \- 1); ()
\&.

.sp

.I val map 
: 
.B f:('a -> 'b) -> 'a array -> 'b array
.sp

.B Array\&.map f a
applies function 
.B f
to all the elements of 
.B a
,
and builds an array with the results returned by 
.B f
:
.B [| f a\&.(0); f a\&.(1); \&.\&.\&.; f a\&.(Array\&.length a \- 1) |]
\&.

.sp

.I val iteri 
: 
.B f:(int -> 'a -> unit) -> 'a array -> unit
.sp
Same as 
.B Array\&.iter
, but the
function is applied to the index of the element as first argument,
and the element itself as second argument\&.

.sp

.I val mapi 
: 
.B f:(int -> 'a -> 'b) -> 'a array -> 'b array
.sp
Same as 
.B Array\&.map
, but the
function is applied to the index of the element as first argument,
and the element itself as second argument\&.

.sp

.I val fold_left 
: 
.B f:('a -> 'b -> 'a) -> init:'a -> 'b array -> 'a
.sp

.B Array\&.fold_left f x a
computes
.B f (\&.\&.\&. (f (f x a\&.(0)) a\&.(1)) \&.\&.\&.) a\&.(n\-1)
,
where 
.B n
is the length of the array 
.B a
\&.

.sp

.I val fold_right 
: 
.B f:('b -> 'a -> 'a) -> 'b array -> init:'a -> 'a
.sp

.B Array\&.fold_right f a x
computes
.B f a\&.(0) (f a\&.(1) ( \&.\&.\&. (f a\&.(n\-1) x) \&.\&.\&.))
,
where 
.B n
is the length of the array 
.B a
\&.

.sp

.PP

.B === 
.B Iterators on two arrays
.B  ===

.PP

.I val iter2 
: 
.B f:('a -> 'b -> unit) -> 'a array -> 'b array -> unit
.sp

.B Array\&.iter2 f a b
applies function 
.B f
to all the elements of 
.B a
and 
.B b
\&.
Raise 
.B Invalid_argument
if the arrays are not the same size\&.

.sp
.B "Since"
4.05.0

.sp

.I val map2 
: 
.B f:('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array
.sp

.B Array\&.map2 f a b
applies function 
.B f
to all the elements of 
.B a
and 
.B b
, and builds an array with the results returned by 
.B f
:
.B [| f a\&.(0) b\&.(0); \&.\&.\&.; f a\&.(Array\&.length a \- 1) b\&.(Array\&.length b \- 1)|]
\&.
Raise 
.B Invalid_argument
if the arrays are not the same size\&.

.sp
.B "Since"
4.05.0

.sp

.PP

.B === 
.B Array scanning
.B  ===

.PP

.I val exists 
: 
.B f:('a -> bool) -> 'a array -> bool
.sp

.B Array\&.exists p [|a1; \&.\&.\&.; an|]
checks if at least one element of
the array satisfies the predicate 
.B p
\&. That is, it returns
.B (p a1) || (p a2) || \&.\&.\&. || (p an)
\&.

.sp
.B "Since"
4.03.0

.sp

.I val for_all 
: 
.B f:('a -> bool) -> 'a array -> bool
.sp

.B Array\&.for_all p [|a1; \&.\&.\&.; an|]
checks if all elements of the array
satisfy the predicate 
.B p
\&. That is, it returns
.B (p a1) && (p a2) && \&.\&.\&. && (p an)
\&.

.sp
.B "Since"
4.03.0

.sp

.I val mem 
: 
.B 'a -> set:'a array -> bool
.sp

.B mem x a
is true if and only if 
.B x
is equal
to an element of 
.B a
\&.

.sp
.B "Since"
4.03.0

.sp

.I val memq 
: 
.B 'a -> set:'a array -> bool
.sp
Same as 
.B Array\&.mem
, but uses physical equality instead of structural
equality to compare list elements\&.

.sp
.B "Since"
4.03.0

.sp

.I val create_float 
: 
.B int -> float array
.sp

.B Array\&.create_float n
returns a fresh float array of length 
.B n
,
with uninitialized data\&.

.sp
.B "Since"
4.03

.sp

.I val make_float 
: 
.B int -> float array
.sp
.B "Deprecated."

.B Array\&.make_float
is an alias for
.B Array\&.create_float
\&.

.sp

.PP

.B === 
.B Sorting
.B  ===

.PP

.I val sort 
: 
.B cmp:('a -> 'a -> int) -> 'a array -> unit
.sp
Sort an array in increasing order according to a comparison
function\&.  The comparison function must return 0 if its arguments
compare as equal, a positive integer if the first is greater,
and a negative integer if the first is smaller (see below for a
complete specification)\&.  For example, 
.B Pervasives\&.compare
is
a suitable comparison function, provided there are no floating\-point
NaN values in the data\&.  After calling 
.B Array\&.sort
, the
array is sorted in place in increasing order\&.
.B Array\&.sort
is guaranteed to run in constant heap space
and (at most) logarithmic stack space\&.
.sp
The current implementation uses Heap Sort\&.  It runs in constant
stack space\&.
.sp
Specification of the comparison function:
Let 
.B a
be the array and 
.B cmp
the comparison function\&.  The following
must be true for all x, y, z in a :
.sp
\-  
.B cmp x y
> 0 if and only if 
.B cmp y x
< 0
.sp
\-  if 
.B cmp x y
>= 0 and 
.B cmp y z
>= 0 then 
.B cmp x z
>= 0

When 
.B Array\&.sort
returns, 
.B a
contains the same elements as before,
reordered in such a way that for all i and j valid indices of 
.B a
:
.sp
\-  
.B cmp a\&.(i) a\&.(j)
>= 0 if and only if i >= j


.sp

.I val stable_sort 
: 
.B cmp:('a -> 'a -> int) -> 'a array -> unit
.sp
Same as 
.B Array\&.sort
, but the sorting algorithm is stable (i\&.e\&.
elements that compare equal are kept in their original order) and
not guaranteed to run in constant heap space\&.
.sp
The current implementation uses Merge Sort\&. It uses 
.B n/2
words of heap space, where 
.B n
is the length of the array\&.
It is usually faster than the current implementation of 
.B Array\&.sort
\&.

.sp

.I val fast_sort 
: 
.B cmp:('a -> 'a -> int) -> 'a array -> unit
.sp
Same as 
.B Array\&.sort
or 
.B Array\&.stable_sort
, whichever is
faster on typical input\&.

.sp