Module `Tablecloth.Array`Source

A fixed lenfth collection of values

A mutable vector of elements which must have the same type.

Has constant time (O(1)) get, set and length operations.

Arrays have a fixed length, if you want to be able to add an arbitrary number of elements maybe you want a List.

Sourcetype 'a t = 'a array

Create

You can create an array in OCaml with the [|1; 2; 3|] syntax.

Sourceval singleton : 'a -> 'a t

Create an array with only one element.

Examples

Array.singleton 1234 = [|1234|]

Array.singleton "hi" = [|"hi"|]

Sourceval repeat : 'a -> length:int -> 'a t

Creates an array of length length with the value x populated at each index.

Examples

Array.repeat ~length:5 'a' = [|'a'; 'a'; 'a'; 'a'; 'a'|]

Array.repeat ~length:0 7 = [||]

Array.repeat ~length:(-1) "Why?" = [||]

Sourceval range : ?from:int -> int -> int t

Creates an array containing all of the integers from from if it is provided or 0 if not, up to but not including to.

Examples

Array.range 5 = [|0; 1; 2; 3; 4|]

Array.range ~from:2 5 = [|2; 3; 4|]

Array.range ~from:(-2) 3 = [|-2; -1; 0; 1; 2|]

Sourceval initialize : int -> f:(int -> 'a) -> 'a t

Initialize an array. Array.initialize n ~f creates an array of length n with the element at index i initialized to the result of (f i).

Examples

Array.initialize 4 ~f:identity = [|0; 1; 2; 3|]

Array.initialize 4 ~f:(fun n -> n * n) = [|0; 1; 4; 9|]

Sourceval from_list : 'a list -> 'a t

Create an array from a List.

Examples

Array.from_list [1;2;3] = [|1;2;3|]

Sourceval clone : 'a t -> 'a t

Create a shallow copy of an array.

Examples

  let numbers = [|1;2;3|] in
  let other_numbers = Array.copy numbers in
  numbers.(1) <- 9;
  numbers = [|1;9;3|];
  other_numbers = [|1;2;3|];

  let number_grid = [|
    [|1;2;3|];
    [|4;5;6|];
    [|7;8;9|];
  |] in

  let number_grid_copy = Array.copy number_grid in

  number_grid.(1).(1) <- 0;

  number_grid_copy.(1).(1) = 9;

Basic operations

Sourceval get : 'a t -> int -> 'a

Get the element at the specified index.

The first element has index number 0.

The last element has index number Array.length a - 1.

You should prefer using the dedicated literal syntax:

array.(n)

Or using the safer Array.get_at function.

Exceptions

Raises Invalid_argument "index out of bounds" for indexes outside of the range 0 to (Array.length a - 1).

Examples

[|1; 2; 3; 2; 1|].(3) = 2

  let animals = [|"cat"; "dog"; "eel"|] in
  animals.(2) = "eel"

Sourceval get_at : 'a t -> index:int -> 'a option

Returns, as an Option, the element at index number n of array a.

Returns None if n is outside the range 0 to (Array.length a - 1).

Examples

Array.get_at [|0; 1; 2|] ~index:5 = None

Array.get_at [||] ~index:0 = None

Sourceval (.?()) : 'element array -> int -> 'element option

The index operator version of get_at

Note Currently this is only supported by the OCaml syntax.

Examples

Array.([||].?(3)) = Some 'g'

Array.([||].?(9)) = None

Sourceval set : 'a t -> int -> 'a -> unit

Modifies an array in place, replacing the element at index with value.

You should prefer either to write

array.(index) <- value

Or use the set_at function instead.

Exceptions

Raises Invalid_argument "index out of bounds" if n is outside the range 0 to Array.length a - 1.

Examples

  let numbers = [|1;2;3|] in
  Array.set numbers 1 1;
  numbers.(2) <- 0;

  numbers = [|1;1;0|]

Sourceval set_at : 'a t -> index:int -> value:'a -> unit

Like set but with labelled arguments.

Sourceval first : 'a t -> 'a option

Get the first element of an array.

Returns None if the array is empty.

Examples

Array.first [|1;2;3|] = Some 1

Array.first [|1|] = Some 1

Array.first [||] = None

Sourceval last : 'a t -> 'a option

Get the last element of an array.

Returns None if the array is empty.

Examples

Array.last [1;2;3] = Some 3

Array.last [1] = Some 1

Array.last [] = None

Sourceval slice : ?to_:int -> 'a t -> from:int -> 'a t

Get a sub-section of a list. from is a zero-based index where we will start our slice.

The to_ is a zero-based index that indicates the end of the slice.

The slice extracts up to but not including to_.

Both the from and to_ indexes can be negative, indicating an offset from the end of the list.

Examples

Array.slice ~from:0 ~to_:3 [0; 1; 2; 3; 4] = [0; 1; 2]

Array.slice ~from:1 ~to_:4 [0; 1; 2; 3; 4] = [1; 2; 3]

Array.slice ~from:5 ~to_:3 [0; 1; 2; 3; 4] = []

Array.slice ~from:1 ~to_:(-1) [0; 1; 2; 3; 4] = [1; 2; 3]

Array.slice ~from:(-2) ~to_:5 [0; 1; 2; 3; 4] = [3; 4]

Array.slice ~from:(-2) ~to_:(-1) [0; 1; 2; 3; 4] = [3]

Sourceval swap : 'a t -> int -> int -> unit

Swaps the values at the provided indicies.

Exceptions

Raises an Invalid_argument exception of either index is out of bounds for the array.

Examples

Array.swap [|1; 2; 3|] 1 2 = [|1; 3; 2|]

Sourceval reverse : 'a t -> unit

Reverses an array in place, mutating the existing array.

Examples

  let numbers = [|1; 2; 3|] in
  Array.reverse numbers;
  numbers = [|3; 2; 1|];

Sourceval sort : 'a t -> compare:('a -> 'a -> int) -> unit

Sort in place, modifying the existing array, using the provided compare function to determine order.

On native it uses merge sort which means the sort is stable, runs in constant heap space, logarithmic stack space and n * log (n) time.

When targeting javascript the time and space complexity of the sort cannot be guaranteed as it depends on the implementation.

Examples

Array.sort_in_place [|5;6;8;3;6|] ~compare:compare = [|3;5;6;6;8|]

Query

Sourceval is_empty : 'a t -> bool

Check if an array is empty.

Examples

Array.is_empty [|1; 2; 3|] = false

Array.is_empty [||] = true

Sourceval length : 'a t -> int

Return the length of an array.

Examples

Array.length [|1; 2; 3|] = 3

Array.length [||] = 0

Sourceval any : 'a t -> f:('a -> bool) -> bool

Determine if f returns true for any values in an array.

Iteration is stopped as soon as f returns true.

Examples

Array.any ~f:Int.is_even [|1;2;3;5|] = true

Array.any ~f:Int.is_even [|1;3;5;7|] = false

Array.any ~f:Int.is_even [||] = false

Sourceval all : 'a t -> f:('a -> bool) -> bool

Determine if f returns true for all values in an array.

Iteration is stopped as soon as f returns false.

Examples

Array.all ~f:Int.is_even [|2;4|] = true

Array.all ~f:Int.is_even [|2;3|] = false

Array.all ~f:Int.is_even [||] = true

Sourceval count : 'a t -> f:('a -> bool) -> int

Count the number of elements which function f will return true.

Examples

Array.count [|7; 5; 8; 6|] ~f:Int.is_even = 2

Sourceval find : 'a t -> f:('a -> bool) -> 'a option

Returns, as an Option, the first element for which f evaluates to true.

If f doesn't return true for any of the elements find will return None

Examples

Array.find ~f:Int.is_even [|1; 3; 4; 8;|] = Some 4

Array.find ~f:Int.is_odd [|0; 2; 4; 8;|] = None

Array.find ~f:Int.is_even [||] = None

Sourceval find_index : 'a t -> f:(int -> 'a -> bool) -> (int * 'a) option

Similar to Array.find but f is also called with the current index, and the return value will be a tuple of the index the passing value was found at and the passing value.

Examples

Array.find_index [|1; 3; 4; 8;|] ~f:(fun index number -> index > 2 && Int.is_even number) = Some (3, 8)

Sourceval includes : 'a t -> 'a -> equal:('a -> 'a -> bool) -> bool

Test if an array contains the specified element using the provided equal to test for equality.

Examples

Array.includes [|1; 2; 3|]  2 ~equal:(=) = true

Sourceval minimum : 'a t -> compare:('a -> 'a -> int) -> 'a option

Find the smallest element using the provided compare function.

Returns None if called on an empty array.

Examples

Array.minimum [|7;5;8;6|] ~compare:Int.compare = Some 5

Array.minimum [||] ~compare:Int.compare = None

Sourceval maximum : 'a t -> compare:('a -> 'a -> int) -> 'a option

Find the largest element using the provided compare function.

Returns None if called on an empty array.

Examples

Array.maximum [|7;5;8;6|] ~compare:Int.compare = Some 8

Array.maximum [||] ~compare:Int.compare = None

Sourceval extent : 'a t -> compare:('a -> 'a -> int) -> ('a * 'a) option

Find a Tuple2 of the minimum and maximum in a single pass.

Returns None if called on an empty array.

Examples

Array.extent [|7;5;8;6|] ~compare:Int.compare = Some (5, 8)

Array.extent [|7|] ~compare:Int.compare = Some (7, 7)

Array.extent [||] ~compare:Int.compare = None

Source

val sum : 
  'a t ->
  (module Tablecloth__.TableclothContainer.Sum with type t = 'a) ->
  'a

Calculate the sum of an array using the provided modules zero value and add function.

Examples

Array.sum [|1; 2; 3|] (module Int) = 6

Array.sum [|4.0; 4.5; 5.0|] (module Float) = 13.5

  Array.sum
    [|"a"; "b"; "c"|]
    (
      module struct
        type t = string
        let zero = ""
        let add = (^)
      end
    )
    = "abc"

Transform

Sourceval map : 'a t -> f:('a -> 'b) -> 'b t

Create a new array which is the result of applying a function f to every element.

Examples

Array.map ~f:Float.square_root [|1.0; 4.0; 9.0|] = [|1.0; 2.0; 3.0|]

Sourceval map_with_index : 'a t -> f:(int -> 'a -> 'b) -> 'b t

Apply a function f to every element with its index as the first argument.

Examples

Array.map_with_index ~f:( * ) [|5; 5; 5|] = [|0; 5; 10|]

Sourceval filter : 'a t -> f:('a -> bool) -> 'a t

Keep elements where function f will return true.

Examples

Array.filter ~f:Int.is_even [|1; 2; 3; 4; 5; 6|] = [|2; 4; 6|]

Sourceval filter_map : 'a t -> f:('a -> 'b option) -> 'b t

Allows you to combine map and filter into a single pass.

The output array only contains elements for which f returns Some.

Why filter_map and not just filter then map?

filter_map removes the Option layer automatically.

If your mapping is already returning an Option and you want to skip over Nones, then filter_map is much nicer to use.

Examples

  let characters = [|'a'; '9'; '6'; ' '; '2'; 'z' |] in
  Array.filter_map characters ~f:Char.to_digit = [|9; 6; 2|]

  Array.filter_map [|3; 4; 5; 6|] ~f:(fun number ->
    if Int.is_even number then
      Some (number * number)
    else
      None
  ) = [|16; 36|]

Sourceval flat_map : 'a t -> f:('a -> 'b t) -> 'b t

map f onto an array and flatten the resulting arrays.

Examples

Array.flat_map ~f:(fun n -> [|n; n|]) [|1; 2; 3|] = [|1; 1; 2; 2; 3; 3|]

Sourceval fold : 'a t -> initial:'b -> f:('b -> 'a -> 'b) -> 'b

Produce a new value from an array.

fold takes two arguments, an initial 'accumulator' value and a function f.

For each element of the array f will be called with two arguments: the current accumulator and an element.

f returns the value that the accumulator should have for the next iteration.

The initial value is the value the accumulator will have on the first call to f.

After applying f to every element of the array, fold returns the accumulator.

fold iterates over the elements of the array from first to last.

Folding is useful whenever you have a collection of something, and want to produce a single value from it.

For example, if we have:

  let numbers = [|1, 2, 3|] in
  let sum =
    Array.fold numbers ~initial:0 ~f:(fun accumulator element -> accumulator +element)
  in
  sum = 6

Walking though each iteration step by step:

accumulator: 0, element: 1, result: 1
accumulator: 1, element: 2, result: 3
accumulator: 3, element: 3, result: 6

And so the final result is 6. (Note that in reality you probably want to use Array.sum)

Examples

Array.fold [|3;4;5|] ~f:Int.multiply ~initial:2 = 120

  Array.fold [|1; 1; 2; 2; 3|] ~initial:Set.Int.empty ~f:Set.add |> Set.to_array = [|1; 2; 3|]

  let last_even integers =
    Array.fold integers ~initial:None ~f:(fun last int ->
      if Int.is_even then
        Some int
      else
        last
    )
  in
  last_even [|1;2;3;4;5|] = Some 4

Sourceval fold_right : 'a t -> initial:'b -> f:('b -> 'a -> 'b) -> 'b

This method is like fold except that it iterates over the elements of the array from last to first.

Examples

Array.fold_right ~f:(+) ~initial:0 (Array.repeat ~length:3 5) = 15

Array.fold_right [|3;4;5|] ~f:Int.multiply ~initial:2 = 120

Sourceval append : 'a t -> 'a t -> 'a t

Creates a new array which is the result of appending the second array onto the end of the first.

Examples

  let forty_twos = Array.repeat ~length:2 42 in
  let eighty_ones = Array.repeat ~length:3 81 in
  Array.append fourty_twos eighty_ones = [|42; 42; 81; 81; 81|];

Sourceval flatten : 'a t t -> 'a t

Flatten an array of arrays into a single array:

Examples

Array.flatten [|[|1; 2|]; [|3|]; [|4; 5|]|] = [|1; 2; 3; 4; 5|]

Sourceval zip : 'a t -> 'b t -> ('a * 'b) t

Combine two arrays by merging each pair of elements into a Tuple2.

If one array is longer, the extra elements are dropped.

The same as Array.map2 ~f:Tuple2.make

Examples

Array.zip [|1;2;3;4;5|] [|"Dog"; "Eagle"; "Ferret"|] = [|(1, "Dog"); (2, "Eagle"); (3, "Ferret")|]

Sourceval map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t

Combine two arrays, using f to combine each pair of elements.

If one array is longer, the extra elements are dropped.

Examples

  let totals (xs : int array) (ys : int array) : int array =
    Array.map2 ~f:(+) xs ys in

  totals [|1;2;3|] [|4;5;6|] = [|5;7;9|]

  Array.map2
    ~f:Tuple2.make
    [|"alice"; "bob"; "chuck"|]
    [|2; 5; 7; 8|] =
      [|("alice",2); ("bob",5); ("chuck",7)|]

Sourceval map3 : 'a t -> 'b t -> 'c t -> f:('a -> 'b -> 'c -> 'd) -> 'd t

Combine three arrays, using f to combine each trio of elements.

If one array is longer, the extra elements are dropped.

Examples

  Array.map3
    ~f:Tuple3.make
    [|"alice"; "bob"; "chuck"|]
    [|2; 5; 7; 8;|]
    [|true; false; true; false|] =
      [|("alice", 2, true); ("bob", 5, false); ("chuck", 7, true)|]

Deconstruct

Sourceval partition : 'a t -> f:('a -> bool) -> 'a t * 'a t

Split an array into a Tuple2 of arrays. Values which f returns true for will end up in Tuple2.first.

Examples

Array.partition [|1;2;3;4;5;6|] ~f:Int.is_odd = ([|1;3;5|], [|2;4;6|])

Sourceval split_at : 'a t -> index:int -> 'a t * 'a t

Divides an array into a Tuple2 of arrays.

Elements which have index upto (but not including) index will be in the first component of the tuple.

Elements with an index greater than or equal to index will be in the second.

Exceptions

Raises an Invalid_argument exception if index is less than zero.

Examples

Array.split_at [|1;2;3;4;5|] ~index:2 = ([|1;2|], [|3;4;5|])

Array.split_at [|1;2;3;4;5|] ~index:10 = ([|1;2;3;4;5|], [||])

Array.split_at [|1;2;3;4;5|] ~index:0 = ([||], [|1;2;3;4;5|])

Sourceval split_when : 'a t -> f:('a -> bool) -> 'a t * 'a t

Divides an array at the first element f returns true for.

Returns a Tuple2, the first component contains the elements f returned false for, the second component includes the element that f retutned true for an all the remaining elements.

Examples

  Array.split_when
    [|5; 7; 8; 6; 4;|]
    ~f:Int.is_even =
    ([|5; 7|], [|8; 6; 4|])

  Array.split_when
    [|"Ant"; "Bat"; "Cat"|]
    ~f:(fun animal -> String.length animal > 3) =
      ([|"Ant"; "Bat"; "Cat"|], [||])

  Array.split_when [|2.; Float.pi; 1.111|] ~f:Float.is_integer =
    ([||], [|2.; Float.pi; 1.111|])

Sourceval unzip : ('a * 'b) t -> 'a t * 'b t

Decompose an array of Tuple2s into a Tuple2 of arrays.

Examples

Array.unzip [|(0, true); (17, false); (1337, true)|] = ([|0; 17; 1337|], [|true; false; true|])

Iterate

Sourceval for_each : 'a t -> f:('a -> unit) -> unit

Iterates over the elements of invokes f for each element.

Examples

Array.for_each [|1; 2; 3|] ~f:(fun int -> print (Int.to_string int))

Sourceval for_each_with_index : 'a t -> f:(int -> 'a -> unit) -> unit

Iterates over the elements of invokes f for each element.

Examples

  Array.for_each_with_index [|1; 2; 3|] ~f:(fun index int -> printf "%d: %d" index int)
  (*
    0: 1
    1: 2
    2: 3
  *)

Sourceval values : 'a option t -> 'a t

Return all of the Some values from an array of options.

Examples

Array.values [|(Some "Ant"); None; (Some "Cat")|] = [|"Ant"; "Cat"|]

Array.values [|None; None; None|] = [||]

Sourceval intersperse : 'a t -> sep:'a -> 'a t

Places sep between all the elements of the given array.

Examples

  Array.intersperse ~sep:"on" [|"turtles"; "turtles"; "turtles"|] =
  [|"turtles"; "on"; "turtles"; "on"; "turtles"|]

Array.intersperse ~sep:0 [||] = [||]

Sourceval chunks_of : 'a t -> size:int -> 'a t t

Split an array into equally sized chunks.

If there aren't enough elements to make the last 'chunk', those elements are ignored.

Examples

  Array.chunks_of ~size:2 [|"#FFBA49"; "#9984D4"; "#20A39E"; "#EF5B5B"; "#23001E"|] =  [|
    [|"#FFBA49"; "#9984D4"|];
    [|"#20A39E"; "#EF5B5B"|];
  |]

Sourceval sliding : ?step:int -> 'a t -> size:int -> 'a t t

Provides a sliding 'window' of sub-arrays over an array.

The first sub-array starts at index 0 of the array and takes the first size elements.

The sub-array then advances the index step (which defaults to 1) positions before taking the next size elements.

The sub-arrays are guaranteed to always be of length size and iteration stops once a sub-array would extend beyond the end of the array.

Examples

Array.sliding [|1;2;3;4;5|] ~size:1 = [|[|1|]; [|2|]; [|3|]; [|4|]; [|5|]|]

Array.sliding [|1;2;3;4;5|] ~size:2 = [|[|1;2|]; [|2;3|]; [|3;4|]; [|4;5|]|]

Array.sliding [|1;2;3;4;5|] ~size:3 = [|[|1;2;3|]; [|2;3;4|]; [|3;4;5|]|]

Array.sliding [|1;2;3;4;5|] ~size:2 ~step:2 = [|[|1;2|]; [|3;4|]|]

Array.sliding [|1;2;3;4;5|] ~size:1 ~step:3 = [|[|1|]; [|4|]|]

Convert

Sourceval join : string t -> sep:string -> string

Converts an array of strings into a String, placing sep between each string in the result.

Examples

Array.join [|"Ant"; "Bat"; "Cat"|] ~sep:", " = "Ant, Bat, Cat"

Source

val group_by : 
  'value t ->
  (module Tablecloth__.TableclothComparator.S
    with type identity = 'id
     and type t = 'key) ->
  f:('value -> 'key) ->
  ('key, 'value list, 'id) Base.Map.t

Collect elements where function f will produce the same key.

Produces a map from 'key to a List of all elements which produce the same 'key.

Examples

  let animals = [|"Ant"; "Bear"; "Cat"; "Dewgong"|] in
  Array.group_by animals (module Int) ~f:String.length = Map.Int.fromArray [|
    (3, ["Cat"; "Ant"]);
    (4, ["Bear"]);
    (7, ["Dewgong"]);
  |]

Sourceval to_list : 'a t -> 'a list

Create a List of elements from an array.

Examples

Array.to_list [|1;2;3|] = [1;2;3]

Array.to_list (Array.from_list [3; 5; 8]) = [3; 5; 8]

Sourceval to_indexed_list : 'a t -> (int * 'a) list

Create an indexed List from an array. Each element of the array will be paired with its index as a Tuple2.

Examples

Array.to_indexed_list [|"cat"; "dog"|] = [(0, "cat"); (1, "dog")]

Sourceval equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool

Test two arrays for equality using the provided function to test pairs of elements.

Sourceval compare : f:('a -> 'a -> int) -> 'a t -> 'a t -> int

Compare two arrays using the f function to compare pairs of elements.

A shorter array is 'less' than a longer one.

Examples

Array.compare ~f:Int.compare [|1;2;3|] [|1;2;3;4|] = (-1)

Array.compare ~f:Int.compare [|1;2;3|] [|1;2;3|] = 0

Array.compare ~f:Int.compare [|1;2;5|] [|1;2;3|] = 1

package tablecloth-base

Module Tablecloth.ArraySource

Create

Basic operations

Query

Transform

Deconstruct

Iterate

Convert

Module `Tablecloth.Array`Source