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_left_map : ('a -> 'b -> 'a * 'c) -> 'a -> 'b array -> 'a *  'c
266       array
267
268
269       fold_left_map  is  a  combination of Array.fold_left and Array.map that
270       threads an accumulator through calls to f .
271
272
273       Since 4.13.0
274
275
276
277       val fold_right : ('b -> 'a -> 'a) -> 'b array -> 'a -> 'a
278
279
280       fold_right f a init computes f a.(0) (f a.(1) ( ...  (f  a.(n-1)  init)
281       ...))  , where n is the length of the array a .
282
283
284
285
286   Iterators on two arrays
287       val iter2 : ('a -> 'b -> unit) -> 'a array -> 'b array -> unit
288
289
290       iter2 f a b applies function f to all the elements of a and b .
291
292
293       Since 4.03.0 (4.05.0 in ArrayLabels)
294
295
296       Raises Invalid_argument if the arrays are not the same size.
297
298
299
300       val map2 : ('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array
301
302
303       map2  f  a  b  applies  function f to all the elements of a and b , and
304       builds an array with the results returned by f : [| f a.(0) b.(0); ...;
305       f a.(length a - 1) b.(length b - 1)|] .
306
307
308       Since 4.03.0 (4.05.0 in ArrayLabels)
309
310
311       Raises Invalid_argument if the arrays are not the same size.
312
313
314
315
316   Array scanning
317       val for_all : ('a -> bool) -> 'a array -> bool
318
319
320       for_all  f  [|a1; ...; an|] checks if all elements of the array satisfy
321       the predicate f . That is, it returns (f a1) && (f a2) && ... && (f an)
322       .
323
324
325       Since 4.03.0
326
327
328
329       val exists : ('a -> bool) -> 'a array -> bool
330
331
332       exists  f  [|a1;  ...; an|] checks if at least one element of the array
333       satisfies the predicate f . That is, it returns (f a1) || (f a2) || ...
334       || (f an) .
335
336
337       Since 4.03.0
338
339
340
341       val for_all2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> bool
342
343       Same as Array.for_all , 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 exists2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> bool
354
355       Same as Array.exists , but for a two-argument predicate.
356
357
358       Since 4.11.0
359
360
361       Raises Invalid_argument if the two arrays have different lengths.
362
363
364
365       val mem : 'a -> 'a array -> bool
366
367
368       mem  a set is true if and only if a is structurally equal to an element
369       of l (i.e. there is an x in l such that compare a x = 0 ).
370
371
372       Since 4.03.0
373
374
375
376       val memq : 'a -> 'a array -> bool
377
378       Same as Array.mem , but uses physical equality  instead  of  structural
379       equality to compare list elements.
380
381
382       Since 4.03.0
383
384
385
386       val find_opt : ('a -> bool) -> 'a array -> 'a option
387
388
389       find_opt  f  a  returns the first element of the array a that satisfies
390       the predicate f , or None if there is no value that satisfies f in  the
391       array a .
392
393
394       Since 4.13.0
395
396
397
398       val find_map : ('a -> 'b option) -> 'a array -> 'b option
399
400
401       find_map  f  a applies f to the elements of a in order, and returns the
402       first result of the form Some v , or None if none exist.
403
404
405       Since 4.13.0
406
407
408
409
410   Arrays of pairs
411       val split : ('a * 'b) array -> 'a array * 'b array
412
413
414       split [|(a1,b1); ...; (an,bn)|] is ([|a1; ...; an|], [|b1; ...; bn|]) .
415
416
417       Since 4.13.0
418
419
420
421       val combine : 'a array -> 'b array -> ('a * 'b) array
422
423
424       combine [|a1; ...; an|] [|b1; ...; bn|] is [|(a1,b1); ...; (an,bn)|]  .
425       Raise Invalid_argument if the two arrays have different lengths.
426
427
428       Since 4.13.0
429
430
431
432
433   Sorting
434       val sort : ('a -> 'a -> int) -> 'a array -> unit
435
436       Sort  an  array in increasing order according to a comparison function.
437       The comparison function must return  0  if  its  arguments  compare  as
438       equal, a positive integer if the first is greater, and a negative inte‐
439       ger if the first is smaller (see below for a  complete  specification).
440       For  example,  compare is a suitable comparison function. After calling
441       sort , the array is sorted in place in increasing order.  sort is guar‐
442       anteed  to  run  in constant heap space and (at most) logarithmic stack
443       space.
444
445       The current implementation uses Heap Sort.  It runs in  constant  stack
446       space.
447
448       Specification  of  the  comparison function: Let a be the array and cmp
449       the comparison function.  The following must be true for all x , y ,  z
450       in a :
451
452       - cmp x y > 0 if and only if cmp y x < 0
453
454       -  if cmp x y >= 0 and cmp y z >= 0 then cmp x z >= 0
455
456       When sort returns, a contains the same elements as before, reordered in
457       such a way that for all i and j valid indices of a :
458
459       - cmp a.(i) a.(j) >= 0 if and only if i >= j
460
461
462
463
464       val stable_sort : ('a -> 'a -> int) -> 'a array -> unit
465
466       Same as Array.sort , but the sorting algorithm is  stable  (i.e.   ele‐
467       ments  that  compare  equal  are  kept in their original order) and not
468       guaranteed to run in constant heap space.
469
470       The current implementation uses Merge Sort. It uses a  temporary  array
471       of  length  n/2  ,  where  n is the length of the array.  It is usually
472       faster than the current implementation of Array.sort .
473
474
475
476       val fast_sort : ('a -> 'a -> int) -> 'a array -> unit
477
478       Same as Array.sort or Array.stable_sort , whichever is faster on  typi‐
479       cal input.
480
481
482
483
484   Arrays and Sequences
485       val to_seq : 'a array -> 'a Seq.t
486
487       Iterate  on  the array, in increasing order. Modifications of the array
488       during iteration will be reflected in the sequence.
489
490
491       Since 4.07
492
493
494
495       val to_seqi : 'a array -> (int * 'a) Seq.t
496
497       Iterate on the array, in increasing order, yielding indices along  ele‐
498       ments.   Modifications  of the array during iteration will be reflected
499       in the sequence.
500
501
502       Since 4.07
503
504
505
506       val of_seq : 'a Seq.t -> 'a array
507
508       Create an array from the generator
509
510
511       Since 4.07
512
513
514
515
516
517OCamldoc                          2023-01-23                          Array(3)