| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

This module provides various helpful utilities for dealing with lists. Written by John Goerzen, jgoerzen@complete.org | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Synopsis | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Merging | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

merge :: Ord a => [a] -> [a] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Merge two sorted lists into a single, sorted whole. Example: merge [1,3,5] [1,2,4,6] -> [1,1,2,3,4,5,6] QuickCheck test property: prop_merge xs ys = merge (sort xs) (sort ys) == sort (xs ++ ys) where types = xs :: [Int] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Merge two sorted lists using into a single, sorted whole, allowing the programmer to specify the comparison function. QuickCheck test property: prop_mergeBy xs ys = mergeBy cmp (sortBy cmp xs) (sortBy cmp ys) == sortBy cmp (xs ++ ys) where types = xs :: [ (Int, Int) ] cmp (x1,_) (x2,_) = compare x1 x2 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Tests | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

startswith :: Eq a => [a] -> [a] -> Bool | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Returns true if the given list starts with the specified elements; false otherwise. (This is an alias for Data.List.isPrefixOf.) Example: startswith "He" "Hello" -> True | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

endswith :: Eq a => [a] -> [a] -> Bool | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Returns true if the given list ends with the specified elements; false otherwise. (This is an alias for Data.List.isSuffixOf.) Example: endswith "lo" "Hello" -> True | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

contains :: Eq a => [a] -> [a] -> Bool | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Returns true if the given parameter is a sublist of the given list; false otherwise. Example: contains "Haskell" "I really like Haskell." -> True contains "Haskell" "OCaml is great." -> False | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

hasAny | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Association List Utilities | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

These functions are designed to augment the association list functions in Data.List and provide an interface similar to Data.FiniteMap or Data.Map for association lists. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

addToAL :: Eq key => [(key, elt)] -> key -> elt -> [(key, elt)] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Adds the specified (key, value) pair to the given list, removing any existing pair with the same key already present. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

delFromAL :: Eq key => [(key, a)] -> key -> [(key, a)] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Removes all (key, value) pairs from the given list where the key matches the given one. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

flipAL :: (Eq key, Eq val) => [(key, val)] -> [(val, [key])] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Flips an association list. Converts (key1, val), (key2, val) pairs to (val, [key1, key2]). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

keysAL :: [(key, a)] -> [key] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Returns the keys that comprise the (key, value) pairs of the given AL. Same as: map fst | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

valuesAL :: [(a, value)] -> [value] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Returns the values the comprise the (key, value) pairs of the given AL. Same as: map snd | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

hasKeyAL :: Eq a => a -> [(a, b)] -> Bool | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Indicates whether or not the given key is in the AL. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Association List Conversions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

strFromAL :: (Show a, Show b) => [(a, b)] -> String | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Converts an association list to a string. The string will have one pair per line, with the key and value both represented as a Haskell string. This function is designed to work with [(String, String)] association lists, but may work with other types as well. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

strToAL :: (Read a, Read b) => String -> [(a, b)] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

The inverse of Like | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Conversions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

split :: Eq a => [a] -> [a] -> [[a]] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Given a delimiter and a list (or string), split into components. Example: split "," "foo,bar,,baz," -> ["foo", "bar", "", "baz", ""] split "ba" ",foo,bar,,baz," -> [",foo,","r,,","z,"] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

join :: [a] -> [[a]] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Given a delimiter and a list of items (or strings), join the items by using the delimiter. Example: join "|" ["foo", "bar", "baz"] -> "foo|bar|baz" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

replace :: Eq a => [a] -> [a] -> [a] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Given a list and a replacement list, replaces each occurance of the search list with the replacement list in the operation list. Example: replace "," "." "127,0,0,1" -> "127.0.0.1" This could logically be thought of as: replace old new l = join new . split old $ l | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

genericJoin :: Show a => String -> [a] -> String | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Like Examples: genericJoin ", " [1, 2, 3, 4] -> "1, 2, 3, 4" genericJoin "|" ["foo", "bar", "baz"] -> "\"foo\"|\"bar\"|\"baz\"" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

takeWhileList :: ([a] -> Bool) -> [a] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Similar to Data.List.takeWhile, takes elements while the func is true. The function is given the remainder of the list to examine. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

dropWhileList :: ([a] -> Bool) -> [a] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Similar to Data.List.dropWhile, drops elements while the func is true. The function is given the remainder of the list to examine. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

spanList :: ([a] -> Bool) -> [a] -> ([a], [a]) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Similar to Data.List.span, but performs the test on the entire remaining list instead of just one element.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

breakList :: ([a] -> Bool) -> [a] -> ([a], [a]) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Similar to Data.List.break, but performs the test on the entire remaining list instead of just one element. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Advanced Conversions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

newtype WholeFunc a b | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

wholeMap :: WholeFunc a b -> [a] -> [b] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

This is an enhanced version of the concatMap or map functions in Data.List. Unlike those functions, this one: - Can consume a varying number of elements from the input list during each iteration
- Can arbitrarily decide when to stop processing data
- Can return a varying number of elements to insert into the output list
- Can actually switch processing functions mid-stream
- Is not even restricted to processing the input list intact
The function used by wholeMap, of type Processing stops when the remaining input list is empty. An example
of a | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

fixedWidth :: [Int] -> WholeFunc a [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

A parser designed to process fixed-width input fields. Use it with
The Int list passed to this function is the list of the field widths desired from the input. The result is a list of those widths, if possible. If any of the input remains after processing this list, it is added on as the final element in the result list. If the input is less than the sum of the requested widths, then the result list will be short the appropriate number of elements, and its final element may be shorter than requested. Examples: wholeMap (fixedWidth [1, 2, 3]) "1234567890" --> ["1","23","456","7890"] wholeMap (fixedWidth (repeat 2)) "123456789" --> ["12","34","56","78","9"] wholeMap (fixedWidth []) "123456789" --> ["123456789"] wholeMap (fixedWidth [5, 3, 6, 1]) "Hello, This is a test." --> ["Hello",", T","his is"," ","a test."] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Fixed-Width and State Monad Utilities | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

grab :: Int -> State [a] [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Helps you pick out fixed-width components from a list. Example: conv :: String -> (String,String) conv = runState $ do f3 <- grab 3 n2 <- grab 2 return $ f3 ++ "," ++ n2 main = print $ conv "TestIng" Prints: ("Tes,tI","ng") | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Miscellaneous | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

countElem :: Eq a => a -> [a] -> Int | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Returns a count of the number of times the given element occured in the given list. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

elemRIndex :: Eq a => a -> [a] -> Maybe Int | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Returns the rightmost index of the given element in the given list. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

alwaysElemRIndex :: Eq a => a -> [a] -> Int | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Like elemRIndex, but returns -1 if there is nothing found. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

seqList :: [a] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Forces the evaluation of the entire list. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

subIndex :: Eq a => [a] -> [a] -> Maybe Int | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Similar to Data.List.elemIndex. Instead of looking for one element in a list, this function looks for the first occurance of a sublist in the list, and returns the index of the first element of that occurance. If there is no such list, returns Nothing. If the list to look for is the empty list, will return Just 0 regardless of the content of the list to search. Examples: subIndex "foo" "asdfoobar" -> Just 3 subIndex "foo" [] -> Nothing subIndex "" [] -> Just 0 subIndex "" "asdf" -> Just 0 subIndex "test" "asdftestbartest" -> Just 4 subIndex [(1::Int), 2] [0, 5, 3, 2, 1, 2, 4] -> Just 4 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

uniq :: Eq a => [a] -> [a] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Given a list, returns a new list with all duplicate elements removed. For example: uniq "Mississippi" -> "Misp" You should not rely on this function necessarily preserving order, though the current implementation happens to. This function is not compatible with infinite lists. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Produced by Haddock version 0.8 |