on package:universum

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)

Create a list, map, Text, etc from a single element.

Async safe version of onException

Type class for types that can be created from one element. singleton is lone name for this function. Also constructions of different type differ: :[] for lists, two arguments for Maps. Also some data types are monomorphic.

>>> one True :: [Bool]
[True]

>>> one 'a' :: Text
"a"

>>> one (3, "hello") :: HashMap Int String
fromList [(3,"hello")]

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.

The Const functor.

One or none. It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int

>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> final
Left "it failed"

>>> runExcept $ optional canFail *> final
Right 42

The kind of constraints, like Show a

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.

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

The concatenation of all the elements of a container of lists.

Examples

Basic usage:

>>> concat (Just [1, 2, 3])
[1,2,3]

>>> concat (Left 42)
[]

>>> concat [[1, 2, 3], [4, 5], [6], []]
[1,2,3,4,5,6]

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.

The function properFraction takes a real fractional number x and returns a pair (n,f) such that x = n+f, and:

• n is an integral number with the same sign as x; and
• f is a fraction with the same type and sign as x, and with absolute value less than 1.

The default definitions of the ceiling, floor, truncate and round functions are in terms of properFraction.

the rational equivalent of its real argument with full precision

This module exports all container-related stuff.

Very similar to Foldable but also allows instances for monomorphic types like Text but forbids instances for Maybe and similar. This class is used as a replacement for Foldable type class. It solves the following problems:

1. Container, foldr and other functions work on more types for which it makes sense.
2. You can't accidentally use Container on polymorphic Foldable (like list), replace list with Maybe and then debug error for two days.
3. More efficient implementaions of functions for polymorphic types (like elem for Set).

The drawbacks:

1. Type signatures of polymorphic functions look more scary.
2. Orphan instances are involved if you want to use foldr (and similar) on types from libraries.

Version of concatMap constrained to Container.

>>> concatMap (\x -> [x + 1, x + 2]) [1, 2, 3]
[2,3,3,4,4,5]

Re-exports most useful functionality from 'safe-exceptions'. Also provides some functions to work with exceptions over MonadError.