FSharp.Core


Map Module

Contains operations for working with values of type Map.

Functions and values

Function or value Description

Map.add key value table

Full Usage: Map.add key value table

Parameters:
    key : 'Key - The input key.
    value : 'T - The input value.
    table : Map<'Key, 'T> - The input map.

Returns: Map<'Key, 'T> The resulting map.

Returns a new map with the binding added to the given map. If a binding with the given key already exists in the input map, the existing binding is replaced by the new binding in the result map.

key : 'Key

The input key.

value : 'T

The input value.

table : Map<'Key, 'T>

The input map.

Returns: Map<'Key, 'T>

The resulting map.

Example

 let input = Map [ (1, "a"); (2, "b") ]

 input |> Map.add 3 "c" // evaluates to map [(1, "a"); (2, "b"); (3, "c")]
 input |> Map.add 2 "aa" // evaluates to map [(1, "a"); (2, "aa")]

Map.change key f table

Full Usage: Map.change key f table

Parameters:
    key : 'Key - The input key.
    f : 'T option -> 'T option - The change function.
    table : Map<'Key, 'T> - The input map.

Returns: Map<'Key, 'T> The resulting map.

Returns a new map with the value stored under key changed according to f.

key : 'Key

The input key.

f : 'T option -> 'T option

The change function.

table : Map<'Key, 'T>

The input map.

Returns: Map<'Key, 'T>

The resulting map.

Example

 let input = Map [ (1, "a"); (2, "b") ]

 input |> Map.change 1 (fun x ->
     match x with
     | Some s -> Some (s + "z")
     | None -> None
 )
 evaluates to map [(1, "az"); (2, "b")]

Map.containsKey key table

Full Usage: Map.containsKey key table

Parameters:
    key : 'Key - The input key.
    table : Map<'Key, 'T> - The input map.

Returns: bool True if the map contains the key.

Tests if an element is in the domain of the map.

key : 'Key

The input key.

table : Map<'Key, 'T>

The input map.

Returns: bool

True if the map contains the key.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.containsKey 1 // evaluates to true
 sample |> Map.containsKey 3 // evaluates to false

Map.count table

Full Usage: Map.count table

Parameters:
    table : Map<'Key, 'T>

Returns: int

The number of bindings in the map.

table : Map<'Key, 'T>
Returns: int
Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.count // evaluates to 2

Map.empty

Full Usage: Map.empty

Returns: Map<'Key, 'T>

The empty map.

Returns: Map<'Key, 'T>
Example

 let emptyMap = Map.empty<int, string>

Map.exists predicate table

Full Usage: Map.exists predicate table

Parameters:
    predicate : 'Key -> 'T -> bool - The function to test the input elements.
    table : Map<'Key, 'T> - The input map.

Returns: bool True if the predicate returns true for one of the key/value pairs.

Returns true if the given predicate returns true for one of the bindings in the map.

predicate : 'Key -> 'T -> bool

The function to test the input elements.

table : Map<'Key, 'T>

The input map.

Returns: bool

True if the predicate returns true for one of the key/value pairs.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.exists (fun n s -> n = s.Length) // evaluates to true
 sample |> Map.exists (fun n s -> n < s.Length) // evaluates to false

Map.filter predicate table

Full Usage: Map.filter predicate table

Parameters:
    predicate : 'Key -> 'T -> bool - The function to test the key/value pairs.
    table : Map<'Key, 'T> - The input map.

Returns: Map<'Key, 'T> The filtered map.

Builds a new map containing only the bindings for which the given predicate returns 'true'.

predicate : 'Key -> 'T -> bool

The function to test the key/value pairs.

table : Map<'Key, 'T>

The input map.

Returns: Map<'Key, 'T>

The filtered map.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.filter (fun n s -> n = s.Length) // evaluates to map [(1, "a")]

Map.find key table

Full Usage: Map.find key table

Parameters:
    key : 'Key - The input key.
    table : Map<'Key, 'T> - The input map.

Returns: 'T The value mapped to the given key.

Lookup an element in the map, raising KeyNotFoundException if no binding exists in the map.

key : 'Key

The input key.

table : Map<'Key, 'T>

The input map.

Returns: 'T

The value mapped to the given key.

KeyNotFoundException Thrown when the key does not exist in the map.
Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.find 1 // evaluates to "a"
 sample |> Map.find 3 // throws KeyNotFoundException

Map.findKey predicate table

Full Usage: Map.findKey predicate table

Parameters:
    predicate : 'Key -> 'T -> bool - The function to test the input elements.
    table : Map<'Key, 'T> - The input map.

Returns: 'Key The first key for which the predicate evaluates true.

Evaluates the function on each mapping in the collection. Returns the key for the first mapping where the function returns 'true'. Raise KeyNotFoundException if no such element exists.

predicate : 'Key -> 'T -> bool

The function to test the input elements.

table : Map<'Key, 'T>

The input map.

Returns: 'Key

The first key for which the predicate evaluates true.

KeyNotFoundException Thrown if the key does not exist in the map.
Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.findKey (fun n s -> n = s.Length) // evaluates to 1
 sample |> Map.findKey (fun n s -> n < s.Length) // throws KeyNotFoundException

Map.fold folder state table

Full Usage: Map.fold folder state table

Parameters:
    folder : 'State -> 'Key -> 'T -> 'State - The function to update the state given the input key/value pairs.
    state : 'State - The initial state.
    table : Map<'Key, 'T> - The input map.

Returns: 'State The final state value.

Folds over the bindings in the map

folder : 'State -> 'Key -> 'T -> 'State

The function to update the state given the input key/value pairs.

state : 'State

The initial state.

table : Map<'Key, 'T>

The input map.

Returns: 'State

The final state value.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 ("initial", sample) ||> Map.fold (fun state n s -> sprintf "%s %i %s" state n s)
Evaluates to "initial 1 a 2 b".

Map.foldBack folder table state

Full Usage: Map.foldBack folder table state

Parameters:
    folder : 'Key -> 'T -> 'State -> 'State - The function to update the state given the input key/value pairs.
    table : Map<'Key, 'T> - The input map.
    state : 'State - The initial state.

Returns: 'State The final state value.

Folds over the bindings in the map.

folder : 'Key -> 'T -> 'State -> 'State

The function to update the state given the input key/value pairs.

table : Map<'Key, 'T>

The input map.

state : 'State

The initial state.

Returns: 'State

The final state value.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 (sample, "initial") ||> Map.foldBack (fun n s state -> sprintf "%i %s %s" n s state)
Evaluates to "1 a 2 b initial"

Map.forall predicate table

Full Usage: Map.forall predicate table

Parameters:
    predicate : 'Key -> 'T -> bool - The function to test the input elements.
    table : Map<'Key, 'T> - The input map.

Returns: bool True if the predicate evaluates to true for all of the bindings in the map.

Returns true if the given predicate returns true for all of the bindings in the map.

predicate : 'Key -> 'T -> bool

The function to test the input elements.

table : Map<'Key, 'T>

The input map.

Returns: bool

True if the predicate evaluates to true for all of the bindings in the map.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.forall (fun n s -> n >= s.Length) // evaluates to true
 sample |> Map.forall (fun n s -> n = s.Length)  // evaluates to false

Map.isEmpty table

Full Usage: Map.isEmpty table

Parameters:
    table : Map<'Key, 'T> - The input map.

Returns: bool True if the map is empty.

Is the map empty?

table : Map<'Key, 'T>

The input map.

Returns: bool

True if the map is empty.

Example

 let emptyMap = Map.empty<int, string>
 emptyMap |> Map.isEmpty  // evaluates to true

 let notEmptyMap = Map [ (1, "a"); (2, "b") ]
 emptyMap |> Map.isEmpty // evaluates to false

Map.iter action table

Full Usage: Map.iter action table

Parameters:
    action : 'Key -> 'T -> unit - The function to apply to each key/value pair.
    table : Map<'Key, 'T> - The input map.

Applies the given function to each binding in the dictionary

action : 'Key -> 'T -> unit

The function to apply to each key/value pair.

table : Map<'Key, 'T>

The input map.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.iter (fun n s -> printf "%i %s " n s)
Prints "1 a 2 b ".

Map.keys table

Full Usage: Map.keys table

Parameters:
    table : Map<'Key, 'T>

Returns: ICollection<'Key>

The keys in the map. The sequence will be ordered by the keys of the map.

table : Map<'Key, 'T>
Returns: ICollection<'Key>
Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.keys // evaluates to seq [1; 2]

Map.map mapping table

Full Usage: Map.map mapping table

Parameters:
    mapping : 'Key -> 'T -> 'U - The function to transform the key/value pairs.
    table : Map<'Key, 'T> - The input map.

Returns: Map<'Key, 'U> The resulting map of keys and transformed values.

Builds a new collection whose elements are the results of applying the given function to each of the elements of the collection. The key passed to the function indicates the key of element being transformed.

mapping : 'Key -> 'T -> 'U

The function to transform the key/value pairs.

table : Map<'Key, 'T>

The input map.

Returns: Map<'Key, 'U>

The resulting map of keys and transformed values.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.map (fun n s -> sprintf "%i %s" n s) // evaluates to map [(1, "1 a"); (2, "2 b")]

Map.maxKeyValue table

Full Usage: Map.maxKeyValue table

Parameters:
    table : Map<'Key, 'T> - The input map.

Returns: 'Key * 'T

Returns binding for the largest key in the map. Raise KeyNotFoundException when map is empty.

table : Map<'Key, 'T>

The input map.

Returns: 'Key * 'T
KeyNotFoundException Thrown if the map is empty.
Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.maxKeyValue // evaluates to (2, "b")

Map.minKeyValue table

Full Usage: Map.minKeyValue table

Parameters:
    table : Map<'Key, 'T> - The input map.

Returns: 'Key * 'T

Returns binding for the smallest key in the map. Raise KeyNotFoundException when map is empty.

table : Map<'Key, 'T>

The input map.

Returns: 'Key * 'T
KeyNotFoundException Thrown if the map is empty.
Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.minKeyValue // evaluates to (1, "a")

Map.ofArray elements

Full Usage: Map.ofArray elements

Parameters:
    elements : ('Key * 'T)[] - The input array of key/value pairs.

Returns: Map<'Key, 'T> The resulting map.

Returns a new map made from the given bindings.

elements : ('Key * 'T)[]

The input array of key/value pairs.

Returns: Map<'Key, 'T>

The resulting map.

Example

 let input = [| (1, "a"); (2, "b") |]

 input |> Map.ofArray // evaluates to map [(1, "a"); (2, "b")]

Map.ofList elements

Full Usage: Map.ofList elements

Parameters:
    elements : ('Key * 'T) list - The input list of key/value pairs.

Returns: Map<'Key, 'T> The resulting map.

Returns a new map made from the given bindings.

elements : ('Key * 'T) list

The input list of key/value pairs.

Returns: Map<'Key, 'T>

The resulting map.

Example

 let input = [ (1, "a"); (2, "b") ]

 input |> Map.ofList // evaluates to map [(1, "a"); (2, "b")]

Map.ofSeq elements

Full Usage: Map.ofSeq elements

Parameters:
    elements : seq<'Key * 'T> - The input sequence of key/value pairs.

Returns: Map<'Key, 'T> The resulting map.

Returns a new map made from the given bindings.

elements : seq<'Key * 'T>

The input sequence of key/value pairs.

Returns: Map<'Key, 'T>

The resulting map.

Example

 let input = seq { (1, "a"); (2, "b") }

 input |> Map.ofSeq // evaluates to map [(1, "a"); (2, "b")]

Map.partition predicate table

Full Usage: Map.partition predicate table

Parameters:
    predicate : 'Key -> 'T -> bool - The function to test the input elements.
    table : Map<'Key, 'T> - The input map.

Returns: Map<'Key, 'T> * Map<'Key, 'T> A pair of maps in which the first contains the elements for which the predicate returned true and the second containing the elements for which the predicated returned false.

Builds two new maps, one containing the bindings for which the given predicate returns 'true', and the other the remaining bindings.

predicate : 'Key -> 'T -> bool

The function to test the input elements.

table : Map<'Key, 'T>

The input map.

Returns: Map<'Key, 'T> * Map<'Key, 'T>

A pair of maps in which the first contains the elements for which the predicate returned true and the second containing the elements for which the predicated returned false.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.partition (fun n s -> n = s.Length) // evaluates to (map [(1, "a")], map [(2, "b")])

Map.pick chooser table

Full Usage: Map.pick chooser table

Parameters:
    chooser : 'Key -> 'T -> 'U option - The function to generate options from the key/value pairs.
    table : Map<'Key, 'T> - The input map.

Returns: 'U The first result.

Searches the map looking for the first element where the given function returns a Some value. Raise KeyNotFoundException if no such element exists.

chooser : 'Key -> 'T -> 'U option

The function to generate options from the key/value pairs.

table : Map<'Key, 'T>

The input map.

Returns: 'U

The first result.

KeyNotFoundException Thrown if no element returns a Some value when evaluated by the chooser function
Example

 let sample = Map [ (1, "a"); (2, "b"); (10, "ccc"); (20, "ddd") ]

 sample |> Map.pick (fun n s -> if n > 5 && s.Length > 2 then Some s else None)
Evaluates to "ccc"

Example

 let sample = Map [ (1, "a"); (2, "b"); (10, "ccc"); (20, "ddd") ]

 sample |> Map.pick (fun n s -> if n > 5 && s.Length > 4 then Some s else None)
Raises KeyNotFoundException

Map.remove key table

Full Usage: Map.remove key table

Parameters:
    key : 'Key - The input key.
    table : Map<'Key, 'T> - The input map.

Returns: Map<'Key, 'T> The resulting map.

Removes an element from the domain of the map. No exception is raised if the element is not present.

key : 'Key

The input key.

table : Map<'Key, 'T>

The input map.

Returns: Map<'Key, 'T>

The resulting map.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.remove 1 // evaluates to map [(2, "b")]
 sample |> Map.remove 3 // equal to sample

Map.toArray table

Full Usage: Map.toArray table

Parameters:
    table : Map<'Key, 'T> - The input map.

Returns: ('Key * 'T)[] The array of key/value pairs.

Returns an array of all key-value pairs in the mapping. The array will be ordered by the keys of the map.

table : Map<'Key, 'T>

The input map.

Returns: ('Key * 'T)[]

The array of key/value pairs.

Example

 let input = Map [ (1, "a"); (2, "b") ]

 input |> Map.toArray // evaluates to [|(1, "a"); (2, "b")|]

Map.toList table

Full Usage: Map.toList table

Parameters:
    table : Map<'Key, 'T> - The input map.

Returns: ('Key * 'T) list The list of key/value pairs.

Returns a list of all key-value pairs in the mapping. The list will be ordered by the keys of the map.

table : Map<'Key, 'T>

The input map.

Returns: ('Key * 'T) list

The list of key/value pairs.

Example

 let input = Map [ (1, "a"); (2, "b") ]

 input |> Map.toList // evaluates to [(1, "a"); (2, "b")]

Map.toSeq table

Full Usage: Map.toSeq table

Parameters:
    table : Map<'Key, 'T> - The input map.

Returns: seq<'Key * 'T> The sequence of key/value pairs.

Views the collection as an enumerable sequence of pairs. The sequence will be ordered by the keys of the map.

table : Map<'Key, 'T>

The input map.

Returns: seq<'Key * 'T>

The sequence of key/value pairs.

Example

 let input = Map [ (1, "a"); (2, "b") ]

 input |> Map.toSeq // evaluates to seq [(1, "a"); (2, "b")]

Map.tryFind key table

Full Usage: Map.tryFind key table

Parameters:
    key : 'Key - The input key.
    table : Map<'Key, 'T> - The input map.

Returns: 'T option The found Some value or None.

Lookup an element in the map, returning a Some value if the element is in the domain of the map and None if not.

key : 'Key

The input key.

table : Map<'Key, 'T>

The input map.

Returns: 'T option

The found Some value or None.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.tryFind 1 // evaluates to Some "a"
 sample |> Map.tryFind 3 // evaluates to None

Map.tryFindKey predicate table

Full Usage: Map.tryFindKey predicate table

Parameters:
    predicate : 'Key -> 'T -> bool - The function to test the input elements.
    table : Map<'Key, 'T> - The input map.

Returns: 'Key option The first key for which the predicate returns true or None if the predicate evaluates to false for each key/value pair.

Returns the key of the first mapping in the collection that satisfies the given predicate. Returns 'None' if no such element exists.

predicate : 'Key -> 'T -> bool

The function to test the input elements.

table : Map<'Key, 'T>

The input map.

Returns: 'Key option

The first key for which the predicate returns true or None if the predicate evaluates to false for each key/value pair.

Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.tryFindKey (fun n s -> n = s.Length) // evaluates to Some 1
 sample |> Map.tryFindKey (fun n s -> n < s.Length) // evaluates to None

Map.tryPick chooser table

Full Usage: Map.tryPick chooser table

Parameters:
    chooser : 'Key -> 'T -> 'U option - The function to generate options from the key/value pairs.
    table : Map<'Key, 'T> - The input map.

Returns: 'U option The first result.

Searches the map looking for the first element where the given function returns a Some value.

chooser : 'Key -> 'T -> 'U option

The function to generate options from the key/value pairs.

table : Map<'Key, 'T>

The input map.

Returns: 'U option

The first result.

Example

 let sample = Map [ (1, "a"); (2, "b"); (10, "ccc"); (20, "ddd") ]

 sample |> Map.tryPick (fun n s -> if n > 5 && s.Length > 2 then Some s else None)
Evaluates to Some "ccc".

Example

 let sample = Map [ (1, "a"); (2, "b"); (10, "ccc"); (20, "ddd") ]

 sample |> Map.tryPick (fun n s -> if n > 5 && s.Length > 4 then Some s else None)
Evaluates to None.

Map.values table

Full Usage: Map.values table

Parameters:
    table : Map<'Key, 'T>

Returns: ICollection<'T>

The values in the map, including the duplicates. The sequence will be ordered by the keys of the map.

table : Map<'Key, 'T>
Returns: ICollection<'T>
Example

 let sample = Map [ (1, "a"); (2, "b") ]

 sample |> Map.values // evaluates to seq ["a"; "b"]