module BatArray:sig..end
Arrays are mutable data structures with a fixed size, which support fast access and modification, and are used pervasively in imperative computing. While arrays are completely supported in OCaml, it is often a good idea to investigate persistent alternatives, such as lists or hash maps.
This module replaces Stdlib's Array module.
A variant of arrays, arrays with capabilities, is provided in
module BatArray.Cap. This notion of capabilities permit the
transformation of a mutable array into a read-only or a write-only
arrays, without loss of speed and with the possibility of
distributing different capabilities to different expressions.
Author(s): Xavier Leroy, Richard W.M. Jones, David Teller
type'at ='a array
include BatEnum.Enumerable
include BatInterfaces.Mappable
val length : 'a array -> intval get : 'a array -> int -> 'aArray.get a n returns the element number n of array a.
The first element has number 0.
The last element has number Array.length a - 1.
You can also write a.(n) instead of Array.get a n.Invalid_argument if n is outside the range 0 to (Array.length a - 1).val set : 'a array -> int -> 'a -> unitArray.set a n x modifies array a in place, replacing
element number n with x.
You can also write a.(n) <- x instead of Array.set a n x.Invalid_argument if n is outside the range 0 to Array.length a - 1.val make : int -> 'a -> 'a arrayArray.make n x returns a fresh array of length n,
initialized with x.
All the elements of this new array are initially
physically equal to x (in the sense of the == predicate).
Consequently, if x is mutable, it is shared among all elements
of the array, and modifying x through one of the array entries
will modify all other entries at the same time.Invalid_argument if n < 0 or n > Sys.max_array_length.
If the value of x is a floating-point number, then the maximum
size is only Sys.max_array_length / 2.val create_float : int -> float array
val make_float : int -> float arrayArray.make_float n returns a fresh float array of length n,
with uninitialized data.val create : int -> 'a -> 'a arrayArray.create is an alias for Array.make.val init : int -> (int -> 'a) -> 'a arrayArray.init n f returns a fresh array of length n,
with element number i initialized to the result of f i.
In other terms, Array.init n f tabulates the results of f
applied to the integers 0 to n-1.Invalid_argument if n < 0 or n > Sys.max_array_length.
If the return type of f is float, then the maximum
size is only Sys.max_array_length / 2.val make_matrix : int -> int -> 'a -> 'a array arrayArray.make_matrix dimx dimy e returns a two-dimensional array
(an array of arrays) with first dimension dimx and
second dimension dimy. All the elements of this new matrix
are initially physically equal to e.
The element (x,y) of a matrix m is accessed
with the notation m.(x).(y).Invalid_argument if dimx or dimy is negative or
greater than Sys.max_array_length.
If the value of e is a floating-point number, then the maximum
size is only Sys.max_array_length / 2.val create_matrix : int -> int -> 'a -> 'a array arrayArray.create_matrix is an alias for Array.make_matrix.val append : 'a array -> 'a array -> 'a arrayArray.append v1 v2 returns a fresh array containing the
concatenation of the arrays v1 and v2.val concat : 'a array list -> 'a arrayArray.append, but concatenates a list of arrays.val sub : 'a array -> int -> int -> 'a arrayArray.sub a start len returns a fresh array of length len,
containing the elements number start to start + len - 1
of array a.Invalid_argument if start and len do not
designate a valid subarray of a; that is, if
start < 0, or len < 0, or start + len > Array.length a.val copy : 'a array -> 'a arrayArray.copy a returns a copy of a, that is, a fresh array
containing the same elements as a.val fill : 'a array -> int -> int -> 'a -> unitArray.fill a ofs len x modifies the array a in place,
storing x in elements number ofs to ofs + len - 1.Invalid_argument if ofs and len do not
designate a valid subarray of a.val blit : 'a array -> int -> 'a array -> int -> int -> unitArray.blit v1 o1 v2 o2 len copies len elements
from array v1, starting at element number o1, to array v2,
starting at element number o2. It works correctly even if
v1 and v2 are the same array, and the source and
destination chunks overlap.Invalid_argument if o1 and len do not
designate a valid subarray of v1, or if o2 and len do not
designate a valid subarray of v2.val to_list : 'a array -> 'a listArray.to_list a returns the list of all the elements of a.val of_list : 'a list -> 'a arrayArray.of_list l returns a fresh array containing the elements
of l.val max : 'a array -> 'amax a returns the largest value in a as judged by
Pervasives.compareInvalid_argument on empty inputval min : 'a array -> 'amin a returns the smallest value in a as judged by
Pervasives.compareInvalid_argument on empty inputval sum : int array -> intsum l returns the sum of the integers of lval fsum : float array -> floatfsum l returns the sum of the floats of lval kahan_sum : float array -> floatkahan_sum l returns a numerically-accurate
sum of the floats of l.
You should consider using Kahan summation when you really care about very small differences in the result, while the result or one of the intermediate sums can be very large (which usually results in loss of precision of floating-point addition).
The worst-case rounding error is constant, instead of growing with
(the square root of) the length of the input array as with BatArray.fsum. On the other hand, processing each element requires four
floating-point operations instead of one. See
the wikipedia article on Kahan summation for more details.
Since 2.2.0
val avg : int array -> floatavg l returns the average of lval favg : float array -> floatfavg l returns the average of lval left : 'a array -> int -> 'a arrayleft r len returns the array containing the len first
characters of r. If r contains less than len characters, it
returns r.
Examples:
Array.left [|0;1;2;3;4;5;6|] 4 = [|0;1;2;3|]
Array.left [|1;2;3|] 0 = [||]
Array.left [|1;2;3|] 10 = [|1;2;3|]
val right : 'a array -> int -> 'a arrayleft r len returns the array containing the len last characters of r.
If r contains less than len characters, it returns r.
Example: Array.right [|1;2;3;4;5;6|] 4 = [|3;4;5;6|]
val head : 'a array -> int -> 'a array
val tail : 'a array -> int -> 'a arraytail r pos returns the array containing all but the pos first characters of r
Example: Array.tail [|1;2;3;4;5;6|] 4 = [|5;6|]
val iter : ('a -> unit) -> 'a array -> unitArray.iter f a applies function f in turn to all
the elements of a. It is equivalent to
f a.(0); f a.(1); ...; f a.(Array.length a - 1); ().val map : ('a -> 'b) -> 'a array -> 'b arrayArray.map f a applies function f to all the elements of a,
and builds an array with the results returned by f:
[| f a.(0); f a.(1); ...; f a.(Array.length a - 1) |].val iteri : (int -> 'a -> unit) -> 'a array -> unitArray.iter, but the
function is applied to the index of the element as first argument,
and the element itself as second argument.val mapi : (int -> 'a -> 'b) -> 'a array -> 'b arrayArray.map, but the
function is applied to the index of the element as first argument,
and the element itself as second argument.val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b array -> 'aArray.fold_left f x a computes
f (... (f (f x a.(0)) a.(1)) ...) a.(n-1),
where n is the length of the array a.val fold_right : ('b -> 'a -> 'a) -> 'b array -> 'a -> 'aArray.fold_right f a x computes
f a.(0) (f a.(1) ( ... (f a.(n-1) x) ...)),
where n is the length of the array a.val modify : ('a -> 'a) -> 'a array -> unitmodify f a replaces every element x of a with f x.val modifyi : (int -> 'a -> 'a) -> 'a array -> unitBatArray.modify, but the function is applied to the index of
the element as the first argument, and the element itself as
the second argument.val fold_lefti : ('a -> int -> 'b -> 'a) -> 'a -> 'b array -> 'afold_left, but with the index of the element as additional argumentval fold_righti : (int -> 'b -> 'a -> 'a) -> 'b array -> 'a -> 'afold_right, but with the index of the element as additional argumentval reduce : ('a -> 'a -> 'a) -> 'a array -> 'aArray.reduce f a is fold_left f a.(0) [|a.(1); ..; a.(n-1)|]. This
is useful for merging a group of things that have no
reasonable default value to return if the group is empty.Invalid_argument on empty arrays.val singleton : 'a -> 'a arrayval sort : ('a -> 'a -> int) -> 'a array -> unitPervasives.compare is
a suitable comparison function, provided there are no floating-point
NaN values in the data. After calling Array.sort, the
array is sorted in place in increasing order.
Array.sort is guaranteed to run in constant heap space
and (at most) logarithmic stack space.
The current implementation uses Heap Sort. It runs in constant stack space.
Specification of the comparison function:
Let a be the array and cmp the comparison function. The following
must be true for all x, y, z in a :
cmp x y > 0 if and only if cmp y x < 0cmp x y >= 0 and cmp y z >= 0 then cmp x z >= 0Array.sort returns, a contains the same elements as before,
reordered in such a way that for all i and j valid indices of a :cmp a.(i) a.(j) >= 0 if and only if i >= jval stable_sort : ('a -> 'a -> int) -> 'a array -> unitArray.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.
The current implementation uses Merge Sort. It uses n/2
words of heap space, where n is the length of the array.
It is usually faster than the current implementation of Array.sort.
val fast_sort : ('a -> 'a -> int) -> 'a array -> unitArray.sort or Array.stable_sort, whichever is faster
on typical input.val decorate_stable_sort : ('a -> 'b) -> 'a array -> 'a arraydecorate_stable_sort f a returns a sorted copy of a such that if f
x < f y then x is earlier in the result than y. This
function is useful when f is expensive, as it only computes f
x once for each element in the array. See
Schwartzian
Transform.
It is unnecessary to have an additional comparison function as
argument, as the builtin Pervasives.compare is used to compare
the 'b values. This is deemed sufficient.
val decorate_fast_sort : ('a -> 'b) -> 'a array -> 'a arrayArray.decorate_stable_sort, but uses fast_sort internally.val bsearch : 'a BatOrd.ord ->
'a array ->
'a -> [ `All_bigger | `All_lower | `At of int | `Empty | `Just_after of int ]bsearch cmp arr x finds the index of the object x in the array arr,
provided arr is sorted using cmp. If the array is not sorted,
the result is not specified (may raise Invalid_argument).
Complexity: O(log n) where n is the length of the array
(dichotomic search).
Since 2.2.0
Raises Invalid_argument if the array is found to be unsorted w.r.t cmp
Returns - `At i if cmp arr.(i) x = 0 (for some i)
`All_lower if all elements of arr are lower than x`All_bigger if all elements of arr are bigger than x`Just_after i if arr.(i) < x < arr.(i+1)`Empty if the array is emptyval iter2 : ('a -> 'b -> unit) -> 'a array -> 'b array -> unitArray.iter2 f [|a0; a1; ...; an|] [|b0; b1; ...; bn|]
performs calls f a0 b0; f a1 b1; ...; f an bn in that order.Invalid_argument if the two arrays have different lengths.val iter2i : (int -> 'a -> 'b -> unit) -> 'a array -> 'b array -> unitArray.iter2i f [|a0; a1; ...; an|] [|b0; b1; ...; bn|]
performs calls f 0 a0 b0; f 1 a1 b1; ...; f n an bn in that
order.Invalid_argument if the two arrays have different
lengths.val for_all2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> boolArray.for_all but on two arrays.Invalid_argument if the two arrays have different lengths.val exists2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> boolArray.exists but on two arrays.Invalid_argument if the two arrays have different lengths.val map2 : ('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c arrayArray.map but on two arrays.Invalid_argument if the two arrays have different lengths.val cartesian_product : 'a array -> 'b array -> ('a * 'b) arrayval for_all : ('a -> bool) -> 'a array -> boolfor_all p [|a0; a1; ...; an|] checks if all elements of the
array satisfy the predicate p. That is, it returns (p a0)
&& (p a1) && ... && (p an).val exists : ('a -> bool) -> 'a array -> boolexists p [|a0; a1; ...; an|] checks if at least one element of
the array satisfies the predicate p. That is, it returns (p
a0) || (p a1) || ... || (p an).val find : ('a -> bool) -> 'a array -> 'afind p a returns the first element of array a that
satisfies the predicate p.Not_found if there is no value that satisfies p in
the array a.val mem : 'a -> 'a array -> boolmem m a is true if and only if m is equal to an element of a.val memq : 'a -> 'a array -> boolArray.mem but uses physical equality instead of
structural equality to compare array elements.val findi : ('a -> bool) -> 'a array -> intfindi p a returns the index of the first element of array a
that satisfies the predicate p.Not_found if there is no value that satisfies p in the
array a.val filter : ('a -> bool) -> 'a array -> 'a arrayfilter p a returns all the elements of the array a
that satisfy the predicate p. The order of the elements
in the input array is preserved.val filteri : (int -> 'a -> bool) -> 'a array -> 'a arrayfilter but with the index passed to the predicate.val filter_map : ('a -> 'b option) -> 'a array -> 'b arrayfilter_map f e returns an array consisting of all elements
x such that f y returns Some x , where y is an element
of e.val find_all : ('a -> bool) -> 'a array -> 'a arrayfind_all is another name for Array.filter.val partition : ('a -> bool) -> 'a array -> 'a array * 'a arraypartition p a returns a pair of arrays (a1, a2), where
a1 is the array of all the elements of a that
satisfy the predicate p, and a2 is the array of all the
elements of a that do not satisfy p.
The order of the elements in the input array is preserved.val rev : 'a array -> 'a arrayval rev_in_place : 'a array -> unitval enum : 'a array -> 'a BatEnum.tval of_enum : 'a BatEnum.t -> 'a arrayval backwards : 'a array -> 'a BatEnum.tval of_backwards : 'a BatEnum.t -> 'a arrayval range : 'a array -> int BatEnum.trange a returns an enumeration of all valid indexes into the given
array. For example, range [|2;4;6;8|] = 0--3.val insert : 'a array -> 'a -> int -> 'a arrayinsert xs x i returns a copy of xs except the value x is
inserted in position i (and all later indices are shifted to the
right).val print : ?first:string ->
?last:string ->
?sep:string -> ('a, 'b) BatIO.printer -> ('a t, 'b) BatIO.printer~first preceeding the first
item (default: "[|"), ~last following the last item (default:
"|]") and ~sep separating items (default: "; "). A printing
function must be provided to print the items in the array.
Example: IO.to_string (Array.print Int.print) |2;4;66| = "|2; 4; 66|"
val compare : 'a BatOrd.comp -> 'a array BatOrd.compcompare c generates the lexicographical order on arrays induced
by c. That is, given a comparison function for the elements of
an array, this will return a comparison function for arrays of
that type.val ord : 'a BatOrd.ord -> 'a array BatOrd.ordcompare, but is often faster.val equal : 'a BatOrd.eq -> 'a array BatOrd.eqArray with
functions behaving slightly differently but having the same
name. This is by design: the functions are meant to override the
corresponding functions of Array.module Exceptionless:sig..end
Array without exceptions.
module Labels:sig..end
Array with labels.
module Cap:sig..end
module Incubator:sig..end