### [project @ 2003-09-01 09:12:02 by ross]

H98 docs for Data.List
parent e72a1e91
This diff is collapsed.
 ... ... @@ -279,6 +279,12 @@ The rest of the prelude list functions are in GHC.List. ---------------------------------------------- \begin{code} -- | 'foldr', 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: -- -- > foldr f z [x1, x2, ..., xn] == x1 f (x2 f ... (xn f z)...) foldr :: (a -> b -> b) -> b -> [a] -> b -- foldr _ z [] = z -- foldr f z (x:xs) = f x (foldr f z xs) ... ... @@ -344,6 +350,12 @@ augment g xs = g (:) xs ---------------------------------------------- \begin{code} -- | 'map' @f xs@ is the list obtained by applying @f@ to each element -- of @xs@, i.e., -- -- > map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn] -- > map f [x1, x2, ...] == [f x1, f x2, ...] map :: (a -> b) -> [a] -> [b] map _ [] = [] map f (x:xs) = f x : map f xs ... ... @@ -383,6 +395,13 @@ mapFB c f x ys = c (f x) ys -- append ---------------------------------------------- \begin{code} -- | Append two lists, i.e., -- -- > [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn] -- > [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...] -- -- If the first list is not finite, the result is the first list. (++) :: [a] -> [a] -> [a] (++) [] ys = ys (++) (x:xs) ys = x : xs ++ ys ... ...
 ... ... @@ -54,11 +54,7 @@ infix 4 elem, notElem %********************************************************* \begin{code} -- head and tail extract the first element and remaining elements, -- respectively, of a list, which must be non-empty. last and init -- are the dual functions working from the end of a finite list, -- rather than the beginning. -- | Extract the first element of a list, which must be non-empty. head :: [a] -> a head (x:_) = x head [] = badHead ... ... @@ -74,10 +70,12 @@ badHead = errorEmptyList "head" head (augment g xs) = g (\x _ -> x) (head xs) #-} -- | Extract the elements after the head of a list, which must be non-empty. tail :: [a] -> [a] tail (_:xs) = xs tail [] = errorEmptyList "tail" -- | Extract the last element of a list, which must be finite and non-empty. last :: [a] -> a #ifdef USE_REPORT_PRELUDE last [x] = x ... ... @@ -91,6 +89,8 @@ last (x:xs) = last' x xs last' _ (y:ys) = last' y ys #endif -- | Return all the elements of a list except the last one. -- The list must be finite and non-empty. init :: [a] -> [a] #ifdef USE_REPORT_PRELUDE init [x] = [] ... ... @@ -104,13 +104,14 @@ init (x:xs) = init' x xs init' y (z:zs) = y : init' z zs #endif -- | Test whether a list is empty. null :: [a] -> Bool null [] = True null (_:_) = False -- length returns the length of a finite list as an Int; it is an instance -- of the more general genericLength, the result type of which may be -- any kind of number. -- | 'length' returns the length of a finite list as an 'Int'. -- It is an instance of the more general 'Data.List.genericLength', -- the result type of which may be any kind of number. length :: [a] -> Int length l = len l 0# where ... ... @@ -118,9 +119,11 @@ length l = len l 0# len [] a# = I# a# len (_:xs) a# = len xs (a# +# 1#) -- filter, applied to a predicate and a list, returns the list of those -- elements that satisfy the predicate; i.e., -- filter p xs = [ x | x <- xs, p x] -- | 'filter', applied to a predicate and a list, returns the list of -- those elements that satisfy the predicate; i.e., -- -- > filter p xs = [ x | x <- xs, p x] filter :: (a -> Bool) -> [a] -> [a] filter _pred [] = [] filter pred (x:xs) ... ... @@ -147,17 +150,13 @@ filterFB c p x r | p x = x c r -- gave rise to a live bug report. SLPJ. -- foldl, 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: -- foldl f z [x1, x2, ..., xn] == (...((z f x1) f x2) f...) f xn -- foldl1 is a variant that has no starting value argument, and thus must -- be applied to non-empty lists. scanl is similar to foldl, but returns -- a list of successive reduced values from the left: -- scanl f z [x1, x2, ...] == [z, z f x1, (z f x1) f x2, ...] -- Note that last (scanl f z xs) == foldl f z xs. -- scanl1 is similar, again without the starting element: -- scanl1 f [x1, x2, ...] == [x1, x1 f x2, ...] -- | 'foldl', 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: -- -- > foldl f z [x1, x2, ..., xn] == (...((z f x1) f x2) f...) f xn -- -- The list must be finite. -- We write foldl as a non-recursive thing, so that it -- can be inlined, and then (often) strictness-analysed, ... ... @@ -169,15 +168,31 @@ foldl f z xs = lgo z xs lgo z [] = z lgo z (x:xs) = lgo (f z x) xs -- | 'foldl1' is a variant of 'foldl' that has no starting value argument, -- and thus must be applied to non-empty lists. foldl1 :: (a -> a -> a) -> [a] -> a foldl1 f (x:xs) = foldl f x xs foldl1 _ [] = errorEmptyList "foldl1" -- | 'scanl' is similar to 'foldl', but returns a list of successive -- reduced values from the left: -- -- > scanl f z [x1, x2, ...] == [z, z f x1, (z f x1) f x2, ...] -- -- Note that -- -- > last (scanl f z xs) == foldl f z xs. scanl :: (a -> b -> a) -> a -> [b] -> [a] scanl f q ls = q : (case ls of [] -> [] x:xs -> scanl f (f q x) xs) -- | 'scanl1' is a variant of 'scanl' that has no starting value argument: -- -- > scanl1 f [x1, x2, ...] == [x1, x1 f x2, ...] scanl1 :: (a -> a -> a) -> [a] -> [a] scanl1 f (x:xs) = scanl f x xs scanl1 _ [] = [] ... ... @@ -185,24 +200,37 @@ scanl1 _ [] = [] -- foldr, foldr1, scanr, and scanr1 are the right-to-left duals of the -- above functions. -- | 'foldr1' is a variant of 'foldr' that has no starting value argument, -- and thus must be applied to non-empty lists. foldr1 :: (a -> a -> a) -> [a] -> a foldr1 _ [x] = x foldr1 f (x:xs) = f x (foldr1 f xs) foldr1 _ [] = errorEmptyList "foldr1" -- | 'scanr' is the right-to-left dual of 'scanl'. -- Note that -- -- > head (scanr f z xs) == foldr f z xs. scanr :: (a -> b -> b) -> b -> [a] -> [b] scanr _ q0 [] = [q0] scanr f q0 (x:xs) = f x q : qs where qs@(q:_) = scanr f q0 xs -- | 'scanr1' is a variant of 'scanr' that has no starting value argument. scanr1 :: (a -> a -> a) -> [a] -> [a] scanr1 f [] = [] scanr1 f [x] = [x] scanr1 f (x:xs) = f x q : qs where qs@(q:_) = scanr1 f xs -- iterate f x returns an infinite list of repeated applications of f to x: -- iterate f x == [x, f x, f (f x), ...] -- | 'iterate' @f x@ returns an infinite list of repeated applications -- of @f@ to @x@: -- -- > iterate f x == [x, f x, f (f x), ...] iterate :: (a -> a) -> a -> [a] iterate f x = x : iterate f (f x) ... ... @@ -215,7 +243,7 @@ iterateFB c f x = x c iterateFB c f (f x) #-} -- repeat x is an infinite list, with x the value of every element. -- | 'repeat' @x@ is an infinite list, with @x@ the value of every element. repeat :: a -> [a] {-# INLINE  repeat #-} -- The pragma just gives the rules more chance to fire ... ... @@ -230,11 +258,14 @@ repeatFB c x = xs where xs = x c xs "repeatFB"  repeatFB (:) = repeat #-} -- replicate n x is a list of length n with x the value of every element -- | 'replicate' @n x@ is a list of length @n@ with @x@ the value of -- every element. -- It is an instance of the more general 'Data.List.genericReplicate', -- in which @n@ may be of any integral type. replicate :: Int -> a -> [a] replicate n x = take n (repeat x) -- cycle ties a finite list into a circular one, or equivalently, -- | 'cycle' ties a finite list into a circular one, or equivalently, -- the infinite repetition of the original list. It is the identity -- on infinite lists. ... ... @@ -242,10 +273,8 @@ cycle :: [a] -> [a] cycle [] = error "Prelude.cycle: empty list" cycle xs = xs' where xs' = xs ++ xs' -- takeWhile, applied to a predicate p and a list xs, returns the longest -- prefix (possibly empty) of xs of elements that satisfy p. dropWhile p xs -- returns the remaining suffix. Span p xs is equivalent to -- (takeWhile p xs, dropWhile p xs), while break p uses the negation of p. -- | 'takeWhile', applied to a predicate @p@ and a list @xs@, returns the -- longest prefix (possibly empty) of @xs@ of elements that satisfy @p@. takeWhile :: (a -> Bool) -> [a] -> [a] takeWhile _ [] = [] ... ... @@ -253,32 +282,43 @@ takeWhile p (x:xs) | p x = x : takeWhile p xs | otherwise = [] -- | 'dropWhile' @p xs@ returns the suffix remaining after 'takeWhile' @p xs@. dropWhile :: (a -> Bool) -> [a] -> [a] dropWhile _ [] = [] dropWhile p xs@(x:xs') | p x = dropWhile p xs' | otherwise = xs -- take n, applied to a list xs, returns the prefix of xs of length n, -- or xs itself if n > length xs. drop n xs returns the suffix of xs -- after the first n elements, or [] if n > length xs. splitAt n xs -- is equivalent to (take n xs, drop n xs). #ifdef USE_REPORT_PRELUDE -- | 'take' @n@, applied to a list @xs@, returns the prefix of @xs@ -- of length @n@, or @xs@ itself if @n > 'length' xs@. -- It is an instance of the more general 'Data.List.genericTake', -- in which @n@ may be of any integral type. take :: Int -> [a] -> [a] -- | 'drop' @n xs@ returns the suffix of @xs@ -- after the first @n@ elements, or @[]@ if @n > 'length' xs@. -- It is an instance of the more general 'Data.List.genericDrop', -- in which @n@ may be of any integral type. drop :: Int -> [a] -> [a] -- | 'splitAt' @n xs@ is equivalent to @('take' n xs, 'drop' n xs)@. -- It is an instance of the more general 'Data.List.genericSplitAt', -- in which @n@ may be of any integral type. splitAt :: Int -> [a] -> ([a],[a]) #ifdef USE_REPORT_PRELUDE take n _ | n <= 0 = [] take _ [] = [] take n (x:xs) = x : take (n-1) xs drop :: Int -> [a] -> [a] drop n xs | n <= 0 = xs drop _ [] = [] drop n (_:xs) = drop (n-1) xs splitAt :: Int -> [a] -> ([a],[a]) splitAt n xs = (take n xs, drop n xs) splitAt n xs = (take n xs, drop n xs) #else /* hack away */ take :: Int -> [b] -> [b] take (I# n#) xs = takeUInt n# xs -- The general code for take, below, checks n <= maxInt ... ... @@ -309,7 +349,6 @@ take_unsafe_UInt_append m ls rs = [] -> rs (x:xs) -> x : take_unsafe_UInt_append (m -# 1#) xs rs drop :: Int -> [b] -> [b] drop (I# n#) ls | n# <# 0# = [] | otherwise = drop# n# ls ... ... @@ -319,7 +358,6 @@ drop (I# n#) ls drop# _ xs@[] = xs drop# m# (_:xs) = drop# (m# -# 1#) xs splitAt :: Int -> [b] -> ([b], [b]) splitAt (I# n#) ls | n# <# 0# = ([], ls) | otherwise = splitAt# n# ls ... ... @@ -333,12 +371,17 @@ splitAt (I# n#) ls #endif /* USE_REPORT_PRELUDE */ span, break :: (a -> Bool) -> [a] -> ([a],[a]) -- | 'span' @p xs@ is equivalent to @('takeWhile' p xs, 'dropWhile' p xs)@ span :: (a -> Bool) -> [a] -> ([a],[a]) span _ xs@[] = (xs, xs) span p xs@(x:xs') | p x = let (ys,zs) = span p xs' in (x:ys,zs) | otherwise = ([],xs) -- | 'break' @p@ is equivalent to @'span' ('not' . p)@. break :: (a -> Bool) -> [a] -> ([a],[a]) #ifdef USE_REPORT_PRELUDE break p = span (not . p) #else ... ... @@ -349,7 +392,8 @@ break p xs@(x:xs') | otherwise = let (ys,zs) = break p xs' in (x:ys,zs) #endif -- reverse xs returns the elements of xs in reverse order. xs must be finite. -- | 'reverse' @xs@ returns the elements of @xs@ in reverse order. -- @xs@ must be finite. reverse :: [a] -> [a] #ifdef USE_REPORT_PRELUDE reverse = foldl (flip (:)) [] ... ... @@ -360,11 +404,15 @@ reverse l = rev l [] rev (x:xs) a = rev xs (x:a) #endif -- and returns the conjunction of a Boolean list. For the result to be -- True, the list must be finite; False, however, results from a False -- value at a finite index of a finite or infinite list. or is the -- disjunctive dual of and. -- | 'and' returns the conjunction of a Boolean list. For the result to be -- 'True', the list must be finite; 'False', however, results from a 'False' -- value at a finite index of a finite or infinite list. and :: [Bool] -> Bool -- | 'or' returns the disjunction of a Boolean list. For the result to be -- 'False', the list must be finite; 'True', however, results from a 'True' -- value at a finite index of a finite or infinite list. or :: [Bool] -> Bool #ifdef USE_REPORT_PRELUDE and = foldr (&&) True or = foldr (||) False ... ... @@ -382,9 +430,13 @@ or (x:xs) = x || or xs #-} #endif -- Applied to a predicate and a list, any determines if any element -- of the list satisfies the predicate. Similarly, for all. any, all :: (a -> Bool) -> [a] -> Bool -- | Applied to a predicate and a list, 'any' determines if any element -- of the list satisfies the predicate. any :: (a -> Bool) -> [a] -> Bool -- | Applied to a predicate and a list, 'all' determines if all elements -- of the list satisfy the predicate. all :: (a -> Bool) -> [a] -> Bool #ifdef USE_REPORT_PRELUDE any p = or . map p all p = and . map p ... ... @@ -402,9 +454,12 @@ all p (x:xs) = p x && all p xs #-} #endif -- elem is the list membership predicate, usually written in infix form, -- e.g., x elem xs. notElem is the negation. elem, notElem :: (Eq a) => a -> [a] -> Bool -- | 'elem' is the list membership predicate, usually written in infix form, -- e.g., @x elem xs@. elem :: (Eq a) => a -> [a] -> Bool -- | 'notElem' is the negation of 'elem'. notElem :: (Eq a) => a -> [a] -> Bool #ifdef USE_REPORT_PRELUDE elem x = any (== x) notElem x = all (/= x) ... ... @@ -416,28 +471,37 @@ notElem _ [] = True notElem x (y:ys)= x /= y && notElem x ys #endif -- lookup key assocs looks up a key in an association list. -- | 'lookup' @key assocs@ looks up a key in an association list. lookup :: (Eq a) => a -> [(a,b)] -> Maybe b lookup _key [] = Nothing lookup key ((x,y):xys) | key == x = Just y | otherwise = lookup key xys -- maximum and minimum return the maximum or minimum value from a list, -- which must be non-empty, finite, and of an ordered type. {-# SPECIALISE maximum :: [Int] -> Int #-} {-# SPECIALISE minimum :: [Int] -> Int #-} maximum, minimum :: (Ord a) => [a] -> a -- | 'maximum' returns the maximum value from a list, -- which must be non-empty, finite, and of an ordered type. -- It is a special case of 'Data.List.maximumBy', which allows the -- programmer to supply their own comparison function. maximum :: (Ord a) => [a] -> a maximum [] = errorEmptyList "maximum" maximum xs = foldl1 max xs -- | 'minimum' returns the minimum value from a list, -- which must be non-empty, finite, and of an ordered type. -- It is a special case of 'Data.List.minimumBy', which allows the -- programmer to supply their own comparison function. minimum :: (Ord a) => [a] -> a minimum [] = errorEmptyList "minimum" minimum xs = foldl1 min xs -- | Map a function over a list and concatenate the results. concatMap :: (a -> [b]) -> [a] -> [b] concatMap f = foldr ((++) . f) [] -- | Concatenate a list of lists. concat :: [[a]] -> [a] concat = foldr (++) [] ... ... @@ -450,7 +514,9 @@ concat = foldr (++) [] \begin{code} -- List index (subscript) operator, 0-origin -- | List index (subscript) operator, starting from 0. -- It is an instance of the more general 'Data.List.genericIndex', -- which takes an index of any integral type. (!!) :: [a] -> Int -> a #ifdef USE_REPORT_PRELUDE xs !! n | n < 0 = error "Prelude.!!: negative index" ... ... @@ -512,13 +578,13 @@ E.g. main = print (null (zip nonobviousNil (build undefined))) I'm going to leave it though. zip takes two lists and returns a list of corresponding pairs. If one input list is short, excess elements of the longer list are discarded. zip3 takes three lists and returns a list of triples. Zips for larger tuples are in the List module. Zips for larger tuples are in the List module. \begin{code} ---------------------------------------------- -- | 'zip' takes two lists and returns a list of corresponding pairs. -- If one input list is short, excess elements of the longer list are -- discarded. zip :: [a] -> [b] -> [(a,b)] zip (a:as) (b:bs) = (a,b) : zip as bs zip _ _ = [] ... ... @@ -534,6 +600,8 @@ zipFB c x y r = (x,y) c r \begin{code} ---------------------------------------------- -- | 'zip3' takes three lists and returns a list of triples, analogous to -- 'zip'. zip3 :: [a] -> [b] -> [c] -> [(a,b,c)] -- Specification -- zip3 = zipWith3 (,,) ... ... @@ -544,12 +612,13 @@ zip3 _ _ _ = [] -- The zipWith family generalises the zip family by zipping with the -- function given as the first argument, instead of a tupling function. -- For example, zipWith (+) is applied to two lists to produce the list -- of corresponding sums. \begin{code} ---------------------------------------------- -- | 'zipWith' generalises 'zip' by zipping with the function given -- as the first argument, instead of a tupling function. -- For example, @'zipWith' (+)@ is applied to two lists to produce the -- list of corresponding sums. zipWith :: (a->b->c) -> [a]->[b]->[c] zipWith f (a:as) (b:bs) = f a b : zipWith f as bs zipWith _ _ _ = [] ... ... @@ -564,16 +633,22 @@ zipWithFB c f x y r = (x f y) c r \end{code} \begin{code} -- | The 'zipWith3' function takes a function which combines three -- elements, as well as three lists and returns a list of their point-wise -- combination, analogous to 'zipWith'. zipWith3 :: (a->b->c->d) -> [a]->[b]->[c]->[d] zipWith3 z (a:as) (b:bs) (c:cs) = z a b c : zipWith3 z as bs cs zipWith3 _ _ _ _ = [] -- unzip transforms a list of pairs into a pair of lists. -- | 'unzip' transforms a list of pairs into a list of first components -- and a list of second components. unzip :: [(a,b)] -> ([a],[b]) {-# INLINE unzip #-} unzip = foldr (\(a,b) ~(as,bs) -> (a:as,b:bs)) ([],[]) -- | The 'unzip3' function takes a list of triples and returns three -- lists, analogous to 'unzip'. unzip3 :: [(a,b,c)] -> ([a],[b],[c]) {-# INLINE unzip3 #-} unzip3 = foldr (\(a,b,c) ~(as,bs,cs) -> (a:as,b:bs,c:cs)) ... ...
 ... ... @@ -17,13 +17,25 @@ module Prelude ( -- * Basic data types -- * Standard types, classes and related functions -- ** Basic data types Bool(False, True), (&&), (||), not, otherwise, Maybe(Nothing, Just), maybe, Either(Left, Right), either, Ordering(LT, EQ, GT), Char, String, Int, Integer, Float, Double, IO, Rational, Char, String, IO, -- *** Tuples fst, snd, curry, uncurry, #if defined(__NHC__) []((:), []), -- Not legal Haskell 98; -- ... available through built-in syntax ... ... @@ -35,14 +47,20 @@ module Prelude ( (:), -- Not legal Haskell 98 #endif -- * Basic type classes -- ** Basic type classes Eq((==), (/=)), Ord(compare, (<), (<=), (>=), (>), max, min), Enum(succ, pred, toEnum, fromEnum, enumFrom, enumFromThen, enumFromTo, enumFromThenTo), Bounded(minBound, maxBound), -- * Numeric type classes -- ** Numbers -- *** Numeric types Int, Integer, Float, Double, Rational, -- *** Numeric type classes Num((+), (-), (*), negate, abs, signum, fromInteger), Real(toRational), Integral(quot, rem, div, mod, quotRem, divMod, toInteger), ... ... @@ -54,19 +72,44 @@ module Prelude ( encodeFloat, exponent, significand, scaleFloat, isNaN, isInfinite, isDenormalized, isIEEE, isNegativeZero, atan2), -- *** Numeric functions subtract, even, odd, gcd, lcm, (^), (^^), fromIntegral, realToFrac, -- ** Monads and functors Monad((>>=), (>>), return, fail), Functor(fmap), mapM, mapM_, sequence, sequence_, (=<<), -- ** Miscellaneous functions id, const, (.), flip, ($), until, asTypeOf, error, undefined, seq, ($!), -- * List operations map, (++), filter, concat, map, (++), filter, head, last, tail, init, null, length, (!!), foldl, foldl1, scanl, scanl1, foldr, foldr1, scanr, scanr1, reverse, -- ** Reducing lists (folds) foldl, foldl1, foldr, foldr1, -- *** Special folds and, or, any, all, sum, product, concat, concatMap, maximum, minimum, -- ** Building lists -- *** Scans scanl, scanl1, scanr, scanr1, -- *** Infinite lists iterate, repeat, replicate, cycle, -- ** Sublists take, drop, splitAt, takeWhile, dropWhile, span, break, reverse, and, or, any, all, elem, notElem, lookup, maximum, minimum, concatMap, -- ** Searching lists elem, notElem, lookup, -- ** Zipping and unzipping lists zip, zip3, zipWith, zipWith3, unzip, unzip3, -- ** Functions on strings lines, words, unlines, unwords, sum, product, -- * Converting to and from @String@ ReadS, ShowS, ... ... @@ -92,22 +135,7 @@ module Prelude ( FilePath, readFile, writeFile, appendFile, readIO, readLn, -- ** Exception handling in the I\/O monad IOError, ioError, userError, catch, -- * Monads Monad((>>=), (>>), return, fail), Functor(fmap), mapM, mapM_, sequence, sequence_, (=<<), -- * Miscellaneous functions maybe, either, (&&), (||), not, otherwise, subtract, even, odd, gcd, lcm, (^), (^^), fromIntegral, realToFrac, fst, snd, curry, uncurry, id, const, (.), flip, ($), until, asTypeOf, error, undefined, seq, ($!) IOError, ioError, userError, catch ) where ... ...
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!