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

NAME

6       ArrayLabels - Array operations.
7

Module

9       Module   ArrayLabels
10

Documentation

12       Module ArrayLabels
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 ArrayLabels.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 ArrayLabels.create_float .
101
102
103
104       val init : int -> f:(int -> 'a) -> 'a array
105
106
107       init n ~f returns a fresh array of length n ,  with  element  number  i
108       initialized to the result of f i .  In other terms, init n ~f tabulates
109       the 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 : dimx:int -> dimy: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 : dimx:int -> dimy:int -> 'a -> 'a array array
134
135       Deprecated.
136
137       create_matrix is an alias for ArrayLabels.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 ArrayLabels.append , but concatenates a list of arrays.
156
157
158
159       val sub : 'a array -> pos:int -> len:int -> 'a array
160
161
162       sub  a  ~pos  ~len returns a fresh array of length len , containing the
163       elements 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 -> pos:int -> len: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 : src:'a array -> src_pos:int -> dst:'a array  ->  dst_pos:int
192       -> len:int -> unit
193
194
195       blit  ~src  ~src_pos  ~dst ~dst_pos ~len copies len elements from array
196       src , starting at element number src_pos , to array dst ,  starting  at
197       element number dst_pos . It works correctly even if src and dst are the
198       same array, and the source and destination chunks overlap.
199
200
201       Raises Invalid_argument if src_pos and len do  not  designate  a  valid
202       subarray of src , or if dst_pos and len do not designate a valid subar‐
203       ray of dst .
204
205
206
207       val to_list : 'a array -> 'a list
208
209
210       to_list a returns the list of all the elements of a .
211
212
213
214       val of_list : 'a list -> 'a array
215
216
217       of_list l returns a fresh array containing the elements of l .
218
219
220       Raises Invalid_argument if the length of l is greater than  Sys.max_ar‐
221       ray_length .
222
223
224
225
226   Iterators
227       val iter : f:('a -> unit) -> 'a array -> unit
228
229
230       iter  ~f a applies function f in turn to all the elements of a .  It is
231       equivalent to f a.(0); f a.(1); ...; f a.(length a - 1); () .
232
233
234
235       val iteri : f:(int -> 'a -> unit) -> 'a array -> unit
236
237       Same as ArrayLabels.iter , but the function is applied to the index  of
238       the  element  as first argument, and the element itself as second argu‐
239       ment.
240
241
242
243       val map : f:('a -> 'b) -> 'a array -> 'b array
244
245
246       map ~f a applies function f to all the elements of a ,  and  builds  an
247       array  with  the  results  returned  by f : [| f a.(0); f a.(1); ...; f
248       a.(length a - 1) |] .
249
250
251
252       val mapi : f:(int -> 'a -> 'b) -> 'a array -> 'b array
253
254       Same as ArrayLabels.map , but the function is applied to the  index  of
255       the  element  as first argument, and the element itself as second argu‐
256       ment.
257
258
259
260       val fold_left : f:('a -> 'b -> 'a) -> init:'a -> 'b array -> 'a
261
262
263       fold_left ~f ~init a computes f (... (f  (f  init  a.(0))  a.(1))  ...)
264       a.(n-1) , where n is the length of the array a .
265
266
267
268       val  fold_left_map  : f:('a -> 'b -> 'a * 'c) -> init:'a -> 'b array ->
269       'a * 'c array
270
271
272       fold_left_map is a combination of  ArrayLabels.fold_left  and  ArrayLa‐
273       bels.map that threads an accumulator through calls to f .
274
275
276       Since 4.13.0
277
278
279
280       val fold_right : f:('b -> 'a -> 'a) -> 'b array -> init:'a -> 'a
281
282
283       fold_right  ~f a ~init computes f a.(0) (f a.(1) ( ... (f a.(n-1) init)
284       ...))  , where n is the length of the array a .
285
286
287
288
289   Iterators on two arrays
290       val iter2 : f:('a -> 'b -> unit) -> 'a array -> 'b array -> unit
291
292
293       iter2 ~f a b applies function f to all the elements of a and b .
294
295
296       Since 4.05.0
297
298
299       Raises Invalid_argument if the arrays are not the same size.
300
301
302
303       val map2 : f:('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array
304
305
306       map2 ~f a b applies function f to all the elements of a  and  b  ,  and
307       builds an array with the results returned by f : [| f a.(0) b.(0); ...;
308       f a.(length a - 1) b.(length b - 1)|] .
309
310
311       Since 4.05.0
312
313
314       Raises Invalid_argument if the arrays are not the same size.
315
316
317
318
319   Array scanning
320       val for_all : f:('a -> bool) -> 'a array -> bool
321
322
323       for_all ~f [|a1; ...; an|] checks if all elements of the array  satisfy
324       the predicate f . That is, it returns (f a1) && (f a2) && ... && (f an)
325       .
326
327
328       Since 4.03.0
329
330
331
332       val exists : f:('a -> bool) -> 'a array -> bool
333
334
335       exists ~f [|a1; ...; an|] checks if at least one element of  the  array
336       satisfies the predicate f . That is, it returns (f a1) || (f a2) || ...
337       || (f an) .
338
339
340       Since 4.03.0
341
342
343
344       val for_all2 : f:('a -> 'b -> bool) -> 'a array -> 'b array -> bool
345
346       Same as ArrayLabels.for_all , but for a two-argument predicate.
347
348
349       Since 4.11.0
350
351
352       Raises Invalid_argument if the two arrays have different lengths.
353
354
355
356       val exists2 : f:('a -> 'b -> bool) -> 'a array -> 'b array -> bool
357
358       Same as ArrayLabels.exists , but for a two-argument predicate.
359
360
361       Since 4.11.0
362
363
364       Raises Invalid_argument if the two arrays have different lengths.
365
366
367
368       val mem : 'a -> set:'a array -> bool
369
370
371       mem a ~set is true if and only if a is structurally equal to an element
372       of l (i.e. there is an x in l such that compare a x = 0 ).
373
374
375       Since 4.03.0
376
377
378
379       val memq : 'a -> set:'a array -> bool
380
381       Same  as ArrayLabels.mem , but uses physical equality instead of struc‐
382       tural equality to compare list elements.
383
384
385       Since 4.03.0
386
387
388
389       val find_opt : f:('a -> bool) -> 'a array -> 'a option
390
391
392       find_opt ~f a returns the first element of the array a  that  satisfies
393       the  predicate f , or None if there is no value that satisfies f in the
394       array a .
395
396
397       Since 4.13.0
398
399
400
401       val find_map : f:('a -> 'b option) -> 'a array -> 'b option
402
403
404       find_map ~f a applies f to the elements of a in order, and returns  the
405       first result of the form Some v , or None if none exist.
406
407
408       Since 4.13.0
409
410
411
412
413   Arrays of pairs
414       val split : ('a * 'b) array -> 'a array * 'b array
415
416
417       split [|(a1,b1); ...; (an,bn)|] is ([|a1; ...; an|], [|b1; ...; bn|]) .
418
419
420       Since 4.13.0
421
422
423
424       val combine : 'a array -> 'b array -> ('a * 'b) array
425
426
427       combine  [|a1; ...; an|] [|b1; ...; bn|] is [|(a1,b1); ...; (an,bn)|] .
428       Raise Invalid_argument if the two arrays have different lengths.
429
430
431       Since 4.13.0
432
433
434
435
436   Sorting
437       val sort : cmp:('a -> 'a -> int) -> 'a array -> unit
438
439       Sort an array in increasing order according to a  comparison  function.
440       The  comparison  function  must  return  0  if its arguments compare as
441       equal, a positive integer if the first is greater, and a negative inte‐
442       ger  if  the first is smaller (see below for a complete specification).
443       For example, compare is a suitable comparison function.  After  calling
444       sort , the array is sorted in place in increasing order.  sort is guar‐
445       anteed to run in constant heap space and (at  most)  logarithmic  stack
446       space.
447
448       The  current  implementation uses Heap Sort.  It runs in constant stack
449       space.
450
451       Specification of the comparison function: Let a be the  array  and  cmp
452       the  comparison function.  The following must be true for all x , y , z
453       in a :
454
455       - cmp x y > 0 if and only if cmp y x < 0
456
457       -  if cmp x y >= 0 and cmp y z >= 0 then cmp x z >= 0
458
459       When sort returns, a contains the same elements as before, reordered in
460       such a way that for all i and j valid indices of a :
461
462       - cmp a.(i) a.(j) >= 0 if and only if i >= j
463
464
465
466
467       val stable_sort : cmp:('a -> 'a -> int) -> 'a array -> unit
468
469       Same  as  ArrayLabels.sort  , but the sorting algorithm is stable (i.e.
470       elements that compare equal are kept in their original order)  and  not
471       guaranteed to run in constant heap space.
472
473       The  current  implementation uses Merge Sort. It uses a temporary array
474       of length n/2 , where n is the length of  the  array.   It  is  usually
475       faster than the current implementation of ArrayLabels.sort .
476
477
478
479       val fast_sort : cmp:('a -> 'a -> int) -> 'a array -> unit
480
481       Same  as  ArrayLabels.sort  or  ArrayLabels.stable_sort  , whichever is
482       faster on typical input.
483
484
485
486
487   Arrays and Sequences
488       val to_seq : 'a array -> 'a Seq.t
489
490       Iterate on the array, in increasing order. Modifications of  the  array
491       during iteration will be reflected in the sequence.
492
493
494       Since 4.07
495
496
497
498       val to_seqi : 'a array -> (int * 'a) Seq.t
499
500       Iterate  on the array, in increasing order, yielding indices along ele‐
501       ments.  Modifications of the array during iteration will  be  reflected
502       in the sequence.
503
504
505       Since 4.07
506
507
508
509       val of_seq : 'a Seq.t -> 'a array
510
511       Create an array from the generator
512
513
514       Since 4.07
515
516
517
518
519
520OCamldoc                          2023-01-23                    ArrayLabels(3)