assoc-listlike-0.1.0.0: Association lists (list-like collections of tuples)

Data.AssocList.ListLike.Equivalence

Description

Functions on association lists that involve Equivalences on the keys.

Synopsis

# Related modules

Some other modules that are a lot like this one:

# Lookup

lookupFirst :: forall l a b. AssocList l a b => Equivalence a -> a -> l -> Maybe b Source #

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

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


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

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


This function is the same as !? but for the order of its arguments.

lookupAll :: forall l a b. AssocList l a b => Equivalence a -> a -> l -> [b] Source #

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

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


# Removal

removeFirst :: forall l a b. AssocList l a b => Equivalence 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.

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


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

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


removeAll :: forall l a b. AssocList l a b => Equivalence a -> a -> l -> l Source #

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

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


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

>>> removeAll defaultEquivalence 'C' [('A',1), ('B',2), ('B',3)]
[('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 => Equivalence 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.

>>> mapFirst defaultEquivalence 'B' negate [('A', 1), ('B', 4), ('C', 2), ('B', 6)]
[('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.

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


mapAll :: forall l a b. AssocList l a b => Equivalence 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.

>>> mapAll defaultEquivalence 'B' negate [('A', 1), ('B', 4), ('C', 2), ('B', 6)]
[('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.

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


# Alteration

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

Arguments

 :: AssocList l a b => Equivalence a -> a -> (Maybe b -> Maybe b) f -> l -> l

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 = Just x', then that value x will be replaced with x' in the resulting list.

>>> alterFirst defaultEquivalence 'B' (fmap negate) [('A', 1), ('B', 4), ('C', 2), ('B', 6)]
[('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 = Nothing, then that mapping will be removed in the resulting list.

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


Insertion - If the key does not appear in the list and f Nothing = Just x, then x be appended to the end of the list.

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


Arguments

 :: AssocList l a b => Equivalence a -> a -> ([b] -> [b]) f -> l -> l

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

Mapping - For example, to negate all values of B:

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


Length alteration - For example, to limit the number of occurrences of B to at most two:

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


Removal - If f returns an empty list, then the key will be removed from the list entirely.

>>> alterAll defaultEquivalence 'B' (\_ -> []) [('A', 1), ('B', 4), ('B', 5), ('C', 2)]
[('A',1),('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.

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


Insertion - If the key does not appear in the list, then any result from f will be appended to the end of the list.

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


# Grouping

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

Produces a tuple of two results:

1. All values associated with a particular key
2. All of the other key-value pairs
partition eq x l = (lookupAll eq x l, removeAll eq x l)
>>> partition defaultEquivalence 'B' [('A',1), ('B',2), ('B',3), ('C',4), ('B',3)]
([2,3,3],[('A',1),('C',4)])


break :: forall l a b. AssocList l a b => Equivalence a -> a -> l -> (l, l) Source #

Produces a tuple of two results:

1. The longest prefix of the association list that does not contain a particular key
2. The remainder of the list
>>> break defaultEquivalence 'B' [('A',1), ('B',2), ('B',3), ('C',4)]
([('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.

>>> break defaultEquivalence 'A' [('A',1), ('B',2), ('B',3), ('C',4)]
([],[('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.

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


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

break on a key, then partition the remainder.

breakPartition eq key l separates l into three parts:

1. 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))
2. All values associated with key (lookupAll eq key l)
3. 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)))
>>> breakPartition defaultEquivalence 'B' [('A',1),('B',2),('C',3),('B',4)]
([('A',1)],[2,4],[('C',3)])


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.

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