diff options
| -rw-r--r-- | libraries/base/Data/Bifoldable.hs | 2 | ||||
| -rw-r--r-- | libraries/base/Data/Bitraversable.hs | 69 |
2 files changed, 68 insertions, 3 deletions
diff --git a/libraries/base/Data/Bifoldable.hs b/libraries/base/Data/Bifoldable.hs index b8c3ad4d75..e29c18e767 100644 --- a/libraries/base/Data/Bifoldable.hs +++ b/libraries/base/Data/Bifoldable.hs @@ -57,7 +57,7 @@ import GHC.Generics (K1(..)) -- | 'Bifoldable' identifies foldable structures with two different varieties -- of elements (as opposed to 'Foldable', which has one variety of element). --- Common examples are 'Either' and '(,)': +-- Common examples are 'Either' and @(,)@: -- -- > instance Bifoldable Either where -- > bifoldMap f _ (Left a) = f a diff --git a/libraries/base/Data/Bitraversable.hs b/libraries/base/Data/Bitraversable.hs index 6df69b93e6..0d34e2710c 100644 --- a/libraries/base/Data/Bitraversable.hs +++ b/libraries/base/Data/Bitraversable.hs @@ -73,7 +73,7 @@ import GHC.Generics (K1(..)) -- 'Data.Functor.Compose.Compose' are from "Data.Functor.Identity" and -- "Data.Functor.Compose". -- --- Some simple examples are 'Either' and '(,)': +-- Some simple examples are 'Either' and @(,)@: -- -- > instance Bitraversable Either where -- > bitraverse f _ (Left x) = Left <$> f x @@ -101,6 +101,25 @@ class (Bifunctor t, Bifoldable t) => Bitraversable t where -- -- 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 + -- -- @since 4.10.0.0 bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> t a b -> f (t c d) bitraverse f g = bisequenceA . bimap f g @@ -124,6 +143,19 @@ bimapM = bitraverse -- -- @'bisequence' ≡ 'bitraverse' 'id' 'id'@ -- +-- ==== __Examples__ +-- +-- Basic usage: +-- +-- >>> bisequence (Just 4, Nothing) +-- Nothing +-- +-- >>> bisequence (Just 4, Just 5) +-- Just (4,5) +-- +-- >>> bisequence ([1, 2, 3], [4, 5]) +-- [(1,4),(1,5),(2,4),(2,5),(3,4),(3,5)] +-- -- @since 4.10.0.0 bisequence :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b) bisequence = bitraverse id id @@ -169,6 +201,25 @@ instance Bitraversable (K1 i) where -- | 'bifor' is 'bitraverse' with the structure as the first argument. For a -- version that ignores the results, see 'bifor_'. -- +-- ==== __Examples__ +-- +-- Basic usage: +-- +-- >>> bifor (Left []) listToMaybe (find even) +-- Nothing +-- +-- >>> bifor (Left [1, 2, 3]) listToMaybe (find even) +-- Just (Left 1) +-- +-- >>> bifor (Right [4, 5]) listToMaybe (find even) +-- Just (Right 4) +-- +-- >>> bifor ([1, 2, 3], [4, 5]) listToMaybe (find even) +-- Just (1,4) +-- +-- >>> bifor ([], [4, 5]) listToMaybe (find even) +-- Nothing +-- -- @since 4.10.0.0 bifor :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d) @@ -186,6 +237,13 @@ biforM = bifor -- of type @a@ and using the given actions to compute new elements for the -- structure. -- +-- ==== __Examples__ +-- +-- Basic usage: +-- +-- >>> bimapAccumL (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo") +-- (8,("True","oof")) +-- -- @since 4.10.0.0 bimapAccumL :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e) @@ -193,10 +251,17 @@ bimapAccumL f g s t = runStateL (bitraverse (StateL . flip f) (StateL . flip g) t) s -- | The 'bimapAccumR' function behaves like a combination of 'bimap' and --- 'bifoldl'; it traverses a structure from right to left, threading a state +-- 'bifoldr'; it traverses a structure from right to left, threading a state -- of type @a@ and using the given actions to compute new elements for the -- structure. -- +-- ==== __Examples__ +-- +-- Basic usage: +-- +-- >>> bimapAccumR (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo") +-- (7,("True","oof")) +-- -- @since 4.10.0.0 bimapAccumR :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e) |