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

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.

voidRight : a -> Either x b -> Either x a

Ignore the return value of the Right using the specified value instead. Exactly the same as <$ in other languages.

voidRight 2 (Right True)       == Right 2
voidRight 2 (Left "banana")    == Left "banana"

voidLeft : a -> Either b x -> Either a x

Ignore the return value of the Left using the specified value instead. NOT the same as $> in other languages.

voidLeft "two" (Right True) == Right True
voidLeft "two" (Left 6)     == Left "two"

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 (\s -> s ++ "!!") ((+) 1) (Left "Hello") == Left "Hello!!"
mapBoth (\s -> s ++ "!!") ((+) 1) (Right 2)      == Right 3

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 (\s -> s ++ "!!") |> andMap (Left "Hello") == Left "Hello!!"
Left (\s -> s ++ "!!") |> 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 (\i -> Right (i + 1)) == Left "Hello"
Right 2      |> andThen (\i -> Right (i + 1)) == 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 (\s -> Left (s ++ "!!")) == Left "Hello!!"
Right 2      |> andThen (\s -> Left (s ++ "!!")) == Right 2

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

Alias for andThen.

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

Appending (Semigroup)

appendLeft : Either appendable x -> Either appendable x -> Either appendable x

Append inner values of a Left.

appendLeft (Left [ 1, 2 ]) (Left [ 3, 4 ])  == Left [ 1, 2, 3, 4 ]
appendLeft (Left [ 1, 2 ]) (Right 'b')      == Left [ 1, 2 ]
appendLeft (Right 'a')     (Left [ 3, 4 ])  == Left [ 3, 4 ]
appendLeft (Right 'a')     (Right 'b')      == Right 'a'

appendRight : Either x appendable -> Either x appendable -> Either x appendable

Append inner values of a Right.

appendRight (Right "Hello") (Right "World") == Right "HelloWorld"
appendRight (Right "Hello") (Left 1)        == Right "Hello"
appendRight (Left 0)        (Right "World") == Right "World"
appendRight (Left 0)        (Left 1)        == Left 0

Equals (Eq)

equals :

Either comparable comparable1

-> Either comparable comparable1

-> Bool

One rendition of equals assuming both sides of the Either are comparable.

equals (Right "Hello") (Right "Hello") == True
equals (Right "Hello") (Right "World") == False
equals (Right "Hello") (Left "Hello")  == False
equals (Right "Hello") (Left 1)        == False
equals (Left 0)        (Right "World") == False
equals (Left 0)        (Left 0)        == True
equals (Left 0)        (Left 1)        == False
equals (Left 0)        (Right 0)       == False

List Helpers

toList : Either x a -> List a

Converts a Either x b to a List of b.

toList (Right 1)  == [ 1 ]
toList (Left 'a') == []

toListVia : (a -> b) -> Either x a -> List b

Folds a Either x b to a List of c via a transforming function.

toList ((+) 1) (Right 1)  == [ 2 ]
toList ((+) 1) (Left 'a') == []

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

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

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

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

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

rights [ Left "Hello", Left, "world", 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", Left "world", Right 2 ] == ( [ "Hello", "World" ], [ 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 ]

Array Helpers

toArray : Either x b -> Array b

Convert from Either to Array

toArray (Right 1)  == Array.fromList [ 1 ]
toArray (Left 'a') == Array.fromList []

toArrayVia : (a -> b) -> Either x a -> Array b

Folds from Either to Array via a transforming function.

toArrayVia ((+) 1) (Right 1)  == Array.fromList [ 2 ]
toArrayVia ((+) 1) (Left 'a') == Array.fromList []

Set Helpers

toSet : Either x comparable -> Set comparable

Convert from Either to Set

toSet (Right 1)  == Set.fromList [ 1 ]
toSet (Left 'a') == Set.fromList []

toSetVia : (a -> comparable) -> Either x a -> Set comparable

Folds from Either to Set via a transforming function.

toSetVia ((+) 1) (Right 1)  == Set.fromList [ 2 ]
toSetVia ((+) 1) (Left 'a') == Set.fromList []

Dict Helpers

toDict : Either x ( comparable, v ) -> Dict comparable v

Convert from Either to Dict

toDict (Right ( "KEY", 1 ))  == Dict.fromList [ ( "KEY", 1 ) ]
toDict (Left 'a') == Dict.fromList []

toDictVia : (a -> ( comparable, v )) -> Either x a -> Dict comparable v

Folds from Either to Dict via a transforming function.

toDictVia (Right ( "KEY", 1 ))  == Dict.fromList [ ( "KEY", 1 ) ]
toDictVia (Left 'a') == Dict.fromList []

Maybe Helpers

toMaybe : Either x b -> Maybe b

Maybe get the Right side of an Either.

toMaybe (Right 2)      == Just 2
toMaybe (Left "World") == Nothing

toMaybeVia : (b -> c) -> Either x b -> Maybe c

Folds a Maybe get the Right side of an Either via a transforming function.

toMaybeVia ((*) 3) (Right 2)      == Just 6
toMaybeVia ((*) 3) (Left "World") == Nothing

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 (Right 2)      == Ok 2
toResult (Left "World") == Err "World"

toResultVia : (b -> c) -> Either a b -> Result a c

Fold from Either to Result via transforming function.

toResultVia ((+) 3) (Left "World") == Err "World"
toResultVia ((+) 3) (Right 2)      == Ok 5

fromResult : Result a b -> Either a b

Convert from Result to Either.

fromResult (Ok 2)        == Right 2
fromResult (Err "World") == Left "World"

Task Helpers

toTask : Either a b -> Task a b

Convert from Either to Task

toTask (Right "World") -- succeed "World"
toTask (Left 2)      -- fail 2

toTaskVia : (b -> c) -> Either a b -> Task a c

Fold from Either to Task via transforming function.

toTaskVia (\s -> s ++ "!!") (Right "World") -- succeed "World!!"
toTaskVia (\s -> s ++ "!!") (Left 2)        -- fail 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 : b -> (a -> b) -> Either x a -> b

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