Module Tablecloth.Map
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 int
s and string
s 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 Int.compare Int.compare
include Comparator.Make(struct
type nonrec t = t
let compare = compare
end)
end
type animal =
| Cow
| Pig
| Alpacca
let pointToAnimal : animal Map.Of(Point).t =
Map.fromList (module Points) [((0, 0), Alpacca); ((3, 4), Cow); ((6, 7), Sheep)]
See the Comparator
module for a more details.
type ('key, +'value, 'id) t = ('key , 'value , 'id ) Base.Map.t
module Of (M : sig ... end ) : sig ... end
This functor lets you describe the type of Maps a little more concisely.
CreateYou can create sets of modules types which conform to the Comparator.S
signature by using empty
, singleton
, fromList
or fromArray
.
Specialised versions of the empty
, singleton
, fromList
and fromArray
functions available in the Set.Int
and Set.String
sub-modules.
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 lengthToFruit fruit ->
Map.add lengthToFruit (String.length fruit) fruit
)
|> Map.toArray
= [|(4, "Pear"); (6, "Orange"), (10, "Grapefruit")|]
In this particular case you might want to use Array.groupBy
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.toList = [(1, "Ant")]
val fromArray :
(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
val from_array :
(module Tablecloth__.TableclothComparator.S
with type identity = 'identity
and type t = 'key ) ->
('key * 'value ) array ->
('key , 'value , 'identity ) t
val fromList :
(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
val from_list :
(module Tablecloth__.TableclothComparator.S
with type identity = 'identity
and type t = 'key ) ->
('key * 'value ) list ->
('key , 'value , 'identity ) t
Basic operationsval 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.fromList [(1, "Ant"); (2, "Bat")])
~key:3
~value:"Cat"
|> Map.toList = [(1, "Ant"); (2, "Bat"); (3, "Cat")]
Map.add (Map.Int.fromList [(1, "Ant"); (2, "Bat")]) ~key:2 ~value:"Bug" |> Map.toList = [(1, "Ant"); (2, "Bug")]
val (.?{}<-) : ('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 indexToAnimal = Map.Int.fromList [(1, "Ant");(2, "Bat");(3, "Cat")] in
let indexToAnimal = numbers.Map.?{4} <- "Dog" in
indexToAnimal.Map.?{4} = Some "Dog"
val remove : ('key , 'value , 'id ) t -> 'key -> ('key , 'value , 'id ) t
Removes a key-value pair from a map based on they provided key.
Examples
let animalPopulations = Map.String.fromList [
("Elephant", 3_156);
("Mosquito", 56_123_156);
("Rhino", 3);
("Shrew", 56_423);
] in
Map.remove animalPopulations "Mosquito" |> Map.toList = [
("Elephant", 3_156);
("Rhino", 3);
("Shrew", 56_423);
]
val get : ('key , 'value , 'id ) t -> 'key -> 'value option
Get the value associated with a key. If the key is not present in the map, returns None
.
Examples
let animalPopulations = Map.String.fromList ("Elephant", 3_156); ("Mosquito", 56_123_156); ("Rhino", 3); ("Shrew", 56_423);
in Map.get animalPopulations "Shrew" = Some 56_423;
val (.?{}) : ('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 indexToAnimal = Map.Int.fromList [(1, "Ant");(2, "Bat");(3, "Cat")] in
indexToAnimal.Map.?{3} = Some "Cat"
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 animalPopulations = Map.String.fromList [
("Elephant", 3_156);
("Mosquito", 56_123_156);
("Rhino", 3);
("Shrew", 56_423);
] in
Map.update animalPopulations ~key:"Hedgehog" ~f:(fun population ->
match population with
| None -> Some 1
| Some count -> Some (count + 1)
)
|> Map.toList = [
("Elephant", 3_156);
("Hedgehog", 1);
("Mosquito", 56_123_156);
("Rhino", 3);
("Shrew", 56_423);
]
Queryval isEmpty : (_ , _ , _ ) t -> bool
Determine if a map is empty.
val is_empty : (_ , _ , _ ) t -> bool
val length : (_ , _ , _ ) t -> int
Returns the number of key-value pairs present in the map.
Examples
Map.Int.fromList [(1, "Hornet"); (3, "Marmot")]
|> Map.length = 2
val any : (_ , 'value , _ ) t -> f :('value -> bool) -> bool
Determine if f
returns true
for any
values in a map.
val all : (_ , 'value , _ ) t -> f :('value -> bool) -> bool
Determine if f
returns true
for all
values in a map.
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.fromList [
("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)
val includes : ('key , _ , _ ) t -> 'key -> bool
Determine if a map includes key
.
val 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.fromList [(8, "Pigeon"); (1, "Hornet"); (3, "Marmot")]
|> Map.minimum = Some 1
val maximum : ('key , _ , _ ) t -> 'key option
Returns the largest key in the map.
Returns None
if the map is empty.
Examples
Map.Int.fromList [(8, "Pigeon"); (1, "Hornet"); (3, "Marmot")]
|> Map.maximum = Some 8
val extent : ('key , _ , _ ) t -> ('key * 'key ) option
Returns, as an Option
, a Tuple
of the (minimum, maximum)
key s in the map.
Returns None
if the map is empty.
Examples
Map.Int.fromList [(8, "Pigeon"); (1, "Hornet"); (3, "Marmot")]
|> Map.extent = Some (1, 8)
Combineval 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:
1. Only the 'left' map includes a value for the key. 2. Both maps contain a value for the key. 3. Only the 'right' map includes a value for the key.
You then traverse all the keys, building up whatever you want.
Examples
let animalToPopulation =
Map.String.fromList [
("Elephant", 3_156);
("Shrew", 56_423);
]
in
let animalToPopulationGrowthRate = Map.String.fromList [
("Elephant", 0.88);
("Squirrel", 1.2);
("Python", 4.0);
] in
Map.merge
animalToPopulation
animalToPopulationGrowthRate
~f:(fun _animal population growth ->
match (Option.both population growth) with
| Some (population, growth) ->
Some Float.((ofInt population) * growth)
| None -> None
)
|> Map.toList
= [("Elephant", 2777.28)]
val map : ('key , 'value , 'id ) t -> f :('value -> 'b ) -> ('key , 'b , 'id ) t
Apply a function to all values in a dictionary.
Examples
Map.String.fromList [
("Elephant", 3_156);
("Shrew", 56_423);
]
|> Map.map ~f:Int.toString
|> Map.toList
= [
("Elephant", "3156");
("Shrew", "56423");
]
val mapWithIndex :
('key , 'value , 'id ) t ->
f :('key -> 'value -> 'b ) ->
('key , 'b , 'id ) t
Like map
but f
is also called with each values corresponding key
val map_with_index :
('key , 'value , 'id ) t ->
f :('key -> 'value -> 'b ) ->
('key , 'b , 'id ) t
val filter :
('key , 'value , 'id ) t ->
f :('value -> bool) ->
('key , 'value , 'id ) t
Keep elements that f
returns true
for.
Examples
Map.String.fromList [
("Elephant", 3_156);
("Shrew", 56_423);
]
|> Map.map ~f:(fun population -> population > 10_000)
|> Map.toList
= [
("Shrew", "56423");
]
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, notEndangered) = Map.String.fromList [
("Elephant", 3_156);
("Mosquito", 56_123_156);
("Rhino", 3);
("Shrew", 56_423);
]
|> Map.partition ~f:(fun population -> population < 10_000)
in
Map.toList endangered = [
("Elephant", 3_156);
("Rhino", 3);
];
Map.toList notEndangered = [
("Mosquito", 56_123_156);
("Shrew", 56_423);
];
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
Iterateval forEach : (_ , 'value , _ ) t -> f :('value -> unit) -> unit
Runs a function f
against each value in the map.
val for_each : (_ , 'value , _ ) t -> f :('value -> unit) -> unit
val forEachWithIndex :
('key , 'value , _ ) t ->
f :(key :'key -> value :'value -> unit) ->
unit
Like Map.forEach
except ~f
is also called with the corresponding key
val for_each_with_index :
('key , 'value , _ ) t ->
f :(key :'key -> value :'value -> unit) ->
unit
Convertval keys : ('key , _ , _ ) t -> 'key list
Get a List
of all of the keys in a map.
Examples
Map.String.fromList [
("Elephant", 3_156);
("Mosquito", 56_123_156);
("Rhino", 3);
("Shrew", 56_423);
]
|> Map.keys = [
"Elephant";
"Mosquito";
"Rhino";
"Shrew";
]
val values : (_ , 'value , _ ) t -> 'value list
Get a List
of all of the values in a map.
Examples
Map.String.fromList [
("Elephant", 3_156);
("Mosquito", 56_123_156);
("Rhino", 3);
("Shrew", 56_423);
]
|> Map.values = [
3_156;
56_123_156;
3;
56_423;
]
val toArray : ('key , 'value , _ ) t -> ('key * 'value ) array
Get an Array
of all of the key-value pairs in a map.
val to_array : ('key , 'value , _ ) t -> ('key * 'value ) array
val toList : ('key , 'value , _ ) t -> ('key * 'value ) list
Get a List
of all of the key-value pairs in a map.
val to_list : ('key , 'value , _ ) t -> ('key * 'value ) list
module Poly : sig ... end
Construct a Map which can be keyed by any data type using the polymorphic compare
function.
Construct a Map with Int
s for keys.
Construct a Map with String
s for keys.