Module `Tablecloth.Map`Source

A collection of key-value pairs

A Map represents a unique mapping from keys to values.

Map is an immutable data structure which means operations like Map.add and Map.remove do not modify the data structure, but return a new map with the desired changes.

Since maps of ints and strings are so common the specialized Map.Int and Map.String modules are available, which offer a convenient way to construct new maps.

Custom data types can be used with maps as long as the module satisfies the Comparator.S interface.

  module Point = struct
    type t = int * int
    let compare = Tuple2.compare ~f:Int.compare ~g:Int.compare
    include Comparator.Make(struct
      type nonrec t = t
      let compare = compare
    end)
  end

  type animal =
    | Cow
    | Pig
    | Alpacca

  let point_to_animal : animal Map.Of(Point).t =
    Map.from_list (module Point) [((0, 0), Alpacca); ((3, 4), Cow); ((6, 7), Pig)]

See the Comparator module for a more details.

Sourcetype ('key, +'value, 'id) t = ('key, 'value, 'id) Base.Map.t

Sourcemodule Of (M : sig ... end) : sig ... end

This functor lets you describe the type of Maps a little more concisely.

Create

You can create sets of modules types which conform to the Comparator.S signature by using empty, singleton, from_list or from_array.

Specialised versions of the empty, singleton, from_list and from_array functions available in the Set.Int and Set.String sub-modules.

Source

val empty : 
  (module Tablecloth__.TableclothComparator.S
    with type identity = 'identity
     and type t = 'key) ->
  ('key, 'value, 'identity) t

A map with nothing in it.

Often used as an intial value for functions like Array.fold.

Examples

  Array.fold
    [|"Pear"; "Orange"; "Grapefruit"|]
    ~initial:(Map.empty (module Int))
    ~f:(fun length_to_fruit fruit ->
      Map.add length_to_fruit ~key:(String.length fruit) ~value:fruit
    )
  |> Map.to_array
  = [|(4, "Pear"); (6, "Orange"); (10, "Grapefruit")|]

In this particular case you might want to use Array.group_by

Source

val singleton : 
  (module Tablecloth__.TableclothComparator.S
    with type identity = 'identity
     and type t = 'key) ->
  key:'key ->
  value:'value ->
  ('key, 'value, 'identity) t

Create a map from a key and value.

Examples

Map.singleton (module Int) ~key:1 ~value:"Ant" |> Map.to_list = [(1, "Ant")]

Source

val from_array : 
  (module Tablecloth__.TableclothComparator.S
    with type identity = 'identity
     and type t = 'key) ->
  ('key * 'value) array ->
  ('key, 'value, 'identity) t

Create a map from an Array of key-value tuples.

Source

val from_list : 
  (module Tablecloth__.TableclothComparator.S
    with type identity = 'identity
     and type t = 'key) ->
  ('key * 'value) list ->
  ('key, 'value, 'identity) t

Create a map of a List of key-value tuples.

Basic operations

Source

val add : 
  ('key, 'value, 'id) t ->
  key:'key ->
  value:'value ->
  ('key, 'value, 'id) t

Adds a new entry to a map. If key is allready present, its previous value is replaced with value.

Examples

  Map.add
    (Map.Int.from_list [(1, "Ant"); (2, "Bat")])
    ~key:3
    ~value:"Cat"
  |> Map.to_list = [(1, "Ant"); (2, "Bat"); (3, "Cat")]

Map.add (Map.Int.from_list [(1, "Ant"); (2, "Bat")]) ~key:2 ~value:"Bug" |> Map.to_list = [(1, "Ant"); (2, "Bug")]

Sourceval (.?{}<-) : ('key, 'value, 'id) t -> 'key -> 'value -> ('key, 'value, 'id) t

The index operator version of add

Note Currently this is only supported by the OCaml syntax.

Examples

  let index_to_animal = Map.Int.from_list [(1, "Ant");(2, "Bat");(3, "Cat")] in
  let index_to_animal = numbers.Map.?{4} <- "Dog" in
  index_to_animal.Map.?{4} = Some "Dog"

Sourceval remove : ('key, 'value, 'id) t -> key:'key -> ('key, 'value, 'id) t

Removes a key-value pair from a map based on they provided key.

Examples

  let animal_populations = Map.String.from_list [
    ("Elephant", 3_156);
    ("Mosquito", 56_123_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ] in
  animal_populations |> Map.remove ~key:"Mosquito" |> Map.to_list = [
    ("Elephant", 3_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ]

Sourceval get : ('key, 'value, 'id) t -> key:'key -> 'value option

Get the value associated with a key. If the key is not present in the map, returns None.

Examples

let animal_populations = Map.String.from_list ("Elephant", 3_156); ("Mosquito", 56_123_156); ("Rhino", 3); ("Shrew", 56_423); in animal_populations |> Map.get ~key:"Shrew" = Some 56_423;

Sourceval (.?{}) : ('key, 'value, _) t -> 'key -> 'value option

The index operator version of Map.get

Note Currently this is only supported by the OCaml syntax.

Examples

  let index_to_animal = Map.Int.from_list [(1, "Ant");(2, "Bat");(3, "Cat")] in
  index_to_animal.Map.?{3} = Some "Cat"

Source

val update : 
  ('key, 'value, 'id) t ->
  key:'key ->
  f:('value option -> 'value option) ->
  ('key, 'value, 'id) t

Update the value for a specific key using f. If key is not present in the map f will be called with None.

Examples

  let animal_populations = Map.String.from_list [
    ("Elephant", 3_156);
    ("Mosquito", 56_123_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ] in

  animal_populations
  |> Map.update ~key:"Hedgehog" ~f:(fun population ->
    match population with
    | None -> Some 1
    | Some count -> Some (count + 1)
  )
  |> Map.to_list = [
    ("Elephant", 3_156);
    ("Hedgehog", 1);
    ("Mosquito", 56_123_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ]

Query

Sourceval is_empty : (_, _, _) t -> bool

Determine if a map is empty.

Sourceval length : (_, _, _) t -> int

Returns the number of key-value pairs present in the map.

Examples

  Map.Int.from_list [(1, "Hornet"); (3, "Marmot")]
  |> Map.length = 2

Sourceval any : (_, 'value, _) t -> f:('value -> bool) -> bool

Determine if f returns true for any values in a map.

Sourceval all : (_, 'value, _) t -> f:('value -> bool) -> bool

Determine if f returns true for all values in a map.

Source

val find : 
  ('key, 'value, _) t ->
  f:(key:'key -> value:'value -> bool) ->
  ('key * 'value) option

Returns, as an Option the first key-value pair for which f evaluates to true.

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

Searches starting from the smallest key

Examples

  Map.String.from_list [
    ("Elephant", 3_156);
    ("Mosquito", 56_123_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ]
  |> Map.find ~f:(fun ~key ~value -> value > 10_000)
    = Some ("Mosquito", 56_123_156)

Sourceval includes : ('key, _, _) t -> key:'key -> bool

Determine if a map includes key.

Sourceval minimum : ('key, _, _) t -> 'key option

Returns, as an Option, the smallest key in the map.

Returns None if the map is empty.

Examples

  Map.Int.from_list [(8, "Pigeon"); (1, "Hornet"); (3, "Marmot")]
  |> Map.minimum = Some 1

Sourceval maximum : ('key, _, _) t -> 'key option

Returns the largest key in the map.

Returns None if the map is empty.

Examples

  Map.Int.from_list [(8, "Pigeon"); (1, "Hornet"); (3, "Marmot")]
  |> Map.maximum = Some 8

Sourceval extent : ('key, _, _) t -> ('key * 'key) option

Returns, as an Option, a Tuple of the (minimum, maximum) keys in the map.

Returns None if the map is empty.

Examples

  Map.Int.from_list [(8, "Pigeon"); (1, "Hornet"); (3, "Marmot")]
  |> Map.extent = Some (1, 8)

Combine

Source

val merge : 
  ('key, 'v1, 'id) t ->
  ('key, 'v2, 'id) t ->
  f:('key -> 'v1 option -> 'v2 option -> 'v3 option) ->
  ('key, 'v3, 'id) t

Combine two maps.

You provide a function f which is provided the key and the optional value from each map and needs to account for the three possibilities:

Only the 'left' map includes a value for the key.
Both maps contain a value for the key.
Only the 'right' map includes a value for the key.

You then traverse all the keys, building up whatever you want.

Examples

  let animal_to_population =
    Map.String.from_list [
      ("Elephant", 3_156);
      ("Shrew", 56_423);
    ]
  in
  let animal_to_population_growth_rate = Map.String.from_list [
    ("Elephant", 0.88);
    ("Squirrel", 1.2);
    ("Python", 4.0);
  ] in

  Map.merge
    animal_to_population
    animal_to_population_growth_rate
    ~f:(fun _animal population growth ->
      match (Option.both population growth) with
      | Some (population, growth) ->
          Some Float.((from_int population) * growth)
      | None -> None
    )
  |> Map.to_list
    = [("Elephant", 2777.28)]

Transform

Sourceval map : ('key, 'value, 'id) t -> f:('value -> 'b) -> ('key, 'b, 'id) t

Apply a function to all values in a dictionary.

Examples

  Map.String.from_list [
    ("Elephant", 3_156);
    ("Shrew", 56_423);
  ]
  |> Map.map ~f:Int.to_string
  |> Map.to_list
    = [
    ("Elephant", "3156");
    ("Shrew", "56423");
  ]

Source

val map_with_index : 
  ('key, 'value, 'id) t ->
  f:('key -> 'value -> 'b) ->
  ('key, 'b, 'id) t

Like map but f is also called with each values corresponding key.

Source

val filter : 
  ('key, 'value, 'id) t ->
  f:('value -> bool) ->
  ('key, 'value, 'id) t

Keep elements that f returns true for.

Examples

  Map.String.from_list [
    ("Elephant", 3_156);
    ("Shrew", 56_423);
  ]
  |> Map.filter ~f:(fun population -> population > 10_000)
  |> Map.to_list
    = [
    ("Shrew", 56423);
  ]

Source

val filter_map : 
  ('key, 'value, 'id) t ->
  f:(key:'key -> value:'value -> 'b option) ->
  ('key, 'b, 'id) t

Source

val partition : 
  ('key, 'value, 'id) t ->
  f:(key:'key -> value:'value -> bool) ->
  ('key, 'value, 'id) t * ('key, 'value, 'id) t

Divide a map into two, the first map will contain the key-value pairs that f returns true for, pairs that f returns false for will end up in the second.

Examples

  let (endangered, not_endangered) = Map.String.from_list [
    ("Elephant", 3_156);
    ("Mosquito", 56_123_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ]
  |> Map.partition ~f:(fun ~key:_  -> fun ~value:population  -> population < 10000)
  in

  Map.to_list endangered = [
    ("Elephant", 3_156);
    ("Rhino", 3);
  ];

  Map.to_list not_endangered = [
    ("Mosquito", 56_123_156);
    ("Shrew", 56_423);
  ];

Source

val fold : 
  ('key, 'value, _) t ->
  initial:'a ->
  f:('a -> key:'key -> value:'value -> 'a) ->
  'a

Like Array.fold but f is also called with both the key and value.

Iterate

Sourceval for_each : (_, 'value, _) t -> f:('value -> unit) -> unit

Runs a function f against each value in the map.

Source

val for_each_with_index : 
  ('key, 'value, _) t ->
  f:(key:'key -> value:'value -> unit) ->
  unit

Like Map.for_each except ~f is also called with the corresponding key.

Convert

Sourceval keys : ('key, _, _) t -> 'key list

Get a List of all of the keys in a map.

Examples

  Map.String.from_list [
    ("Elephant", 3_156);
    ("Mosquito", 56_123_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ]
  |> Map.keys = [
    "Elephant";
    "Mosquito";
    "Rhino";
    "Shrew";
  ]

Sourceval values : (_, 'value, _) t -> 'value list

Get a List of all of the values in a map.

Examples

  Map.String.from_list [
    ("Elephant", 3_156);
    ("Mosquito", 56_123_156);
    ("Rhino", 3);
    ("Shrew", 56_423);
  ]
  |> Map.values = [
    3_156;
    56_123_156;
    3;
    56_423;
  ]

Sourceval to_array : ('key, 'value, _) t -> ('key * 'value) array

Get an Array of all of the key-value pairs in a map.

Sourceval to_list : ('key, 'value, _) t -> ('key * 'value) list

Get a List of all of the key-value pairs in a map.

Sourcemodule Poly : sig ... end

Construct a Map which can be keyed by any data type using the polymorphic compare function.

Sourcemodule Int : sig ... end

Construct a Map with Ints for keys.

Sourcemodule String : sig ... end

Construct a Map with Strings for keys.

package tablecloth-base

Module Tablecloth.MapSource

Create

Basic operations

Query

Combine

Transform

Iterate

Convert

Module `Tablecloth.Map`Source