Data.List.Split.Internals

A splitting strategy.

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 is a list of predicates on elements, matched by some contiguous subsequence of a list.

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?

What to do with multiple 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).

Tag chunks as delimiters or text.

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.

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 (unless the condense policy is DropBlankFields), 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.

Split a list according to the given splitting strategy. This is how to "run" a Splitter that has been built using the other combinators.

Standard build function, specialized to building lists.

Usually build is given the rank-2 type

build :: (forall b. (a -> b -> b) -> b -> b) -> [a]

but since we only use it when (b ~ [a]), we give it the more restricted type signature in order to avoid needing a non-Haskell2010 extension.

Note that the 0.1.4.3 release of this package did away with a custom build implementation in favor of importing one from GHC.Exts, which was (reportedly) faster for some applications. However, in the interest of simplicity and complete Haskell2010 compliance as split is being included in the Haskel Platform, version 0.2.1.0 has gone back to defining build manually. This is in line with split's design philosophy of having efficiency as a non-goal.

chunksOf 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, chunksOf n l returns an infinite list of empty lists.

>>> chunksOf 3 [1..12][[1,2,3],[4,5,6],[7,8,9],[10,11,12]]

>>> chunksOf 3 "Hello there"["Hel","lo ","the","re"]

>>> chunksOf 3 ([] :: [Int])[]

Note that chunksOf n [] is [], not [[]]. This is intentional, and satisfies the property that

chunksOf n xs ++ chunksOf n ys == chunksOf n (xs ++ ys)

whenever n evenly divides the length of xs.

Split a list into chunks of the given lengths.

>>> 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]]

>>> splitPlaces [4,9,3] [1..10][[1,2,3,4],[5,6,7,8,9,10]]

If the input list is longer than the total of the given lengths, then the remaining elements are dropped. If the list is shorter than the total of the given lengths, then the result may contain fewer chunks than requested, and the last chunk may be shorter than requested.

Split a list into chunks of the given lengths. Unlike splitPlaces, the output list will always be the same length as the first input argument. If the input list is longer than the total of the given lengths, then the remaining elements are dropped. If the list is shorter than the total of the given lengths, then the last several chunks will be shorter than requested or empty.

>>> splitPlacesBlanks [2,3,4] [1..20][[1,2],[3,4,5],[6,7,8,9]]

>>> splitPlacesBlanks [4,9] [1..10][[1,2,3,4],[5,6,7,8,9,10]]

>>> splitPlacesBlanks [4,9,3] [1..10][[1,2,3,4],[5,6,7,8,9,10],[]]

Notice the empty list in the output of the third example, which differs from the behavior of splitPlaces.

A useful recursion pattern for processing a list to produce a new list, often used for "chopping" up the input list. Typically chop is called with some function that will consume an initial prefix of the list and produce a value and the rest of the list.

For example, many common Prelude functions can be implemented in terms of chop:

group :: (Eq a) => [a] -> [[a]]
group = chop (\ xs@(x:_) -> span (==x) xs)

words :: String -> [String]
words = filter (not . null) . chop (break isSpace . dropWhile isSpace)

Divides up an input list into a set of sublists, according to n and m input specifications you provide. Each sublist will have n items, and the start of each sublist will be offset by m items from the previous one.

>>> divvy 5 5 [1..15][[1,2,3,4,5],[6,7,8,9,10],[11,12,13,14,15]]

>>> divvy 5 2 [1..15][[1,2,3,4,5],[3,4,5,6,7],[5,6,7,8,9],[7,8,9,10,11],[9,10,11,12,13],[11,12,13,14,15]]

In the case where a source list's trailing elements do no fill an entire sublist, those trailing elements will be dropped.

>>> divvy 5 2 [1..10][[1,2,3,4,5],[3,4,5,6,7],[5,6,7,8,9]]

As an example, you can generate a moving average over a list of prices:

type Prices = [Float]
type AveragePrices = [Float]

average :: [Float] -> Float
average xs = sum xs / (fromIntegral $ length xs)

simpleMovingAverage :: Prices -> AveragePrices
simpleMovingAverage = map average . divvy 20 1