relude-1.2.2.0: Safe, performant, user-friendly and lightweight Haskell Standard Library

Copyright | (c) 2011-2015 Edward Kmett (c) 2018-2023 Kowainik
License | MIT
Maintainer | Kowainik <xrom.xkov@gmail.com>
Stability | Stable
Portability | Portable
Safe Haskell | Safe
Language | Haskell2010

Relude.Extra.Foldable1

Description

`Foldable1` is a typeclass like `Foldable` but for non-empty structures. For example, `NonEmpty`, `Identity`.

`Foldable1` has all type-safe and total methods like `head1`, `maximum1` in contradiction with `Foldable`.

Since: 0.3.0

Synopsis

- class Foldable f => Foldable1 (f :: Type -> Type) where
  - foldMap1 :: Semigroup m => (a -> m) -> f a -> m
  - fold1 :: Semigroup m => f m -> m
  - foldr1 :: (a -> b -> b) -> b -> f a -> b
  - toNonEmpty :: f a -> NonEmpty a
  - head1 :: f a -> a
  - last1 :: f a -> a
  - maximum1 :: Ord a => f a -> a
  - minimum1 :: Ord a => f a -> a
  - maximumOn1 :: Ord b => (a -> b) -> f a -> a
  - minimumOn1 :: Ord b => (a -> b) -> f a -> a
- foldl1' :: (a -> a -> a) -> NonEmpty a -> a
- average1 :: forall a f. (Foldable1 f, Fractional a) => f a -> a

# Documentation

class Foldable f => Foldable1 (f :: Type -> Type) where #

The class of foldable data structures that cannot be empty.

Since: 0.3.0

Minimal complete definition

foldMap1

Methods

foldMap1 :: Semigroup m => (a -> m) -> f a -> m #

Map each element of the non-empty structure to a semigroup, and combine the results.

    >>> foldMap1 SG.Sum (1 :| [2, 3, 4])
    Sum {getSum = 10}
    >>> foldMap1 show (123 :| [456, 789, 0])
    "1234567890"

fold1 :: Semigroup m => f m -> m #

Combine the elements of a non-empty structure using a semigroup.

    >>> fold1 (1 :| [2, 3, 4 :: SG.Sum Int])
    Sum {getSum = 10}
    >>> fold1 (4 :| [5, 10 :: SG.Product Int])
    Product {getProduct = 200}

foldr1 :: (a -> b -> b) -> b -> f a -> b #

Combines the elements of a non-empty structure using a binary function `f`.

    >>> foldr1 (+) 0 (1 :| [2, 3])
    6
    >>> foldr1 (+) 1 $ Identity 3
    4

Since: 1.0.0.0

toNonEmpty :: f a -> NonEmpty a #

Convert a non-empty data structure to a NonEmpty list.

    >>> toNonEmpty (Identity 2)
    2 :| []

head1 :: f a -> a #

The first element of a non-empty data structure.

    >>> head1 (1 :| [2, 3, 4])
    1

last1 :: f a -> a #

The last element of a non-empty data structure.

    >>> last1 (1 :| [2, 3, 4])
    4

maximum1 :: Ord a => f a -> a #

The largest element of a non-empty data structure.

    >>> maximum1 (32 :| [64, 8, 128, 16])
    128

minimum1 :: Ord a => f a -> a #

The smallest element of a non-empty data structure.

    >>> minimum1 (32 :| [64, 8, 128, 16])
    8

maximumOn1 :: Ord b => (a -> b) -> f a -> a #

The largest element of a non-empty data structure with respect to the given comparison function.

    >>> maximumOn1 abs (0 :| [2, 1, -3, -2])
    -3

Since: 1.0.0.0

minimumOn1 :: Ord b => (a -> b) -> f a -> a #

The smallest element of a non-empty data structure with respect to the given comparison function.

    >>> minimumOn1 abs (0 :| [2, 1, -3, -2])
    0

Since: 1.0.0.0

#### Instances

Instances details

Foldable1 NonEmpty # | Since: 0.3.0
Instance details Defined in Relude.Extra.Foldable1 Methods foldMap1 :: Semigroup m => (a -> m) -> NonEmpty a -> m # fold1 :: Semigroup m => NonEmpty m -> m # foldr1 :: (a -> b -> b) -> b -> NonEmpty a -> b # toNonEmpty :: NonEmpty a -> NonEmpty a # head1 :: NonEmpty a -> a # last1 :: NonEmpty a -> a # maximum1 :: Ord a => NonEmpty a -> a # minimum1 :: Ord a => NonEmpty a -> a # maximumOn1 :: Ord b => (a -> b) -> NonEmpty a -> a # minimumOn1 :: Ord b => (a -> b) -> NonEmpty a -> a #
Foldable1 Identity # | Since: 0.3.0
Instance details Defined in Relude.Extra.Foldable1 Methods foldMap1 :: Semigroup m => (a -> m) -> Identity a -> m # fold1 :: Semigroup m => Identity m -> m # foldr1 :: (a -> b -> b) -> b -> Identity a -> b # toNonEmpty :: Identity a -> NonEmpty a # head1 :: Identity a -> a # last1 :: Identity a -> a # maximum1 :: Ord a => Identity a -> a # minimum1 :: Ord a => Identity a -> a # maximumOn1 :: Ord b => (a -> b) -> Identity a -> a # minimumOn1 :: Ord b => (a -> b) -> Identity a -> a #
IsListError => Foldable1 [] # | ⚠️CAUTION⚠️ This instance is for custom error display only. `Foldable1` is not supposed to be used with the lists. In case it is used by mistake, the user will see the following:
    >>> head1 [1, 2, 3]
    ...
    ... The methods of the 'Foldable1' type class work with non-empty containers.
          However, one of the 'Foldable1' functions is applied to the List.
    ...
          Possible fixes:
            * Replace []
              with one of the: 'NonEmpty', 'Identity', '(c,)', 'Compose f g', 'Product f g', 'Sum f g'
            * Or use 'Foldable' class for your own risk.
    ...
Since: 0.6.0.0
Instance details Defined in Relude.Extra.Foldable1 Methods foldMap1 :: Semigroup m => (a -> m) -> [a] -> m # fold1 :: Semigroup m => [m] -> m # foldr1 :: (a -> b -> b) -> b -> [a] -> b # toNonEmpty :: [a] -> NonEmpty a # head1 :: [a] -> a # last1 :: [a] -> a # maximum1 :: Ord a => [a] -> a # minimum1 :: Ord a => [a] -> a # maximumOn1 :: Ord b => (a -> b) -> [a] -> a # minimumOn1 :: Ord b => (a -> b) -> [a] -> a #
Foldable1 ((,) c) # | Since: 0.3.0
Instance details Defined in Relude.Extra.Foldable1 Methods foldMap1 :: Semigroup m => (a -> m) -> (c, a) -> m # fold1 :: Semigroup m => (c, m) -> m # foldr1 :: (a -> b -> b) -> b -> (c, a) -> b # toNonEmpty :: (c, a) -> NonEmpty a # head1 :: (c, a) -> a # last1 :: (c, a) -> a # maximum1 :: Ord a => (c, a) -> a # minimum1 :: Ord a => (c, a) -> a # maximumOn1 :: Ord b => (a -> b) -> (c, a) -> a # minimumOn1 :: Ord b => (a -> b) -> (c, a) -> a #
(Foldable1 f, Foldable1 g) => Foldable1 (Product f g) # | Since: 0.3.0
Instance details Defined in Relude.Extra.Foldable1 Methods foldMap1 :: Semigroup m => (a -> m) -> Product f g a -> m # fold1 :: Semigroup m => Product f g m -> m # foldr1 :: (a -> b -> b) -> b -> Product f g a -> b # toNonEmpty :: Product f g a -> NonEmpty a # head1 :: Product f g a -> a # last1 :: Product f g a -> a # maximum1 :: Ord a => Product f g a -> a # minimum1 :: Ord a => Product f g a -> a # maximumOn1 :: Ord b => (a -> b) -> Product f g a -> a # minimumOn1 :: Ord b => (a -> b) -> Product f g a -> a #
(Foldable1 f, Foldable1 g) => Foldable1 (Sum f g) # | Since: 0.3.0
Instance details Defined in Relude.Extra.Foldable1 Methods foldMap1 :: Semigroup m => (a -> m) -> Sum f g a -> m # fold1 :: Semigroup m => Sum f g m -> m # foldr1 :: (a -> b -> b) -> b -> Sum f g a -> b # toNonEmpty :: Sum f g a -> NonEmpty a # head1 :: Sum f g a -> a # last1 :: Sum f g a -> a # maximum1 :: Ord a => Sum f g a -> a # minimum1 :: Ord a => Sum f g a -> a # maximumOn1 :: Ord b => (a -> b) -> Sum f g a -> a # minimumOn1 :: Ord b => (a -> b) -> Sum f g a -> a #
(Foldable1 f, Foldable1 g) => Foldable1 (Compose f g) # | Since: 0.3.0
Instance details Defined in Relude.Extra.Foldable1 Methods foldMap1 :: Semigroup m => (a -> m) -> Compose f g a -> m # fold1 :: Semigroup m => Compose f g m -> m # foldr1 :: (a -> b -> b) -> b -> Compose f g a -> b # toNonEmpty :: Compose f g a -> NonEmpty a # head1 :: Compose f g a -> a # last1 :: Compose f g a -> a # maximum1 :: Ord a => Compose f g a -> a # minimum1 :: Ord a => Compose f g a -> a # maximumOn1 :: Ord b => (a -> b) -> Compose f g a -> a # minimumOn1 :: Ord b => (a -> b) -> Compose f g a -> a #

foldl1' :: (a -> a -> a) -> NonEmpty a -> a #

Strictly folds non-empty structure with given function `f`:

    foldl1' f [x0, x1, x2 ...] = f (f x0 x1) x2 ...

    >>> foldl1' (++) ([1,2] :| [[3,4], [5,6]])
    [1,2,3,4,5,6]

Since: 0.3.0

average1 :: forall a f. (Foldable1 f, Fractional a) => f a -> a #

Given a `Foldable1` of `Fractional` elements, computes the average if possible and returns the resulting element.

    >>> average1 (42 :| [])
    42.0
    >>> average1 (1 :| [2,3,4])
    2.5

Since: 1.0.0.0