on package:incipit-base

on b u x y runs the binary function b on the results of applying unary function u to two arguments x and y. From the opposite perspective, it transforms two inputs and combines the outputs.

((+) `on` f) x y = f x + f y

Typical usage: sortBy (compare `on` fst). Algebraic properties:

• (*) `on` id = (*) -- (if (*) ∉ {⊥, const
  ⊥})

• ((*) `on` f) `on` g = (*) `on` (f . g)

• flip on f . flip on g = flip on (g .
  f)

A handler for a decoding error.

Function type for handling a coding error. It is supplied with two inputs:

• A String that describes the error.
• The input value that caused the error. If the error arose because the end of input was reached or could not be identified precisely, this value will be Nothing.

If the handler returns a value wrapped with Just, that value will be used in the output as the replacement for the invalid input. If it returns Nothing, no value will be used in the output. Should the handler need to abort processing, it should use error or throw an exception (preferably a UnicodeException). It may use the description provided to construct a more helpful error report.

Convert a character to its Unicode code point (cf. ord)

Extending a type-level symbol with a type-level character

The Const functor.

The kind of constraints, like Show a

The class of contravariant functors. Whereas in Haskell, one can think of a Functor as containing or producing values, a contravariant functor is a functor that can be thought of as consuming values. As an example, consider the type of predicate functions a -> Bool. One such predicate might be negative x = x < 0, which classifies integers as to whether they are negative. However, given this predicate, we can re-use it in other situations, providing we have a way to map values to integers. For instance, we can use the negative predicate on a person's bank balance to work out if they are currently overdrawn:

newtype Predicate a = Predicate { getPredicate :: a -> Bool }

instance Contravariant Predicate where
contramap :: (a' -> a) -> (Predicate a -> Predicate a')
contramap f (Predicate p) = Predicate (p . f)
|   `- First, map the input...
`----- then apply the predicate.

overdrawn :: Predicate Person
overdrawn = contramap personBankBalance negative

Any instance should be subject to the following laws:

• Identity contramap id = id
• Composition contramap (g . f) = contramap f . contramap g

Note, that the second law follows from the free theorem of the type of contramap and the first law, so you need only check that the former condition holds.

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
SomeCompilerException a <- fromException x
cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
toException = compilerExceptionToException
fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
SomeFrontendException a <- fromException x
cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
deriving Show

instance Exception MismatchedParentheses where
toException   = frontendExceptionToException
fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

Fractional numbers, supporting real division. The Haskell Report defines no laws for Fractional. However, (+) and (*) are customarily expected to define a division ring and have the following properties:

• recip gives the multiplicative inverse x * recip x = recip x * x = fromInteger 1

Note that it isn't customarily expected that a type instance of Fractional implement a field. However, all instances in base do.

The Monad class defines the basic operations over a monad, a concept from a branch of mathematics known as category theory. From the perspective of a Haskell programmer, however, it is best to think of a monad as an abstract datatype of actions. Haskell's do expressions provide a convenient syntax for writing monadic expressions. Instances of Monad should satisfy the following:

• Left identity return a >>= k = k a
• Right identity m >>= return = m
• Associativity m >>= (\x -> k x >>= h) = (m >>= k) >>= h

Furthermore, the Monad and Applicative operations should relate as follows:

• pure = return

• m1 <*> m2 = m1 >>= (x1 -> m2
  >>= (x2 -> return (x1 x2)))

The above laws imply:

• fmap f xs = xs >>= return .
  f

• (>>) = (*>)

and that pure and (<*>) satisfy the applicative functor laws. The instances of Monad for lists, Maybe and IO defined in the Prelude satisfy these laws.

When a value is bound in do-notation, the pattern on the left hand side of <- might not match. In this case, this class provides a function to recover. A Monad without a MonadFail instance may only be used in conjunction with pattern that always match, such as newtypes, tuples, data types with only a single data constructor, and irrefutable patterns (~pat). Instances of MonadFail should satisfy the following law: fail s should be a left zero for >>=,

fail s >>= f  =  fail s

If your Monad is also MonadPlus, a popular definition is

fail _ = mzero

Monads that also support choice and failure.

The class of monoids (types with an associative binary operation that has an identity). Instances should satisfy the following:

• Right identity x <> mempty = x
• Left identity mempty <> x = x
• Associativity x <> (y <> z) = (x <> y) <> z (Semigroup law)
• Concatenation mconcat = foldr (<>) mempty

The method names refer to the monoid of lists under concatenation, but there are many other instances. Some types can be viewed as a monoid in more than one way, e.g. both addition and multiplication on numbers. In such cases we often define newtypes and make those instances of Monoid, e.g. Sum and Product. NOTE: Semigroup is a superclass of Monoid since base-4.11.0.0.

Non-empty (and non-strict) list type.

Arbitrary-precision rational numbers, represented as a ratio of two Integer values. A rational number may be constructed using the % operator.

The SomeException type is the root of the exception type hierarchy. When an exception of type e is thrown, behind the scenes it is encapsulated in a SomeException.

This type family yields type-level Just storing the first character of a symbol and its tail if it is defined and Nothing otherwise.

const x is a unary function which evaluates to x for all inputs.

>>> const 42 "hello"
42

>>> map (const 42) [0..3]
[42,42,42,42]

Conversion from a Rational (that is Ratio Integer). A floating literal stands for an application of fromRational to a value of type Rational, so such literals have type (Fractional a) => a.

Fold a list using the monoid. For most types, the default definition for mconcat will be used, but the function is included in the class definition so that an optimized version can be provided for specific types.

>>> mconcat ["Hello", " ", "Haskell", "!"]
"Hello Haskell!"