Module ArrayLabels
: sigend
Array operations.
The labeled version of this module can be used as described in the StdLabels module.
type'at = 'aarray
An alias for the type of arrays.
vallength : 'aarray->int
Return the length (number of elements) of the given array.
valget : 'aarray->int->'agetan returns the element number n of array a . The first element has number 0. The last element has
number lengtha-1 . You can also write a.(n) instead of getan .
RaisesInvalid_argument if n is outside the range 0 to (lengtha-1) .
valset : 'aarray->int->'a->unitsetanx modifies array a in place, replacing element number n with x . You can also write a.(n)<-x
instead of setanx .
RaisesInvalid_argument if n is outside the range 0 to lengtha-1 .
valmake : int->'a->'aarraymakenx 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.
RaisesInvalid_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 .
valcreate_float : int->floatarraycreate_floatn returns a fresh float array of length n , with uninitialized data.
Since 4.03
valinit : int->f:(int->'a)->'aarrayinitn~f returns a fresh array of length n , with element number i initialized to the result of fi .
In other terms, initn~f tabulates the results of f applied in order to the integers 0 to n-1 .
RaisesInvalid_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 .
valmake_matrix : dimx:int->dimy:int->'a->'aarrayarraymake_matrix~dimx~dimye 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) .
RaisesInvalid_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 .
valinit_matrix : dimx:int->dimy:int->f:(int->int->'a)->'aarrayarrayinit_matrix~dimx~dimy~f returns a two-dimensional array (an array of arrays) with first dimension dimx
and second dimension dimy , where the element at index ( x,y ) is initialized with fxy . The element (
x,y ) of a matrix m is accessed with the notation m.(x).(y) .
Since 5.2
RaisesInvalid_argument if dimx or dimy is negative or greater than Sys.max_array_length . If the return
type of f is float , then the maximum size is only Sys.max_array_length/2 .
valappend : 'aarray->'aarray->'aarrayappendv1v2 returns a fresh array containing the concatenation of the arrays v1 and v2 .
RaisesInvalid_argument if lengthv1+lengthv2>Sys.max_array_length .
valconcat : 'aarraylist->'aarray
Same as ArrayLabels.append , but concatenates a list of arrays.
valsub : 'aarray->pos:int->len:int->'aarraysuba~pos~len returns a fresh array of length len , containing the elements number pos to pos+len-1
of array a .
RaisesInvalid_argument if pos and len do not designate a valid subarray of a ; that is, if pos<0 , or
len<0 , or pos+len>lengtha .
valcopy : 'aarray->'aarraycopya returns a copy of a , that is, a fresh array containing the same elements as a .
valfill : 'aarray->pos:int->len:int->'a->unitfilla~pos~lenx modifies the array a in place, storing x in elements number pos to pos+len-1 .
RaisesInvalid_argument if pos and len do not designate a valid subarray of a .
valblit : src:'aarray->src_pos:int->dst:'aarray->dst_pos:int->len:int->unitblit~src~src_pos~dst~dst_pos~len copies len elements from array src , starting at element number
src_pos , to array dst , starting at element number dst_pos . It works correctly even if src and dst are
the same array, and the source and destination chunks overlap.
RaisesInvalid_argument if src_pos and len do not designate a valid subarray of src , or if dst_pos and
len do not designate a valid subarray of dst .
valto_list : 'aarray->'alistto_lista returns the list of all the elements of a .
valof_list : 'alist->'aarrayof_listl returns a fresh array containing the elements of l .
RaisesInvalid_argument if the length of l is greater than Sys.max_array_length .
Iteratorsvaliter : f:('a->unit)->'aarray->unititer~fa applies function f in turn to all the elements of a . It is equivalent to fa.(0);fa.(1);...;fa.(lengtha-1);() .
valiteri : f:(int->'a->unit)->'aarray->unit
Same as ArrayLabels.iter , but the function is applied to the index of the element as first argument, and
the element itself as second argument.
valmap : f:('a->'b)->'aarray->'barraymap~fa applies function f to all the elements of a , and builds an array with the results returned by f
: [|fa.(0);fa.(1);...;fa.(lengtha-1)|] .
valmap_inplace : f:('a->'a)->'aarray->unitmap_inplace~fa applies function f to all elements of a , and updates their values in place.
Since 5.1
valmapi : f:(int->'a->'b)->'aarray->'barray
Same as ArrayLabels.map , but the function is applied to the index of the element as first argument, and
the element itself as second argument.
valmapi_inplace : f:(int->'a->'a)->'aarray->unit
Same as ArrayLabels.map_inplace , but the function is applied to the index of the element as first
argument, and the element itself as second argument.
Since 5.1
valfold_left : f:('acc->'a->'acc)->init:'acc->'aarray->'accfold_left~f~inita computes f(...(f(finita.(0))a.(1))...)a.(n-1) , where n is the length of the
array a .
valfold_left_map : f:('acc->'a->'acc*'b)->init:'acc->'aarray->'acc*'barrayfold_left_map is a combination of ArrayLabels.fold_left and ArrayLabels.map that threads an accumulator
through calls to f .
Since 4.13
valfold_right : f:('a->'acc->'acc)->'aarray->init:'acc->'accfold_right~fa~init computes fa.(0)(fa.(1)(...(fa.(n-1)init)...)) , where n is the length of
the array a .
Iteratorsontwoarraysvaliter2 : f:('a->'b->unit)->'aarray->'barray->unititer2~fab applies function f to all the elements of a and b .
Since 4.05
RaisesInvalid_argument if the arrays are not the same size.
valmap2 : f:('a->'b->'c)->'aarray->'barray->'carraymap2~fab applies function f to all the elements of a and b , and builds an array with the results
returned by f : [|fa.(0)b.(0);...;fa.(lengtha-1)b.(lengthb-1)|] .
Since 4.05
RaisesInvalid_argument if the arrays are not the same size.
Arrayscanningvalfor_all : f:('a->bool)->'aarray->boolfor_all~f[|a1;...;an|] checks if all elements of the array satisfy the predicate f . That is, it
returns (fa1)&&(fa2)&&...&&(fan) .
Since 4.03
valexists : f:('a->bool)->'aarray->boolexists~f[|a1;...;an|] checks if at least one element of the array satisfies the predicate f . That
is, it returns (fa1)||(fa2)||...||(fan) .
Since 4.03
valfor_all2 : f:('a->'b->bool)->'aarray->'barray->bool
Same as ArrayLabels.for_all , but for a two-argument predicate.
Since 4.11
RaisesInvalid_argument if the two arrays have different lengths.
valexists2 : f:('a->'b->bool)->'aarray->'barray->bool
Same as ArrayLabels.exists , but for a two-argument predicate.
Since 4.11
RaisesInvalid_argument if the two arrays have different lengths.
valmem : 'a->set:'aarray->boolmema~set is true if and only if a is structurally equal to an element of set (i.e. there is an x in set
such that compareax=0 ).
Since 4.03
valmemq : 'a->set:'aarray->bool
Same as ArrayLabels.mem , but uses physical equality instead of structural equality to compare array
elements.
Since 4.03
valfind_opt : f:('a->bool)->'aarray->'aoptionfind_opt~fa returns the first element of the array a that satisfies the predicate f , or None if there
is no value that satisfies f in the array a .
Since 4.13
valfind_index : f:('a->bool)->'aarray->intoptionfind_index~fa returns Somei , where i is the index of the first element of the array a that satisfies
fx , if there is such an element.
It returns None if there is no such element.
Since 5.1
valfind_map : f:('a->'boption)->'aarray->'boptionfind_map~fa applies f to the elements of a in order, and returns the first result of the form Somev ,
or None if none exist.
Since 4.13
valfind_mapi : f:(int->'a->'boption)->'aarray->'boption
Same as find_map , but the predicate is applied to the index of the element as first argument (counting
from 0), and the element itself as second argument.
Since 5.1
Arraysofpairsvalsplit : ('a*'b)array->'aarray*'barraysplit[|(a1,b1);...;(an,bn)|] is ([|a1;...;an|],[|b1;...;bn|]) .
Since 4.13
valcombine : 'aarray->'barray->('a*'b)arraycombine[|a1;...;an|][|b1;...;bn|] is [|(a1,b1);...;(an,bn)|] . Raise Invalid_argument if the two
arrays have different lengths.
Since 4.13
Sortingandshufflingvalsort : cmp:('a->'a->int)->'aarray->unit
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, compare is a
suitable comparison function. After calling sort , the array is sorted in place in increasing order.
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 :
- cmpxy > 0 if and only if cmpyx < 0
- if cmpxy >= 0 and cmpyz >= 0 then cmpxz >= 0
When sort returns, a contains the same elements as before, reordered in such a way that for all i and j
valid indices of a :
- cmpa.(i)a.(j) >= 0 if i >= j
valstable_sort : cmp:('a->'a->int)->'aarray->unit
Same as ArrayLabels.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 a temporary array of length n/2 , where n is the
length of the array. It is usually faster than the current implementation of ArrayLabels.sort .
valfast_sort : cmp:('a->'a->int)->'aarray->unit
Same as ArrayLabels.sort or ArrayLabels.stable_sort , whichever is faster on typical input.
valshuffle : rand:(int->int)->'aarray->unitshuffle~randa randomly permutes a 's element using rand for randomness. The distribution of
permutations is uniform.
rand must be such that a call to randn returns a uniformly distributed random number in the range [ 0 ;
n-1 ]. Random.int can be used for this (do not forget to Random.self_init the generator).
Since 5.2
ArraysandSequencesvalto_seq : 'aarray->'aSeq.t
Iterate on the array, in increasing order. Modifications of the array during iteration will be reflected
in the sequence.
Since 4.07
valto_seqi : 'aarray->(int*'a)Seq.t
Iterate on the array, in increasing order, yielding indices along elements. Modifications of the array
during iteration will be reflected in the sequence.
Since 4.07
valof_seq : 'aSeq.t->'aarray
Create an array from the generator
Since 4.07
Arraysandconcurrencysafety
Care must be taken when concurrently accessing arrays from multiple domains: accessing an array will
never crash a program, but unsynchronized accesses might yield surprising (non-sequentially-consistent)
results.
Atomicity
Every array operation that accesses more than one array element is not atomic. This includes iteration,
scanning, sorting, splitting and combining arrays.
For example, consider the following program:
letsize=100_000_000leta=ArrayLabels.makesize1letd1=Domain.spawn(fun()->ArrayLabels.iteri~f:(funix->a.(i)<-x+1)a)letd2=Domain.spawn(fun()->ArrayLabels.iteri~f:(funix->a.(i)<-2*x+1)a)let()=Domain.joind1;Domain.joind2
After executing this code, each field of the array a is either 2 , 3 , 4 or 5 . If atomicity is required,
then the user must implement their own synchronization (for example, using Mutex.t ).
Dataraces
If two domains only access disjoint parts of the array, then the observed behaviour is the equivalent to
some sequential interleaving of the operations from the two domains.
A data race is said to occur when two domains access the same array element without synchronization and
at least one of the accesses is a write. In the absence of data races, the observed behaviour is
equivalent to some sequential interleaving of the operations from different domains.
Whenever possible, data races should be avoided by using synchronization to mediate the accesses to the
array elements.
Indeed, in the presence of data races, programs will not crash but the observed behaviour may not be
equivalent to any sequential interleaving of operations from different domains. Nevertheless, even in the
presence of data races, a read operation will return the value of some prior write to that location (with
a few exceptions for float arrays).
Floatarrays
Float arrays have two supplementary caveats in the presence of data races.
First, the blit operation might copy an array byte-by-byte. Data races between such a blit operation and
another operation might produce surprising values due to tearing: partial writes interleaved with other
operations can create float values that would not exist with a sequential execution.
For instance, at the end of
letzeros=Array.makesize0.letmax_floats=Array.makesizeFloat.max_floatletres=Array.copyzerosletd1=Domain.spawn(fun()->Array.blitzeros0res0size)letd2=Domain.spawn(fun()->Array.blitmax_floats0res0size)let()=Domain.joind1;Domain.joind2
the res array might contain values that are neither 0. nor max_float .
Second, on 32-bit architectures, getting or setting a field involves two separate memory accesses. In the
presence of data races, the user may observe tearing on any operation.
OCamldoc 2025-06-12 ArrayLabels(3o)
Install Now
PNG Icons