|
Data.List.Split.Internals | Portability | unportable (GADTs, Rank2Types) | Stability | experimental | Maintainer | byorgey@gmail.com |
|
|
|
|
|
Description |
Implementation module for Data.List.Split, a combinator library
for splitting lists. See the Data.List.Split documentation for
more description and examples.
|
|
Synopsis |
|
|
|
|
Types and utilities
|
|
|
A splitting strategy.
| Constructors | Splitter | | delimiter :: Delimiter a | What delimiter to split on
| delimPolicy :: DelimPolicy | What to do with delimiters (drop
from output, keep as separate
elements in output, or merge with
previous or following chunks)
| condensePolicy :: CondensePolicy | What to do with multiple
consecutive delimiters
| initBlankPolicy :: EndPolicy | Drop an initial blank?
| finalBlankPolicy :: EndPolicy | Drop a final blank?
|
|
|
|
|
|
The default splitting strategy: keep delimiters in the output
as separate chunks, don't condense multiple consecutive
delimiters into one, keep initial and final blank chunks.
Default delimiter is the constantly false predicate.
Note that defaultSplitter should normally not be used; use
oneOf, onSublist, or whenElt instead, which are the same as
the defaultSplitter with just the delimiter overridden.
The defaultSplitter strategy with any delimiter gives a
maximally information-preserving splitting strategy, in the sense
that (a) taking the concat of the output yields the original
list, and (b) given only the output list, we can reconstruct a
Splitter which would produce the same output list again given
the original input list. This default strategy can be overridden
to allow discarding various sorts of information.
|
|
|
A delimiter can either be a predicate on elements, or a list of
elements to be matched as a subsequence.
| Constructors | |
|
|
|
Try to match a delimiter at the start of a list, either failing
or decomposing the list into the portion which matched the delimiter
and the remainder.
|
|
|
What to do with delimiters?
| Constructors | Drop | Drop delimiters from the output.
| Keep | Keep delimiters as separate chunks
of the output.
| KeepLeft | Keep delimiters in the output,
prepending them to the following
chunk.
| KeepRight | Keep delimiters in the output,
appending them to the previous chunk.
|
|
|
|
|
What to do with multiple consecutive delimiters?
| Constructors | Condense | Condense into a single delimiter.
| KeepBlankFields | Insert blank chunks
between consecutive
delimiters.
|
|
|
|
|
What to do with a blank chunk at either end of the list
(i.e. when the list begins or ends with a delimiter).
| Constructors | |
|
|
|
Tag chunks as delimiters or text.
| Constructors | |
|
|
|
Internal representation of a split list that tracks which pieces
are delimiters and which aren't.
|
|
|
Untag a Chunk.
|
|
|
Test whether a Chunk is a delimiter.
|
|
|
Test whether a Chunk is text.
|
|
build :: (forall b. (a -> b -> b) -> b -> b) -> [a] | Source |
|
Standard build function.
|
|
Implementation
|
|
|
Given a delimiter to use, split a list into an internal
representation with chunks tagged as delimiters or text. This
transformation is lossless; in particular, concatMap fromElem
(splitInternal d l) == l.
|
|
|
Given a split list in the internal tagged representation, produce
a new internal tagged representation corresponding to the final
output, according to the strategy defined by the given
Splitter.
|
|
|
Drop delimiters if the DelimPolicy is Drop.
|
|
|
Condense multiple consecutive delimiters into one if the
CondensePolicy is Condense.
|
|
|
Insert blank chunks between any remaining consecutive delimiters,
and at the beginning or end if the first or last element is a
delimiter.
|
|
|
Insert blank chunks between consecutive delimiters.
|
|
|
Merge delimiters into adjacent chunks according to the DelimPolicy.
|
|
|
Merge delimiters with adjacent chunks to the right (yes, that's
not a typo: the delimiters should end up on the left of the
chunks, so they are merged with chunks to their right).
|
|
|
Merge delimiters with adjacent chunks to the left.
|
|
|
Drop an initial blank chunk according to the given EndPolicy.
|
|
|
Drop a final blank chunk according to the given EndPolicy.
|
|
Combinators
|
|
|
Split a list according to the given splitting strategy. This is
how to "run" a Splitter that has been built using the other
combinators.
|
|
Basic strategies
|
|
All these basic strategies have the same parameters as the
defaultSplitter except for the delimiters.
|
|
|
A splitting strategy that splits on any one of the given
elements. For example:
split (oneOf "xyz") "aazbxyzcxd" == ["aa","z","b","x","","y","","z","c","x","d"]
|
|
|
A splitting strategy that splits on the given list, when it is
encountered as an exact subsequence. For example:
split (onSublist "xyz") "aazbxyzcxd" == ["aazb","xyz","cxd"]
Note that splitting on the empty list is a special case, which
splits just before every element of the list being split. For example:
split (onSublist "") "abc" == ["","","a","","b","","c"]
split (dropDelims . dropBlanks $ onSublist "") "abc" == ["a","b","c"]
However, if you want to break a list into singleton elements like
this, you are better off using splitEvery 1, or better yet,
map (:[]).
|
|
|
A splitting strategy that splits on any elements that satisfy the
given predicate. For example:
split (whenElt (<0)) [2,4,-3,6,-9,1] == [[2,4],[-3],[6],[-9],[1]]
|
|
Strategy transformers
|
|
|
Drop delimiters from the output (the default is to keep
them). For example,
split (oneOf ":") "a:b:c" == ["a", ":", "b", ":", "c"]
split (dropDelims $ oneOf ":") "a:b:c" == ["a", "b", "c"]
|
|
|
Keep delimiters in the output by prepending them to adjacent
chunks. For example:
split (keepDelimsL $ oneOf "xyz") "aazbxyzcxd" == ["aa","zb","x","y","zc","xd"]
|
|
|
Keep delimiters in the output by appending them to adjacent
chunks. For example:
split (keepDelimsR $ oneOf "xyz") "aazbxyzcxd" == ["aaz","bx","y","z","cx","d"]
|
|
|
Condense multiple consecutive delimiters into one. For example:
split (condense $ oneOf "xyz") "aazbxyzcxd" == ["aa","z","b","xyz","c","x","d"]
split (dropDelims $ oneOf "xyz") "aazbxyzcxd" == ["aa","b","","","c","d"]
split (condense . dropDelims $ oneOf "xyz") "aazbxyzcxd" == ["aa","b","c","d"]
|
|
|
Don't generate a blank chunk if there is a delimiter at the
beginning. For example:
split (oneOf ":") ":a:b" == ["",":","a",":","b"]
split (dropInitBlank $ oneOf ":") ":a:b" == [":","a",":","b"]
|
|
|
Don't generate a blank chunk if there is a delimiter at the end.
For example:
split (oneOf ":") "a:b:" == ["a",":","b",":",""]
split (dropFinalBlank $ oneOf ":") "a:b:" == ["a",":","b",":"]
|
|
Derived combinators
|
|
|
Drop all blank chunks from the output. Equivalent to
dropInitBlank . dropFinalBlank . condense. For example:
split (oneOf ":") "::b:::a" == ["",":","",":","b",":","",":","",":","a"]
split (dropBlanks $ oneOf ":") "::b:::a" == ["::","b",":::","a"]
|
|
|
Make a strategy that splits a list into chunks that all start
with the given subsequence (except possibly the first).
Equivalent to dropInitBlank . keepDelimsL . onSublist.
For example:
split (startsWith "app") "applyappicativeapplaudapproachapple" == ["apply","appicative","applaud","approach","apple"]
|
|
|
Make a strategy that splits a list into chunks that all start
with one of the given elements (except possibly the first).
Equivalent to dropInitBlank . keepDelimsL . oneOf. For
example:
split (startsWithOneOf ['A'..'Z']) "ACamelCaseIdentifier" == ["A","Camel","Case","Identifier"]
|
|
|
Make a strategy that splits a list into chunks that all end with
the given subsequence, except possibly the last. Equivalent to
dropFinalBlank . keepDelimsR . onSublist. For example:
split (endsWith "ly") "happilyslowlygnarlylily" == ["happily","slowly","gnarly","lily"]
|
|
|
Make a strategy that splits a list into chunks that all end with
one of the given elements, except possibly the last. Equivalent
to dropFinalBlank . keepDelimsR . oneOf. For example:
split (condense $ endsWithOneOf ".,?! ") "Hi, there! How are you?" == ["Hi, ","there! ","How ","are ","you?"]
|
|
Convenience functions
|
|
splitOneOf :: Eq a => [a] -> [a] -> [[a]] | Source |
|
Split on any of the given elements. Equivalent to split
. dropDelims . oneOf. For example:
splitOneOf ";.," "foo,bar;baz.glurk" == ["foo","bar","baz","glurk"]
|
|
splitOn :: Eq a => [a] -> [a] -> [[a]] | Source |
|
Split on the given sublist. Equivalent to split
. dropDelims . onSublist. For example:
splitOn ".." "a..b...c....d.." == ["a","b",".c","","d",""]
|
|
|
Split on elements satisfying the given predicate. Equivalent to
split . dropDelims . whenElt. For example:
splitWhen (<0) [1,3,-4,5,7,-9,0,2] == [[1,3],[5,7],[0,2]]
|
|
sepBy :: Eq a => [a] -> [a] -> [[a]] | Source |
|
A synonym for splitOn.
|
|
sepByOneOf :: Eq a => [a] -> [a] -> [[a]] | Source |
|
A synonym for splitOneOf.
|
|
endBy :: Eq a => [a] -> [a] -> [[a]] | Source |
|
Split into chunks terminated by the given subsequence.
Equivalent to split . dropFinalBlank . dropDelims
. onSublist. For example:
endBy ";" "foo;bar;baz;" == ["foo","bar","baz"]
Note also that the lines function from Data.List is equivalent
to endBy "\n".
|
|
endByOneOf :: Eq a => [a] -> [a] -> [[a]] | Source |
|
Split into chunks terminated by one of the given elements.
Equivalent to split . dropFinalBlank . dropDelims . oneOf.
|
|
unintercalate :: Eq a => [a] -> [a] -> [[a]] | Source |
|
A synonym for sepBy / splitOn.
Note that this is the right inverse of the intercalate function
from Data.List, that is, intercalate x . unintercalate x
== id. It is also the case that unintercalate x
. intercalate x is idempotent. unintercalate x
. intercalate x is the identity on certain lists, but it is
tricky to state the precise conditions under which this holds.
(For example, it is not enough to say that x does not occur in
any elements of the input list. Working out why is left as an
exercise for the reader.)
|
|
|
Split into words, with word boundaries indicated by the given
predicate. Satisfies words === wordsBy isSpace; equivalent to
split . dropBlanks . dropDelims . whenElt. For example:
wordsBy (=='x') "dogxxxcatxbirdxx" == ["dog","cat","bird"]
|
|
|
Split into lines, with line boundaries indicated by the given
predicate. Satisfies lines === linesBy (=='\n'); equivalent to
split . dropFinalBlank . dropDelims . whenElt. For example:
linesBy (=='x') "dogxxxcatxbirdxx" == ["dog","","","cat","bird",""]
|
|
Other splitting methods
|
|
|
splitEvery n splits a list into length-n pieces. The last
piece will be shorter if n does not evenly divide the length of
the list. If n <= 0, splitEvery n l returns an infinite list
of empty lists.
Note that splitEvery n [] is [], not [[]]. This is
intentional, and is consistent with a recursive definition of
splitEvery; it satisfies the property that
splitEvery n xs ++ splitEvery n ys == splitEvery n (xs ++ ys) whenever n evenly divides the length of xs.
|
|
|
A common synonym for splitEvery.
|
|
|
Split a list into chunks of the given lengths. For example:
splitPlaces [2,3,4] [1..20] == [[1,2],[3,4,5],[6,7,8,9]]
splitPlaces [4,9] [1..10] == [[1,2,3,4],[5,6,7,8,9,10]]
The behavior of splitPlaces ls xs when sum ls /= length xs can
be inferred from the above examples and the fact that splitPlaces
is total.
|
|
Produced by Haddock version 2.6.0 |