@@ -157,7 +157,7 @@ drop Z xs = xs
157drop (S n) [] = []
157drop (S n) [] = []
158drop (S n) (x::xs) = drop n xs
158drop (S n) (x::xs) = drop n xs
160−||| Take the longest prefix of a list such that all elements satsify some
160+||| Take the longest prefix of a list such that all elements satisfy some
161||| Boolean predicate.
161||| Boolean predicate.
163||| @ p the predicate
163||| @ p the predicate
@@ -165,7 +165,7 @@ takeWhile : (p : a -> Bool) -> List a -> List a
165takeWhile p [] = []
165takeWhile p [] = []
166takeWhile p (x::xs) = if p x then x :: takeWhile p xs else []
166takeWhile p (x::xs) = if p x then x :: takeWhile p xs else []
168−||| Remove the longest prefix of a list such that all removed elements satsify some
168+||| Remove the longest prefix of a list such that all removed elements satisfy some
169||| Boolean predicate.
169||| Boolean predicate.
171||| @ p the predicate
171||| @ p the predicate
@@ -340,6 +340,9 @@ reverse = reverse' []
340 reverse' acc (x::xs) = reverse' (x::acc) xs
340 reverse' acc (x::xs) = reverse' (x::acc) xs
342||| Insert some separator between the elements of a list.
342||| Insert some separator between the elements of a list.
344+||| > intersperse ',' (unpack "abcde") == unpack "a,b,c,d,e"
343intersperse : a -> List a -> List a
346intersperse : a -> List a -> List a
344intersperse sep [] = []
347intersperse sep [] = []
345intersperse sep (x::xs) = x :: intersperse' sep xs
348intersperse sep (x::xs) = x :: intersperse' sep xs
@@ -468,6 +471,10 @@ elemIndices = elemIndicesBy (==)
468-- Filters
471-- Filters
469--------------------------------------------------------------------------------
472--------------------------------------------------------------------------------
474+||| filter, applied to a predicate and a list, returns the list of those elements that satisfy the predicate; e.g.,
476+||| > filter (<3) [0..5] == [0,1,2]
471filter : (a -> Bool) -> List a -> List a
478filter : (a -> Bool) -> List a -> List a
472filter p [] = []
479filter p [] = []
473filter p (x::xs) =
480filter p (x::xs) =
@@ -476,6 +483,7 @@ filter p (x::xs) =
477 filter p xs
484 filter p xs
486+||| The nubBy function behaves just like nub, except it uses a user-supplied equality predicate instead of the overloaded == function.
479nubBy : (a -> a -> Bool) -> List a -> List a
487nubBy : (a -> a -> Bool) -> List a -> List a
480nubBy = nubBy' []
488nubBy = nubBy' []
@@ -487,22 +495,40 @@ nubBy = nubBy' []
488 x :: nubBy' (x::acc) p xs
496 x :: nubBy' (x::acc) p xs
498+||| O(n^2). The nub function removes duplicate elements from a list. In particular, it keeps only the first occurrence of each element. It is a special case of nubBy, which allows the programmer to supply their own equality test.
500+||| > nub (the (List _) [1,2,1,3]) == [1,2,3]
490nub : Eq a => List a -> List a
502nub : Eq a => List a -> List a
491nub = nubBy (==)
503nub = nubBy (==)
505+||| The deleteBy function behaves like delete, but takes a user-supplied equality predicate.
493deleteBy : (a -> a -> Bool) -> a -> List a -> List a
506deleteBy : (a -> a -> Bool) -> a -> List a -> List a
494deleteBy _ _ [] = []
507deleteBy _ _ [] = []
495deleteBy eq x (y::ys) = if x `eq` y then ys else y :: deleteBy eq x ys
508deleteBy eq x (y::ys) = if x `eq` y then ys else y :: deleteBy eq x ys
510+||| delete x removes the first occurrence of x from its list argument. For example,
512+||| > delete 'a' (unpack "banana") == unpack "bnana"
514+||| It is a special case of deleteBy, which allows the programmer to supply their own equality test.
497delete : (Eq a) => a -> List a -> List a
515delete : (Eq a) => a -> List a -> List a
498delete = deleteBy (==)
516delete = deleteBy (==)
518+||| The \\ function is list difference (non-associative). In the result of xs \\ ys, the first occurrence of each element of ys in turn (if any) has been removed from xs, e.g.,
520+||| > (([1,2] ++ [2,3]) \\ [1,2]) == [2,3]
500(\\) : (Eq a) => List a -> List a -> List a
522(\\) : (Eq a) => List a -> List a -> List a
501(\\) = foldl (flip delete)
523(\\) = foldl (flip delete)
503unionBy : (a -> a -> Bool) -> List a -> List a -> List a
525unionBy : (a -> a -> Bool) -> List a -> List a -> List a
504unionBy eq xs ys = xs ++ foldl (flip (deleteBy eq)) (nubBy eq ys) xs
526unionBy eq xs ys = xs ++ foldl (flip (deleteBy eq)) (nubBy eq ys) xs
528+||| The union function returns the list union of the two lists. For example,
530+||| > union (unpack "dog") (unpack "cow") == unpack "dogcw"
506union : (Eq a) => List a -> List a -> List a
532union : (Eq a) => List a -> List a -> List a
507union = unionBy (==)
533union = unionBy (==)
@@ -512,6 +538,9 @@ union = unionBy (==)
513||| Given a list and a predicate, returns a pair consisting of the longest
539||| Given a list and a predicate, returns a pair consisting of the longest
514||| prefix of the list that satisfies a predicate and the rest of the list.
540||| prefix of the list that satisfies a predicate and the rest of the list.
542+||| > span (<3) [1,2,3,2,1] == the ((List _, List _)) ([1, 2], [3, 2, 1])
515span : (a -> Bool) -> List a -> (List a, List a)
544span : (a -> Bool) -> List a -> (List a, List a)
516span p [] = ([], [])
545span p [] = ([], [])
517span p (x::xs) =
546span p (x::xs) =
@@ -521,9 +550,18 @@ span p (x::xs) =
522 ([], x::xs)
551 ([], x::xs)
553+||| Given a list and a predicate, returns a pair consisting of the longest
554+||| prefix of the list that does not satisfy a predicate and the rest of the list.
556+||| > break (>=3) [1,2,3,2,1] == the ((List _, List _)) ([1, 2], [3, 2, 1])
524break : (a -> Bool) -> List a -> (List a, List a)
558break : (a -> Bool) -> List a -> (List a, List a)
525break p = span (not . p)
559break p = span (not . p)
561+||| Split on any elements that satisfy the given predicate.
563+||| > split (<2) [2,0,3,1,4] == [[2], [3], [4]]
527split : (a -> Bool) -> List a -> List (List a)
565split : (a -> Bool) -> List a -> List (List a)
528split p xs =
566split p xs =
529 case break p xs of
567 case break p xs of
@@ -538,6 +576,10 @@ split p xs =
538splitAt : (n : Nat) -> (xs : List a) -> (List a, List a)
576splitAt : (n : Nat) -> (xs : List a) -> (List a, List a)
539splitAt n xs = (take n xs, drop n xs)
577splitAt n xs = (take n xs, drop n xs)
579+||| The partition function takes a predicate a list and returns the pair of lists of elements which do and do not satisfy the predicate, respectively; e.g.,
581+||| > partition (<3) [0..5] == (the (List Integer) [0,1,2], the (List Integer) [3,4,5])
541partition : (a -> Bool) -> List a -> (List a, List a)
583partition : (a -> Bool) -> List a -> (List a, List a)
542partition p [] = ([], [])
584partition p [] = ([], [])
543partition p (x::xs) =
585partition p (x::xs) =
@@ -547,19 +589,35 @@ partition p (x::xs) =
548 (lefts, x::rights)
590 (lefts, x::rights)
592+||| The inits function returns all initial segments of the argument, shortest first. For example,
594+||| > inits [1,2,3] == [[],[1],[1,2],[1,2,3]]
550inits : List a -> List (List a)
596inits : List a -> List (List a)
551inits xs = [] :: case xs of
597inits xs = [] :: case xs of
553 x :: xs' => map (x ::) (inits xs')
599 x :: xs' => map (x ::) (inits xs')
601+||| The tails function returns all final segments of the argument, longest first. For example,
603+||| > tails [1,2,3] == [[1,2,3], [2,3], [3], []]
555tails : List a -> List (List a)
605tails : List a -> List (List a)
556tails xs = xs :: case xs of
606tails xs = xs :: case xs of
558 _ :: xs' => tails xs'
608 _ :: xs' => tails xs'
610+||| Split on the given element.
612+||| > splitOn 0 [1,0,2,0,0,3] == [[1],[2],[],[3]]
560splitOn : Eq a => a -> List a -> List (List a)
614splitOn : Eq a => a -> List a -> List (List a)
561splitOn a = split (== a)
615splitOn a = split (== a)
617+||| Replaces all occurences of the first argument with the second argument in a list.
619+||| > replaceOn '-' ',' (unpack "1-2-3") == unpack "1,2,3"
563replaceOn : Eq a => a -> a -> List a -> List a
621replaceOn : Eq a => a -> a -> List a -> List a
564replaceOn a b l = map (\c => if c == a then b else c) l
622replaceOn a b l = map (\c => if c == a then b else c) l
@@ -576,15 +634,22 @@ isPrefixOfBy p (x::xs) (y::ys) =
637+||| The isPrefixOf function takes two lists and returns True iff the first list is a prefix of the second.
579isPrefixOf : Eq a => List a -> List a -> Bool
638isPrefixOf : Eq a => List a -> List a -> Bool
580isPrefixOf = isPrefixOfBy (==)
639isPrefixOf = isPrefixOfBy (==)
582isSuffixOfBy : (a -> a -> Bool) -> List a -> List a -> Bool
641isSuffixOfBy : (a -> a -> Bool) -> List a -> List a -> Bool
583isSuffixOfBy p left right = isPrefixOfBy p (reverse left) (reverse right)
642isSuffixOfBy p left right = isPrefixOfBy p (reverse left) (reverse right)
644+||| The isSuffixOf function takes two lists and returns True iff the first list is a suffix of the second.
585isSuffixOf : Eq a => List a -> List a -> Bool
645isSuffixOf : Eq a => List a -> List a -> Bool
586isSuffixOf = isSuffixOfBy (==)
646isSuffixOf = isSuffixOfBy (==)
648+||| The isInfixOf function takes two lists and returns True iff the first list is contained, wholly and intact, anywhere within the second.
650+||| > isInfixOf "Idris" "I really like Idris." == True
651+||| > isInfixOf "Ial" "I really like Idris." == False
588isInfixOf : Eq a => List a -> List a -> Bool
653isInfixOf : Eq a => List a -> List a -> Bool
589isInfixOf n h = any (isPrefixOf n) (tails h)
654isInfixOf n h = any (isPrefixOf n) (tails h)