2999 lines
102 KiB
Text
2999 lines
102 KiB
Text
-- Hoogle documentation, generated by Haddock
|
|
-- See Hoogle, http://www.haskell.org/hoogle/
|
|
|
|
|
|
-- | A Haskell prelude optimized for safety
|
|
--
|
|
-- Please see README.md
|
|
@package safe-prelude
|
|
@version 0.1.0.0
|
|
|
|
module SafePrelude
|
|
|
|
-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
|
|
-- <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
|
|
-- (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
|
|
-- as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
|
|
-- errors or exceptional cases without resorting to drastic measures such
|
|
-- as <a>error</a>.
|
|
--
|
|
-- The <a>Maybe</a> type is also a monad. It is a simple kind of error
|
|
-- monad, where all errors are represented by <a>Nothing</a>. A richer
|
|
-- error monad can be built using the <a>Either</a> type.
|
|
data Maybe a :: * -> *
|
|
Nothing :: Maybe a
|
|
Just :: a -> Maybe a
|
|
data Ordering :: *
|
|
LT :: Ordering
|
|
EQ :: Ordering
|
|
GT :: Ordering
|
|
data Bool :: *
|
|
False :: Bool
|
|
True :: Bool
|
|
|
|
-- | The character type <a>Char</a> is an enumeration whose values
|
|
-- represent Unicode (or equivalently ISO/IEC 10646) characters (see
|
|
-- <a>http://www.unicode.org/</a> for details). This set extends the ISO
|
|
-- 8859-1 (Latin-1) character set (the first 256 characters), which is
|
|
-- itself an extension of the ASCII character set (the first 128
|
|
-- characters). A character literal in Haskell has type <a>Char</a>.
|
|
--
|
|
-- To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
|
|
-- defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
|
|
-- <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and
|
|
-- <tt>chr</tt>).
|
|
data Char :: *
|
|
|
|
-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
|
|
-- performed, does some I/O before returning a value of type <tt>a</tt>.
|
|
--
|
|
-- There is really only one way to "perform" an I/O action: bind it to
|
|
-- <tt>Main.main</tt> 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 <a>IO</a> monad and
|
|
-- called at some point, directly or indirectly, from <tt>Main.main</tt>.
|
|
--
|
|
-- <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
|
|
-- either the do-notation or the <tt>>></tt> and <tt>>>=</tt>
|
|
-- operations from the <tt>Monad</tt> class.
|
|
data IO a :: * -> *
|
|
|
|
-- | The <a>Either</a> type represents values with two possibilities: a
|
|
-- value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
|
|
-- a</tt> or <tt><a>Right</a> b</tt>.
|
|
--
|
|
-- The <a>Either</a> type is sometimes used to represent a value which is
|
|
-- either correct or an error; by convention, the <a>Left</a> constructor
|
|
-- is used to hold an error value and the <a>Right</a> constructor is
|
|
-- used to hold a correct value (mnemonic: "right" also means "correct").
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
|
|
-- of values which can be either a <a>String</a> or an <a>Int</a>. The
|
|
-- <a>Left</a> constructor can be used only on <a>String</a>s, and the
|
|
-- <a>Right</a> constructor can be used only on <a>Int</a>s:
|
|
--
|
|
-- <pre>
|
|
-- >>> let s = Left "foo" :: Either String Int
|
|
--
|
|
-- >>> s
|
|
-- Left "foo"
|
|
--
|
|
-- >>> let n = Right 3 :: Either String Int
|
|
--
|
|
-- >>> n
|
|
-- Right 3
|
|
--
|
|
-- >>> :type s
|
|
-- s :: Either String Int
|
|
--
|
|
-- >>> :type n
|
|
-- n :: Either String Int
|
|
-- </pre>
|
|
--
|
|
-- The <a>fmap</a> from our <a>Functor</a> instance will ignore
|
|
-- <a>Left</a> values, but will apply the supplied function to values
|
|
-- contained in a <a>Right</a>:
|
|
--
|
|
-- <pre>
|
|
-- >>> let s = Left "foo" :: Either String Int
|
|
--
|
|
-- >>> let n = Right 3 :: Either String Int
|
|
--
|
|
-- >>> fmap (*2) s
|
|
-- Left "foo"
|
|
--
|
|
-- >>> fmap (*2) n
|
|
-- Right 6
|
|
-- </pre>
|
|
--
|
|
-- The <a>Monad</a> instance for <a>Either</a> allows us to chain
|
|
-- together multiple actions which may fail, and fail overall if any of
|
|
-- the individual steps failed. First we'll write a function that can
|
|
-- either parse an <a>Int</a> from a <a>Char</a>, or fail.
|
|
--
|
|
-- <pre>
|
|
-- >>> import Data.Char ( digitToInt, isDigit )
|
|
--
|
|
-- >>> :{
|
|
-- let parseEither :: Char -> Either String Int
|
|
-- parseEither c
|
|
-- | isDigit c = Right (digitToInt c)
|
|
-- | otherwise = Left "parse error"
|
|
--
|
|
-- >>> :}
|
|
-- </pre>
|
|
--
|
|
-- The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
|
|
-- can be parsed as <a>Int</a>s.
|
|
--
|
|
-- <pre>
|
|
-- >>> :{
|
|
-- let parseMultiple :: Either String Int
|
|
-- parseMultiple = do
|
|
-- x <- parseEither '1'
|
|
-- y <- parseEither '2'
|
|
-- return (x + y)
|
|
--
|
|
-- >>> :}
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> parseMultiple
|
|
-- Right 3
|
|
-- </pre>
|
|
--
|
|
-- But the following should fail overall, since the first operation where
|
|
-- we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
|
|
--
|
|
-- <pre>
|
|
-- >>> :{
|
|
-- let parseMultiple :: Either String Int
|
|
-- parseMultiple = do
|
|
-- x <- parseEither 'm'
|
|
-- y <- parseEither '2'
|
|
-- return (x + y)
|
|
--
|
|
-- >>> :}
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> parseMultiple
|
|
-- Left "parse error"
|
|
-- </pre>
|
|
data Either a b :: * -> * -> *
|
|
Left :: a -> Either a b
|
|
Right :: b -> Either a b
|
|
|
|
-- | A space-efficient representation of a <a>Word8</a> vector, supporting
|
|
-- many efficient operations.
|
|
--
|
|
-- A <a>ByteString</a> contains 8-bit bytes, or by using the operations
|
|
-- from <a>Data.ByteString.Char8</a> it can be interpreted as containing
|
|
-- 8-bit characters.
|
|
data ByteString :: *
|
|
|
|
-- | A space efficient, packed, unboxed Unicode text type.
|
|
data Text :: *
|
|
|
|
-- | A Map from keys <tt>k</tt> to values <tt>a</tt>.
|
|
data Map k a :: * -> * -> *
|
|
|
|
-- | A map from keys to values. A map cannot contain duplicate keys; each
|
|
-- key can map to at most one value.
|
|
data HashMap k v :: * -> * -> *
|
|
|
|
-- | A map of integers to values <tt>a</tt>.
|
|
data IntMap a :: * -> *
|
|
|
|
-- | A set of values <tt>a</tt>.
|
|
data Set a :: * -> *
|
|
|
|
-- | A set of values. A set cannot contain duplicate values.
|
|
data HashSet a :: * -> *
|
|
|
|
-- | A set of integers.
|
|
data IntSet :: *
|
|
|
|
-- | General-purpose finite sequences.
|
|
data Seq a :: * -> *
|
|
|
|
-- | Identity functor and monad. (a non-strict monad)
|
|
newtype Identity a :: * -> *
|
|
Identity :: a -> Identity a
|
|
[runIdentity] :: Identity a -> a
|
|
|
|
-- | The <tt>SomeException</tt> type is the root of the exception type
|
|
-- hierarchy. When an exception of type <tt>e</tt> is thrown, behind the
|
|
-- scenes it is encapsulated in a <tt>SomeException</tt>.
|
|
data SomeException :: *
|
|
[SomeException] :: SomeException
|
|
|
|
-- | Superclass for asynchronous exceptions.
|
|
data SomeAsyncException :: *
|
|
[SomeAsyncException] :: SomeAsyncException
|
|
|
|
-- | A <a>String</a> is a list of characters. String constants in Haskell
|
|
-- are values of type <a>String</a>.
|
|
type String = [Char]
|
|
|
|
-- | File and directory names are values of type <a>String</a>, 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.
|
|
type FilePath = String
|
|
|
|
-- | A <a>Word</a> is an unsigned integral type, with the same size as
|
|
-- <a>Int</a>.
|
|
data Word :: *
|
|
|
|
-- | 8-bit unsigned integer type
|
|
data Word8 :: *
|
|
|
|
-- | 16-bit unsigned integer type
|
|
data Word16 :: *
|
|
|
|
-- | 32-bit unsigned integer type
|
|
data Word32 :: *
|
|
|
|
-- | 64-bit unsigned integer type
|
|
data Word64 :: *
|
|
|
|
-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
|
|
-- 2^29-1]</tt>. The exact range for a given implementation can be
|
|
-- determined by using <a>minBound</a> and <a>maxBound</a> from the
|
|
-- <a>Bounded</a> class.
|
|
data Int :: *
|
|
|
|
-- | 8-bit signed integer type
|
|
data Int8 :: *
|
|
|
|
-- | 16-bit signed integer type
|
|
data Int16 :: *
|
|
|
|
-- | 32-bit signed integer type
|
|
data Int32 :: *
|
|
|
|
-- | 64-bit signed integer type
|
|
data Int64 :: *
|
|
|
|
-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
|
|
-- <a>S#</a>
|
|
--
|
|
-- Useful properties resulting from the invariants:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre>abs (<a>S#</a> _) <= abs (<a>Jp#</a> _)</pre></li>
|
|
-- <li><pre>abs (<a>S#</a> _) < abs (<a>Jn#</a> _)</pre></li>
|
|
-- </ul>
|
|
data Integer :: *
|
|
|
|
-- | Arbitrary-precision rational numbers, represented as a ratio of two
|
|
-- <a>Integer</a> values. A rational number may be constructed using the
|
|
-- <a>%</a> operator.
|
|
type Rational = Ratio Integer
|
|
|
|
-- | Single-precision floating point numbers. It is desirable that this
|
|
-- type be at least equal in range and precision to the IEEE
|
|
-- single-precision type.
|
|
data Float :: *
|
|
|
|
-- | Double-precision floating point numbers. It is desirable that this
|
|
-- type be at least equal in range and precision to the IEEE
|
|
-- double-precision type.
|
|
data Double :: *
|
|
|
|
-- | A concrete, poly-kinded proxy type
|
|
data Proxy k (t :: k) :: forall k. k -> *
|
|
Proxy :: Proxy k
|
|
|
|
-- | The <a>Ord</a> class is used for totally ordered datatypes.
|
|
--
|
|
-- Instances of <a>Ord</a> can be derived for any user-defined datatype
|
|
-- whose constituent types are in <a>Ord</a>. The declared order of the
|
|
-- constructors in the data declaration determines the ordering in
|
|
-- derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
|
|
-- single comparison to determine the precise ordering of two objects.
|
|
--
|
|
-- Minimal complete definition: either <a>compare</a> or <a><=</a>.
|
|
-- Using <a>compare</a> can be more efficient for complex types.
|
|
class Eq a => Ord a
|
|
compare :: a -> a -> Ordering
|
|
(<) :: a -> a -> Bool
|
|
(<=) :: a -> a -> Bool
|
|
(>) :: a -> a -> Bool
|
|
(>=) :: a -> a -> Bool
|
|
max :: a -> a -> a
|
|
min :: a -> a -> a
|
|
|
|
-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
|
|
-- (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
|
|
-- are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
|
|
-- datatype whose constituents are also instances of <a>Eq</a>.
|
|
--
|
|
-- Minimal complete definition: either <a>==</a> or <a>/=</a>.
|
|
class Eq a
|
|
(==) :: a -> a -> Bool
|
|
(/=) :: a -> a -> Bool
|
|
|
|
-- | The <a>Bounded</a> class is used to name the upper and lower limits of
|
|
-- a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
|
|
-- that are not totally ordered may also have upper and lower bounds.
|
|
--
|
|
-- The <a>Bounded</a> class may be derived for any enumeration type;
|
|
-- <a>minBound</a> is the first constructor listed in the <tt>data</tt>
|
|
-- declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
|
|
-- be derived for single-constructor datatypes whose constituent types
|
|
-- are in <a>Bounded</a>.
|
|
class Bounded a
|
|
minBound :: a
|
|
maxBound :: a
|
|
|
|
-- | Conversion of values to readable <a>String</a>s.
|
|
--
|
|
-- Derived instances of <a>Show</a> have the following properties, which
|
|
-- are compatible with derived instances of <a>Read</a>:
|
|
--
|
|
-- <ul>
|
|
-- <li>The result of <a>show</a> is a syntactically correct Haskell
|
|
-- expression containing only constants, given the fixity declarations in
|
|
-- force at the point where the type is declared. It contains only the
|
|
-- constructor names defined in the data type, parentheses, and spaces.
|
|
-- When labelled constructor fields are used, braces, commas, field
|
|
-- names, and equal signs are also used.</li>
|
|
-- <li>If the constructor is defined to be an infix operator, then
|
|
-- <a>showsPrec</a> will produce infix applications of the
|
|
-- constructor.</li>
|
|
-- <li>the representation will be enclosed in parentheses if the
|
|
-- precedence of the top-level constructor in <tt>x</tt> is less than
|
|
-- <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
|
|
-- <tt>0</tt> then the result is never surrounded in parentheses; if
|
|
-- <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
|
|
-- unless it is an atomic expression.</li>
|
|
-- <li>If the constructor is defined using record syntax, then
|
|
-- <a>show</a> will produce the record-syntax form, with the fields given
|
|
-- in the same order as the original declaration.</li>
|
|
-- </ul>
|
|
--
|
|
-- For example, given the declarations
|
|
--
|
|
-- <pre>
|
|
-- infixr 5 :^:
|
|
-- data Tree a = Leaf a | Tree a :^: Tree a
|
|
-- </pre>
|
|
--
|
|
-- the derived instance of <a>Show</a> is equivalent to
|
|
--
|
|
-- <pre>
|
|
-- instance (Show a) => Show (Tree a) where
|
|
--
|
|
-- showsPrec d (Leaf m) = showParen (d > app_prec) $
|
|
-- showString "Leaf " . showsPrec (app_prec+1) m
|
|
-- where app_prec = 10
|
|
--
|
|
-- showsPrec d (u :^: v) = showParen (d > up_prec) $
|
|
-- showsPrec (up_prec+1) u .
|
|
-- showString " :^: " .
|
|
-- showsPrec (up_prec+1) v
|
|
-- where up_prec = 5
|
|
-- </pre>
|
|
--
|
|
-- Note that right-associativity of <tt>:^:</tt> is ignored. For example,
|
|
--
|
|
-- <ul>
|
|
-- <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
|
|
-- string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
|
|
-- </ul>
|
|
class Show a
|
|
|
|
-- | Convert a value to a readable <a>String</a>.
|
|
--
|
|
-- <a>showsPrec</a> should satisfy the law
|
|
--
|
|
-- <pre>
|
|
-- showsPrec d x r ++ s == showsPrec d x (r ++ s)
|
|
-- </pre>
|
|
--
|
|
-- Derived instances of <a>Read</a> and <a>Show</a> satisfy the
|
|
-- following:
|
|
--
|
|
-- <ul>
|
|
-- <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
|
|
-- (<a>showsPrec</a> d x ""))</tt>.</li>
|
|
-- </ul>
|
|
--
|
|
-- That is, <a>readsPrec</a> parses the string produced by
|
|
-- <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
|
|
-- with.
|
|
showsPrec :: Int -> a -> ShowS
|
|
|
|
-- | A specialised variant of <a>showsPrec</a>, using precedence context
|
|
-- zero, and returning an ordinary <a>String</a>.
|
|
show :: a -> String
|
|
|
|
-- | The method <a>showList</a> is provided to allow the programmer to give
|
|
-- a specialised way of showing lists of values. For example, this is
|
|
-- used by the predefined <a>Show</a> instance of the <a>Char</a> type,
|
|
-- where values of type <a>String</a> should be shown in double quotes,
|
|
-- rather than between square brackets.
|
|
showList :: [a] -> ShowS
|
|
|
|
-- | Parsing of <a>String</a>s, producing values.
|
|
--
|
|
-- Derived instances of <a>Read</a> make the following assumptions, which
|
|
-- derived instances of <a>Show</a> obey:
|
|
--
|
|
-- <ul>
|
|
-- <li>If the constructor is defined to be an infix operator, then the
|
|
-- derived <a>Read</a> instance will parse only infix applications of the
|
|
-- constructor (not the prefix form).</li>
|
|
-- <li>Associativity is not used to reduce the occurrence of parentheses,
|
|
-- although precedence may be.</li>
|
|
-- <li>If the constructor is defined using record syntax, the derived
|
|
-- <a>Read</a> will parse only the record-syntax form, and furthermore,
|
|
-- the fields must be given in the same order as the original
|
|
-- declaration.</li>
|
|
-- <li>The derived <a>Read</a> instance allows arbitrary Haskell
|
|
-- whitespace between tokens of the input string. Extra parentheses are
|
|
-- also allowed.</li>
|
|
-- </ul>
|
|
--
|
|
-- For example, given the declarations
|
|
--
|
|
-- <pre>
|
|
-- infixr 5 :^:
|
|
-- data Tree a = Leaf a | Tree a :^: Tree a
|
|
-- </pre>
|
|
--
|
|
-- the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
|
|
--
|
|
-- <pre>
|
|
-- instance (Read a) => Read (Tree a) where
|
|
--
|
|
-- readsPrec d r = readParen (d > app_prec)
|
|
-- (\r -> [(Leaf m,t) |
|
|
-- ("Leaf",s) <- lex r,
|
|
-- (m,t) <- readsPrec (app_prec+1) s]) r
|
|
--
|
|
-- ++ readParen (d > up_prec)
|
|
-- (\r -> [(u:^:v,w) |
|
|
-- (u,s) <- readsPrec (up_prec+1) r,
|
|
-- (":^:",t) <- lex s,
|
|
-- (v,w) <- readsPrec (up_prec+1) t]) r
|
|
--
|
|
-- where app_prec = 10
|
|
-- up_prec = 5
|
|
-- </pre>
|
|
--
|
|
-- Note that right-associativity of <tt>:^:</tt> is unused.
|
|
--
|
|
-- The derived instance in GHC is equivalent to
|
|
--
|
|
-- <pre>
|
|
-- instance (Read a) => Read (Tree a) where
|
|
--
|
|
-- readPrec = parens $ (prec app_prec $ do
|
|
-- Ident "Leaf" <- lexP
|
|
-- m <- step readPrec
|
|
-- return (Leaf m))
|
|
--
|
|
-- +++ (prec up_prec $ do
|
|
-- u <- step readPrec
|
|
-- Symbol ":^:" <- lexP
|
|
-- v <- step readPrec
|
|
-- return (u :^: v))
|
|
--
|
|
-- where app_prec = 10
|
|
-- up_prec = 5
|
|
--
|
|
-- readListPrec = readListPrecDefault
|
|
-- </pre>
|
|
class Read a
|
|
|
|
-- | attempts to parse a value from the front of the string, returning a
|
|
-- list of (parsed value, remaining string) pairs. If there is no
|
|
-- successful parse, the returned list is empty.
|
|
--
|
|
-- Derived instances of <a>Read</a> and <a>Show</a> satisfy the
|
|
-- following:
|
|
--
|
|
-- <ul>
|
|
-- <li><tt>(x,"")</tt> is an element of <tt>(<a>readsPrec</a> d
|
|
-- (<a>showsPrec</a> d x ""))</tt>.</li>
|
|
-- </ul>
|
|
--
|
|
-- That is, <a>readsPrec</a> parses the string produced by
|
|
-- <a>showsPrec</a>, and delivers the value that <a>showsPrec</a> started
|
|
-- with.
|
|
readsPrec :: Int -> ReadS a
|
|
|
|
-- | The method <a>readList</a> is provided to allow the programmer to give
|
|
-- a specialised way of parsing lists of values. For example, this is
|
|
-- used by the predefined <a>Read</a> instance of the <a>Char</a> type,
|
|
-- where values of type <a>String</a> should be are expected to use
|
|
-- double quotes, rather than square brackets.
|
|
readList :: ReadS [a]
|
|
|
|
-- | Proposed replacement for <a>readsPrec</a> using new-style parsers (GHC
|
|
-- only).
|
|
readPrec :: ReadPrec a
|
|
|
|
-- | Proposed replacement for <a>readList</a> using new-style parsers (GHC
|
|
-- only). The default definition uses <a>readList</a>. Instances that
|
|
-- define <a>readPrec</a> should also define <a>readListPrec</a> as
|
|
-- <a>readListPrecDefault</a>.
|
|
readListPrec :: ReadPrec [a]
|
|
|
|
-- | The <a>Functor</a> class is used for types that can be mapped over.
|
|
-- Instances of <a>Functor</a> should satisfy the following laws:
|
|
--
|
|
-- <pre>
|
|
-- fmap id == id
|
|
-- fmap (f . g) == fmap f . fmap g
|
|
-- </pre>
|
|
--
|
|
-- The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a>
|
|
-- satisfy these laws.
|
|
class Functor (f :: * -> *)
|
|
fmap :: (a -> b) -> f a -> f b
|
|
|
|
-- | Replace all locations in the input with the same value. The default
|
|
-- definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
|
|
-- overridden with a more efficient version.
|
|
(<$) :: a -> f b -> f a
|
|
|
|
-- | A functor with application, providing operations to
|
|
--
|
|
-- <ul>
|
|
-- <li>embed pure expressions (<a>pure</a>), and</li>
|
|
-- <li>sequence computations and combine their results
|
|
-- (<a><*></a>).</li>
|
|
-- </ul>
|
|
--
|
|
-- A minimal complete definition must include implementations of these
|
|
-- functions satisfying the following laws:
|
|
--
|
|
-- <ul>
|
|
-- <li><i><i>identity</i></i> <pre><a>pure</a> <a>id</a> <a><*></a>
|
|
-- v = v</pre></li>
|
|
-- <li><i><i>composition</i></i> <pre><a>pure</a> (.) <a><*></a> u
|
|
-- <a><*></a> v <a><*></a> w = u <a><*></a> (v
|
|
-- <a><*></a> w)</pre></li>
|
|
-- <li><i><i>homomorphism</i></i> <pre><a>pure</a> f <a><*></a>
|
|
-- <a>pure</a> x = <a>pure</a> (f x)</pre></li>
|
|
-- <li><i><i>interchange</i></i> <pre>u <a><*></a> <a>pure</a> y =
|
|
-- <a>pure</a> (<a>$</a> y) <a><*></a> u</pre></li>
|
|
-- </ul>
|
|
--
|
|
-- The other methods have the following default definitions, which may be
|
|
-- overridden with equivalent specialized implementations:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre>u <a>*></a> v = <a>pure</a> (<a>const</a> <a>id</a>)
|
|
-- <a><*></a> u <a><*></a> v</pre></li>
|
|
-- <li><pre>u <a><*</a> v = <a>pure</a> <a>const</a> <a><*></a>
|
|
-- u <a><*></a> v</pre></li>
|
|
-- </ul>
|
|
--
|
|
-- As a consequence of these laws, the <a>Functor</a> instance for
|
|
-- <tt>f</tt> will satisfy
|
|
--
|
|
-- <ul>
|
|
-- <li><pre><a>fmap</a> f x = <a>pure</a> f <a><*></a> x</pre></li>
|
|
-- </ul>
|
|
--
|
|
-- If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
|
|
--
|
|
-- <ul>
|
|
-- <li><pre><a>pure</a> = <a>return</a></pre></li>
|
|
-- <li><pre>(<a><*></a>) = <a>ap</a></pre></li>
|
|
-- </ul>
|
|
--
|
|
-- (which implies that <a>pure</a> and <a><*></a> satisfy the
|
|
-- applicative functor laws).
|
|
class Functor f => Applicative (f :: * -> *)
|
|
|
|
-- | Lift a value.
|
|
pure :: a -> f a
|
|
|
|
-- | Sequential application.
|
|
(<*>) :: f (a -> b) -> f a -> f b
|
|
|
|
-- | Sequence actions, discarding the value of the first argument.
|
|
(*>) :: f a -> f b -> f b
|
|
|
|
-- | Sequence actions, discarding the value of the second argument.
|
|
(<*) :: f a -> f b -> f a
|
|
|
|
-- | A monoid on applicative functors.
|
|
--
|
|
-- If defined, <a>some</a> and <a>many</a> should be the least solutions
|
|
-- of the equations:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre>some v = (:) <tt><$></tt> v <a><*></a> many
|
|
-- v</pre></li>
|
|
-- <li><pre>many v = some v <a><|></a> <a>pure</a> []</pre></li>
|
|
-- </ul>
|
|
class Applicative f => Alternative (f :: * -> *)
|
|
|
|
-- | The identity of <a><|></a>
|
|
empty :: f a
|
|
|
|
-- | An associative binary operation
|
|
(<|>) :: f a -> f a -> f a
|
|
|
|
-- | One or more.
|
|
some :: f a -> f [a]
|
|
|
|
-- | Zero or more.
|
|
many :: f a -> f [a]
|
|
|
|
-- | The <a>Monad</a> class defines the basic operations over a
|
|
-- <i>monad</i>, a concept from a branch of mathematics known as
|
|
-- <i>category theory</i>. From the perspective of a Haskell programmer,
|
|
-- however, it is best to think of a monad as an <i>abstract datatype</i>
|
|
-- of actions. Haskell's <tt>do</tt> expressions provide a convenient
|
|
-- syntax for writing monadic expressions.
|
|
--
|
|
-- Instances of <a>Monad</a> should satisfy the following laws:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre><a>return</a> a <a>>>=</a> k = k a</pre></li>
|
|
-- <li><pre>m <a>>>=</a> <a>return</a> = m</pre></li>
|
|
-- <li><pre>m <a>>>=</a> (x -> k x <a>>>=</a> h) = (m
|
|
-- <a>>>=</a> k) <a>>>=</a> h</pre></li>
|
|
-- </ul>
|
|
--
|
|
-- Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
|
|
-- relate as follows:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre><a>pure</a> = <a>return</a></pre></li>
|
|
-- <li><pre>(<a><*></a>) = <a>ap</a></pre></li>
|
|
-- </ul>
|
|
--
|
|
-- The above laws imply:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre><a>fmap</a> f xs = xs <a>>>=</a> <a>return</a> .
|
|
-- f</pre></li>
|
|
-- <li><pre>(<a>>></a>) = (<a>*></a>)</pre></li>
|
|
-- </ul>
|
|
--
|
|
-- and that <a>pure</a> and (<a><*></a>) satisfy the applicative
|
|
-- functor laws.
|
|
--
|
|
-- The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
|
|
-- defined in the <a>Prelude</a> satisfy these laws.
|
|
class Applicative m => Monad (m :: * -> *)
|
|
|
|
-- | Sequentially compose two actions, passing any value produced by the
|
|
-- first as an argument to the second.
|
|
(>>=) :: m a -> (a -> m b) -> m b
|
|
|
|
-- | Sequentially compose two actions, discarding any value produced by the
|
|
-- first, like sequencing operators (such as the semicolon) in imperative
|
|
-- languages.
|
|
(>>) :: m a -> m b -> m b
|
|
|
|
-- | Inject a value into the monadic type.
|
|
return :: a -> m a
|
|
|
|
-- | Fail with a message. This operation is not part of the mathematical
|
|
-- definition of a monad, but is invoked on pattern-match failure in a
|
|
-- <tt>do</tt> expression.
|
|
--
|
|
-- As part of the MonadFail proposal (MFP), this function is moved to its
|
|
-- own class <tt>MonadFail</tt> (see <a>Control.Monad.Fail</a> for more
|
|
-- details). The definition here will be removed in a future release.
|
|
fail :: String -> m a
|
|
|
|
-- | Monads in which <a>IO</a> computations may be embedded. Any monad
|
|
-- built by applying a sequence of monad transformers to the <a>IO</a>
|
|
-- monad will be an instance of this class.
|
|
--
|
|
-- Instances should satisfy the following laws, which state that
|
|
-- <a>liftIO</a> is a transformer of monads:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
|
|
-- <li><pre><a>liftIO</a> (m >>= f) = <a>liftIO</a> m >>=
|
|
-- (<a>liftIO</a> . f)</pre></li>
|
|
-- </ul>
|
|
class Monad m => MonadIO (m :: * -> *)
|
|
|
|
-- | Lift a computation from the <a>IO</a> monad.
|
|
liftIO :: IO a -> m a
|
|
|
|
-- | The class of monad transformers. Instances should satisfy the
|
|
-- following laws, which state that <a>lift</a> is a monad
|
|
-- transformation:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre><a>lift</a> . <a>return</a> = <a>return</a></pre></li>
|
|
-- <li><pre><a>lift</a> (m >>= f) = <a>lift</a> m >>=
|
|
-- (<a>lift</a> . f)</pre></li>
|
|
-- </ul>
|
|
class MonadTrans (t :: (* -> *) -> * -> *)
|
|
|
|
-- | Lift a computation from the argument monad to the constructed monad.
|
|
lift :: Monad m => m a -> t m a
|
|
|
|
-- | See examples in <a>Control.Monad.Reader</a>. Note, the partially
|
|
-- applied function type <tt>(->) r</tt> is a simple reader monad. See
|
|
-- the <tt>instance</tt> declaration below.
|
|
class Monad m => MonadReader r (m :: * -> *) | m -> r
|
|
|
|
-- | Retrieves the monad environment.
|
|
ask :: m r
|
|
|
|
-- | Executes a computation in a modified environment.
|
|
local :: (r -> r) -> m a -> m a
|
|
|
|
-- | Retrieves a function of the current environment.
|
|
reader :: (r -> a) -> m a
|
|
|
|
-- | A class for monads in which exceptions may be thrown.
|
|
--
|
|
-- Instances should obey the following law:
|
|
--
|
|
-- <pre>
|
|
-- throwM e >> x = throwM e
|
|
-- </pre>
|
|
--
|
|
-- In other words, throwing an exception short-circuits the rest of the
|
|
-- monadic computation.
|
|
class Monad m => MonadThrow (m :: * -> *)
|
|
|
|
-- | Any type that you wish to throw or catch as an exception must be an
|
|
-- instance of the <tt>Exception</tt> class. The simplest case is a new
|
|
-- exception type directly below the root:
|
|
--
|
|
-- <pre>
|
|
-- data MyException = ThisException | ThatException
|
|
-- deriving (Show, Typeable)
|
|
--
|
|
-- instance Exception MyException
|
|
-- </pre>
|
|
--
|
|
-- The default method definitions in the <tt>Exception</tt> class do what
|
|
-- we need in this case. You can now throw and catch
|
|
-- <tt>ThisException</tt> and <tt>ThatException</tt> as exceptions:
|
|
--
|
|
-- <pre>
|
|
-- *Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
|
|
-- Caught ThisException
|
|
-- </pre>
|
|
--
|
|
-- In more complicated examples, you may wish to define a whole hierarchy
|
|
-- of exceptions:
|
|
--
|
|
-- <pre>
|
|
-- ---------------------------------------------------------------------
|
|
-- -- Make the root exception type for all the exceptions in a compiler
|
|
--
|
|
-- data SomeCompilerException = forall e . Exception e => SomeCompilerException e
|
|
-- deriving Typeable
|
|
--
|
|
-- 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
|
|
-- deriving Typeable
|
|
--
|
|
-- 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 (Typeable, Show)
|
|
--
|
|
-- instance Exception MismatchedParentheses where
|
|
-- toException = frontendExceptionToException
|
|
-- fromException = frontendExceptionFromException
|
|
-- </pre>
|
|
--
|
|
-- We can now catch a <tt>MismatchedParentheses</tt> exception as
|
|
-- <tt>MismatchedParentheses</tt>, <tt>SomeFrontendException</tt> or
|
|
-- <tt>SomeCompilerException</tt>, but not other types, e.g.
|
|
-- <tt>IOException</tt>:
|
|
--
|
|
-- <pre>
|
|
-- *Main> throw MismatchedParentheses <tt>catch</tt> e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
|
|
-- Caught MismatchedParentheses
|
|
-- *Main> throw MismatchedParentheses <tt>catch</tt> e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
|
|
-- Caught MismatchedParentheses
|
|
-- *Main> throw MismatchedParentheses <tt>catch</tt> e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
|
|
-- Caught MismatchedParentheses
|
|
-- *Main> throw MismatchedParentheses <tt>catch</tt> e -> putStrLn ("Caught " ++ show (e :: IOException))
|
|
-- *** Exception: MismatchedParentheses
|
|
-- </pre>
|
|
class (Typeable * e, Show e) => Exception e
|
|
toException :: e -> SomeException
|
|
fromException :: SomeException -> Maybe e
|
|
|
|
-- | Render this exception value in a human-friendly manner.
|
|
--
|
|
-- Default implementation: <tt><a>show</a></tt>.
|
|
displayException :: e -> String
|
|
|
|
-- | A class for monads which allow exceptions to be caught, in particular
|
|
-- exceptions which were thrown by <a>throwM</a>.
|
|
--
|
|
-- Instances should obey the following law:
|
|
--
|
|
-- <pre>
|
|
-- catch (throwM e) f = f e
|
|
-- </pre>
|
|
--
|
|
-- Note that the ability to catch an exception does <i>not</i> guarantee
|
|
-- that we can deal with all possible exit points from a computation.
|
|
-- Some monads, such as continuation-based stacks, allow for more than
|
|
-- just a success/failure strategy, and therefore <tt>catch</tt>
|
|
-- <i>cannot</i> be used by those monads to properly implement a function
|
|
-- such as <tt>finally</tt>. For more information, see <a>MonadMask</a>.
|
|
class MonadThrow m => MonadCatch (m :: * -> *)
|
|
|
|
-- | A class for monads which provide for the ability to account for all
|
|
-- possible exit points from a computation, and to mask asynchronous
|
|
-- exceptions. Continuation-based monads, and stacks such as <tt>ErrorT e
|
|
-- IO</tt> which provide for multiple failure modes, are invalid
|
|
-- instances of this class.
|
|
--
|
|
-- Note that this package <i>does</i> provide a <tt>MonadMask</tt>
|
|
-- instance for <tt>CatchT</tt>. This instance is <i>only</i> valid if
|
|
-- the base monad provides no ability to provide multiple exit. For
|
|
-- example, <tt>IO</tt> or <tt>Either</tt> would be invalid base monads,
|
|
-- but <tt>Reader</tt> or <tt>State</tt> would be acceptable.
|
|
--
|
|
-- Instances should ensure that, in the following code:
|
|
--
|
|
-- <pre>
|
|
-- f `finally` g
|
|
-- </pre>
|
|
--
|
|
-- The action <tt>g</tt> is called regardless of what occurs within
|
|
-- <tt>f</tt>, including async exceptions.
|
|
class MonadCatch m => MonadMask (m :: * -> *)
|
|
|
|
-- | Data structures that can be folded.
|
|
--
|
|
-- For example, given a data type
|
|
--
|
|
-- <pre>
|
|
-- data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
|
|
-- </pre>
|
|
--
|
|
-- a suitable instance would be
|
|
--
|
|
-- <pre>
|
|
-- instance Foldable Tree where
|
|
-- foldMap f Empty = mempty
|
|
-- foldMap f (Leaf x) = f x
|
|
-- foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
|
|
-- </pre>
|
|
--
|
|
-- This is suitable even for abstract types, as the monoid is assumed to
|
|
-- satisfy the monoid laws. Alternatively, one could define
|
|
-- <tt>foldr</tt>:
|
|
--
|
|
-- <pre>
|
|
-- instance Foldable Tree where
|
|
-- foldr f z Empty = z
|
|
-- foldr f z (Leaf x) = f x z
|
|
-- foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
|
|
-- </pre>
|
|
--
|
|
-- <tt>Foldable</tt> instances are expected to satisfy the following
|
|
-- laws:
|
|
--
|
|
-- <pre>
|
|
-- foldr f z t = appEndo (foldMap (Endo . f) t ) z
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- fold = foldMap id
|
|
-- </pre>
|
|
--
|
|
-- <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
|
|
-- should all be essentially equivalent to <tt>foldMap</tt> forms, such
|
|
-- as
|
|
--
|
|
-- <pre>
|
|
-- sum = getSum . foldMap Sum
|
|
-- </pre>
|
|
--
|
|
-- but may be less defined.
|
|
--
|
|
-- If the type is also a <a>Functor</a> instance, it should satisfy
|
|
--
|
|
-- <pre>
|
|
-- foldMap f = fold . fmap f
|
|
-- </pre>
|
|
--
|
|
-- which implies that
|
|
--
|
|
-- <pre>
|
|
-- foldMap f . fmap g = foldMap (f . g)
|
|
-- </pre>
|
|
class Foldable (t :: * -> *)
|
|
|
|
-- | Combine the elements of a structure using a monoid.
|
|
fold :: Monoid m => t m -> m
|
|
|
|
-- | Map each element of the structure to a monoid, and combine the
|
|
-- results.
|
|
foldMap :: Monoid m => (a -> m) -> t a -> m
|
|
|
|
-- | Right-associative fold of a structure.
|
|
--
|
|
-- In the case of lists, <a>foldr</a>, when applied to a binary operator,
|
|
-- a starting value (typically the right-identity of the operator), and a
|
|
-- list, reduces the list using the binary operator, from right to left:
|
|
--
|
|
-- <pre>
|
|
-- foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
|
|
-- </pre>
|
|
--
|
|
-- Note that, since the head of the resulting expression is produced by
|
|
-- an application of the operator to the first element of the list,
|
|
-- <a>foldr</a> can produce a terminating expression from an infinite
|
|
-- list.
|
|
--
|
|
-- For a general <a>Foldable</a> structure this should be semantically
|
|
-- identical to,
|
|
--
|
|
-- <pre>
|
|
-- foldr f z = <a>foldr</a> f z . <a>toList</a>
|
|
-- </pre>
|
|
foldr :: (a -> b -> b) -> b -> t a -> b
|
|
|
|
-- | Right-associative fold of a structure, but with strict application of
|
|
-- the operator.
|
|
foldr' :: (a -> b -> b) -> b -> t a -> b
|
|
|
|
-- | Left-associative fold of a structure.
|
|
--
|
|
-- In the case of lists, <a>foldl</a>, when applied to a binary operator,
|
|
-- a starting value (typically the left-identity of the operator), and a
|
|
-- list, reduces the list using the binary operator, from left to right:
|
|
--
|
|
-- <pre>
|
|
-- foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn
|
|
-- </pre>
|
|
--
|
|
-- Note that to produce the outermost application of the operator the
|
|
-- entire input list must be traversed. This means that <a>foldl'</a>
|
|
-- will diverge if given an infinite list.
|
|
--
|
|
-- Also note that if you want an efficient left-fold, you probably want
|
|
-- to use <a>foldl'</a> instead of <a>foldl</a>. The reason for this is
|
|
-- that latter does not force the "inner" results (e.g. <tt>z <tt>f</tt>
|
|
-- x1</tt> in the above example) before applying them to the operator
|
|
-- (e.g. to <tt>(<tt>f</tt> x2)</tt>). This results in a thunk chain
|
|
-- <tt>O(n)</tt> elements long, which then must be evaluated from the
|
|
-- outside-in.
|
|
--
|
|
-- For a general <a>Foldable</a> structure this should be semantically
|
|
-- identical to,
|
|
--
|
|
-- <pre>
|
|
-- foldl f z = <a>foldl</a> f z . <a>toList</a>
|
|
-- </pre>
|
|
foldl :: (b -> a -> b) -> b -> t a -> b
|
|
|
|
-- | Left-associative fold of a structure but with strict application of
|
|
-- the operator.
|
|
--
|
|
-- This ensures that each step of the fold is forced to weak head normal
|
|
-- form before being applied, avoiding the collection of thunks that
|
|
-- would otherwise occur. This is often what you want to strictly reduce
|
|
-- a finite list to a single, monolithic result (e.g. <a>length</a>).
|
|
--
|
|
-- For a general <a>Foldable</a> structure this should be semantically
|
|
-- identical to,
|
|
--
|
|
-- <pre>
|
|
-- foldl f z = <a>foldl'</a> f z . <a>toList</a>
|
|
-- </pre>
|
|
foldl' :: (b -> a -> b) -> b -> t a -> b
|
|
|
|
-- | List of elements of a structure, from left to right.
|
|
toList :: t a -> [a]
|
|
|
|
-- | Test whether the structure is empty. The default implementation is
|
|
-- optimized for structures that are similar to cons-lists, because there
|
|
-- is no general way to do better.
|
|
null :: t a -> Bool
|
|
|
|
-- | Returns the size/length of a finite structure as an <a>Int</a>. The
|
|
-- default implementation is optimized for structures that are similar to
|
|
-- cons-lists, because there is no general way to do better.
|
|
length :: t a -> Int
|
|
|
|
-- | Does the element occur in the structure?
|
|
elem :: Eq a => a -> t a -> Bool
|
|
|
|
-- | List of elements of a structure, from left to right.
|
|
toList :: Foldable t => forall a. t a -> [a]
|
|
|
|
-- | Test whether the structure is empty. The default implementation is
|
|
-- optimized for structures that are similar to cons-lists, because there
|
|
-- is no general way to do better.
|
|
null :: Foldable t => forall a. t a -> Bool
|
|
|
|
-- | Returns the size/length of a finite structure as an <a>Int</a>. The
|
|
-- default implementation is optimized for structures that are similar to
|
|
-- cons-lists, because there is no general way to do better.
|
|
length :: Foldable t => forall a. t a -> Int
|
|
|
|
-- | Does the element occur in the structure?
|
|
elem :: Foldable t => forall a. Eq a => a -> t a -> Bool
|
|
|
|
-- | Functors representing data structures that can be traversed from left
|
|
-- to right.
|
|
--
|
|
-- A definition of <a>traverse</a> must satisfy the following laws:
|
|
--
|
|
-- <ul>
|
|
-- <li><i><i>naturality</i></i> <tt>t . <a>traverse</a> f =
|
|
-- <a>traverse</a> (t . f)</tt> for every applicative transformation
|
|
-- <tt>t</tt></li>
|
|
-- <li><i><i>identity</i></i> <tt><a>traverse</a> Identity =
|
|
-- Identity</tt></li>
|
|
-- <li><i><i>composition</i></i> <tt><a>traverse</a> (Compose .
|
|
-- <a>fmap</a> g . f) = Compose . <a>fmap</a> (<a>traverse</a> g) .
|
|
-- <a>traverse</a> f</tt></li>
|
|
-- </ul>
|
|
--
|
|
-- A definition of <a>sequenceA</a> must satisfy the following laws:
|
|
--
|
|
-- <ul>
|
|
-- <li><i><i>naturality</i></i> <tt>t . <a>sequenceA</a> =
|
|
-- <a>sequenceA</a> . <a>fmap</a> t</tt> for every applicative
|
|
-- transformation <tt>t</tt></li>
|
|
-- <li><i><i>identity</i></i> <tt><a>sequenceA</a> . <a>fmap</a> Identity
|
|
-- = Identity</tt></li>
|
|
-- <li><i><i>composition</i></i> <tt><a>sequenceA</a> . <a>fmap</a>
|
|
-- Compose = Compose . <a>fmap</a> <a>sequenceA</a> .
|
|
-- <a>sequenceA</a></tt></li>
|
|
-- </ul>
|
|
--
|
|
-- where an <i>applicative transformation</i> is a function
|
|
--
|
|
-- <pre>
|
|
-- t :: (Applicative f, Applicative g) => f a -> g a
|
|
-- </pre>
|
|
--
|
|
-- preserving the <a>Applicative</a> operations, i.e.
|
|
--
|
|
-- <ul>
|
|
-- <li><pre>t (<a>pure</a> x) = <a>pure</a> x</pre></li>
|
|
-- <li><pre>t (x <a><*></a> y) = t x <a><*></a> t
|
|
-- y</pre></li>
|
|
-- </ul>
|
|
--
|
|
-- and the identity functor <tt>Identity</tt> and composition of functors
|
|
-- <tt>Compose</tt> are defined as
|
|
--
|
|
-- <pre>
|
|
-- newtype Identity a = Identity a
|
|
--
|
|
-- instance Functor Identity where
|
|
-- fmap f (Identity x) = Identity (f x)
|
|
--
|
|
-- instance Applicative Identity where
|
|
-- pure x = Identity x
|
|
-- Identity f <*> Identity x = Identity (f x)
|
|
--
|
|
-- newtype Compose f g a = Compose (f (g a))
|
|
--
|
|
-- instance (Functor f, Functor g) => Functor (Compose f g) where
|
|
-- fmap f (Compose x) = Compose (fmap (fmap f) x)
|
|
--
|
|
-- instance (Applicative f, Applicative g) => Applicative (Compose f g) where
|
|
-- pure x = Compose (pure (pure x))
|
|
-- Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)
|
|
-- </pre>
|
|
--
|
|
-- (The naturality law is implied by parametricity.)
|
|
--
|
|
-- Instances are similar to <a>Functor</a>, e.g. given a data type
|
|
--
|
|
-- <pre>
|
|
-- data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
|
|
-- </pre>
|
|
--
|
|
-- a suitable instance would be
|
|
--
|
|
-- <pre>
|
|
-- instance Traversable Tree where
|
|
-- traverse f Empty = pure Empty
|
|
-- traverse f (Leaf x) = Leaf <$> f x
|
|
-- traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r
|
|
-- </pre>
|
|
--
|
|
-- This is suitable even for abstract types, as the laws for
|
|
-- <a><*></a> imply a form of associativity.
|
|
--
|
|
-- The superclass instances should satisfy the following:
|
|
--
|
|
-- <ul>
|
|
-- <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
|
|
-- to traversal with the identity applicative functor
|
|
-- (<a>fmapDefault</a>).</li>
|
|
-- <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
|
|
-- equivalent to traversal with a constant applicative functor
|
|
-- (<a>foldMapDefault</a>).</li>
|
|
-- </ul>
|
|
class (Functor t, Foldable t) => Traversable (t :: * -> *)
|
|
|
|
-- | Map each element of a structure to an action, evaluate these actions
|
|
-- from left to right, and collect the results. For a version that
|
|
-- ignores the results see <a>traverse_</a>.
|
|
traverse :: Applicative f => (a -> f b) -> t a -> f (t b)
|
|
|
|
-- | Evaluate each action in the structure from left to right, and and
|
|
-- collect the results. For a version that ignores the results see
|
|
-- <a>sequenceA_</a>.
|
|
sequenceA :: Applicative f => t (f a) -> f (t a)
|
|
|
|
-- | The class <a>Typeable</a> allows a concrete representation of a type
|
|
-- to be calculated.
|
|
class Typeable k (a :: k)
|
|
|
|
-- | Class for string-like datastructures; used by the overloaded string
|
|
-- extension (-XOverloadedStrings in GHC).
|
|
class IsString a
|
|
fromString :: String -> a
|
|
|
|
-- | The class of types that can be converted to a hash value.
|
|
--
|
|
-- Minimal implementation: <a>hashWithSalt</a>.
|
|
class Hashable a
|
|
|
|
-- | Return a hash value for the argument, using the given salt.
|
|
--
|
|
-- The general contract of <a>hashWithSalt</a> is:
|
|
--
|
|
-- <ul>
|
|
-- <li>If two values are equal according to the <a>==</a> method, then
|
|
-- applying the <a>hashWithSalt</a> method on each of the two values
|
|
-- <i>must</i> produce the same integer result if the same salt is used
|
|
-- in each case.</li>
|
|
-- <li>It is <i>not</i> required that if two values are unequal according
|
|
-- to the <a>==</a> method, then applying the <a>hashWithSalt</a> method
|
|
-- on each of the two values must produce distinct integer results.
|
|
-- However, the programmer should be aware that producing distinct
|
|
-- integer results for unequal values may improve the performance of
|
|
-- hashing-based data structures.</li>
|
|
-- <li>This method can be used to compute different hash values for the
|
|
-- same input by providing a different salt in each application of the
|
|
-- method. This implies that any instance that defines
|
|
-- <a>hashWithSalt</a> <i>must</i> make use of the salt in its
|
|
-- implementation.</li>
|
|
-- </ul>
|
|
hashWithSalt :: Int -> a -> Int
|
|
|
|
-- | Like <a>hashWithSalt</a>, but no salt is used. The default
|
|
-- implementation uses <a>hashWithSalt</a> with some default salt.
|
|
-- Instances might want to implement this method to provide a more
|
|
-- efficient implementation than the default implementation.
|
|
hash :: a -> Int
|
|
|
|
-- | The class of semigroups (types with an associative binary operation).
|
|
class Semigroup a
|
|
|
|
-- | An associative operation.
|
|
--
|
|
-- <pre>
|
|
-- (a <a><></a> b) <a><></a> c = a <a><></a> (b <a><></a> c)
|
|
-- </pre>
|
|
--
|
|
-- If <tt>a</tt> is also a <a>Monoid</a> we further require
|
|
--
|
|
-- <pre>
|
|
-- (<a><></a>) = <a>mappend</a>
|
|
-- </pre>
|
|
(<>) :: a -> a -> a
|
|
|
|
-- | Reduce a non-empty list with <tt><></tt>
|
|
--
|
|
-- The default definition should be sufficient, but this can be
|
|
-- overridden for efficiency.
|
|
sconcat :: NonEmpty a -> a
|
|
|
|
-- | Repeat a value <tt>n</tt> times.
|
|
--
|
|
-- Given that this works on a <a>Semigroup</a> it is allowed to fail if
|
|
-- you request 0 or fewer repetitions, and the default definition will do
|
|
-- so.
|
|
--
|
|
-- By making this a member of the class, idempotent semigroups and
|
|
-- monoids can upgrade this to execute in <i>O(1)</i> by picking
|
|
-- <tt>stimes = stimesIdempotent</tt> or <tt>stimes =
|
|
-- stimesIdempotentMonoid</tt> respectively.
|
|
stimes :: Integral b => b -> a -> a
|
|
|
|
-- | The class of monoids (types with an associative binary operation that
|
|
-- has an identity). Instances should satisfy the following laws:
|
|
--
|
|
-- <ul>
|
|
-- <li><pre>mappend mempty x = x</pre></li>
|
|
-- <li><pre>mappend x mempty = x</pre></li>
|
|
-- <li><pre>mappend x (mappend y z) = mappend (mappend x y) z</pre></li>
|
|
-- <li><pre>mconcat = <a>foldr</a> mappend mempty</pre></li>
|
|
-- </ul>
|
|
--
|
|
-- 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
|
|
-- <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
|
|
-- <tt>Sum</tt> and <tt>Product</tt>.
|
|
class Monoid a
|
|
|
|
-- | Identity of <a>mappend</a>
|
|
mempty :: a
|
|
|
|
-- | An associative operation
|
|
mappend :: a -> a -> a
|
|
|
|
-- | Fold a list using the monoid. For most types, the default definition
|
|
-- for <a>mconcat</a> will be used, but the function is included in the
|
|
-- class definition so that an optimized version can be provided for
|
|
-- specific types.
|
|
mconcat :: [a] -> a
|
|
|
|
-- | Basic numeric class.
|
|
class Num a
|
|
(+) :: a -> a -> a
|
|
(-) :: a -> a -> a
|
|
(*) :: a -> a -> a
|
|
|
|
-- | Unary negation.
|
|
negate :: a -> a
|
|
|
|
-- | Absolute value.
|
|
abs :: a -> a
|
|
|
|
-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
|
|
-- satisfy the law:
|
|
--
|
|
-- <pre>
|
|
-- abs x * signum x == x
|
|
-- </pre>
|
|
--
|
|
-- For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
|
|
-- <tt>0</tt> (zero) or <tt>1</tt> (positive).
|
|
signum :: a -> a
|
|
|
|
-- | Conversion from an <a>Integer</a>. An integer literal represents the
|
|
-- application of the function <a>fromInteger</a> to the appropriate
|
|
-- value of type <a>Integer</a>, so such literals have type
|
|
-- <tt>(<a>Num</a> a) => a</tt>.
|
|
fromInteger :: Integer -> a
|
|
class (Num a, Ord a) => Real a
|
|
|
|
-- | the rational equivalent of its real argument with full precision
|
|
toRational :: a -> Rational
|
|
|
|
-- | Integral numbers, supporting integer division.
|
|
class (Real a, Enum a) => Integral a
|
|
|
|
-- | integer division truncated toward zero
|
|
quot :: a -> a -> a
|
|
|
|
-- | integer remainder, satisfying
|
|
--
|
|
-- <pre>
|
|
-- (x `quot` y)*y + (x `rem` y) == x
|
|
-- </pre>
|
|
rem :: a -> a -> a
|
|
|
|
-- | integer division truncated toward negative infinity
|
|
div :: a -> a -> a
|
|
|
|
-- | integer modulus, satisfying
|
|
--
|
|
-- <pre>
|
|
-- (x `div` y)*y + (x `mod` y) == x
|
|
-- </pre>
|
|
mod :: a -> a -> a
|
|
|
|
-- | simultaneous <a>quot</a> and <a>rem</a>
|
|
quotRem :: a -> a -> (a, a)
|
|
|
|
-- | simultaneous <a>div</a> and <a>mod</a>
|
|
divMod :: a -> a -> (a, a)
|
|
|
|
-- | conversion to <a>Integer</a>
|
|
toInteger :: a -> Integer
|
|
|
|
-- | Fractional numbers, supporting real division.
|
|
class Num a => Fractional a
|
|
|
|
-- | fractional division
|
|
(/) :: a -> a -> a
|
|
|
|
-- | reciprocal fraction
|
|
recip :: a -> a
|
|
|
|
-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
|
|
-- <a>Integer</a></tt>). A floating literal stands for an application of
|
|
-- <a>fromRational</a> to a value of type <a>Rational</a>, so such
|
|
-- literals have type <tt>(<a>Fractional</a> a) => a</tt>.
|
|
fromRational :: Rational -> a
|
|
|
|
-- | Trigonometric and hyperbolic functions and related functions.
|
|
class Fractional a => Floating a
|
|
pi :: a
|
|
exp :: a -> a
|
|
log :: a -> a
|
|
sqrt :: a -> a
|
|
(**) :: a -> a -> a
|
|
logBase :: a -> a -> a
|
|
sin :: a -> a
|
|
cos :: a -> a
|
|
tan :: a -> a
|
|
asin :: a -> a
|
|
acos :: a -> a
|
|
atan :: a -> a
|
|
sinh :: a -> a
|
|
cosh :: a -> a
|
|
tanh :: a -> a
|
|
asinh :: a -> a
|
|
acosh :: a -> a
|
|
atanh :: a -> a
|
|
|
|
-- | Extracting components of fractions.
|
|
class (Real a, Fractional a) => RealFrac a
|
|
|
|
-- | The function <a>properFraction</a> takes a real fractional number
|
|
-- <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
|
|
-- n+f</tt>, and:
|
|
--
|
|
-- <ul>
|
|
-- <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
|
|
-- and</li>
|
|
-- <li><tt>f</tt> is a fraction with the same type and sign as
|
|
-- <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
|
|
-- </ul>
|
|
--
|
|
-- The default definitions of the <a>ceiling</a>, <a>floor</a>,
|
|
-- <a>truncate</a> and <a>round</a> functions are in terms of
|
|
-- <a>properFraction</a>.
|
|
properFraction :: Integral b => a -> (b, a)
|
|
|
|
-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
|
|
-- between zero and <tt>x</tt>
|
|
truncate :: Integral b => a -> b
|
|
|
|
-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
|
|
-- even integer if <tt>x</tt> is equidistant between two integers
|
|
round :: Integral b => a -> b
|
|
|
|
-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
|
|
-- <tt>x</tt>
|
|
ceiling :: Integral b => a -> b
|
|
|
|
-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
|
|
-- <tt>x</tt>
|
|
floor :: Integral b => a -> b
|
|
|
|
-- | Efficient, machine-independent access to the components of a
|
|
-- floating-point number.
|
|
class (RealFrac a, Floating a) => RealFloat a
|
|
|
|
-- | a constant function, returning the radix of the representation (often
|
|
-- <tt>2</tt>)
|
|
floatRadix :: a -> Integer
|
|
|
|
-- | a constant function, returning the number of digits of
|
|
-- <a>floatRadix</a> in the significand
|
|
floatDigits :: a -> Int
|
|
|
|
-- | a constant function, returning the lowest and highest values the
|
|
-- exponent may assume
|
|
floatRange :: a -> (Int, Int)
|
|
|
|
-- | The function <a>decodeFloat</a> applied to a real floating-point
|
|
-- number returns the significand expressed as an <a>Integer</a> and an
|
|
-- appropriately scaled exponent (an <a>Int</a>). If
|
|
-- <tt><a>decodeFloat</a> x</tt> yields <tt>(m,n)</tt>, then <tt>x</tt>
|
|
-- is equal in value to <tt>m*b^^n</tt>, where <tt>b</tt> is the
|
|
-- floating-point radix, and furthermore, either <tt>m</tt> and
|
|
-- <tt>n</tt> are both zero or else <tt>b^(d-1) <= <a>abs</a> m <
|
|
-- b^d</tt>, where <tt>d</tt> is the value of <tt><a>floatDigits</a>
|
|
-- x</tt>. In particular, <tt><a>decodeFloat</a> 0 = (0,0)</tt>. If the
|
|
-- type contains a negative zero, also <tt><a>decodeFloat</a> (-0.0) =
|
|
-- (0,0)</tt>. <i>The result of</i> <tt><a>decodeFloat</a> x</tt> <i>is
|
|
-- unspecified if either of</i> <tt><a>isNaN</a> x</tt> <i>or</i>
|
|
-- <tt><a>isInfinite</a> x</tt> <i>is</i> <a>True</a>.
|
|
decodeFloat :: a -> (Integer, Int)
|
|
|
|
-- | <a>encodeFloat</a> performs the inverse of <a>decodeFloat</a> in the
|
|
-- sense that for finite <tt>x</tt> with the exception of <tt>-0.0</tt>,
|
|
-- <tt><tt>uncurry</tt> <a>encodeFloat</a> (<a>decodeFloat</a> x) =
|
|
-- x</tt>. <tt><a>encodeFloat</a> m n</tt> is one of the two closest
|
|
-- representable floating-point numbers to <tt>m*b^^n</tt> (or
|
|
-- <tt>±Infinity</tt> if overflow occurs); usually the closer, but if
|
|
-- <tt>m</tt> contains too many bits, the result may be rounded in the
|
|
-- wrong direction.
|
|
encodeFloat :: Integer -> Int -> a
|
|
|
|
-- | <a>exponent</a> corresponds to the second component of
|
|
-- <a>decodeFloat</a>. <tt><a>exponent</a> 0 = 0</tt> and for finite
|
|
-- nonzero <tt>x</tt>, <tt><a>exponent</a> x = snd (<a>decodeFloat</a> x)
|
|
-- + <a>floatDigits</a> x</tt>. If <tt>x</tt> is a finite floating-point
|
|
-- number, it is equal in value to <tt><a>significand</a> x * b ^^
|
|
-- <a>exponent</a> x</tt>, where <tt>b</tt> is the floating-point radix.
|
|
-- The behaviour is unspecified on infinite or <tt>NaN</tt> values.
|
|
exponent :: a -> Int
|
|
|
|
-- | The first component of <a>decodeFloat</a>, scaled to lie in the open
|
|
-- interval (<tt>-1</tt>,<tt>1</tt>), either <tt>0.0</tt> or of absolute
|
|
-- value <tt>>= 1/b</tt>, where <tt>b</tt> is the floating-point
|
|
-- radix. The behaviour is unspecified on infinite or <tt>NaN</tt>
|
|
-- values.
|
|
significand :: a -> a
|
|
|
|
-- | multiplies a floating-point number by an integer power of the radix
|
|
scaleFloat :: Int -> a -> a
|
|
|
|
-- | <a>True</a> if the argument is an IEEE "not-a-number" (NaN) value
|
|
isNaN :: a -> Bool
|
|
|
|
-- | <a>True</a> if the argument is an IEEE infinity or negative infinity
|
|
isInfinite :: a -> Bool
|
|
|
|
-- | <a>True</a> if the argument is too small to be represented in
|
|
-- normalized format
|
|
isDenormalized :: a -> Bool
|
|
|
|
-- | <a>True</a> if the argument is an IEEE negative zero
|
|
isNegativeZero :: a -> Bool
|
|
|
|
-- | <a>True</a> if the argument is an IEEE floating point number
|
|
isIEEE :: a -> Bool
|
|
|
|
-- | a version of arctangent taking two real floating-point arguments. For
|
|
-- real floating <tt>x</tt> and <tt>y</tt>, <tt><a>atan2</a> y x</tt>
|
|
-- computes the angle (from the positive x-axis) of the vector from the
|
|
-- origin to the point <tt>(x,y)</tt>. <tt><a>atan2</a> y x</tt> returns
|
|
-- a value in the range [<tt>-pi</tt>, <tt>pi</tt>]. It follows the
|
|
-- Common Lisp semantics for the origin when signed zeroes are supported.
|
|
-- <tt><a>atan2</a> y 1</tt>, with <tt>y</tt> in a type that is
|
|
-- <a>RealFloat</a>, should return the same value as <tt><a>atan</a>
|
|
-- y</tt>. A default definition of <a>atan2</a> is provided, but
|
|
-- implementors can provide a more accurate implementation.
|
|
atan2 :: a -> a -> a
|
|
|
|
-- | Application operator. This operator is redundant, since ordinary
|
|
-- application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
|
|
-- However, <a>$</a> has low, right-associative binding precedence, so it
|
|
-- sometimes allows parentheses to be omitted; for example:
|
|
--
|
|
-- <pre>
|
|
-- f $ g $ h x = f (g (h x))
|
|
-- </pre>
|
|
--
|
|
-- It is also useful in higher-order situations, such as <tt><a>map</a>
|
|
-- (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
|
|
($) :: (a -> b) -> a -> b
|
|
infixr 0 $
|
|
|
|
-- | <a>&</a> is a reverse application operator. This provides
|
|
-- notational convenience. Its precedence is one higher than that of the
|
|
-- forward application operator <a>$</a>, which allows <a>&</a> to be
|
|
-- nested in <a>$</a>.
|
|
(&) :: a -> (a -> b) -> b
|
|
infixl 1 &
|
|
|
|
-- | 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.
|
|
($!) :: (a -> b) -> a -> b
|
|
infixr 0 $!
|
|
|
|
-- | Boolean "and"
|
|
(&&) :: Bool -> Bool -> Bool
|
|
infixr 3 &&
|
|
|
|
-- | Boolean "or"
|
|
(||) :: Bool -> Bool -> Bool
|
|
infixr 2 ||
|
|
|
|
-- | Function composition.
|
|
(.) :: (b -> c) -> (a -> b) -> a -> c
|
|
infixr 9 .
|
|
|
|
-- | Boolean "not"
|
|
not :: Bool -> Bool
|
|
|
|
-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
|
|
-- guards more readable. eg.
|
|
--
|
|
-- <pre>
|
|
-- f x | x < 0 = ...
|
|
-- | otherwise = ...
|
|
-- </pre>
|
|
otherwise :: Bool
|
|
|
|
-- | Extract the first component of a pair.
|
|
fst :: (a, b) -> a
|
|
|
|
-- | Extract the second component of a pair.
|
|
snd :: (a, b) -> b
|
|
|
|
-- | Identity function.
|
|
id :: a -> a
|
|
|
|
-- | The <a>maybe</a> function takes a default value, a function, and a
|
|
-- <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
|
|
-- function returns the default value. Otherwise, it applies the function
|
|
-- to the value inside the <a>Just</a> and returns the result.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> maybe False odd (Just 3)
|
|
-- True
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> maybe False odd Nothing
|
|
-- False
|
|
-- </pre>
|
|
--
|
|
-- Read an integer from a string using <tt>readMaybe</tt>. If we succeed,
|
|
-- return twice the integer; that is, apply <tt>(*2)</tt> to it. If
|
|
-- instead we fail to parse an integer, return <tt>0</tt> by default:
|
|
--
|
|
-- <pre>
|
|
-- >>> import Text.Read ( readMaybe )
|
|
--
|
|
-- >>> maybe 0 (*2) (readMaybe "5")
|
|
-- 10
|
|
--
|
|
-- >>> maybe 0 (*2) (readMaybe "")
|
|
-- 0
|
|
-- </pre>
|
|
--
|
|
-- Apply <tt>show</tt> to a <tt>Maybe Int</tt>. If we have <tt>Just
|
|
-- n</tt>, we want to show the underlying <a>Int</a> <tt>n</tt>. But if
|
|
-- we have <a>Nothing</a>, we return the empty string instead of (for
|
|
-- example) "Nothing":
|
|
--
|
|
-- <pre>
|
|
-- >>> maybe "" show (Just 5)
|
|
-- "5"
|
|
--
|
|
-- >>> maybe "" show Nothing
|
|
-- ""
|
|
-- </pre>
|
|
maybe :: b -> (a -> b) -> Maybe a -> b
|
|
|
|
-- | Case analysis for the <a>Either</a> type. If the value is
|
|
-- <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
|
|
-- is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- We create two values of type <tt><a>Either</a> <a>String</a>
|
|
-- <a>Int</a></tt>, one using the <a>Left</a> constructor and another
|
|
-- using the <a>Right</a> constructor. Then we apply "either" the
|
|
-- <tt>length</tt> function (if we have a <a>String</a>) or the
|
|
-- "times-two" function (if we have an <a>Int</a>):
|
|
--
|
|
-- <pre>
|
|
-- >>> let s = Left "foo" :: Either String Int
|
|
--
|
|
-- >>> let n = Right 3 :: Either String Int
|
|
--
|
|
-- >>> either length (*2) s
|
|
-- 3
|
|
--
|
|
-- >>> either length (*2) n
|
|
-- 6
|
|
-- </pre>
|
|
either :: (a -> c) -> (b -> c) -> Either a b -> c
|
|
|
|
-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
|
|
-- order of <tt>f</tt>.
|
|
flip :: (a -> b -> c) -> b -> a -> c
|
|
|
|
-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
|
|
-- all inputs.
|
|
--
|
|
-- For instance,
|
|
--
|
|
-- <pre>
|
|
-- >>> map (const 42) [0..3]
|
|
-- [42,42,42,42]
|
|
-- </pre>
|
|
const :: a -> b -> a
|
|
odd :: Integral a => a -> Bool
|
|
even :: Integral a => a -> Bool
|
|
|
|
-- | <a>uncurry</a> converts a curried function to a function on pairs.
|
|
uncurry :: (a -> b -> c) -> (a, b) -> c
|
|
|
|
-- | <a>curry</a> converts an uncurried function to a curried function.
|
|
curry :: ((a, b) -> c) -> a -> b -> c
|
|
|
|
-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. 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.
|
|
asTypeOf :: a -> a -> a
|
|
|
|
-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
|
|
-- otherwise equal to <tt>b</tt>. <tt>seq</tt> is usually introduced to
|
|
-- improve performance by avoiding unneeded laziness.
|
|
--
|
|
-- A note on evaluation order: the expression <tt>seq a b</tt> does
|
|
-- <i>not</i> guarantee that <tt>a</tt> will be evaluated before
|
|
-- <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
|
|
-- <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
|
|
-- returns a value. In particular, this means that <tt>b</tt> may be
|
|
-- evaluated before <tt>a</tt>. If you need to guarantee a specific order
|
|
-- of evaluation, you must use the function <tt>pseq</tt> from the
|
|
-- "parallel" package.
|
|
seq :: a -> b -> b
|
|
|
|
-- | <tt><a>fix</a> f</tt> is the least fixed point of the function
|
|
-- <tt>f</tt>, i.e. the least defined <tt>x</tt> such that <tt>f x =
|
|
-- x</tt>.
|
|
fix :: (a -> a) -> a
|
|
|
|
-- | raise a number to a non-negative integral power
|
|
(^) :: (Num a, Integral b) => a -> b -> a
|
|
infixr 8 ^
|
|
|
|
-- | raise a number to an integral power
|
|
(^^) :: (Fractional a, Integral b) => a -> b -> a
|
|
infixr 8 ^^
|
|
|
|
-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
|
|
--
|
|
-- Because <tt>-</tt> is treated specially in the Haskell grammar,
|
|
-- <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
|
|
-- prefix negation. However, <tt>(<a>subtract</a></tt>
|
|
-- <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
|
|
subtract :: Num a => a -> a -> a
|
|
|
|
-- | general coercion from integral types
|
|
fromIntegral :: (Integral a, Num b) => a -> b
|
|
|
|
-- | general coercion to fractional types
|
|
realToFrac :: (Real a, Fractional b) => a -> b
|
|
|
|
-- | Get the sum of the elements in a <a>Foldable</a>.
|
|
--
|
|
-- This is not the same as the function from <a>Foldable</a>; instead,
|
|
-- this function uses a strict left fold.
|
|
sum :: (Foldable f, Num a) => f a -> a
|
|
|
|
-- | Get the product of the elements in a <a>Foldable</a>.
|
|
--
|
|
-- This is not the same as the function from <a>Foldable</a>; instead,
|
|
-- this function uses a strict left fold.
|
|
product :: (Foldable f, Num a) => f a -> a
|
|
|
|
-- | Monadic fold over the elements of a structure, associating to the
|
|
-- right, i.e. from right to left.
|
|
foldrM :: (Foldable t, Monad m) => (a -> b -> m b) -> b -> t a -> m b
|
|
|
|
-- | Monadic fold over the elements of a structure, associating to the
|
|
-- left, i.e. from left to right.
|
|
foldlM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
|
|
|
|
-- | Map each element of a structure to an action, evaluate these actions
|
|
-- from left to right, and ignore the results. For a version that doesn't
|
|
-- ignore the results see <a>traverse</a>.
|
|
traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f ()
|
|
|
|
-- | <a>for_</a> is <a>traverse_</a> with its arguments flipped. For a
|
|
-- version that doesn't ignore the results see <a>for</a>.
|
|
--
|
|
-- <pre>
|
|
-- >>> for_ [1..4] print
|
|
-- 1
|
|
-- 2
|
|
-- 3
|
|
-- 4
|
|
-- </pre>
|
|
for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f ()
|
|
|
|
-- | Evaluate each action in the structure from left to right, and ignore
|
|
-- the results. For a version that doesn't ignore the results see
|
|
-- <a>sequenceA</a>.
|
|
sequenceA_ :: (Foldable t, Applicative f) => t (f a) -> f ()
|
|
|
|
-- | The sum of a collection of actions, generalizing <a>concat</a>.
|
|
asum :: (Foldable t, Alternative f) => t (f a) -> f a
|
|
|
|
-- | Synonym for <a>traverse_</a>; different from base to generalize to
|
|
-- <a>Applicative</a>.
|
|
mapM_ :: (Applicative m, Foldable f) => (a -> m b) -> f a -> m ()
|
|
|
|
-- | Flipped version of <a>mapM_</a>.
|
|
forM_ :: (Applicative m, Foldable f) => f a -> (a -> m b) -> m ()
|
|
|
|
-- | Synonym for <a>sequence_</a>; different from base to generalize to
|
|
-- <a>Applicative</a>.
|
|
sequence_ :: (Applicative m, Foldable f) => f (m a) -> m ()
|
|
|
|
-- | The sum of a collection of actions, generalizing <a>concat</a>. As of
|
|
-- base 4.8.0.0, <a>msum</a> is just <a>asum</a>, specialized to
|
|
-- <a>MonadPlus</a>.
|
|
msum :: (Foldable t, MonadPlus m) => t (m a) -> m a
|
|
|
|
-- | The concatenation of all the elements of a container of lists.
|
|
concat :: Foldable t => t [a] -> [a]
|
|
|
|
-- | Map a function over all the elements of a container and concatenate
|
|
-- the resulting lists.
|
|
concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
|
|
|
|
-- | <a>and</a> returns the conjunction of a container of Bools. For the
|
|
-- result to be <a>True</a>, the container must be finite; <a>False</a>,
|
|
-- however, results from a <a>False</a> value finitely far from the left
|
|
-- end.
|
|
and :: Foldable t => t Bool -> Bool
|
|
|
|
-- | <a>or</a> returns the disjunction of a container of Bools. For the
|
|
-- result to be <a>False</a>, the container must be finite; <a>True</a>,
|
|
-- however, results from a <a>True</a> value finitely far from the left
|
|
-- end.
|
|
or :: Foldable t => t Bool -> Bool
|
|
|
|
-- | Determines whether any element of the structure satisfies the
|
|
-- predicate.
|
|
any :: Foldable t => (a -> Bool) -> t a -> Bool
|
|
|
|
-- | Determines whether all elements of the structure satisfy the
|
|
-- predicate.
|
|
all :: Foldable t => (a -> Bool) -> t a -> Bool
|
|
|
|
-- | <a>notElem</a> is the negation of <a>elem</a>.
|
|
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
|
|
infix 4 `notElem`
|
|
|
|
-- | The <a>find</a> function takes a predicate and a structure and returns
|
|
-- the leftmost element of the structure matching the predicate, or
|
|
-- <a>Nothing</a> if there is no such element.
|
|
find :: Foldable t => (a -> Bool) -> t a -> Maybe a
|
|
|
|
-- | Synonym for <a>traverse</a>; different from base to generalize to
|
|
-- <a>Applicative</a>.
|
|
mapM :: (Applicative m, Traversable t) => (a -> m b) -> t a -> m (t b)
|
|
|
|
-- | Synonym for <a>sequenceA</a>; different from base to generalize to
|
|
-- <a>Applicative</a>.
|
|
sequence :: (Applicative m, Traversable t) => t (m a) -> m (t a)
|
|
|
|
-- | <a>for</a> is <a>traverse</a> with its arguments flipped. For a
|
|
-- version that ignores the results see <a>for_</a>.
|
|
for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)
|
|
|
|
-- | Flipped version of <a>mapM</a>.
|
|
forM :: (Applicative m, Traversable t) => t a -> (a -> m b) -> m (t b)
|
|
|
|
-- | The <a>mapAccumL</a> function behaves like a combination of
|
|
-- <a>fmap</a> and <tt>foldl</tt>; it applies a function to each element
|
|
-- of a structure, passing an accumulating parameter from left to right,
|
|
-- and returning a final value of this accumulator together with the new
|
|
-- structure.
|
|
mapAccumL :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
|
|
|
|
-- | The <a>mapAccumR</a> function behaves like a combination of
|
|
-- <a>fmap</a> and <tt>foldr</tt>; it applies a function to each element
|
|
-- of a structure, passing an accumulating parameter from right to left,
|
|
-- and returning a final value of this accumulator together with the new
|
|
-- structure.
|
|
mapAccumR :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
|
|
|
|
-- | Flipped version of <a><$</a>.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Replace the contents of a <tt><tt>Maybe</tt> <tt>Int</tt></tt> with a
|
|
-- constant <tt>String</tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> Nothing $> "foo"
|
|
-- Nothing
|
|
--
|
|
-- >>> Just 90210 $> "foo"
|
|
-- Just "foo"
|
|
-- </pre>
|
|
--
|
|
-- Replace the contents of an <tt><tt>Either</tt> <tt>Int</tt>
|
|
-- <tt>Int</tt></tt> with a constant <tt>String</tt>, resulting in an
|
|
-- <tt><tt>Either</tt> <tt>Int</tt> <tt>String</tt></tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> Left 8675309 $> "foo"
|
|
-- Left 8675309
|
|
--
|
|
-- >>> Right 8675309 $> "foo"
|
|
-- Right "foo"
|
|
-- </pre>
|
|
--
|
|
-- Replace each element of a list with a constant <tt>String</tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> [1,2,3] $> "foo"
|
|
-- ["foo","foo","foo"]
|
|
-- </pre>
|
|
--
|
|
-- Replace the second element of a pair with a constant <tt>String</tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> (1,2) $> "foo"
|
|
-- (1,"foo")
|
|
-- </pre>
|
|
($>) :: Functor f => f a -> b -> f b
|
|
infixl 4 $>
|
|
|
|
-- | An infix synonym for <a>fmap</a>.
|
|
--
|
|
-- The name of this operator is an allusion to <tt>$</tt>. Note the
|
|
-- similarities between their types:
|
|
--
|
|
-- <pre>
|
|
-- ($) :: (a -> b) -> a -> b
|
|
-- (<$>) :: Functor f => (a -> b) -> f a -> f b
|
|
-- </pre>
|
|
--
|
|
-- Whereas <tt>$</tt> is function application, <a><$></a> is
|
|
-- function application lifted over a <a>Functor</a>.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Convert from a <tt><tt>Maybe</tt> <tt>Int</tt></tt> to a
|
|
-- <tt><tt>Maybe</tt> <tt>String</tt></tt> using <tt>show</tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> show <$> Nothing
|
|
-- Nothing
|
|
--
|
|
-- >>> show <$> Just 3
|
|
-- Just "3"
|
|
-- </pre>
|
|
--
|
|
-- Convert from an <tt><tt>Either</tt> <tt>Int</tt> <tt>Int</tt></tt> to
|
|
-- an <tt><tt>Either</tt> <tt>Int</tt></tt> <tt>String</tt> using
|
|
-- <tt>show</tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> show <$> Left 17
|
|
-- Left 17
|
|
--
|
|
-- >>> show <$> Right 17
|
|
-- Right "17"
|
|
-- </pre>
|
|
--
|
|
-- Double each element of a list:
|
|
--
|
|
-- <pre>
|
|
-- >>> (*2) <$> [1,2,3]
|
|
-- [2,4,6]
|
|
-- </pre>
|
|
--
|
|
-- Apply <tt>even</tt> to the second element of a pair:
|
|
--
|
|
-- <pre>
|
|
-- >>> even <$> (2,2)
|
|
-- (2,True)
|
|
-- </pre>
|
|
(<$>) :: Functor f => (a -> b) -> f a -> f b
|
|
infixl 4 <$>
|
|
|
|
-- | <tt><a>void</a> value</tt> discards or ignores the result of
|
|
-- evaluation, such as the return value of an <a>IO</a> action.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Replace the contents of a <tt><tt>Maybe</tt> <tt>Int</tt></tt> with
|
|
-- unit:
|
|
--
|
|
-- <pre>
|
|
-- >>> void Nothing
|
|
-- Nothing
|
|
--
|
|
-- >>> void (Just 3)
|
|
-- Just ()
|
|
-- </pre>
|
|
--
|
|
-- Replace the contents of an <tt><tt>Either</tt> <tt>Int</tt>
|
|
-- <tt>Int</tt></tt> with unit, resulting in an <tt><tt>Either</tt>
|
|
-- <tt>Int</tt> '()'</tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> void (Left 8675309)
|
|
-- Left 8675309
|
|
--
|
|
-- >>> void (Right 8675309)
|
|
-- Right ()
|
|
-- </pre>
|
|
--
|
|
-- Replace every element of a list with unit:
|
|
--
|
|
-- <pre>
|
|
-- >>> void [1,2,3]
|
|
-- [(),(),()]
|
|
-- </pre>
|
|
--
|
|
-- Replace the second element of a pair with unit:
|
|
--
|
|
-- <pre>
|
|
-- >>> void (1,2)
|
|
-- (1,())
|
|
-- </pre>
|
|
--
|
|
-- Discard the result of an <a>IO</a> action:
|
|
--
|
|
-- <pre>
|
|
-- >>> mapM print [1,2]
|
|
-- 1
|
|
-- 2
|
|
-- [(),()]
|
|
--
|
|
-- >>> void $ mapM print [1,2]
|
|
-- 1
|
|
-- 2
|
|
-- </pre>
|
|
void :: Functor f => f a -> f ()
|
|
|
|
-- | Lift a function to actions. This function may be used as a value for
|
|
-- <a>fmap</a> in a <a>Functor</a> instance.
|
|
liftA :: Applicative f => (a -> b) -> f a -> f b
|
|
|
|
-- | Lift a binary function to actions.
|
|
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
|
|
|
|
-- | Lift a ternary function to actions.
|
|
liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
|
|
|
|
-- | One or none.
|
|
optional :: Alternative f => f a -> f (Maybe a)
|
|
|
|
-- | Same as <a>>>=</a>, but with the arguments interchanged.
|
|
(=<<) :: Monad m => (a -> m b) -> m a -> m b
|
|
infixr 1 =<<
|
|
|
|
-- | Left-to-right Kleisli composition of monads.
|
|
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
|
|
infixr 1 >=>
|
|
|
|
-- | Right-to-left Kleisli composition of monads.
|
|
-- <tt>(<a>>=></a>)</tt>, with the arguments flipped.
|
|
--
|
|
-- Note how this operator resembles function composition
|
|
-- <tt>(<a>.</a>)</tt>:
|
|
--
|
|
-- <pre>
|
|
-- (.) :: (b -> c) -> (a -> b) -> a -> c
|
|
-- (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
|
|
-- </pre>
|
|
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
|
|
infixr 1 <=<
|
|
|
|
-- | <tt><a>forever</a> act</tt> repeats the action infinitely.
|
|
forever :: Applicative f => f a -> f b
|
|
|
|
-- | The <a>join</a> function is the conventional monad join operator. It
|
|
-- is used to remove one level of monadic structure, projecting its bound
|
|
-- argument into the outer level.
|
|
join :: Monad m => m (m a) -> m a
|
|
|
|
-- | The <a>foldM</a> function is analogous to <tt>foldl</tt>, except that
|
|
-- its result is encapsulated in a monad. Note that <a>foldM</a> works
|
|
-- from left-to-right over the list arguments. This could be an issue
|
|
-- where <tt>(<a>>></a>)</tt> and the `folded function' are not
|
|
-- commutative.
|
|
--
|
|
-- <pre>
|
|
-- foldM f a1 [x1, x2, ..., xm]
|
|
-- </pre>
|
|
--
|
|
-- ==
|
|
--
|
|
-- <pre>
|
|
-- do
|
|
-- a2 <- f a1 x1
|
|
-- a3 <- f a2 x2
|
|
-- ...
|
|
-- f am xm
|
|
-- </pre>
|
|
--
|
|
-- If right-to-left evaluation is required, the input list should be
|
|
-- reversed.
|
|
--
|
|
-- Note: <a>foldM</a> is the same as <a>foldlM</a>
|
|
foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
|
|
|
|
-- | Like <a>foldM</a>, but discards the result.
|
|
foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()
|
|
|
|
-- | Like <a>replicateM</a>, but discards the result.
|
|
replicateM_ :: Applicative m => Int -> m a -> m ()
|
|
|
|
-- | <tt><a>guard</a> b</tt> is <tt><a>pure</a> ()</tt> if <tt>b</tt> is
|
|
-- <a>True</a>, and <a>empty</a> if <tt>b</tt> is <a>False</a>.
|
|
guard :: Alternative f => Bool -> f ()
|
|
|
|
-- | Conditional execution of <a>Applicative</a> expressions. For example,
|
|
--
|
|
-- <pre>
|
|
-- when debug (putStrLn "Debugging")
|
|
-- </pre>
|
|
--
|
|
-- will output the string <tt>Debugging</tt> if the Boolean value
|
|
-- <tt>debug</tt> is <a>True</a>, and otherwise do nothing.
|
|
when :: Applicative f => Bool -> f () -> f ()
|
|
|
|
-- | The reverse of <a>when</a>.
|
|
unless :: Applicative f => Bool -> f () -> f ()
|
|
|
|
-- | Promote a function to a monad.
|
|
liftM :: Monad m => (a1 -> r) -> m a1 -> m r
|
|
|
|
-- | In many situations, the <a>liftM</a> operations can be replaced by
|
|
-- uses of <a>ap</a>, which promotes function application.
|
|
--
|
|
-- <pre>
|
|
-- return f `ap` x1 `ap` ... `ap` xn
|
|
-- </pre>
|
|
--
|
|
-- is equivalent to
|
|
--
|
|
-- <pre>
|
|
-- liftMn f x1 x2 ... xn
|
|
-- </pre>
|
|
ap :: Monad m => m (a -> b) -> m a -> m b
|
|
|
|
-- | Strict version of <a><$></a>.
|
|
(<$!>) :: Monad m => (a -> b) -> m a -> m b
|
|
infixl 4 <$!>
|
|
|
|
-- | Suspends the current thread for a given number of microseconds (GHC
|
|
-- only).
|
|
--
|
|
-- There is no guarantee that the thread will be rescheduled promptly
|
|
-- when the delay has expired, but the thread will never continue to run
|
|
-- <i>earlier</i> than specified.
|
|
threadDelay :: Int -> IO ()
|
|
|
|
-- | An <a>MVar</a> (pronounced "em-var") is a synchronising variable, used
|
|
-- for communication between concurrent threads. It can be thought of as
|
|
-- a a box, which may be empty or full.
|
|
data MVar a :: * -> *
|
|
|
|
-- | Create an <a>MVar</a> which is initially empty.
|
|
newEmptyMVar :: IO (MVar a)
|
|
|
|
-- | Create an <a>MVar</a> which contains the supplied value.
|
|
newMVar :: a -> IO (MVar a)
|
|
|
|
-- | Return the contents of the <a>MVar</a>. If the <a>MVar</a> is
|
|
-- currently empty, <a>takeMVar</a> will wait until it is full. After a
|
|
-- <a>takeMVar</a>, the <a>MVar</a> is left empty.
|
|
--
|
|
-- There are two further important properties of <a>takeMVar</a>:
|
|
--
|
|
-- <ul>
|
|
-- <li><a>takeMVar</a> is single-wakeup. That is, if there are multiple
|
|
-- threads blocked in <a>takeMVar</a>, and the <a>MVar</a> becomes full,
|
|
-- only one thread will be woken up. The runtime guarantees that the
|
|
-- woken thread completes its <a>takeMVar</a> operation.</li>
|
|
-- <li>When multiple threads are blocked on an <a>MVar</a>, they are
|
|
-- woken up in FIFO order. This is useful for providing fairness
|
|
-- properties of abstractions built using <a>MVar</a>s.</li>
|
|
-- </ul>
|
|
takeMVar :: MVar a -> IO a
|
|
|
|
-- | Put a value into an <a>MVar</a>. If the <a>MVar</a> is currently full,
|
|
-- <a>putMVar</a> will wait until it becomes empty.
|
|
--
|
|
-- There are two further important properties of <a>putMVar</a>:
|
|
--
|
|
-- <ul>
|
|
-- <li><a>putMVar</a> is single-wakeup. That is, if there are multiple
|
|
-- threads blocked in <a>putMVar</a>, and the <a>MVar</a> becomes empty,
|
|
-- only one thread will be woken up. The runtime guarantees that the
|
|
-- woken thread completes its <a>putMVar</a> operation.</li>
|
|
-- <li>When multiple threads are blocked on an <a>MVar</a>, they are
|
|
-- woken up in FIFO order. This is useful for providing fairness
|
|
-- properties of abstractions built using <a>MVar</a>s.</li>
|
|
-- </ul>
|
|
putMVar :: MVar a -> a -> IO ()
|
|
|
|
-- | Atomically read the contents of an <a>MVar</a>. If the <a>MVar</a> is
|
|
-- currently empty, <a>readMVar</a> will wait until its full.
|
|
-- <a>readMVar</a> is guaranteed to receive the next <a>putMVar</a>.
|
|
--
|
|
-- <a>readMVar</a> is multiple-wakeup, so when multiple readers are
|
|
-- blocked on an <a>MVar</a>, all of them are woken up at the same time.
|
|
--
|
|
-- <i>Compatibility note:</i> Prior to base 4.7, <a>readMVar</a> was a
|
|
-- combination of <a>takeMVar</a> and <a>putMVar</a>. This mean that in
|
|
-- the presence of other threads attempting to <a>putMVar</a>,
|
|
-- <a>readMVar</a> could block. Furthermore, <a>readMVar</a> would not
|
|
-- receive the next <a>putMVar</a> if there was already a pending thread
|
|
-- blocked on <a>takeMVar</a>. The old behavior can be recovered by
|
|
-- implementing 'readMVar as follows:
|
|
--
|
|
-- <pre>
|
|
-- readMVar :: MVar a -> IO a
|
|
-- readMVar m =
|
|
-- mask_ $ do
|
|
-- a <- takeMVar m
|
|
-- putMVar m a
|
|
-- return a
|
|
-- </pre>
|
|
readMVar :: MVar a -> IO a
|
|
|
|
-- | Take a value from an <a>MVar</a>, put a new value into the <a>MVar</a>
|
|
-- and return the value taken. This function is atomic only if there are
|
|
-- no other producers for this <a>MVar</a>.
|
|
swapMVar :: MVar a -> a -> IO a
|
|
|
|
-- | A non-blocking version of <a>takeMVar</a>. The <a>tryTakeMVar</a>
|
|
-- function returns immediately, with <a>Nothing</a> if the <a>MVar</a>
|
|
-- was empty, or <tt><a>Just</a> a</tt> if the <a>MVar</a> was full with
|
|
-- contents <tt>a</tt>. After <a>tryTakeMVar</a>, the <a>MVar</a> is left
|
|
-- empty.
|
|
tryTakeMVar :: MVar a -> IO (Maybe a)
|
|
|
|
-- | A non-blocking version of <a>putMVar</a>. The <a>tryPutMVar</a>
|
|
-- function attempts to put the value <tt>a</tt> into the <a>MVar</a>,
|
|
-- returning <a>True</a> if it was successful, or <a>False</a> otherwise.
|
|
tryPutMVar :: MVar a -> a -> IO Bool
|
|
|
|
-- | Check whether a given <a>MVar</a> is empty.
|
|
--
|
|
-- Notice that the boolean value returned is just a snapshot of the state
|
|
-- of the MVar. By the time you get to react on its result, the MVar may
|
|
-- have been filled (or emptied) - so be extremely careful when using
|
|
-- this operation. Use <a>tryTakeMVar</a> instead if possible.
|
|
isEmptyMVar :: MVar a -> IO Bool
|
|
|
|
-- | <a>withMVar</a> is an exception-safe wrapper for operating on the
|
|
-- contents of an <a>MVar</a>. This operation is exception-safe: it will
|
|
-- replace the original contents of the <a>MVar</a> if an exception is
|
|
-- raised (see <a>Control.Exception</a>). However, it is only atomic if
|
|
-- there are no other producers for this <a>MVar</a>.
|
|
withMVar :: MVar a -> (a -> IO b) -> IO b
|
|
|
|
-- | Like <a>withMVar</a>, but the <tt>IO</tt> action in the second
|
|
-- argument is executed with asynchronous exceptions masked.
|
|
withMVarMasked :: MVar a -> (a -> IO b) -> IO b
|
|
|
|
-- | An exception-safe wrapper for modifying the contents of an
|
|
-- <a>MVar</a>. Like <a>withMVar</a>, <a>modifyMVar</a> will replace the
|
|
-- original contents of the <a>MVar</a> if an exception is raised during
|
|
-- the operation. This function is only atomic if there are no other
|
|
-- producers for this <a>MVar</a>.
|
|
modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
|
|
|
|
-- | A slight variation on <a>modifyMVar_</a> that allows a value to be
|
|
-- returned (<tt>b</tt>) in addition to the modified value of the
|
|
-- <a>MVar</a>.
|
|
modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b
|
|
|
|
-- | Like <a>modifyMVar_</a>, but the <tt>IO</tt> action in the second
|
|
-- argument is executed with asynchronous exceptions masked.
|
|
modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO ()
|
|
|
|
-- | Like <a>modifyMVar</a>, but the <tt>IO</tt> action in the second
|
|
-- argument is executed with asynchronous exceptions masked.
|
|
modifyMVarMasked :: MVar a -> (a -> IO (a, b)) -> IO b
|
|
|
|
-- | A non-blocking version of <a>readMVar</a>. The <a>tryReadMVar</a>
|
|
-- function returns immediately, with <a>Nothing</a> if the <a>MVar</a>
|
|
-- was empty, or <tt><a>Just</a> a</tt> if the <a>MVar</a> was full with
|
|
-- contents <tt>a</tt>.
|
|
tryReadMVar :: MVar a -> IO (Maybe a)
|
|
|
|
-- | Make a <a>Weak</a> pointer to an <a>MVar</a>, using the second
|
|
-- argument as a finalizer to run when <a>MVar</a> is garbage-collected
|
|
mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a))
|
|
|
|
-- | <a>Chan</a> is an abstract type representing an unbounded FIFO
|
|
-- channel.
|
|
data Chan a :: * -> *
|
|
|
|
-- | Build and returns a new instance of <a>Chan</a>.
|
|
newChan :: IO (Chan a)
|
|
|
|
-- | Write a value to a <a>Chan</a>.
|
|
writeChan :: Chan a -> a -> IO ()
|
|
|
|
-- | Read the next value from the <a>Chan</a>.
|
|
readChan :: Chan a -> IO a
|
|
|
|
-- | Duplicate a <a>Chan</a>: the duplicate channel begins empty, but data
|
|
-- written to either channel from then on will be available from both.
|
|
-- Hence this creates a kind of broadcast channel, where data written by
|
|
-- anyone is seen by everyone else.
|
|
--
|
|
-- (Note that a duplicated channel is not equal to its original. So:
|
|
-- <tt>fmap (c /=) $ dupChan c</tt> returns <tt>True</tt> for all
|
|
-- <tt>c</tt>.)
|
|
dupChan :: Chan a -> IO (Chan a)
|
|
|
|
-- | Retrieves a function of the current environment.
|
|
asks :: MonadReader r m => (r -> a) -> m a
|
|
|
|
-- | Synonym for <a>throw</a>
|
|
throwIO :: (MonadThrow m, Exception e) => e -> m a
|
|
|
|
-- | Synonym for <a>throw</a>
|
|
throwM :: (MonadThrow m, Exception e) => e -> m a
|
|
|
|
-- | Throw an asynchronous exception to another thread
|
|
--
|
|
-- It's usually a better idea to use the async package, see
|
|
-- <a>https://github.com/fpco/safe-exceptions#quickstart</a>
|
|
throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m ()
|
|
|
|
-- | Same as upstream <a>catch</a>, but will not catch asynchronous
|
|
-- exceptions
|
|
catch :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a
|
|
|
|
-- | <a>catch</a> specialized to only catching <a>IOException</a>s
|
|
catchIO :: MonadCatch m => m a -> (IOException -> m a) -> m a
|
|
|
|
-- | <a>catch</a> specialized to catch all synchronous exception
|
|
catchAny :: MonadCatch m => m a -> (SomeException -> m a) -> m a
|
|
|
|
-- | Same as <a>catch</a>, but fully force evaluation of the result value
|
|
-- to find all impure exceptions.
|
|
catchDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a
|
|
|
|
-- | <a>catchDeep</a> specialized to catch all synchronous exception
|
|
catchAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> (SomeException -> m a) -> m a
|
|
|
|
-- | Flipped version of <a>catch</a>
|
|
handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
|
|
|
|
-- | <a>handle</a> specialized to only catching <a>IOException</a>s
|
|
handleIO :: MonadCatch m => (IOException -> m a) -> m a -> m a
|
|
|
|
-- | Flipped version of <a>catchAny</a>
|
|
handleAny :: MonadCatch m => (SomeException -> m a) -> m a -> m a
|
|
|
|
-- | Flipped version of <a>catchDeep</a>
|
|
handleDeep :: (MonadCatch m, Exception e, MonadIO m, NFData a) => (e -> m a) -> m a -> m a
|
|
|
|
-- | Flipped version of <a>catchAnyDeep</a>
|
|
handleAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => (SomeException -> m a) -> m a -> m a
|
|
|
|
-- | Same as upstream <a>try</a>, but will not catch asynchronous
|
|
-- exceptions
|
|
try :: (MonadCatch m, Exception e) => m a -> m (Either e a)
|
|
|
|
-- | <a>try</a> specialized to only catching <a>IOException</a>s
|
|
tryIO :: MonadCatch m => m a -> m (Either IOException a)
|
|
|
|
-- | <a>try</a> specialized to catch all synchronous exceptions
|
|
tryAny :: MonadCatch m => m a -> m (Either SomeException a)
|
|
|
|
-- | Same as <a>try</a>, but fully force evaluation of the result value to
|
|
-- find all impure exceptions.
|
|
tryDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> m (Either e a)
|
|
|
|
-- | <a>tryDeep</a> specialized to catch all synchronous exceptions
|
|
tryAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> m (Either SomeException a)
|
|
|
|
-- | Async safe version of <a>onException</a>
|
|
onException :: MonadMask m => m a -> m b -> m a
|
|
|
|
-- | Async safe version of <a>bracket</a>
|
|
bracket :: MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
|
|
|
|
-- | Async safe version of <a>bracket_</a>
|
|
bracket_ :: MonadMask m => m a -> m b -> m c -> m c
|
|
|
|
-- | Async safe version of <a>finally</a>
|
|
finally :: MonadMask m => m a -> m b -> m a
|
|
|
|
-- | Like <a>onException</a>, but provides the handler the thrown
|
|
-- exception.
|
|
withException :: (MonadMask m, Exception e) => m a -> (e -> m b) -> m a
|
|
|
|
-- | Async safe version of <a>bracketOnError</a>
|
|
bracketOnError :: MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
|
|
|
|
-- | Async safe version of <a>bracketOnError_</a>
|
|
bracketOnError_ :: MonadMask m => m a -> m b -> m c -> m c
|
|
|
|
-- | Render this exception value in a human-friendly manner.
|
|
--
|
|
-- Default implementation: <tt><a>show</a></tt>.
|
|
displayException :: Exception e => e -> String
|
|
|
|
-- | Fanout: send the input to both argument arrows and combine their
|
|
-- output.
|
|
--
|
|
-- The default definition may be overridden with a more efficient version
|
|
-- if desired.
|
|
(&&&) :: Arrow a => forall b c c'. a b c -> a b c' -> a b (c, c')
|
|
|
|
-- | Split the input between the two argument arrows and combine their
|
|
-- output. Note that this is in general not a functor.
|
|
--
|
|
-- The default definition may be overridden with a more efficient version
|
|
-- if desired.
|
|
(***) :: Arrow a => forall b c b' c'. a b c -> a b' c' -> a (b, b') (c, c')
|
|
|
|
-- | The <a>mapMaybe</a> function is a version of <a>map</a> which can
|
|
-- throw out elements. In particular, the functional argument returns
|
|
-- something of type <tt><a>Maybe</a> b</tt>. If this is <a>Nothing</a>,
|
|
-- no element is added on to the result list. If it is <tt><a>Just</a>
|
|
-- b</tt>, then <tt>b</tt> is included in the result list.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Using <tt><a>mapMaybe</a> f x</tt> is a shortcut for
|
|
-- <tt><a>catMaybes</a> $ <a>map</a> f x</tt> in most cases:
|
|
--
|
|
-- <pre>
|
|
-- >>> import Text.Read ( readMaybe )
|
|
--
|
|
-- >>> let readMaybeInt = readMaybe :: String -> Maybe Int
|
|
--
|
|
-- >>> mapMaybe readMaybeInt ["1", "Foo", "3"]
|
|
-- [1,3]
|
|
--
|
|
-- >>> catMaybes $ map readMaybeInt ["1", "Foo", "3"]
|
|
-- [1,3]
|
|
-- </pre>
|
|
--
|
|
-- If we map the <a>Just</a> constructor, the entire list should be
|
|
-- returned:
|
|
--
|
|
-- <pre>
|
|
-- >>> mapMaybe Just [1,2,3]
|
|
-- [1,2,3]
|
|
-- </pre>
|
|
mapMaybe :: (a -> Maybe b) -> [a] -> [b]
|
|
|
|
-- | The <a>catMaybes</a> function takes a list of <a>Maybe</a>s and
|
|
-- returns a list of all the <a>Just</a> values.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> catMaybes [Just 1, Nothing, Just 3]
|
|
-- [1,3]
|
|
-- </pre>
|
|
--
|
|
-- When constructing a list of <a>Maybe</a> values, <a>catMaybes</a> can
|
|
-- be used to return all of the "success" results (if the list is the
|
|
-- result of a <a>map</a>, then <a>mapMaybe</a> would be more
|
|
-- appropriate):
|
|
--
|
|
-- <pre>
|
|
-- >>> import Text.Read ( readMaybe )
|
|
--
|
|
-- >>> [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
|
|
-- [Just 1,Nothing,Just 3]
|
|
--
|
|
-- >>> catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
|
|
-- [1,3]
|
|
-- </pre>
|
|
catMaybes :: [Maybe a] -> [a]
|
|
|
|
-- | The <a>fromMaybe</a> function takes a default value and and
|
|
-- <a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
|
|
-- the default values; otherwise, it returns the value contained in the
|
|
-- <a>Maybe</a>.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> fromMaybe "" (Just "Hello, World!")
|
|
-- "Hello, World!"
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> fromMaybe "" Nothing
|
|
-- ""
|
|
-- </pre>
|
|
--
|
|
-- Read an integer from a string using <tt>readMaybe</tt>. If we fail to
|
|
-- parse an integer, we want to return <tt>0</tt> by default:
|
|
--
|
|
-- <pre>
|
|
-- >>> import Text.Read ( readMaybe )
|
|
--
|
|
-- >>> fromMaybe 0 (readMaybe "5")
|
|
-- 5
|
|
--
|
|
-- >>> fromMaybe 0 (readMaybe "")
|
|
-- 0
|
|
-- </pre>
|
|
fromMaybe :: a -> Maybe a -> a
|
|
|
|
-- | The <a>isJust</a> function returns <a>True</a> iff its argument is of
|
|
-- the form <tt>Just _</tt>.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> isJust (Just 3)
|
|
-- True
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> isJust (Just ())
|
|
-- True
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> isJust Nothing
|
|
-- False
|
|
-- </pre>
|
|
--
|
|
-- Only the outer constructor is taken into consideration:
|
|
--
|
|
-- <pre>
|
|
-- >>> isJust (Just Nothing)
|
|
-- True
|
|
-- </pre>
|
|
isJust :: Maybe a -> Bool
|
|
|
|
-- | The <a>isNothing</a> function returns <a>True</a> iff its argument is
|
|
-- <a>Nothing</a>.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> isNothing (Just 3)
|
|
-- False
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> isNothing (Just ())
|
|
-- False
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> isNothing Nothing
|
|
-- True
|
|
-- </pre>
|
|
--
|
|
-- Only the outer constructor is taken into consideration:
|
|
--
|
|
-- <pre>
|
|
-- >>> isNothing (Just Nothing)
|
|
-- False
|
|
-- </pre>
|
|
isNothing :: Maybe a -> Bool
|
|
|
|
-- | The <a>listToMaybe</a> function returns <a>Nothing</a> on an empty
|
|
-- list or <tt><a>Just</a> a</tt> where <tt>a</tt> is the first element
|
|
-- of the list.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> listToMaybe []
|
|
-- Nothing
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> listToMaybe [9]
|
|
-- Just 9
|
|
-- </pre>
|
|
--
|
|
-- <pre>
|
|
-- >>> listToMaybe [1,2,3]
|
|
-- Just 1
|
|
-- </pre>
|
|
--
|
|
-- Composing <a>maybeToList</a> with <a>listToMaybe</a> should be the
|
|
-- identity on singleton/empty lists:
|
|
--
|
|
-- <pre>
|
|
-- >>> maybeToList $ listToMaybe [5]
|
|
-- [5]
|
|
--
|
|
-- >>> maybeToList $ listToMaybe []
|
|
-- []
|
|
-- </pre>
|
|
--
|
|
-- But not on lists with more than one element:
|
|
--
|
|
-- <pre>
|
|
-- >>> maybeToList $ listToMaybe [1,2,3]
|
|
-- [1]
|
|
-- </pre>
|
|
listToMaybe :: [a] -> Maybe a
|
|
|
|
-- | Partitions a list of <a>Either</a> into two lists. All the <a>Left</a>
|
|
-- elements are extracted, in order, to the first component of the
|
|
-- output. Similarly the <a>Right</a> elements are extracted to the
|
|
-- second component of the output.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
|
|
--
|
|
-- >>> partitionEithers list
|
|
-- (["foo","bar","baz"],[3,7])
|
|
-- </pre>
|
|
--
|
|
-- The pair returned by <tt><a>partitionEithers</a> x</tt> should be the
|
|
-- same pair as <tt>(<a>lefts</a> x, <a>rights</a> x)</tt>:
|
|
--
|
|
-- <pre>
|
|
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
|
|
--
|
|
-- >>> partitionEithers list == (lefts list, rights list)
|
|
-- True
|
|
-- </pre>
|
|
partitionEithers :: [Either a b] -> ([a], [b])
|
|
|
|
-- | Extracts from a list of <a>Either</a> all the <a>Left</a> elements.
|
|
-- All the <a>Left</a> elements are extracted in order.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
|
|
--
|
|
-- >>> lefts list
|
|
-- ["foo","bar","baz"]
|
|
-- </pre>
|
|
lefts :: [Either a b] -> [a]
|
|
|
|
-- | Extracts from a list of <a>Either</a> all the <a>Right</a> elements.
|
|
-- All the <a>Right</a> elements are extracted in order.
|
|
--
|
|
-- <h4><b>Examples</b></h4>
|
|
--
|
|
-- Basic usage:
|
|
--
|
|
-- <pre>
|
|
-- >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
|
|
--
|
|
-- >>> rights list
|
|
-- [3,7]
|
|
-- </pre>
|
|
rights :: [Either a b] -> [b]
|
|
|
|
-- | <tt>(*) `on` f = \x y -> f x * f y</tt>.
|
|
--
|
|
-- Typical usage: <tt><a>sortBy</a> (<tt>compare</tt> `on`
|
|
-- <tt>fst</tt>)</tt>.
|
|
--
|
|
-- Algebraic properties:
|
|
--
|
|
-- <ul>
|
|
-- <li><tt>(*) `on` <a>id</a> = (*)</tt> (if <tt>(*) ∉ {⊥, <a>const</a>
|
|
-- ⊥}</tt>)</li>
|
|
-- <li><pre>((*) `on` f) `on` g = (*) `on` (f . g)</pre></li>
|
|
-- <li><pre><a>flip</a> on f . <a>flip</a> on g = <a>flip</a> on (g .
|
|
-- f)</pre></li>
|
|
-- </ul>
|
|
on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
|
|
infixl 0 `on`
|
|
|
|
-- | <pre>
|
|
-- comparing p x y = compare (p x) (p y)
|
|
-- </pre>
|
|
--
|
|
-- Useful combinator for use in conjunction with the <tt>xxxBy</tt>
|
|
-- family of functions from <a>Data.List</a>, for example:
|
|
--
|
|
-- <pre>
|
|
-- ... sortBy (comparing fst) ...
|
|
-- </pre>
|
|
comparing :: Ord a => (b -> a) -> b -> b -> Ordering
|
|
|
|
-- | Send a <a>Text</a> to standard output, appending a newline, and
|
|
-- chunking the data. By default, the chunk size is 2048 characters, so
|
|
-- any messages below that size will be sent as one contiguous unit. If
|
|
-- larger messages are used, it is possible for interleaving with other
|
|
-- threads to occur.
|
|
say :: MonadIO m => Text -> m ()
|
|
|
|
-- | Same as <a>say</a>, but operates on a <a>String</a>. Note that this
|
|
-- will force the entire <tt>String</tt> into memory at once, and will
|
|
-- fail for infinite <tt>String</tt>s.
|
|
sayString :: MonadIO m => String -> m ()
|
|
|
|
-- | Same as <a>say</a>, but for instances of <a>Show</a>.
|
|
--
|
|
-- If your <tt>Show</tt> instance generates infinite output, this will
|
|
-- fail. However, an infinite result for <tt>show</tt> would generally be
|
|
-- considered an invalid instance anyway.
|
|
sayShow :: (MonadIO m, Show a) => a -> m ()
|
|
|
|
-- | Same as <a>say</a>, but data is sent to standard error.
|
|
sayErr :: MonadIO m => Text -> m ()
|
|
|
|
-- | Same as <a>sayString</a>, but data is sent to standard error.
|
|
sayErrString :: MonadIO m => String -> m ()
|
|
|
|
-- | Same as <a>sayShow</a>, but data is sent to standard error.
|
|
sayErrShow :: (MonadIO m, Show a) => a -> m ()
|
|
|
|
-- | Same as <a>say</a>, but data is sent to the provided <a>Handle</a>.
|
|
hSay :: MonadIO m => Handle -> Text -> m ()
|
|
|
|
-- | Same as <a>sayString</a>, but data is sent to the provided
|
|
-- <a>Handle</a>.
|
|
hSayString :: MonadIO m => Handle -> String -> m ()
|
|
|
|
-- | Same as <a>sayShow</a>, but data is sent to the provided
|
|
-- <a>Handle</a>.
|
|
hSayShow :: (MonadIO m, Show a) => Handle -> a -> m ()
|
|
|
|
-- | A mutable variable in the <a>IO</a> monad
|
|
data IORef a :: * -> *
|
|
|
|
-- | Build a new <a>IORef</a>
|
|
newIORef :: a -> IO (IORef a)
|
|
|
|
-- | Read the value of an <a>IORef</a>
|
|
readIORef :: IORef a -> IO a
|
|
|
|
-- | Write a new value into an <a>IORef</a>
|
|
writeIORef :: IORef a -> a -> IO ()
|
|
|
|
-- | Mutate the contents of an <a>IORef</a>.
|
|
--
|
|
-- Be warned that <a>modifyIORef</a> does not apply the function
|
|
-- strictly. This means if the program calls <a>modifyIORef</a> many
|
|
-- times, but seldomly uses the value, thunks will pile up in memory
|
|
-- resulting in a space leak. This is a common mistake made when using an
|
|
-- IORef as a counter. For example, the following will likely produce a
|
|
-- stack overflow:
|
|
--
|
|
-- <pre>
|
|
-- ref <- newIORef 0
|
|
-- replicateM_ 1000000 $ modifyIORef ref (+1)
|
|
-- readIORef ref >>= print
|
|
-- </pre>
|
|
--
|
|
-- To avoid this problem, use <a>modifyIORef'</a> instead.
|
|
modifyIORef :: IORef a -> (a -> a) -> IO ()
|
|
|
|
-- | Strict version of <a>modifyIORef</a>
|
|
modifyIORef' :: IORef a -> (a -> a) -> IO ()
|
|
|
|
-- | Atomically modifies the contents of an <a>IORef</a>.
|
|
--
|
|
-- This function is useful for using <a>IORef</a> in a safe way in a
|
|
-- multithreaded program. If you only have one <a>IORef</a>, then using
|
|
-- <a>atomicModifyIORef</a> to access and modify it will prevent race
|
|
-- conditions.
|
|
--
|
|
-- Extending the atomicity to multiple <a>IORef</a>s is problematic, so
|
|
-- it is recommended that if you need to do anything more complicated
|
|
-- then using <a>MVar</a> instead is a good idea.
|
|
--
|
|
-- <a>atomicModifyIORef</a> does not apply the function strictly. This is
|
|
-- important to know even if all you are doing is replacing the value.
|
|
-- For example, this will leak memory:
|
|
--
|
|
-- <pre>
|
|
-- ref <- newIORef '1'
|
|
-- forever $ atomicModifyIORef ref (\_ -> ('2', ()))
|
|
-- </pre>
|
|
--
|
|
-- Use <a>atomicModifyIORef'</a> or <a>atomicWriteIORef</a> to avoid this
|
|
-- problem.
|
|
atomicModifyIORef :: IORef a -> (a -> (a, b)) -> IO b
|
|
|
|
-- | Strict version of <a>atomicModifyIORef</a>. This forces both the value
|
|
-- stored in the <a>IORef</a> as well as the value returned.
|
|
atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b
|
|
|
|
-- | Variant of <a>writeIORef</a> with the "barrier to reordering" property
|
|
-- that <a>atomicModifyIORef</a> has.
|
|
atomicWriteIORef :: IORef a -> a -> IO ()
|
|
|
|
-- | Make a <a>Weak</a> pointer to an <a>IORef</a>, using the second
|
|
-- argument as a finalizer to run when <a>IORef</a> is garbage-collected
|
|
mkWeakIORef :: IORef a -> IO () -> IO (Weak (IORef a))
|
|
|
|
-- | Haskell defines operations to read and write characters from and to
|
|
-- files, represented by values of type <tt>Handle</tt>. Each value of
|
|
-- this type is a <i>handle</i>: a record used by the Haskell run-time
|
|
-- system to <i>manage</i> I/O with file system objects. A handle has at
|
|
-- least the following properties:
|
|
--
|
|
-- <ul>
|
|
-- <li>whether it manages input or output or both;</li>
|
|
-- <li>whether it is <i>open</i>, <i>closed</i> or
|
|
-- <i>semi-closed</i>;</li>
|
|
-- <li>whether the object is seekable;</li>
|
|
-- <li>whether buffering is disabled, or enabled on a line or block
|
|
-- basis;</li>
|
|
-- <li>a buffer (whose length may be zero).</li>
|
|
-- </ul>
|
|
--
|
|
-- Most handles will also have a current I/O position indicating where
|
|
-- the next input or output operation will occur. A handle is
|
|
-- <i>readable</i> if it manages only input or both input and output;
|
|
-- likewise, it is <i>writable</i> if it manages only output or both
|
|
-- input and output. A handle is <i>open</i> when first allocated. Once
|
|
-- it is closed it can no longer be used for either input or output,
|
|
-- though an implementation cannot re-use its storage while references
|
|
-- remain to it. Handles are in the <a>Show</a> and <a>Eq</a> classes.
|
|
-- The string produced by showing a handle is system dependent; it should
|
|
-- include enough information to identify the handle for debugging. A
|
|
-- handle is equal according to <a>==</a> only to itself; no attempt is
|
|
-- made to compare the internal state of different handles for equality.
|
|
data Handle :: *
|
|
|
|
-- | See <a>openFile</a>
|
|
data IOMode :: *
|
|
ReadMode :: IOMode
|
|
WriteMode :: IOMode
|
|
AppendMode :: IOMode
|
|
ReadWriteMode :: IOMode
|
|
|
|
-- | A handle managing input from the Haskell program's standard input
|
|
-- channel.
|
|
stdin :: Handle
|
|
|
|
-- | A handle managing output to the Haskell program's standard output
|
|
-- channel.
|
|
stdout :: Handle
|
|
|
|
-- | A handle managing output to the Haskell program's standard error
|
|
-- channel.
|
|
stderr :: Handle
|
|
|
|
-- | Computation <a>hClose</a> <tt>hdl</tt> makes handle <tt>hdl</tt>
|
|
-- closed. Before the computation finishes, if <tt>hdl</tt> is writable
|
|
-- its buffer is flushed as for <a>hFlush</a>. Performing <a>hClose</a>
|
|
-- on a handle that has already been closed has no effect; doing so is
|
|
-- not an error. All other operations on a closed handle will fail. If
|
|
-- <a>hClose</a> fails for any reason, any further operations (apart from
|
|
-- <a>hClose</a>) on the handle will still fail as if <tt>hdl</tt> had
|
|
-- been successfully closed.
|
|
hClose :: Handle -> IO ()
|
|
|
|
-- | <tt><a>withBinaryFile</a> name mode act</tt> opens a file using
|
|
-- <a>openBinaryFile</a> and passes the resulting handle to the
|
|
-- computation <tt>act</tt>. The handle will be closed on exit from
|
|
-- <a>withBinaryFile</a>, whether by normal termination or by raising an
|
|
-- exception.
|
|
withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
|
|
|
|
-- | Read an entire file strictly into a <a>ByteString</a>.
|
|
readFile :: FilePath -> IO ByteString
|
|
|
|
-- | Write a <a>ByteString</a> to a file.
|
|
writeFile :: FilePath -> ByteString -> IO ()
|
|
|
|
-- | Read a file assuming a UTF-8 character encoding.
|
|
--
|
|
-- This leverages <a>decodeUtf8</a>, so in the event of a character
|
|
-- encoding issue, replacement characters will be used.
|
|
readFileUtf8 :: MonadIO m => FilePath -> m Text
|
|
|
|
-- | Write a file using a UTF-8 character encoding.
|
|
writeFileUtf8 :: MonadIO m => FilePath -> Text -> m ()
|
|
|
|
-- | Encode text using UTF-8 encoding.
|
|
encodeUtf8 :: Text -> ByteString
|
|
|
|
-- | A total function for decoding a <a>ByteString</a> into <a>Text</a>
|
|
-- using a UTF-8 character encoding. This uses <a>lenientDecode</a> in
|
|
-- the case of any encoding errors.
|
|
decodeUtf8 :: ByteString -> Text
|
|
|
|
-- | A class of types that can be fully evaluated.
|
|
class NFData a
|
|
|
|
-- | <a>rnf</a> should reduce its argument to normal form (that is, fully
|
|
-- evaluate all sub-components), and then return '()'.
|
|
--
|
|
-- <h3><a>Generic</a> <a>NFData</a> deriving</h3>
|
|
--
|
|
-- Starting with GHC 7.2, you can automatically derive instances for
|
|
-- types possessing a <a>Generic</a> instance.
|
|
--
|
|
-- <pre>
|
|
-- {-# LANGUAGE DeriveGeneric #-}
|
|
--
|
|
-- import GHC.Generics (Generic)
|
|
-- import Control.DeepSeq
|
|
--
|
|
-- data Foo a = Foo a String
|
|
-- deriving (Eq, Generic)
|
|
--
|
|
-- instance NFData a => NFData (Foo a)
|
|
--
|
|
-- data Colour = Red | Green | Blue
|
|
-- deriving Generic
|
|
--
|
|
-- instance NFData Colour
|
|
-- </pre>
|
|
--
|
|
-- Starting with GHC 7.10, the example above can be written more
|
|
-- concisely by enabling the new <tt>DeriveAnyClass</tt> extension:
|
|
--
|
|
-- <pre>
|
|
-- {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
|
|
--
|
|
-- import GHC.Generics (Generic)
|
|
-- import Control.DeepSeq
|
|
--
|
|
-- data Foo a = Foo a String
|
|
-- deriving (Eq, Generic, NFData)
|
|
--
|
|
-- data Colour = Red | Green | Blue
|
|
-- deriving (Generic, NFData)
|
|
-- </pre>
|
|
--
|
|
-- <h3>Compatibility with previous <tt>deepseq</tt> versions</h3>
|
|
--
|
|
-- Prior to version 1.4.0.0, the default implementation of the <a>rnf</a>
|
|
-- method was defined as
|
|
--
|
|
-- <pre>
|
|
-- <a>rnf</a> a = <a>seq</a> a ()
|
|
-- </pre>
|
|
--
|
|
-- However, starting with <tt>deepseq-1.4.0.0</tt>, the default
|
|
-- implementation is based on <tt>DefaultSignatures</tt> allowing for
|
|
-- more accurate auto-derived <a>NFData</a> instances. If you need the
|
|
-- previously used exact default <a>rnf</a> method implementation
|
|
-- semantics, use
|
|
--
|
|
-- <pre>
|
|
-- instance NFData Colour where rnf x = seq x ()
|
|
-- </pre>
|
|
--
|
|
-- or alternatively
|
|
--
|
|
-- <pre>
|
|
-- {-# LANGUAGE BangPatterns #-}
|
|
-- instance NFData Colour where rnf !_ = ()
|
|
-- </pre>
|
|
rnf :: a -> ()
|
|
|
|
-- | <a>deepseq</a>: fully evaluates the first argument, before returning
|
|
-- the second.
|
|
--
|
|
-- The name <a>deepseq</a> is used to illustrate the relationship to
|
|
-- <a>seq</a>: where <a>seq</a> is shallow in the sense that it only
|
|
-- evaluates the top level of its argument, <a>deepseq</a> traverses the
|
|
-- entire data structure evaluating it completely.
|
|
--
|
|
-- <a>deepseq</a> can be useful for forcing pending exceptions,
|
|
-- eradicating space leaks, or forcing lazy I/O to happen. It is also
|
|
-- useful in conjunction with parallel Strategies (see the
|
|
-- <tt>parallel</tt> package).
|
|
--
|
|
-- There is no guarantee about the ordering of evaluation. The
|
|
-- implementation may evaluate the components of the structure in any
|
|
-- order or in parallel. To impose an actual order on evaluation, use
|
|
-- <tt>pseq</tt> from <a>Control.Parallel</a> in the <tt>parallel</tt>
|
|
-- package.
|
|
deepseq :: NFData a => a -> b -> b
|
|
|
|
-- | the deep analogue of <a>$!</a>. In the expression <tt>f $!! x</tt>,
|
|
-- <tt>x</tt> is fully evaluated before the function <tt>f</tt> is
|
|
-- applied to it.
|
|
($!!) :: NFData a => (a -> b) -> a -> b
|
|
infixr 0 $!!
|
|
|
|
-- | a variant of <a>deepseq</a> that is useful in some circumstances:
|
|
--
|
|
-- <pre>
|
|
-- force x = x `deepseq` x
|
|
-- </pre>
|
|
--
|
|
-- <tt>force x</tt> fully evaluates <tt>x</tt>, and then returns it. Note
|
|
-- that <tt>force x</tt> only performs evaluation when the value of
|
|
-- <tt>force x</tt> itself is demanded, so essentially it turns shallow
|
|
-- evaluation into deep evaluation.
|
|
--
|
|
-- <a>force</a> can be conveniently used in combination with
|
|
-- <tt>ViewPatterns</tt>:
|
|
--
|
|
-- <pre>
|
|
-- {-# LANGUAGE BangPatterns, ViewPatterns #-}
|
|
-- import Control.DeepSeq
|
|
--
|
|
-- someFun :: ComplexData -> SomeResult
|
|
-- someFun (force -> !arg) = {- 'arg' will be fully evaluated -}
|
|
-- </pre>
|
|
--
|
|
-- Another useful application is to combine <a>force</a> with
|
|
-- <a>evaluate</a> in order to force deep evaluation relative to other
|
|
-- <a>IO</a> operations:
|
|
--
|
|
-- <pre>
|
|
-- import Control.Exception (evaluate)
|
|
-- import Control.DeepSeq
|
|
--
|
|
-- main = do
|
|
-- result <- evaluate $ force $ pureComputation
|
|
-- {- 'result' will be fully evaluated at this point -}
|
|
-- return ()
|
|
-- </pre>
|
|
force :: NFData a => a -> a
|
|
|
|
-- | Operator version of <a>mappend</a>.
|
|
--
|
|
-- In base, this operator is known as <a><></a>. However, this is
|
|
-- the name of the operator for <a>Semigroup</a> as well. Once
|
|
-- <a>Semigroup</a> is a superclass of <a>Monoid</a>, this historical
|
|
-- accident will be unimportant. In the meanwhile, <tt>SafePrelude</tt>
|
|
-- deals with this situation by making <a><></a> the
|
|
-- <a>Semigroup</a> operator, and <a>++</a> the <a>Monoid</a> operator.
|
|
(++) :: Monoid m => m -> m -> m
|
|
infixr 5 ++
|
|
|
|
-- | Parse a string using the <a>Read</a> instance. Succeeds if there is
|
|
-- exactly one valid result.
|
|
readMaybe :: Read a => String -> Maybe a
|
|
|
|
-- | Parse a string using the <a>Read</a> instance. Succeeds if there is
|
|
-- exactly one valid result. A <a>Left</a> value indicates a parse error.
|
|
readEither :: Read a => String -> Either String a
|