1Array(3)                         OCaml library                        Array(3)
2
3
4

NAME

6       Array - Array operations.
7

Module

9       Module   Array
10

Documentation

12       Module Array
13        : sig end
14
15
16       Array operations.
17
18       The labeled version of this module can be used as described in the Std‐
19       Labels module.
20
21
22
23
24
25       type 'a t = 'a array
26
27
28       An alias for the type of arrays.
29
30
31
32       val length : 'a array -> int
33
34       Return the length (number of elements) of the given array.
35
36
37
38       val get : 'a array -> int -> 'a
39
40
41       get a n returns the element number n of array a .   The  first  element
42       has number 0.  The last element has number length a - 1 .  You can also
43       write a.(n) instead of get a n .
44
45
46       Raises Invalid_argument if n is outside the range 0 to (length a - 1) .
47
48
49
50       val set : 'a array -> int -> 'a -> unit
51
52
53       set a n x modifies array a in place, replacing element number n with  x
54       .  You can also write a.(n) <- x instead of set a n x .
55
56
57       Raises Invalid_argument if n is outside the range 0 to length a - 1 .
58
59
60
61       val make : int -> 'a -> 'a array
62
63
64       make  n x returns a fresh array of length n , initialized with x .  All
65       the elements of this new array are initially physically equal to x  (in
66       the  sense  of the == predicate).  Consequently, if x is mutable, it is
67       shared among all elements of the array, and modifying x through one  of
68       the array entries will modify all other entries at the same time.
69
70
71       Raises  Invalid_argument if n < 0 or n > Sys.max_array_length .  If the
72       value of x is a floating-point number, then the maximum  size  is  only
73       Sys.max_array_length / 2 .
74
75
76
77       val create : int -> 'a -> 'a array
78
79       Deprecated.
80
81       create is an alias for Array.make .
82
83
84
85       val create_float : int -> float array
86
87
88       create_float  n  returns  a fresh float array of length n , with unini‐
89       tialized data.
90
91
92       Since 4.03
93
94
95
96       val make_float : int -> float array
97
98       Deprecated.
99
100       make_float is an alias for Array.create_float .
101
102
103
104       val init : int -> (int -> 'a) -> 'a array
105
106
107       init n f returns a fresh array of length n , with element number i ini‐
108       tialized to the result of f i .  In other terms, init n f tabulates the
109       results of f applied to the integers 0 to n-1 .
110
111
112       Raises Invalid_argument if n < 0 or n > Sys.max_array_length .  If  the
113       return  type  of f is float , then the maximum size is only Sys.max_ar‐
114       ray_length / 2 .
115
116
117
118       val make_matrix : int -> int -> 'a -> 'a array array
119
120
121       make_matrix dimx dimy e returns a two-dimensional array  (an  array  of
122       arrays)  with  first dimension dimx and second dimension dimy . All the
123       elements of this new matrix are initially physically equal to e .   The
124       element ( x,y ) of a matrix m is accessed with the notation m.(x).(y) .
125
126
127       Raises  Invalid_argument  if  dimx  or dimy is negative or greater than
128       Sys.max_array_length .  If the value of e is a  floating-point  number,
129       then the maximum size is only Sys.max_array_length / 2 .
130
131
132
133       val create_matrix : int -> int -> 'a -> 'a array array
134
135       Deprecated.
136
137       create_matrix is an alias for Array.make_matrix .
138
139
140
141       val append : 'a array -> 'a array -> 'a array
142
143
144       append  v1 v2 returns a fresh array containing the concatenation of the
145       arrays v1 and v2 .
146
147
148       Raises Invalid_argument if length v1 + length v2 > Sys.max_array_length
149       .
150
151
152
153       val concat : 'a array list -> 'a array
154
155       Same as Array.append , but concatenates a list of arrays.
156
157
158
159       val sub : 'a array -> int -> int -> 'a array
160
161
162       sub a pos len returns a fresh array of length len , containing the ele‐
163       ments number pos to pos + len - 1 of array a .
164
165
166       Raises Invalid_argument if pos and len do not designate a valid  subar‐
167       ray of a ; that is, if pos < 0 , or len < 0 , or pos + len > length a .
168
169
170
171       val copy : 'a array -> 'a array
172
173
174       copy a returns a copy of a , that is, a fresh array containing the same
175       elements as a .
176
177
178
179       val fill : 'a array -> int -> int -> 'a -> unit
180
181
182       fill a pos len x modifies the array a in place, storing x  in  elements
183       number pos to pos + len - 1 .
184
185
186       Raises  Invalid_argument if pos and len do not designate a valid subar‐
187       ray of a .
188
189
190
191       val blit : 'a array -> int -> 'a array -> int -> int -> unit
192
193
194       blit src src_pos dst dst_pos len copies len elements from array  src  ,
195       starting at element number src_pos , to array dst , starting at element
196       number dst_pos . It works correctly even if src and dst  are  the  same
197       array, and the source and destination chunks overlap.
198
199
200       Raises  Invalid_argument  if  src_pos  and len do not designate a valid
201       subarray of src , or if dst_pos and len do not designate a valid subar‐
202       ray of dst .
203
204
205
206       val to_list : 'a array -> 'a list
207
208
209       to_list a returns the list of all the elements of a .
210
211
212
213       val of_list : 'a list -> 'a array
214
215
216       of_list l returns a fresh array containing the elements of l .
217
218
219       Raises  Invalid_argument if the length of l is greater than Sys.max_ar‐
220       ray_length .
221
222
223
224
225   Iterators
226       val iter : ('a -> unit) -> 'a array -> unit
227
228
229       iter f a applies function f in turn to all the elements of a .   It  is
230       equivalent to f a.(0); f a.(1); ...; f a.(length a - 1); () .
231
232
233
234       val iteri : (int -> 'a -> unit) -> 'a array -> unit
235
236       Same  as  Array.iter  , but the function is applied to the index of the
237       element as first argument, and the element itself as second argument.
238
239
240
241       val map : ('a -> 'b) -> 'a array -> 'b array
242
243
244       map f a applies function f to all the elements of a , and builds an ar‐
245       ray  with  the  results  returned  by  f  : [| f a.(0); f a.(1); ...; f
246       a.(length a - 1) |] .
247
248
249
250       val mapi : (int -> 'a -> 'b) -> 'a array -> 'b array
251
252       Same as Array.map , but the function is applied to the index of the el‐
253       ement as first argument, and the element itself as second argument.
254
255
256
257       val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b array -> 'a
258
259
260       fold_left  f  init  a  computes  f  (...  (f (f init a.(0)) a.(1)) ...)
261       a.(n-1) , where n is the length of the array a .
262
263
264
265       val fold_right : ('b -> 'a -> 'a) -> 'b array -> 'a -> 'a
266
267
268       fold_right f a init computes f a.(0) (f a.(1) ( ...  (f  a.(n-1)  init)
269       ...))  , where n is the length of the array a .
270
271
272
273
274   Iterators on two arrays
275       val iter2 : ('a -> 'b -> unit) -> 'a array -> 'b array -> unit
276
277
278       iter2 f a b applies function f to all the elements of a and b .
279
280
281       Since 4.03.0 (4.05.0 in ArrayLabels)
282
283
284       Raises Invalid_argument if the arrays are not the same size.
285
286
287
288       val map2 : ('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array
289
290
291       map2  f  a  b  applies  function f to all the elements of a and b , and
292       builds an array with the results returned by f : [| f a.(0) b.(0); ...;
293       f a.(length a - 1) b.(length b - 1)|] .
294
295
296       Since 4.03.0 (4.05.0 in ArrayLabels)
297
298
299       Raises Invalid_argument if the arrays are not the same size.
300
301
302
303
304   Array scanning
305       val for_all : ('a -> bool) -> 'a array -> bool
306
307
308       for_all  f  [|a1; ...; an|] checks if all elements of the array satisfy
309       the predicate f . That is, it returns (f a1) && (f a2) && ... && (f an)
310       .
311
312
313       Since 4.03.0
314
315
316
317       val exists : ('a -> bool) -> 'a array -> bool
318
319
320       exists  f  [|a1;  ...; an|] checks if at least one element of the array
321       satisfies the predicate f . That is, it returns (f a1) || (f a2) || ...
322       || (f an) .
323
324
325       Since 4.03.0
326
327
328
329       val for_all2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> bool
330
331       Same as Array.for_all , but for a two-argument predicate.
332
333
334       Since 4.11.0
335
336
337       Raises Invalid_argument if the two arrays have different lengths.
338
339
340
341       val exists2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> bool
342
343       Same as Array.exists , but for a two-argument predicate.
344
345
346       Since 4.11.0
347
348
349       Raises Invalid_argument if the two arrays have different lengths.
350
351
352
353       val mem : 'a -> 'a array -> bool
354
355
356       mem  a set is true if and only if a is structurally equal to an element
357       of l (i.e. there is an x in l such that compare a x = 0 ).
358
359
360       Since 4.03.0
361
362
363
364       val memq : 'a -> 'a array -> bool
365
366       Same as Array.mem , but uses physical equality  instead  of  structural
367       equality to compare list elements.
368
369
370       Since 4.03.0
371
372
373
374
375   Sorting
376       val sort : ('a -> 'a -> int) -> 'a array -> unit
377
378       Sort  an  array in increasing order according to a comparison function.
379       The comparison function must return  0  if  its  arguments  compare  as
380       equal, a positive integer if the first is greater, and a negative inte‐
381       ger if the first is smaller (see below for a  complete  specification).
382       For  example,  compare is a suitable comparison function. After calling
383       sort , the array is sorted in place in increasing order.  sort is guar‐
384       anteed  to  run  in constant heap space and (at most) logarithmic stack
385       space.
386
387       The current implementation uses Heap Sort.  It runs in  constant  stack
388       space.
389
390       Specification  of  the  comparison function: Let a be the array and cmp
391       the comparison function.  The following must be true for all x , y ,  z
392       in a :
393
394       - cmp x y > 0 if and only if cmp y x < 0
395
396       -  if cmp x y >= 0 and cmp y z >= 0 then cmp x z >= 0
397
398       When sort returns, a contains the same elements as before, reordered in
399       such a way that for all i and j valid indices of a :
400
401       - cmp a.(i) a.(j) >= 0 if and only if i >= j
402
403
404
405
406       val stable_sort : ('a -> 'a -> int) -> 'a array -> unit
407
408       Same as Array.sort , but the sorting algorithm is  stable  (i.e.   ele‐
409       ments  that  compare  equal  are  kept in their original order) and not
410       guaranteed to run in constant heap space.
411
412       The current implementation uses Merge Sort. It uses a  temporary  array
413       of  length  n/2  ,  where  n is the length of the array.  It is usually
414       faster than the current implementation of Array.sort .
415
416
417
418       val fast_sort : ('a -> 'a -> int) -> 'a array -> unit
419
420       Same as Array.sort or Array.stable_sort , whichever is faster on  typi‐
421       cal input.
422
423
424
425
426   Iterators
427       val to_seq : 'a array -> 'a Seq.t
428
429       Iterate  on  the array, in increasing order. Modifications of the array
430       during iteration will be reflected in the iterator.
431
432
433       Since 4.07
434
435
436
437       val to_seqi : 'a array -> (int * 'a) Seq.t
438
439       Iterate on the array, in increasing order, yielding indices along  ele‐
440       ments.   Modifications  of the array during iteration will be reflected
441       in the iterator.
442
443
444       Since 4.07
445
446
447
448       val of_seq : 'a Seq.t -> 'a array
449
450       Create an array from the generator
451
452
453       Since 4.07
454
455
456
457
458
459OCamldoc                          2021-07-22                          Array(3)