Safe Haskell | None |
---|---|

Language | Haskell2010 |

Functions on association lists that make use of an `Eq`

constraint
on the type of the keys.

## Synopsis

- lookupFirst :: forall l a b. (AssocList l a b, Eq a) => a -> l -> Maybe b
- lookupAll :: forall l a b. (AssocList l a b, Eq a) => a -> l -> [b]
- removeFirst :: forall l a b. (AssocList l a b, Eq a) => a -> l -> l
- removeAll :: forall l a b. (AssocList l a b, Eq a) => a -> l -> l
- mapFirst :: forall l a b. (AssocList l a b, Eq a) => a -> (b -> b) -> l -> l
- mapAll :: forall l a b. (AssocList l a b, Eq a) => a -> (b -> b) -> l -> l
- alterFirst :: forall l a b. (AssocList l a b, Eq a) => a -> (Maybe b -> Maybe b) -> l -> l
- alterAll :: forall l a b. (AssocList l a b, Eq a) => a -> ([b] -> [b]) -> l -> l
- partition :: forall l a b. (AssocList l a b, Eq a) => a -> l -> ([b], l)
- break :: forall l a b. (AssocList l a b, Eq a) => a -> l -> (l, l)
- breakPartition :: forall l a b. (AssocList l a b, Eq a) => a -> l -> (l, [b], l)
- (!) :: forall l a b. (AssocList l a b, Eq a) => l -> a -> b
- (!?) :: forall l a b. (AssocList l a b, Eq a) => l -> a -> Maybe b

# Related modules

Some other modules that are a lot like this one:

- Data.AssocList.ListLike.Equivalence - Functions on association
lists that involve
`Equivalence`

s on the keys - Data.AssocList.ListLike.Predicate - Functions on association
lists that involve
`Predicate`

s on the keys

# Lookup

lookupFirst :: forall l a b. (AssocList l a b, Eq a) => a -> l -> Maybe b Source #

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

`>>>`

Just 2`lookupFirst '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 'D' [('A',1), ('B',2), ('B',3), ('C',4)]`

This function is the same as `!?`

but for the order of its
arguments.

lookupAll :: forall l a b. (AssocList l a b, Eq a) => a -> l -> [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 'B' [('A',1), ('B',2), ('B',3), ('C',4), ('B',3)]`

# Removal

removeFirst :: forall l a b. (AssocList l a b, Eq a) => a -> l -> l 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 '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 'C' [('A',1), ('B',2), ('B',3)]`

removeAll :: forall l a b. (AssocList l a b, Eq a) => a -> l -> l 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 '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 '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 :: forall l a b. (AssocList l a b, Eq a) => a -> (b -> b) -> l -> l 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 '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 'D' negate [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

mapAll :: forall l a b. (AssocList l a b, Eq a) => a -> (b -> b) -> l -> l 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 '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 '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.

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 '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 '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 'D' (\_ -> Just 0) [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

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 '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 '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 '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 '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 'D' (\_ -> [7, 8]) [('A', 1), ('B', 4), ('C', 2), ('B', 6)]`

# Grouping

break :: forall l a b. (AssocList l a b, Eq a) => a -> l -> (l, l) 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 '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 '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 'D' [('A',1), ('B',2), ('B',3), ('C',4)]`

breakPartition :: forall l a b. (AssocList l a b, Eq a) => a -> l -> (l, [b], l) Source #

`break`

on a key, then `partition`

the remainder.

separates `breakPartition`

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`

key l) - All values associated with
`key`

(

)`lookupAll`

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`

key (snd (`break`

key l))

`>>>`

([('A',1)],[2,4],[('C',3)])`breakPartition '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 'D' [('A',1),('B',2),('C',3),('B',4)]`

# Operators

(!) :: forall l a b. (AssocList l a b, Eq a) => l -> a -> b Source #

Obtain the first value associated with a particular key.

`>>>`

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

This function is to be used only when the key must be known to
be present in the mapping. If `x`

is not mapped by any entry in
`AssocList`

`l`

, then `l `

throws `!`

x`MissingAssocListKey`

.
The exclamation mark is intended as a reminder of this danger.

`>>>`

*** Exception: MissingAssocListKey`[('A', 1), ('B', 2), ('B', 3), ('C', 4)] ! 'D'`

There is a related operator called `!?`

which maps the
missing-key condition to `Nothing`

instead.

(!?) :: forall l a b. (AssocList l a b, Eq a) => l -> a -> Maybe b Source #

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

`>>>`

Just 2`[('A',1), ('B',2), ('B',3), ('C',4)] !? 'B'`

The result is `Nothing`

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

`>>>`

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

This function is the same as `lookupFirst`

but for the order of
its arguments.