Safe Haskell | Safe-Inferred |
---|---|

Language | Haskell2010 |

Functions on `AssocList`

s that involve `Equivalence`

s on the keys.

## Synopsis

- lookupFirst :: Equivalence a -> a -> AssocList a b -> Maybe b
- lookupAll :: Equivalence a -> a -> AssocList a b -> [b]
- removeFirst :: Equivalence a -> a -> AssocList a b -> AssocList a b
- removeAll :: Equivalence a -> a -> AssocList a b -> AssocList a b
- mapFirst :: Equivalence a -> a -> (b -> b) -> AssocList a b -> AssocList a b
- mapAll :: Equivalence a -> a -> (b -> b) -> AssocList a b -> AssocList a b
- alterFirst :: Equivalence a -> a -> (Maybe b -> Maybe b) -> AssocList a b -> AssocList a b
- alterAll :: Equivalence a -> a -> ([b] -> [b]) -> AssocList a b -> AssocList a b
- partition :: Equivalence a -> a -> AssocList a b -> ([b], AssocList a b)
- break :: Equivalence a -> a -> AssocList a b -> (AssocList a b, AssocList a b)
- breakPartition :: Equivalence a -> a -> AssocList a b -> (AssocList a b, [b], AssocList a b)

# Related modules

Some other modules that are a lot like this one:

- Data.AssocList.List.Eq - Functions on
`AssocList`

s that make use of an`Eq`

constraint on the type of the keys - Data.AssocList.List.Predicate - Functions on
`AssocList`

s that involve`Predicate`

s on the keys

# Lookup

lookupFirst :: Equivalence a -> a -> AssocList a b -> Maybe b Source #

Obtain the first value associated with a particular key, if such a mapping is present.

`>>>`

Just 2`lookupFirst defaultEquivalence 'B' [('A',1), ('B',2), ('B',3), ('C',4)]`

The result is `Nothing`

if the key is not mapped by any entry in
the list.

`>>>`

Nothing`lookupFirst defaultEquivalence 'D' [('A',1), ('B',2), ('B',3), ('C',4)]`

This function is the same as `!?`

but for the order of its
arguments.

lookupAll :: Equivalence a -> a -> AssocList a b -> [b] Source #

Obtain all values associated with a particular key, in the order in which the mappings appear in the list.

`>>>`

[2,3,3]`lookupAll defaultEquivalence 'B' [('A',1), ('B',2), ('B',3), ('C',4), ('B',3)]`

# Removal

removeFirst :: Equivalence a -> a -> AssocList a b -> AssocList a b Source #

Produce a modified version of the association list in which the first occurrence of a particular key has been removed.

`>>>`

[('A',1),('B',3),('C',4)]`removeFirst defaultEquivalence 'B' [('A',1), ('B',2), ('B',3), ('C',4)]`

If the key is not present in the mapping, then the original list is returned.

`>>>`

[('A',1),('B',2),('B',3)]`removeFirst defaultEquivalence 'C' [('A',1), ('B',2), ('B',3)]`

removeAll :: Equivalence a -> a -> AssocList a b -> AssocList a b Source #

Produce a modified version of the association list in which all occurrences of a particular key have been removed.

`>>>`

[('A',1),('C',4)]`removeAll defaultEquivalence 'B' [('A',1), ('B',2), ('B',3), ('C',4)]`

If the key is not present in the mapping, then the original list is returned.

`>>>`

[('A',1),('B',2),('B',3)]`removeAll defaultEquivalence 'C' [('A',1), ('B',2), ('B',3)]`

# Mapping

The "map" functions modify values while preserving the structure of the assocative list. The resulting list has the same size and order as the original.

mapFirst :: Equivalence a -> a -> (b -> b) -> AssocList a b -> AssocList a b Source #

At the position where a particular key first appears in the list, apply a function to the corresponding value.

`>>>`

[('A',1),('B',-4),('C',2),('B',6)]`mapFirst defaultEquivalence 'B' negate [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

If the key does not appear in the list, then the original list is returned without modification.

`>>>`

[('A',1),('B',4),('C',2),('B',6)]`mapFirst defaultEquivalence 'D' negate [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

mapAll :: Equivalence a -> a -> (b -> b) -> AssocList a b -> AssocList a b Source #

At each position where a particular key appears in the list, apply a function to the corresponding value.

`>>>`

[('A',1),('B',-4),('C',2),('B',-6)]`mapAll defaultEquivalence 'B' negate [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

If the key does not appear in the list, then the original list is returned without modification.

`>>>`

[('A',1),('B',4),('C',2),('B',6)]`mapAll defaultEquivalence 'D' negate [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

# Alteration

The "alter" functions provide an all-in-one way to do insertion, modification, and removal.

:: Equivalence a | |

-> a | |

-> (Maybe b -> Maybe b) | f |

-> AssocList a b | |

-> AssocList a b |

Insert, modify, or delete a single value corresponding to the first place where a particular key appears in the list.

**Modification** - If the key first appears in the list with a
corresponding value of `x`

, and `f x = `

, then that value
`Just`

x'`x`

will be replaced with `x'`

in the resulting list.

`>>>`

[('A',1),('B',-4),('C',2),('B',6)]`alterFirst defaultEquivalence 'B' (fmap negate) [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

**Removal** - If the key first appears in the list with a corresponding
value of `x`

, and `f x = `

, then that mapping will be removed
in the resulting list.`Nothing`

`>>>`

[('A',1),('C',2),('B',6)]`alterFirst defaultEquivalence 'B' (\_ -> Nothing) [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

**Insertion** - If the key does not appear in the list and
`f `

, then `Nothing`

= `Just`

x`x`

be appended to the *end* of the list.

`>>>`

[('A',1),('B',4),('C',2),('B',6),('D',0)]`alterFirst defaultEquivalence 'D' (\_ -> Just 0) [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

:: Equivalence a | |

-> a | |

-> ([b] -> [b]) | f |

-> AssocList a b | |

-> AssocList a b |

Modify the list of values that correspond to a particular key.

**Mapping** - For example, to negate all values of

:`B`

`>>>`

[('A',1),('B',-4),('B',-5),('C',2)]`alterAll defaultEquivalence 'B' (map negate) [('A', 1), ('B', 4), ('B', 5), ('C', 2)]`

**Length alteration** - For example, to limit the number of occurrences
of `B`

to at most two:

`>>>`

[('A',1),('B',4),('B',5),('C',2)]`alterAll defaultEquivalence 'B' (take 2) [('A', 1), ('B', 4), ('B', 5), ('B', 6), ('C', 2)]`

**Removal** - If `f`

returns an empty list, then the key will be removed
from the list entirely.

`>>>`

[('A',1),('C',2)]`alterAll defaultEquivalence 'B' (\_ -> []) [('A', 1), ('B', 4), ('B', 5), ('C', 2)]`

**Reordering** - The key may appear in multiple noncontiguous positions
in the input list, but all of the new mappings for the key in the output
will be in one contiguous sequence starting at the position where the
key *first* appears in the input list.

`>>>`

[('A',1),('B',-4),('B',-5),('B',-6),('C',2),('D',3)]`alterAll defaultEquivalence 'B' (map negate) [('A', 1), ('B', 4), ('C', 2), ('B', 5), ('D', 3), ('B', 6)]`

**Insertion** - If the key does not appear in the list, then any result
from `f`

will be appended to the *end* of the list.

`>>>`

[('A',1),('B',4),('C',2),('B',6),('D',7),('D',8)]`alterAll defaultEquivalence 'D' (\_ -> [7, 8]) [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

# Grouping

break :: Equivalence a -> a -> AssocList a b -> (AssocList a b, AssocList a b) Source #

Produces a tuple of two results:

- The longest prefix of the association list that does
*not*contain a particular key - The remainder of the list

`>>>`

([('A',1)],[('B',2),('B',3),('C',4)])`break defaultEquivalence 'B' [('A',1), ('B',2), ('B',3), ('C',4)]`

If the first mapping in the list contains the given key, then the first part of the resulting tuple is empty, and the second part of the result is the entire list.

`>>>`

([],[('A',1),('B',2),('B',3),('C',4)])`break defaultEquivalence 'A' [('A',1), ('B',2), ('B',3), ('C',4)]`

If the key is not present in the list, then the first part of the resulting tuple is the entire list, and the second part of the result is empty.

`>>>`

([('A',1),('B',2),('B',3),('C',4)],[])`break defaultEquivalence 'D' [('A',1), ('B',2), ('B',3), ('C',4)]`

breakPartition :: Equivalence a -> a -> AssocList a b -> (AssocList a b, [b], AssocList a b) Source #

`break`

on a key, then `partition`

the remainder.

separates `breakPartition`

eq key l`l`

into three parts:

- The key-value pairs for which the key is
*not*`key`

that occur in the list*before*the first occurrence of`key`

(`fst (`

)`break`

eq key l) - All values associated with
`key`

(

)`lookupAll`

eq key l - The key-value pairs for which the key is
*not*`key`

that occur in the list*after*the first occurrence of`key`

(

)`removeAll`

eq key (snd (`break`

eq key l))

`>>>`

([('A',1)],[2,4],[('C',3)])`breakPartition defaultEquivalence 'B' [('A',1),('B',2),('C',3),('B',4)]`

If the key is not present in the list, then the first part of the result is the entire list, and the other parts are empty.

`>>>`

([('A',1),('B',2),('C',3),('B',4)],[],[])`breakPartition defaultEquivalence 'D' [('A',1),('B',2),('C',3),('B',4)]`