-- Standard functions over tuples
#if !defined(__HUGS__) && !defined(__NHC__)
+-- | Extract the first component of a pair.
fst :: (a,b) -> a
fst (x,_) = x
+-- | Extract the second component of a pair.
snd :: (a,b) -> b
snd (_,y) = y
--- curry converts an uncurried function to a curried function;
--- uncurry converts a curried function to a function on pairs.
+-- | 'curry' converts an uncurried function to a curried function.
curry :: ((a, b) -> c) -> a -> b -> c
curry f x y = f (x, y)
+-- | 'uncurry' converts a curried function to a function on pairs.
uncurry :: (a -> b -> c) -> ((a, b) -> c)
uncurry f p = f (fst p) (snd p)
#endif /* neither __HUGS__ nor __NHC__ */
%*********************************************************
\begin{code}
--- identity function
+-- | Identity function.
id :: a -> a
id x = x
lazy :: a -> a
lazy x = x
--- Assertion function. This simply ignores its boolean argument.
--- The compiler may rewrite it to (assertError line)
+-- | Assertion function. This simply ignores its boolean argument.
+-- The compiler may rewrite it to @('assertError' line)@.
+
-- SLPJ: in 5.04 etc 'assert' is in GHC.Prim,
-- but from Template Haskell onwards it's simply
-- defined here in Base.lhs
assert :: Bool -> a -> a
assert pred r = r
--- constant function
+-- | Constant function.
const :: a -> b -> a
const x _ = x
--- function composition
+-- | Function composition.
{-# INLINE (.) #-}
(.) :: (b -> c) -> (a -> b) -> a -> c
(.) f g x = f (g x)
--- flip f takes its (first) two arguments in the reverse order of f.
+-- | @'flip' f@ takes its (first) two arguments in the reverse order of @f@.
flip :: (a -> b -> c) -> b -> a -> c
flip f x y = f y x
--- right-associating infix application operator (useful in continuation-
--- passing style)
+-- | Application operator. This operator is redundant, since ordinary
+-- application @(f x)@ means the same as @(f '$' x)@. However, '$' has
+-- low, right-associative binding precedence, so it sometimes allows
+-- parentheses to be omitted; for example:
+--
+-- > f $ g $ h x = f (g (h x))
+--
+-- It is also useful in higher-order situations, such as @'map' ('$' 0) xs@,
+-- or @'Data.List.zipWith' ('$') fs xs@.
{-# INLINE ($) #-}
($) :: (a -> b) -> a -> b
f $ x = f x
--- until p f yields the result of applying f until p holds.
+-- | @'until' p f@ yields the result of applying @f@ until @p@ holds.
until :: (a -> Bool) -> (a -> a) -> a -> a
until p f x | p x = x
| otherwise = until p f (f x)
--- asTypeOf is a type-restricted version of const. It is usually used
--- as an infix operator, and its typing forces its first argument
+-- | 'asTypeOf' is a type-restricted version of 'const'. It is usually
+-- used as an infix operator, and its typing forces its first argument
-- (which is usually overloaded) to have the same type as the second.
asTypeOf :: a -> a -> a
asTypeOf = const
%*********************************************************
\begin{code}
--- error stops execution and displays an error message
+-- | 'error' stops execution and displays an error message.
error :: String -> a
error s = throw (ErrorCall s)
+-- | A special case of 'error'.
-- It is expected that compilers will recognize this and insert error
--- messages which are more appropriate to the context in which undefined
+-- messages which are more appropriate to the context in which 'undefined'
-- appears.
undefined :: a
-- -----------------------------------------------------------------------------
-- Miscellaneous functions
+-- | Strict (call-by-value) application, defined in terms of 'seq'.
($!) :: (a -> b) -> a -> b
f $! x = x `seq` f x
#endif
+#ifdef __HADDOCK__
+-- | The value of @'seq' a b@ is bottom if @a@ is bottom, and otherwise
+-- equal to @b@. 'seq' is usually introduced to improve performance by
+-- avoiding unneeded laziness.
+seq :: a -> b -> b
+seq _ y = y
+#endif