Relude.Base

The Prelude.toEnum method restricted to the type Char.

The character type Char represents Unicode codespace and its elements are code points as in definitions D9 and D10 of the Unicode Standard.

Character literals in Haskell are single-quoted: 'Q', 'Я' or 'Ω'. To represent a single quote itself use '\'', and to represent a backslash use '\\'. The full grammar can be found in the section 2.6 of the Haskell 2010 Language Report.

To specify a character by its code point one can use decimal, hexadecimal or octal notation: '\65', '\x41' and '\o101' are all alternative forms of 'A'. The largest code point is '\x10ffff'.

There is a special escape syntax for ASCII control characters:

Data.Char provides utilities to work with Char.

The Eq class defines equality (==) and inequality (/=). All the basic datatypes exported by the Prelude are instances of Eq, and Eq may be derived for any datatype whose constituents are also instances of Eq.

The Haskell Report defines no laws for Eq. However, instances are encouraged to follow these properties:

Reflexivity

x == x

=

True

Symmetry

x == y

=

y == x

Transitivity

if

x == y && y == z

=

True

, then

x == z

=

True

Extensionality

if

x == y

=

True

and

f

is a function whose return type is an instance of

Eq

, then

f x == f y

=

True

Negation

x /= y

=

not (x == y)

comparing p x y = compare (p x) (p y)

Useful combinator for use in conjunction with the xxxBy family of functions from Data.List, for example:

  ... sortBy (comparing fst) ...

The Ord class is used for totally ordered datatypes.

Instances of Ord can be derived for any user-defined datatype whose constituent types are in Ord. The declared order of the constructors in the data declaration determines the ordering in derived Ord instances. The Ordering datatype allows a single comparison to determine the precise ordering of two objects.

Ord, as defined by the Haskell report, implements a total order and has the following properties:

Comparability

x <= y || y <= x

=

True

Transitivity

if

x <= y && y <= z

=

True

, then

x <= z

=

True

Reflexivity

x <= x

=

True

Antisymmetry

if

x <= y && y <= x

=

True

, then

x == y

=

True

The following operator interactions are expected to hold:

1. x >= y = y <= x

2. x < y = x <= y && x /= y

3. x > y = y < x

4. x < y = compare x y == LT

5. x > y = compare x y == GT

6. x == y = compare x y == EQ

7. min x y == if x <= y then x else y = True

8. max x y == if x >= y then x else y = True

Note that (7.) and (8.) do not require min and max to return either of their arguments. The result is merely required to equal one of the arguments in terms of (==). Users who expect a stronger guarantee are advised to write their own min and/or max functions.

The nuance of the above distinction is not always fully internalized by developers, and in the past (tracing back to the Haskell 1.4 Report) the specification for Ord asserted the stronger property that (min x y, max x y) = (x, y) or (y, x), or in other words, that min and max will return one of their arguments, using argument order as the tie-breaker if the arguments are equal by comparison. A few list and Foldable functions have behavior that is best understood with this assumption in mind: all variations of minimumBy and maximumBy (which can't use min and max in their implementations) are written such that minimumBy compare and maximumBy compare are respectively equivalent to minimum and maximum (which do use min and max) only if min and max adhere to this tie-breaking convention. Otherwise, if there are multiple least or largest elements in a container, minimum and maximum may not return the same one that minimumBy compare and maximumBy compare do (though they should return something that is equal). (This is relevant for types with non-extensional equality, like Arg, but also in cases where the precise reference held matters for memory-management reasons.) Unless there is a reason to deviate, it is less confusing for implementors of Ord to respect this same convention (as the default definitions of min and max do).

Minimal complete definition: either compare or <=. Using compare can be more efficient for complex types.

The Down type allows you to reverse sort order conveniently. A value of type Down a contains a value of type a (represented as Down a).

If a has an Ord instance associated with it then comparing two values thus wrapped will give you the opposite of their normal sort order. This is particularly useful when sorting in generalised list comprehensions, as in: then sortWith by Down x.

>>> compare True FalseGT

>>> compare (Down True) (Down False)LT

If a has a Bounded instance then the wrapped instance also respects the reversed ordering by exchanging the values of minBound and maxBound.

>>> minBound :: Int-9223372036854775808

>>> minBound :: Down IntDown 9223372036854775807

All other instances of Down a behave as they do for a.

File and directory names are values of type String, whose precise meaning is operating system dependent. Files can be opened, yielding a handle which can then be used to operate on the contents of that file.

See GHC.Internal.System.IO.openFile

A value of type IO a is a computation which, when performed, does some I/O before returning a value of type a.

There is really only one way to "perform" an I/O action: bind it to Main.main in your program. When your program is run, the I/O will be performed. It isn't possible to perform I/O from an arbitrary function, unless that function is itself in the IO monad and called at some point, directly or indirectly, from Main.main.

IO is a monad, so IO actions can be combined using either the do-notation or the Prelude.>> and Prelude.>>= operations from the Prelude.Monad class.

The function coerce allows you to safely convert between values of types that have the same representation with no run-time overhead. In the simplest case you can use it instead of a newtype constructor, to go from the newtype's concrete type to the abstract type. But it also works in more complicated settings, e.g. converting a list of newtypes to a list of concrete types.

When used in conversions involving a newtype wrapper, make sure the newtype constructor is in scope.

This function is representation-polymorphic, but the RuntimeRep type argument is marked as Inferred, meaning that it is not available for visible type application. This means the typechecker will accept coerce @Int @Age 42.

Examples

>>> newtype TTL = TTL Int deriving (Eq, Ord, Show)>>> newtype Age = Age Int deriving (Eq, Ord, Show)>>> coerce (Age 42) :: TTLTTL 42>>> coerce (+ (1 :: Int)) (Age 42) :: TTLTTL 43>>> coerce (map (+ (1 :: Int))) [Age 42, Age 24] :: [TTL][TTL 43,TTL 25]

Coercible is a two-parameter class that has instances for types a and b if the compiler can infer that they have the same representation. This class does not have regular instances; instead they are created on-the-fly during type-checking. Trying to manually declare an instance of Coercible is an error.

Nevertheless one can pretend that the following three kinds of instances exist. First, as a trivial base-case:

instance Coercible a a

Furthermore, for every type constructor there is an instance that allows to coerce under the type constructor. For example, let D be a prototypical type constructor (data or newtype) with three type arguments, which have roles nominal, representational resp. phantom. Then there is an instance of the form

instance Coercible b b' => Coercible (D a b c) (D a b' c')

Note that the nominal type arguments are equal, the representational type arguments can differ, but need to have a Coercible instance themself, and the phantom type arguments can be changed arbitrarily.

The third kind of instance exists for every newtype NT = MkNT T and comes in two variants, namely

instance Coercible a T => Coercible a NT

instance Coercible T b => Coercible NT b

This instance is only usable if the constructor MkNT is in scope.

If, as a library author of a type constructor like Set a, you want to prevent a user of your module to write coerce :: Set T -> Set NT, you need to set the role of Set's type parameter to nominal, by writing

type role Set nominal

For more details about this feature, please refer to Safe Coercions by Joachim Breitner, Richard A. Eisenberg, Simon Peyton Jones and Stephanie Weirich.

The kind of lifted constraints

The kind of types with lifted values. For example Int :: Type.

Proxy is a type that holds no data, but has a phantom parameter of arbitrary type (or even kind). Its use is to provide type information, even though there is no value available of that type (or it may be too costly to create one).

Historically, Proxy :: Proxy a is a safer alternative to the undefined :: a idiom.

>>> Proxy :: Proxy (Void, Int -> Int)Proxy

Proxy can even hold types of higher kinds,

>>> Proxy :: Proxy EitherProxy

>>> Proxy :: Proxy FunctorProxy

>>> Proxy :: Proxy complicatedStructureProxy

Lifted, homogeneous equality. By lifted, we mean that it can be bogus (deferred type error). By homogeneous, the two types a and b must have the same kinds.

The class Typeable allows a concrete representation of a type to be calculated.

Since Void values logically don't exist, this witnesses the logical reasoning tool of "ex falso quodlibet".

>>> let x :: Either Void Int; x = Right 5>>> :{case x of    Right r -> r    Left l  -> absurd l:}5

If Void is uninhabited then any Functor that holds only values of type Void is holding no values. It is implemented in terms of fmap absurd.

Uninhabited data type

Strict (call-by-value) application operator. It takes a function and an argument, evaluates the argument to weak head normal form (WHNF), then calls the function with that value.

asTypeOf is a type-restricted version of const. It is usually used as an infix operator, and its typing forces its first argument (which is usually overloaded) to have the same type as the second.

The Prelude.fromEnum method restricted to the type Char.

The value of seq a b is bottom if a is bottom, and otherwise equal to b. In other words, it evaluates the first argument a to weak head normal form (WHNF). seq is usually introduced to improve performance by avoiding unneeded laziness.

A note on evaluation order: the expression seq a b does not guarantee that a will be evaluated before b. The only guarantee given by seq is that the both a and b will be evaluated before seq returns a value. In particular, this means that b may be evaluated before a. If you need to guarantee a specific order of evaluation, you must use the function pseq from the "parallel" package.

Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.

A Generic instance must satisfy the following laws:

from . to ≡ Prelude.id
to . from ≡ Prelude.id