Documentation

Solo is the canonical lifted 1-tuple, just like (,) is the canonical lifted 2-tuple (pair) and (,,) is the canonical lifted 3-tuple (triple).

The most important feature of Solo is that it is possible to force its "outside" (usually by pattern matching) without forcing its "inside", because it is defined as a datatype rather than a newtype. One situation where this can be useful is when writing a function to extract a value from a data structure. Suppose you write an implementation of arrays and offer only this function to index into them:

index :: Array a -> Int -> a

Now imagine that someone wants to extract a value from an array and store it in a lazy-valued finite map/dictionary:

insert "hello" (arr index 12) m

This can actually lead to a space leak. The value is not actually extracted from the array until that value (now buried in a map) is forced. That means the entire array may be kept live by just that value! Often, the solution is to use a strict map, or to force the value before storing it, but for some purposes that's undesirable.

One common solution is to include an indexing function that can produce its result in an arbitrary Applicative context:

indexA :: Applicative f => Array a -> Int -> f a

When using indexA in a pure context, Solo serves as a handy Applicative functor to hold the result. You could write a non-leaky version of the above example thus:

case arr indexA 12 of
  Solo a -> insert "hello" a m

While such simple extraction functions are the most common uses for unary tuples, they can also be useful for fine-grained control of strict-spined data structure traversals, and for unifying the implementations of lazy and strict mapping functions.

uncurry converts a curried function to a function on pairs.

Examples

>>> uncurry (+) (1,2)
3

>>> uncurry ($) (show, 1)
"1"

>>> map (uncurry max) [(1,2), (3,4), (6,8)]
[2,4,8]

Extract the value from a Solo. Very often, values should be extracted directly using pattern matching, to control just what gets evaluated when. getSolo is for convenience in situations where that is not the case:

When the result is passed to a strict function, it makes no difference whether the pattern matching is done on the "outside" or on the "inside":

Data.Set.insert (getSolo sol) set === case sol of Solo v -> Data.Set.insert v set

A traversal may be performed in Solo in order to control evaluation internally, while using getSolo to extract the final result. A strict mapping function, for example, could be defined

map' :: Traversable t => (a -> b) -> t a -> t b
map' f = getSolo . traverse ((Solo $!) . f)

Extract the first component of a pair.

Extract the second component of a pair.

curry converts an uncurried function to a curried function.

Examples

>>> curry fst 1 2
1

Swap the components of a pair.

Counts the number of occurrences on a list.

Nubs using a given field.

Equivalent to nub . sort but running in O(n log n).

Zips Monoid values leaving trailing values.

> mzip ["ab","cd"] ["ef"]
["abef","cd"]

Group values using a given field selector.

WARNING: uses unsafePerformIO and should only be used for debugging!

> idIO print 10
10
10

Applies a function to the head of a list.

Return sets of values based on the list.

The values in the list must me unique.

Like head but allows providing a default value.

Checks if all elements of a list are equal.

Checks if all elements of a list are equal.

Exceptionally this function returns false for an empty or unit list.

This returns true when all elements are equal and the list has a length greater than or equal to two.

Lists choices of values.

Lists choices of values that follow a property.

A variation of foldr that only uses "zero" when the list is empty

Indents a block of text by 4 spaces

Indents a block of text with the provided amount of spaces

Classify values using their Eq instance.

> classify [1,2,3,1,2,1]
[[1,1,1],[2,2],[3]]

(cf. classifyBy, classifyOn)

Classify values by a given comparison function.

> classifyBy (\(x,_) (y,_) -> x == y) [(1,1),(1,2),(2,1),(2,2)]
[[(1,1),(1,2)],[(2,1),(2,2)]]

(cf. classify, classifyOn)

Classify values based on the result of a given function.

> classifyOn head ["sheep", "chip", "ship", "cheap"]
[["sheep","ship"],["chip","cheap"]]

> classifyOn odd [1,2,3,4,5,6]
[[1,3,5],[2,4,6]]

(cf. classify, classifyBy)

Updates the value in a list at a given position.

> updateAt 2 (*10) [1,2,3,4]
[1,2,30,4]

Applies a function to the first element of a pair. Often known on the wild as mapFst.

> first (*10) (1,2)
(10,2)

Applies a function to the second element of a pair. Often known on the wild as mapSnd.

> second (*100) (1,2)
(1,200)

O(n log n). Checks that all elements of the first list are elements of the second.