Data.Bitraversable

class (Bifunctor t, Bifoldable t) => Bitraversable (t :: Type -> Type -> Type) where Исходный код

Bitraversable обозначает бифункториальные структуры данных, элементы которых можно обходить по порядку, выполняя действия Applicative или Monad над каждым элементом и собирая результирующую структуру той же формы.

В отличие от структур данных Traversable, в которых имеется один тип элементов, над которыми можно выполнять действие, структуры данных Bitraversable содержат два таких типа элементов.

Определение bitraverse должно удовлетворять следующим законам:

Естественность

bitraverse (t . f) (t . g) ≡ t . bitraverse f g для каждого аппликативного преобразования t

Тождественность

bitraverse Identity Identity ≡ Identity

Композиция

Compose . fmap (bitraverse g1 g2) . bitraverse f1 f2 ≡ bitraverse (Compose . fmap g1 . f1) (Compose . fmap g2 . f2)

где аппликативное преобразование — это функция

t :: (Applicative f, Applicative g) => f a -> g a

сохраняющая операции Applicative:

t (pure x) ≡ pure x
t (f <*> x) ≡ t f <*> t x

а функтор тождества Identity и функторы композиции Compose находятся в модулях Data.Functor.Identity и Data.Functor.Compose.

Простые примеры — Either и (,):

instance Bitraversable Either where
  bitraverse f _ (Left x) = Left <$> f x
  bitraverse _ g (Right y) = Right <$> g y

instance Bitraversable (,) where
  bitraverse f g (x, y) = (,) <$> f x <*> g y

Bitraversable связан со своими суперклассами следующим образом:

bimap f g ≡ runIdentity . bitraverse (Identity . f) (Identity . g)
bifoldMap f g ≡ getConst . bitraverse (Const . f) (Const . g)

Они доступны соответственно как bimapDefault и bifoldMapDefault.

Если тип также является экземпляром Traversable, он должен удовлетворять следующему условию (с точностью до ленивости):

traverse ≡ bitraverse pure

Начиная с: base-4.10.0.0

bitraverse f g ≡ bisequenceA . bimap f g

>>> 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

>>> (bitraverse pure pure undefined :: IO (Int, Word)) `seq` ()
()
>>> (traverse pure (errorWithoutStackTrace "error!") :: IO (Int, Word)) `seq` ()
*** Exception: error!

bisequenceA :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b) Исходный код

Псевдоним для bisequence.

Начиная с: base-4.10.0.0

bisequence :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b) Исходный код

Последовательно выполняет все действия в структуре и строит новую структуру той же формы, используя результаты этих действий. Вариант, который игнорирует результаты, см. в bisequence_.

bisequence ≡ bitraverse id id

Примеры

>>> 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)]

Начиная с: base-4.10.0.0

bimapM :: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d) Исходный код

Псевдоним для bitraverse.

Начиная с: base-4.10.0.0

firstA :: (Bitraversable t, Applicative f) => (a -> f c) -> t a b -> f (t c b) Исходный код

Обходит только первый аргумент.

firstA f ≡ bitraverse f pure

secondA :: (Bitraversable t, Applicative f) => (b -> f c) -> t a b -> f (t a c) Исходный код

Обходит только второй аргумент.

secondA f ≡ bitraverse pure f

Примеры

>>> secondA (find odd) (Left [])
Just (Left [])

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

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

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

>>> secondA (find odd) ([1,2,3], [4])
Nothing

Начиная с: base-4.21.0.0

bifor :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d) Исходный код

bifor — это bitraverse, в котором структура передаётся первым аргументом. Вариант, который игнорирует результаты, см. в bifor_.

Примеры

>>> 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

Начиная с: base-4.10.0.0

biforM :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d) Исходный код

Псевдоним для bifor.

Начиная с: base-4.10.0.0

bimapAccumL :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e) Исходный код

Функция bimapAccumL действует как комбинация bimap и bifoldl; она обходит структуру слева направо, передавая состояние типа a и используя заданные действия для вычисления новых элементов структуры.

Примеры

>>> bimapAccumL (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo")
(8,("True","oof"))

Начиная с: base-4.10.0.0

bimapAccumR :: Bitraversable t => (a -> b -> (a, c)) -> (a -> d -> (a, e)) -> a -> t b d -> (a, t c e) Исходный код

Функция bimapAccumR действует как комбинация bimap и bifoldr; она обходит структуру справа налево, передавая состояние типа a и используя заданные действия для вычисления новых элементов структуры.

Примеры

>>> bimapAccumR (\acc bool -> (acc + 1, show bool)) (\acc string -> (acc * 2, reverse string)) 3 (True, "foo")
(7,("True","oof"))

Начиная с: base-4.10.0.0

bimapDefault :: Bitraversable t => (a -> b) -> (c -> d) -> t a c -> t b d Исходный код

Определение bimap по умолчанию через операции Bitraversable.

bimapDefault f g ≡
     runIdentity . bitraverse (Identity . f) (Identity . g)

Начиная с: base-4.10.0.0

bifoldMapDefault :: (Bitraversable t, Monoid m) => (a -> m) -> (b -> m) -> t a b -> m Исходный код

Определение bifoldMap по умолчанию через операции Bitraversable.

bifoldMapDefault f g ≡
    getConst . bitraverse (Const . f) (Const . g)

Начиная с: base-4.10.0.0