Either

A generic structure for a type with two possibilities: a Left a or a Right b.

Definition

type Either a b

= Left a

| Right b

The only implementation

Mapping (Functor & Bifunctor)

map : (a -> b) -> Either x a -> Either x b

Apply a function to an Either. If the argument is Right, it will be converted. If the argument is an Left, the same left value will propogate through.

map ((+) 1) <| Left "Hello" == Left "Hello"
map ((+) 1) <| Right 2      == Right 3

mapBoth : (a -> b) -> (c -> d) -> Either a c -> Either b d

Apply the first argument function to a Left and the second argument function to a Right of an Either.

mapBoth (flip (++) "!!") ((+) 1) <| Left "Hello" == Left "Hello!!"
mapBoth (flip (++) "!!") ((+) 1) <| Right 2      == Right 3

mapLeft : (a -> b) -> Either a x -> Either b x

Apply a function to the Left of an Either.

mapLeft ((+) 1) <| Left 2  == Left 3
mapLeft ((+) 1) <| Right 2 == Right 2

mapRight : (a -> b) -> Either x a -> Either x b

Alias for map.

mapEach : (a -> b) -> Either a a -> Either b b

Not crazy on the name, but apply a function to either the Left or the Right where the Left and the Right are of the same type.

mapEach ((+) 1) <| Left 2  == Left 3
mapEach ((+) 1) <| Right 3 == Right 4

Applying (Applicative)

singleton : b -> Either x b

Create a singleton from a value to an Either with a Right of the same type. Also known as pure. Use the Left constructor for a singleton of the Left variety.

singleton 2 == Right 2

andMap : Either x a -> Either x (a -> b) -> Either x b

Apply the function that is inside Either to a value that is inside Either. Return the result inside Either. If one of the Either arguments is Left x, return Left x. Also known as apply.

Left "Hello" |> andMap (Left "World")  == Left "Hello"
Left "Hello" |> andMap (Right 2)       == Left "Hello"
Right ((+) 1) |> andMap (Left "World") == Left "World"
Right ((+) 1) |> andMap (Right 2)      == Right 3

andMapLeft : Either a x -> Either (a -> b) x -> Either b x

Apply the function that is inside Either to a value that is inside Either. Return the result inside Either. If one of the Either arguments is Right x, return Right x. Also known as apply.

Left (flip (++) "!!" ) |> andMap Left "Hello" == Left "Hello!!"
Left (flip (++) "!!" ) |> andMap Right 2      == Right 2
Right 99 |> andMap (Left "World")             == Right 99
Right 99 |> andMap (Right 2)                  == Right 99

andMapRight : Either x a -> Either x (a -> b) -> Either x b

Alias for andMap.

map2 : (a -> b -> c) -> Either x a -> Either x b -> Either x c

Apply a function to two eithers, if both arguments are Right. If not, the first argument which is a Left will propagate through. Also known as liftA2.

map2 (+) (Left "Hello") <| Left "World" == Left "Hello"
map2 (+) (Left "Hello") <| Right 3      == Left "Hello"
map2 (+) (Right 2) <| Left "World"      == Left "World"
map2 (+) (Right 2) <| Right 3           == Right 5

It’s essentially a helper for (and why it’s under applicative)

singleton (+) |> andMap (Right 2) |> andMap (Right 3) == Right 5

map3 : (a -> b -> c -> d) -> Either x a -> Either x b -> Either x c -> Either x d

Like map2, but with 3 eithers. Also known as liftA3

map4 :

(a -> b -> c -> d -> e)

-> Either x a

-> Either x b

-> Either x c

-> Either x d

-> Either x e

Like map2, but with 4 eithers. Also known as liftA4

Folding (Foldable)

length : Either a b -> Int

Returns the length of an Either. This happens to be 0 for a Left and 1 for a Right.

length <| Left 2         == 0
length <| Right "Sharks" == 1

foldl : (a -> b -> b) -> b -> Either a a -> b

Folds an Either over a function with an accumulator. If it is a Left the function is applied with the accumulator. If it is a Right only the accumulator is returned.

foldl (*) 2 <| Left 3  == 6
foldl (*) 2 <| Right 3 == 2

foldr : (a -> b -> b) -> b -> Either a a -> b

Folds an Either over a function with an accumulator. If it is a Right the function is applied with the accumulator. If it is a Left only the accumulator is returned.

foldr (*) 2 <| Left 3  == 2
foldr (*) 2 <| Right 3 == 6

Chaining (Monad)

andThen : (a -> Either x b) -> Either x a -> Either x b

Chain together in many computations that will stop computing if a chain is on a Left. Also known as bind.

Left "Hello" |> andThen ((+) 1 >> Right) == Left "Hello"
Right 2 |> andThen ((+) 1 >> Right)      == Right 3

andThenLeft : (a -> Either b x) -> Either a x -> Either b x

Chain together in many computations that will stop computing if a chain is on a Right. Also known as bind.

Left "Hello" |> andThen (flip (++) "!!" >> Left) == Left "Hello!!"
Right 2 |> andThen (flip (++) "!!" >> Left)      == Right 2

andThenRight : (a -> Either x b) -> Either x a -> Either x b

Alias for andThen.

List Helpers

lefts : List (Either a x) -> List a

Converts a List of Either a x to a List of a.

lefts [ Left "Hello", Right 2 ] == [ "Hello" ]

rights : List (Either x b) -> List b

Converts a List of Either x b to a List of b.

rights [ Left "Hello", Right 2 ] == [ 2 ]

partition : List (Either a b) -> ( List a, List b )

Converts a List of Either a b, into a tuple2 where the first value is a List a and the second is List b.

partition [ Left "Hello", Right 2 ] == ( [ "Hello" ], [ 2 ] )

biList : Either a a -> List a

Collects the list of elements of a structure, from left to right.

biList <| Left 4  == [ 4 ]
biList <| Right 9 == [ 9 ]

Maybe Helpers

toMaybe : Either x b -> Maybe b

Maybe get the Right side of an Either.

toMaybe <| Left "World" == Nothing
toMaybe <| Right 2      == Just 2

leftToMaybe : Either a x -> Maybe a

Maybe get the Left side of an Either.

leftToMaybe <| Left "World" == Just "World"
leftToMaybe <| Right 2 == Nothing

rightToMaybe : Either x b -> Maybe b

Alias for toMaybe.

fromMaybe : a -> Maybe b -> Either a b

Convert from a Maybe to Either with a default value for Left for Nothing.

fromMaybe "Hello" <| Just 2 == Right 2
fromMaybe "Hello" Nothing   == Left "Hello"

leftFromMaybe : b -> Maybe a -> Either a b

Convert from a Maybe to Either with a default value for Right for Nothing.

leftFromMaybe 3 <| Just "World" == Left "World"
leftFromMaybe 3 Nothing         == Right 3

rightFromMaybe : a -> Maybe b -> Either a b

Alias for fromMaybe.

Result Helpers

toResult : Either a b -> Result a b

Convert from Either to Result.

toResult <| Left "World" == Err "World"
toResult <| Right 2      == Ok 2

fromResult : Result a b -> Either a b

Convert from Result to Either.

fromResult <| Err "World" == Left "World"
fromResult <| Ok 2        == Right 2

Rest of the Helpers

isLeft : Either a b -> Bool

Returns True if argument is Left _

isLeft <| Left "World" == True
isLeft <| Right 2      == False

isRight : Either a b -> Bool

Returns True if argument is Right _

isRight <| Left "World" == False
isRight <| Right 2      == True

fromLeft : a -> Either a b -> a

Extract left value or a default.

fromLeft "World" <| Left "Hello" == "Hello"
fromLeft "World" <| Right 2      == "World"

fromRight : b -> Either a b -> b

Extract right value or a default.

fromRight 3 <| Left "Hello" == 3
fromRight 3 <| Right 2      == 2

withDefault : b -> Either a b -> b

Alias for fromRight.

unpack : (a -> c) -> (b -> c) -> Either a b -> c

Given a function for both Left and Right to to type a generic type c, collapse down the Either to a value of that type.

unpack identity toString <| Left "World" == "World"
unpack identity toString <| Right 2      == "2"

unwrap : c -> (b -> c) -> Either x b -> c

Apply a function to Right value. If argument was a Left use the default value. Equivalent to Either.map >> Either.fromRight.

unwrap 99 ((+) 1) <| Left "Hello" == 99
unwrap 99 ((+) 1) <| Right 2      == 3

swap : Either a b -> Either b a

Swap the Left and Right sides of an Either.

swap <| Left "World" == Right "World"
swap <| Right 2      == Left 2

toastal/either/3.2.0