-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Combinator library for splitting vectors.
--   
--   This package aims to be a vector-based drop-in replacement for the
--   list-based split package. For more information see the haddocs or
--   checkout the source on github.
@package vector-split
@version 1.0.0.2

module Data.Vector.Split.Internal
split :: Vector v a => Splitter v a -> v a -> [v a]
type Splitter v a = v a -> SplitList v a

-- | Split on the given sublist. Equivalent to split . dropDelims .
--   onSublist. For example:
--   
--   <pre>
--   &gt;&gt;&gt; splitOn (BV.fromList "..") (BV.fromList "a..b...c....d..")
--   ["a","b",".c","","d",""]
--   </pre>
--   
--   In some parsing combinator frameworks this is also known as sepBy.
--   
--   Note that this is the right inverse of the intercalate function from
--   Data.List, that is,
--   
--   <pre>
--   &gt; \xs -&gt; (intercalate xs . splitOn xs) === id
--   </pre>
--   
--   splitOn 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.)
splitOn :: (Vector v a, Eq a) => v a -> v a -> [v a]

-- | Split on any of the given elements. Equivalent to split . dropDelims .
--   oneOf. For example:
--   
--   <pre>
--   &gt;&gt;&gt; splitOneOf (BV.fromList ";.,") (BV.fromList "foo,bar;baz.glurk")
--   ["foo","bar","baz","glurk"]
--   </pre>
splitOneOf :: (Vector v a, Eq a) => v a -> v a -> [v a]

-- | Split on elements satisfying the given predicate. Equivalent to split
--   . dropDelims . whenElt. For example:
--   
--   <pre>
--   &gt;&gt;&gt; splitWhen (&lt;0) (BV.fromList [1,3,-4,5,7,-9,0,2])
--   [[1,3],[5,7],[0,2]]
--   </pre>
splitWhen :: (Vector v a) => (a -> Bool) -> v a -> [v a]

-- | Split into chunks terminated by the given subsequence. Equivalent to
--   split . dropFinalBlank . dropDelims . onSublist. For example:
--   
--   <pre>
--   &gt;&gt;&gt; endBy (BV.fromList ";") (BV.fromList "foo;bar;baz;")
--   ["foo","bar","baz"]
--   </pre>
--   
--   Note also that the lines function from Data.List is equivalent to
--   endBy "n".
endBy :: (Vector v a, Eq a) => v a -> v a -> [v a]

-- | A splitting strategy that splits on any one of the given elements. For
--   example: &gt;&gt;&gt; split (oneOf (BV.fromList "xyz")) (BV.fromList
--   "aazbxyzcxd") ["aa","z","b","x","","y","","z","c","x","d"]
oneOf :: (Vector v a, Eq a) => v a -> Splitter v a

-- | Split into chunks terminated by one of the given elements. Equivalent
--   to split . dropFinalBlank . dropDelims . oneOf. For example:
--   
--   <pre>
--   &gt;&gt;&gt; endByOneOf (BV.fromList ";,") (BV.fromList "foo;bar,baz;")
--   ["foo","bar","baz"]
--   </pre>
endByOneOf :: (Vector v a, Eq a) => v a -> v a -> [v a]

-- | Split into "words", with word boundaries indicated by the given
--   predicate. Satisfies words === wordsBy isSpace; equivalent to split .
--   dropBlanks . dropDelims . whenElt. For example:
--   
--   <pre>
--   &gt;&gt;&gt; wordsBy (=='x') (BV.fromList "dogxxxcatxbirdxx")
--   ["dog","cat","bird"]
--   </pre>
wordsBy :: Vector v a => (a -> Bool) -> v a -> [v a]

-- | Split into "lines", with line boundaries indicated by the given
--   predicate. Satisfies lines === linesBy (=='\n'); equivalent to split .
--   dropFinalBlank . dropDelims . whenElt. For example:
--   
--   <pre>
--   &gt;&gt;&gt; linesBy (=='x') (BV.fromList "dogxxxcatxbirdxx")
--   ["dog","","","cat","bird",""]
--   </pre>
linesBy :: Vector v a => (a -> Bool) -> v a -> [v a]

-- | A splitting strategy that splits on the given list, when it is
--   encountered as an exact subsequence. For example:
--   
--   <pre>
--   &gt;&gt;&gt; split (onSublist (BV.fromList "xyz")) (BV.fromList "aazbxyzcxd")
--   ["aazb","xyz","cxd"]
--   </pre>
--   
--   Note that splitting on the empty list is not allowed in
--   `vector-split`. This is a major difference between <a>split</a> and
--   `vector-split`. In any case nobody should use `vector-split` to do
--   this anyway.
onSublist :: (Vector v a, Eq a) => v a -> Splitter v a

-- | A splitting strategy that splits on any elements that satisfy the
--   given predicate. For example:
--   
--   <pre>
--   &gt;&gt;&gt; split (whenElt (&lt;0)) (BV.fromList [2,4,-3,6,-9,1])
--   [[2,4],[-3],[6],[-9],[1]]
--   </pre>
whenElt :: (Vector v a) => (a -> Bool) -> Splitter v a

-- | Drop delimiters from the output (the default is to keep them). For
--   example,
--   
--   <pre>
--   &gt;&gt;&gt; split (oneOf (BV.fromList ":")) (BV.fromList "a:b:c")
--   ["a",":","b",":","c"]
--   
--   &gt;&gt;&gt; split (dropDelims . oneOf (BV.fromList ":")) (BV.fromList "a:b:c")
--   ["a","b","c"]
--   </pre>
dropDelims :: Vector v a => SplitList v a -> SplitList v a

-- | Keep delimiters in the output by prepending them to adjacent chunks.
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; split (keepDelimsL . oneOf (BV.fromList "xyz")) (BV.fromList "aazbxyzcxd")
--   ["aa","zb","x","y","zc","xd"]
--   </pre>
keepDelimsL :: Vector v a => SplitList v a -> SplitList v a

-- | Keep delimiters in the output by appending them to adjacent chunks.
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; split (keepDelimsR . oneOf (BV.fromList "xyz")) (BV.fromList "aazbxyzcxd")
--   ["aaz","bx","y","z","cx","d"]
--   </pre>
keepDelimsR :: Vector v a => SplitList v a -> SplitList v a

-- | Condense multiple consecutive delimiters into one. For example:
--   
--   <pre>
--   &gt;&gt;&gt; split (condense . oneOf (BV.fromList "xyz")) (BV.fromList "aazbxyzcxd")
--   ["aa","z","b","xyz","c","x","d"]
--   
--   &gt;&gt;&gt; split (dropDelims . oneOf (BV.fromList "xyz")) (BV.fromList "aazbxyzcxd")
--   ["aa","b","","","c","d"]
--   
--   &gt;&gt;&gt; split (condense . dropDelims . oneOf (BV.fromList "xyz")) (BV.fromList "aazbxyzcxd")
--   ["aa","b","c","d"]
--   </pre>
--   
--   FIXME this function is not fully compatible with the Data.List.Split
--   version.
condense :: Vector v a => SplitList v a -> SplitList v a

-- | Don't generate a blank chunk if there is a delimiter at the beginning.
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; split (oneOf (BV.fromList ":")) (BV.fromList ":a:b")
--   ["",":","a",":","b"]
--   
--   &gt;&gt;&gt; split (dropInitBlank . oneOf (BV.fromList ":")) (BV.fromList ":a:b")
--   [":","a",":","b"]
--   </pre>
dropInitBlank :: Vector v a => SplitList v a -> SplitList v a

-- | Don't generate blank chunks between consecutive delimiters. For
--   example:
--   
--   <pre>
--   &gt;&gt;&gt; split (oneOf (BV.fromList ":")) (BV.fromList "::b:::a")
--   ["",":","",":","b",":","",":","",":","a"]
--   
--   &gt;&gt;&gt; split (dropInnerBlanks . oneOf (BV.fromList ":")) (BV.fromList "::b:::a")
--   ["",":",":","b",":",":",":","a"]
--   </pre>
dropInnerBlanks :: Vector v a => SplitList v a -> SplitList v a

-- | Don't generate a blank chunk if there is a delimiter at the end. For
--   example:
--   
--   split (oneOf (BV.fromList ":")) (BV.fromList "a:b:")
--   ["a",":","b",":",""] split (dropFinalBlank . oneOf (BV.fromList ":"))
--   (BV.fromList "a:b:") ["a",":","b",":"]
dropFinalBlank :: Vector v a => SplitList v a -> SplitList v a

-- | Drop all blank chunks from the output, and condense consecutive
--   delimiters into one. Equivalent to dropInitBlank . dropFinalBlank .
--   condense. For example:
--   
--   <pre>
--   &gt;&gt;&gt; split (oneOf (BV.fromList ":")) (BV.fromList "::b:::a")
--   ["",":","",":","b",":","",":","",":","a"]
--   
--   &gt;&gt;&gt; split (dropBlanks . oneOf (BV.fromList ":")) (BV.fromList "::b:::a")
--   ["::","b",":::","a"]
--   </pre>
dropBlanks :: Vector v a => SplitList v a -> SplitList v 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:
--   
--   <pre>
--   &gt;&gt;&gt; split (startsWith (BV.fromList "app")) (BV.fromList "applyapplicativeapplaudapproachapple")
--   ["apply","applicative","applaud","approach","apple"]
--   </pre>
startsWith :: (Vector v a, Eq a) => v a -> Splitter v a

-- | 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:
--   
--   <pre>
--   &gt;&gt;&gt; split (startsWithOneOf (BV.fromList ['A'..'Z'])) (BV.fromList "ACamelCaseIdentifier")
--   ["A","Camel","Case","Identifier"]
--   </pre>
startsWithOneOf :: (Vector v a, Eq a) => v a -> Splitter v a

-- | 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:
--   
--   <pre>
--   &gt;&gt;&gt; split (endsWith (BV.fromList "ly")) (BV.fromList "happilyslowlygnarlylily")
--   ["happily","slowly","gnarly","lily"]
--   </pre>
endsWith :: (Vector v a, Eq a) => v a -> Splitter v a

-- | 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:
--   
--   <pre>
--   &gt;&gt;&gt; split (condense . endsWithOneOf (BV.fromList ".,?! ")) (BV.fromList "Hi, there!  How are you?")
--   ["Hi, ","there!  ","How ","are ","you?"]
--   </pre>
endsWithOneOf :: (Vector v a, Eq a) => v a -> Splitter v a
instance GHC.Classes.Eq (v a) => GHC.Classes.Eq (Data.Vector.Split.Internal.Chunk v a)
instance GHC.Show.Show (v a) => GHC.Show.Show (Data.Vector.Split.Internal.Chunk v a)

module Data.Vector.Split

-- | <tt><a>chunksOf</a> n</tt> splits a vector into length-n pieces. The
--   last piece will be shorter if <tt>n</tt> does not evenly divide the
--   length of the vector. If <tt>n &lt;= 0</tt>, <tt><a>chunksOf</a> n
--   l</tt> returns an infinite list of empty vectors. For example:
--   
--   Note that <tt><a>chunksOf</a> n []</tt> is <tt>[]</tt>, not
--   <tt>[[]]</tt>. This is intentional, and is consistent with a recursive
--   definition of <a>chunksOf</a>; it satisfies the property that
--   
--   <pre>
--   chunksOf n xs ++ chunksOf n ys == chunksOf n (xs ++ ys)
--   </pre>
--   
--   whenever <tt>n</tt> evenly divides the length of <tt>xs</tt>.
chunksOf :: Vector v a => Int -> v a -> [v a]

-- | Split a vector into chunks of the given lengths. For example:
--   
--   <pre>
--   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]]
--   </pre>
--   
--   If the input vector is longer than the total of the given lengths,
--   then the remaining elements are dropped. If the vector 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.
splitPlaces :: Vector v a => [Int] -> v a -> [v a]

-- | Split a vector into chunks of the given lengths. Unlike
--   <a>splitPlaces</a>, the output list will always be the same length as
--   the first input argument. If the input vector is longer than the total
--   of the given lengths, then the remaining elements are dropped. If the
--   vector is shorter than the total of the given lengths, then the last
--   several chunks will be shorter than requested or empty. For example:
--   
--   <pre>
--   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],[]]
--   </pre>
--   
--   Notice the empty list in the output of the third example, which
--   differs from the behavior of <a>splitPlaces</a>.
splitPlacesBlanks :: Vector v a => [Int] -> v a -> [v a]

-- | 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 <tt>chop</tt>:
--   
--   <pre>
--   group :: (Eq a) =&gt; [a] -&gt; [[a]]
--   group = chop (\ xs@(x:_) -&gt; span (==x) xs)
--   
--   words :: String -&gt; [String]
--   words = filter (not . null) . chop (span (not . isSpace) . dropWhile isSpace)
--   </pre>
chop :: Vector v a => (v a -> (b, v a)) -> v a -> [b]

-- | Divides up an input vector into a set of subvectors, according to
--   <tt>n</tt> and <tt>m</tt> input specifications you provide. Each
--   subvector will have <tt>n</tt> items, and the start of each subvector
--   will be offset by <tt>m</tt> items from the previous one.
--   
--   <pre>
--   divvy 5 5 [1..20] == [[1,2,3,4,5],[6,7,8,9,10],[11,12,13,14,15],[16,17,18,19,20]]
--   </pre>
--   
--   In the case where a source vector's trailing elements do no fill an
--   entire subvector, those trailing elements will be dropped.
--   
--   <pre>
--   divvy 5 2 [1..10] == [[1,2,3,4,5],[3,4,5,6,7],[5,6,7,8,9]]
--   </pre>
--   
--   As an example, you can generate a moving average over a vector of
--   prices:
--   
--   <pre>
--   type Prices = [Float]
--   type AveragePrices = [Float]
--   
--   average :: [Float] -&gt; Float
--   average xs = sum xs / (fromIntegral $ length xs)
--   
--   simpleMovingAverage :: Prices -&gt; AveragePrices
--   simpleMovingAverage priceList =
--     map average divvyedPrices
--       where divvyedPrices = divvy 20 1 priceList
--   </pre>
divvy :: Vector v a => Int -> Int -> v a -> [v a]