author Julie Moronuki Wed, 1 Nov 2017 03:28:46 +0000 (23:28 -0400) committer Ben Gamari Mon, 6 Nov 2017 21:43:35 +0000 (16:43 -0500)

@@ -20,7 +20,15 @@ module Data.Bifunctor
import Control.Applicative  ( Const(..) )
import GHC.Generics ( K1(..) )

--- | Formally, the class 'Bifunctor' represents a bifunctor
+-- | A bifunctor is a type constructor that takes
+-- two type arguments and is a functor in /both/ arguments. That
+-- is, unlike with 'Functor', a type constructor such as 'Either'
+-- does not need to be partially applied for a 'Bifunctor'
+-- instance, and the methods in this class permit mapping
+-- functions over the 'Left' value or the 'Right' value,
+-- or both at the same time.
+--
+-- Formally, the class 'Bifunctor' represents a bifunctor
--
-- Intuitively it is a bifunctor where both the first and second
@@ -59,22 +67,49 @@ class Bifunctor p where
-- | Map over both arguments at the same time.
--
-- @'bimap' f g ≡ 'first' f '.' 'second' g@
+    --
+    -- ==== __Examples__
+    -- >>> bimap toUpper (+1) ('j', 3)
+    -- ('J',4)
+    --
+    -- >>> bimap toUpper (+1) (Left 'j')
+    -- Left 'J'
+    --
+    -- >>> bimap toUpper (+1) (Right 3)
+    -- Right 4
bimap :: (a -> b) -> (c -> d) -> p a c -> p b d
bimap f g = first f . second g

+
-- | Map covariantly over the first argument.
--
-- @'first' f ≡ 'bimap' f 'id'@
+    --
+    -- ==== __Examples__
+    -- >>> first toUpper ('j', 3)
+    -- ('J',3)
+    --
+    -- >>> first toUpper (Left 'j')
+    -- Left 'J'
first :: (a -> b) -> p a c -> p b c
first f = bimap f id

+
-- | Map covariantly over the second argument.
--
-- @'second' ≡ 'bimap' 'id'@
+    --
+    -- ==== __Examples__
+    -- >>> second (+1) ('j', 3)
+    -- ('j',4)
+    --
+    -- >>> second (+1) (Right 3)
+    -- Right 4
second :: (b -> c) -> p a b -> p a c
second = bimap id

+
-- | @since 4.8.0.0
instance Bifunctor (,) where
bimap f g ~(a, b) = (f a, g b)