traverse -package:base-compat -package:case-insensitive package:rio

Map each element of a structure to an action, evaluate these actions from left to right, and collect the results. For a version that ignores the results see traverse_.

Examples

Basic usage: In the first two examples we show each evaluated action mapping to the output structure.

>>> traverse Just [1,2,3,4]
Just [1,2,3,4]

>>> traverse id [Right 1, Right 2, Right 3, Right 4]
Right [1,2,3,4]

In the next examples, we show that Nothing and Left values short circuit the created structure.

>>> traverse (const Nothing) [1,2,3,4]
Nothing

>>> traverse (\x -> if odd x then Just x else Nothing)  [1,2,3,4]
Nothing

>>> traverse id [Right 1, Right 2, Right 3, Right 4, Left 0]
Left 0

Perform an Applicative action for each key-value pair in a HashMap and produce a HashMap of all the results. Each HashMap will be strict in all its values.

traverseWithKey f = fmap (map id) . Data.HashMap.Lazy.traverseWithKey f

Note: the order in which the actions occur is unspecified. In particular, when the map contains hash collisions, the order in which the actions associated with the keys involved will depend in an unspecified way on their insertion order.

traversed traverses any Traversable container (list, vector, Map, Maybe, you name it):

>>> Just 1 ^.. traversed
[1]

traversed is the same as traverse, but can be faster thanks to magic rewrite rules.

Traverse keys/values and collect the Just results.

traverseWithKey f m == fromList <$> traverse (\(k, v) -> (v' -> v' `seq` (k,v')) <$> f k v) (toList m) That is, it behaves much like a regular traverse except that the traversing function also has access to the key associated with a value and the values are forced before they are installed in the result map.

traverseWithKey (\k v -> if odd k then Just (succ v) else Nothing) (fromList [(1, 'a'), (5, 'e')]) == Just (fromList [(1, 'b'), (5, 'f')])
traverseWithKey (\k v -> if odd k then Just (succ v) else Nothing) (fromList [(2, 'c')])           == Nothing

Map each element of a structure to an Applicative action, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results see traverse. traverse_ is just like mapM_, but generalised to Applicative actions.

Examples

Basic usage:

>>> traverse_ print ["Hello", "world", "!"]
"Hello"
"world"
"!"

traverseWithIndex is a version of traverse that also offers access to the index of each element.

Evaluates the relevant functions at each element in the structure, running the action, and builds a new structure with the same shape, using the results produced from sequencing the actions.

bitraverse f g ≡ bisequenceA . bimap f g

For a version that ignores the results, see bitraverse_.

Examples

Basic usage:

>>> bitraverse listToMaybe (find odd) (Left [])
Nothing

>>> bitraverse listToMaybe (find odd) (Left [1, 2, 3])
Just (Left 1)

>>> bitraverse listToMaybe (find odd) (Right [4, 5])
Just (Right 5)

>>> bitraverse listToMaybe (find odd) ([1, 2, 3], [4, 5])
Just (1,5)

>>> bitraverse listToMaybe (find odd) ([], [4, 5])
Nothing

Map each element of a structure using one of two actions, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results, see bitraverse.

Examples

Basic usage:

>>> bitraverse_ print (print . show) ("Hello", True)
"Hello"
"True"

>>> bitraverse_ print (print . show) (Right True)
"True"

>>> bitraverse_ print (print . show) (Left "Hello")
"Hello"