Typeclass for box and unboxed vectors, which are created by slicing arrays.

Instead of providing a generalized vector with polymorphric array field, we use this typeclass so that instances use concrete array type can unpack their array payload.

Vector types, e.g. Vector,PrimVector... are obivious instances, with O(1) toArr and fromArr, which convert slices to (array, offset, length) tuple back and forth.

Array types can also be instances of this class, e.g. Array, PrimArray..., in this case toArr will always return offset 0 and whole array length, and fromArr is O(n) copyArr.

Change vector types based on same array type, e.g. construct an array from a slice, or vice-versa.

O(1) Index vector's element.

Return Nothing if index is out of bounds.

O(1) Index array element.

Throw IndexOutOfVectorRange if index outside of the vector.

O(1) Index array element.

Throw IndexOutOfVectorRange if index outside of the vector.

O(n) Modify vector's element under given index.

Throw IndexOutOfVectorRange if index outside of the vector.

O(n) Modify vector's element under given index.

Return original vector if index outside of the vector.

O(n) insert element to vector under given index.

Throw IndexOutOfVectorRange if index outside of the vector.

O(n) insert element to vector under given index.

Return original vector if index outside of the vector.

O(n) Delete vector's element under given index.

Throw IndexOutOfVectorRange if index outside of the vector.

O(n) Delete vector's element under given index.

Return original vector if index outside of the vector.

Boxed vector

Primitive vector

Bytes is just primitive word8 vectors.

O(n), pack an ASCII String, multi-bytes char WILL BE CHOPPED!

O(1). The empty vector.

O(1). Single element vector.

O(n). Copy a vector from slice.

O(n) Convert a list into a vector

Alias for packN defaultInitSize.

O(n) Convert a list into a vector with an approximate size.

If the list's length is large than the size given, we simply double the buffer size and continue building.

This function is a good consumer in the sense of build/foldr fusion.

O(n) Convert a list into a vector with given size.

If the list's length is large than the size given, we drop the rest elements.

This function is a good consumer in the sense of build/foldr fusion.

O(n) Alias for packRN defaultInitSize.

O(n) packN in reverse order.

This function is a good consumer in the sense of build/foldr fusion.

O(n) packN' in reverse order.

>>> packRN' 3 [1,2,3,4,5]
>>> [3,2,1]

This function is a good consumer in the sense of build/foldr fusion.

O(n) Convert vector to a list.

Unpacking is done lazily. i.e. we will retain reference to the array until all element are consumed.

This function is a good producer in the sense of build/foldr fusion.

O(n) Convert vector to a list in reverse order.

This function is a good producer in the sense of build/foldr fusion.

O(1) Test whether a vector is empty.

O(1) The length of a vector.

O(m+n)

There's no need to guard empty vector because we guard them for you, so appending empty vectors are no-ops.

Mapping between vectors (possiblely with two different vector types).

NOTE, the result vector contain thunks in lifted Vector case, use map' if that's not desired.

For PrimVector, map and map' are same, since PrimVectors never store thunks.

Mapping between vectors (possiblely with two different vector types).

This is the strict version map. Note that the Functor instance of lifted Vector is defined with map to statisfy laws, which this strict version breaks (map' id arrayContainsBottom /= arrayContainsBottom ).

Strict mapping with index.

Traverse vector and gather result in another vector.

There're rules to optimize the intermedia list away when f is an instance of PrimMoand, such as IO, ST or Parser.

Traverse vector and gather result in another vector.

Traverse vector without gathering result.

Traverse vector with index.

Strict left to right fold.

Strict left to right fold with index.

Strict left to right fold using first element as the initial value.

Throw EmptyVector if vector is empty.

Strict left to right fold using first element as the initial value. return Nothing when vector is empty.

Strict right to left fold

Strict right to left fold with index

NOTE: the index is counting from 0, not backwards

Strict right to left fold using last element as the initial value.

Throw EmptyVector if vector is empty.

Strict right to left fold using last element as the initial value, return Nothing when vector is empty.

O(n) Concatenate a list of vector.

Note: concat have to force the entire list to filter out empty vector and calculate the length for allocation.

Map a function over a vector and concatenate the results

O(n) maximum returns the maximum value from a vector

It's defined with foldl1', an EmptyVector exception will be thrown in the case of an empty vector.

O(n) minimum returns the minimum value from a vector

An EmptyVector exception will be thrown in the case of an empty vector.

O(n) maximum returns the maximum value from a vector, return Nothing in the case of an empty vector.

O(n) minimum returns the minimum value from a vector, return Nothing in the case of an empty vector.

O(n) sum returns the sum value from a vector

O(n) count returns count of an element from a vector

O(n) product returns the product value from a vector

O(n) product returns the product value from a vector

This function will shortcut on zero. Note this behavior change the semantics for lifted vector: product [1,0,undefined] /= product' [1,0,undefined].

O(n) Applied to a predicate and a vector, all determines if all elements of the vector satisfy the predicate.

O(n) Applied to a predicate and a vector, any determines if any elements of the vector satisfy the predicate.

The mapAccumL function behaves like a combination of map and foldl; it applies a function to each element of a vector, passing an accumulating parameter from left to right, and returning a final value of this accumulator together with the new list.

Note, this function will only force the result tuple, not the elements inside, to prevent creating thunks during mapAccumL, seq your accumulator and result with the result tuple.

The mapAccumR function behaves like a combination of map and foldr; it applies a function to each element of a vector, passing an accumulating parameter from right to left, and returning a final value of this accumulator together with the new vector.

The same strictness property with mapAccumL applys to mapAccumR too.

O(n) replicate n x is a vector of length n with x the value of every element.

Note: replicate will not force the element in boxed vector case.

A version of replicateM which works on Vec, with specialized rules under PrimMonad.

There're rules to optimize the intermedia list away when m is an instance of PrimMoand, such as IO, ST or Parser.

O(n*m) cycleN a vector n times.

O(n), where n is the length of the result. The unfoldr function is analogous to the List 'unfoldr'. unfoldr builds a vector from a seed value. The function takes the element and returns Nothing if it is done producing the vector or returns Just (a,b), in which case, a is the next byte in the string, and b is the seed value for further production.

Examples:

   unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
== pack [0, 1, 2, 3, 4, 5]

O(n) Like unfoldr, unfoldrN builds a vector from a seed value. However, the length of the result is limited by the first argument to unfoldrN. This function is more efficient than unfoldr when the maximum length of the result is known.

The following equation relates unfoldrN and unfoldr:

fst (unfoldrN n f s) == take n (unfoldr f s)

O(n) cons is analogous to (:) for lists, but of different complexity, as it requires making a copy.

O(n) Append a byte to the end of a vector

O(1) Extract the head and tail of a vector, return Nothing if it is empty.

O(1) Extract the init and last of a vector, return Nothing if vector is empty.

O(1) Extract the first element of a vector.

O(1) Extract the elements after the head of a vector.

NOTE: tailMayEmpty return empty vector in the case of an empty vector.

O(1) Extract the last element of a vector.

O(1) Extract the elements before of the last one.

NOTE: initMayEmpty return empty vector in the case of an empty vector.

O(1) Extract the first element of a vector.

Throw EmptyVector if vector is empty.

O(1) Extract the elements after the head of a vector.

Throw EmptyVector if vector is empty.

O(1) Extract the last element of a vector.

Throw EmptyVector if vector is empty.

O(1) Extract the elements before of the last one.

Throw EmptyVector if vector is empty.

O(n) Return all initial segments of the given vector, empty first.

O(n) Return all final segments of the given vector, whole vector first.

O(1) take n, applied to a vector xs, returns the prefix of xs of length n, or xs itself if n > length xs.

O(1) drop n xs returns the suffix of xs after the first n elements, or [] if n > length xs.

O(1) takeR n, applied to a vector xs, returns the suffix of xs of length n, or xs itself if n > length xs.

O(1) dropR n xs returns the prefix of xs before the last n elements, or [] if n > length xs.

O(1) Extract a sub-range vector with give start index and length.

This function is a total function just like 'takedrop', indexlength exceeds range will be ingored, e.g.

slice 1 3 "hello"   == "ell"
slice -1 -1 "hello" == ""
slice -2 2 "hello"  == ""
slice 2 10 "hello"  == "llo"

This holds for all x y: slice x y vs == drop x . take (x+y) vs

O(1) splitAt n xs is equivalent to (take n xs, drop n xs).

O(n) Applied to a predicate p and a vector vs, returns the longest prefix (possibly empty) of vs of elements that satisfy p.

O(n) Applied to a predicate p and a vector vs, returns the longest suffix (possibly empty) of vs of elements that satisfy p.

O(n) Applied to a predicate p and a vector vs, returns the suffix (possibly empty) remaining after takeWhile p vs.

O(n) Applied to a predicate p and a vector vs, returns the prefix (possibly empty) remaining before takeWhileR p vs.

O(n) dropAround f = dropWhile f . dropWhileR f

O(n) Split the vector into the longest prefix of elements that do not satisfy the predicate and the rest without copying.

break (==x) will be rewritten using a memchr.

O(n) Split the vector into the longest prefix of elements that satisfy the predicate and the rest without copying.

span (/=x) will be rewritten using a memchr.

breakR behaves like break but from the end of the vector.

breakR p == spanR (not.p)

spanR behaves like span but from the end of the vector.

Break a vector on a subvector, returning a pair of the part of the vector prior to the match, and the rest of the vector, e.g.

break "wor" "hello, world" = ("hello, ", "world")

O(n) The stripPrefix function takes two vectors and returns Just the remainder of the second iff the first is its prefix, and otherwise Nothing.

O(n) The stripSuffix function takes two vectors and returns Just the remainder of the second iff the first is its suffix, and otherwise Nothing.

O(n) Break a vector into pieces separated by the delimiter element consuming the delimiter. I.e.

split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
split 'a'  "aXaXaXa"    == ["","X","X","X",""]
split 'x'  "x"          == ["",""]

and

intercalate [c] . split c == id
split == splitWith . (==)

NOTE, this function behavior different with bytestring's. see #56.

O(n) Splits a vector into components delimited by separators, where the predicate returns True for a separator element. The resulting components do not contain the separators. Two adjacent separators result in an empty component in the output. eg.

splitWith (=='a') "aabbaca" == ["","","bb","c",""]
splitWith (=='a') []        == [""]

NOTE, this function behavior different with bytestring's. see #56.

O(m+n) Break haystack into pieces separated by needle.

Note: An empty needle will essentially split haystack element by element.

Examples:

>>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"
["a","b","d","e"]

>>> splitOn "aaa"  "aaaXaaaXaaaXaaa"
["","X","X","X",""]

>>> splitOn "x"  "x"
["",""]

and

intercalate s . splitOn s         == id
splitOn (singleton c)             == split (==c)

The isPrefix function returns True if the first argument is a prefix of the second.

O(n) The isSuffixOf function takes two vectors and returns True if the first is a suffix of the second.

Check whether one vector is a subvector of another.

needle isInfixOf haystack === null haystack || indices needle haystake /= [].

O(n) Find the longest non-empty common prefix of two strings and return it, along with the suffixes of each string at which they no longer match. e.g.

>>> commonPrefix "foobar" "fooquux"
("foo","bar","quux")

>>> commonPrefix "veeble" "fetzer"
("","veeble","fetzer")

O(n) Breaks a Bytes up into a list of words, delimited by ascii space.

O(n) Breaks a Bytes up into a list of lines, delimited by ascii n, The resulting strings do not contain newlines.

Note that it does not regard CR ('\r') as a newline character.

O(n) Joins words with ascii space.

O(n) Joins lines with ascii n.

NOTE: This functions is different from unlines, it DOES NOT add a trailing n.

Add padding to the left so that the whole vector's length is at least n.

Add padding to the right so that the whole vector's length is at least n.

O(n) reverse vs efficiently returns the elements of xs in reverse order.

O(n) The intersperse function takes an element and a vector and `intersperses' that element between the elements of the vector. It is analogous to the intersperse function on Lists.

O(n) The intercalate function takes a vector and a list of vectors and concatenates the list after interspersing the first argument between each element of the list.

Note: intercalate will force the entire vector list.

O(n) An efficient way to join vector with an element.

The transpose function transposes the rows and columns of its vector argument.

zipWith' zip two vector with a zipping function.

For example, zipWith (+) is applied to two vector to produce a vector of corresponding sums, the result will be evaluated strictly.

unzipWith' disassemble a vector with a disassembling function,

The results inside tuple will be evaluated strictly.

scanl' is similar to foldl, but returns a list of successive reduced values from the left.

scanl' f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]

Note that

lastM (scanl' f z xs) == Just (foldl f z xs).

'scanl1'' is a variant of scanl that has no starting value argument.

scanl1' f [x1, x2, ...] == [x1, x1 `f` x2, ...]
scanl1' f [] == []

scanr' is the right-to-left dual of scanl'.

scanr1' is a variant of scanr that has no starting value argument.

O(n) elem test if given element is in given vector.

O(n) 'not . elem'

O(n) The elemIndex function returns the index of the first element in the given vector which is equal to the query element, or Nothing if there is no such element.

O(n) find the first index and element matching the predicate in a vector from left to right, if there isn't one, return (length of the vector, Nothing).

O(n) Find the first index and element matching the predicate in a vector from right to left, if there isn't one, return '(-1, Nothing)'.

The findIndex function takes a predicate and a vector and returns the index of the first element in the vector satisfying the predicate.

O(n) The elemIndices function extends elemIndex, by returning the indices of all elements equal to the query element, in ascending order.

O(n) filter, applied to a predicate and a vector, returns a vector containing those elements that satisfy the predicate.

O(n) The partition function takes a predicate, a vector, returns a pair of vector with elements which do and do not satisfy the predicate, respectively; i.e.,

partition p vs == (filter p vs, filter (not . p) vs)

O(n+m) Find the offsets of all indices (possibly overlapping) of needle within haystack using KMP algorithm.

The KMP algorithm need pre-calculate a shift table in O(m) time and space, the worst case time complexity is O(n+m). Partial apply this function to reuse pre-calculated table between same needles.

Chunked input are support via partial match argument, if set we will return an extra negative index in case of partial match at the end of input chunk, e.g.

indicesOverlapping [ascii|ada|]  [ascii|adadad|] True == [0,2,-2]

Where -2 is the length of the partial match part ad 's negation.

If an empty pattern is supplied, we will return every possible index of haystack, e.g.

indicesOverlapping "" "abc" = [0,1,2]

References:

• Knuth, Donald; Morris, James H.; Pratt, Vaughan: "Fast pattern matching in strings" (1977)
• http://www-igm.univ-mlv.fr/~lecroq/string/node8.html#SECTION0080

O(n+m) Find the offsets of all non-overlapping indices of needle within haystack using KMP algorithm.

If an empty pattern is supplied, we will return every possible index of haystack, e.g.

indicesOverlapping "" "abc" = [0,1,2]

O(n*log(n)) Sort vector based on element's Ord instance with classic mergesort algorithm.

This is a stable sort, During sorting two O(n) worker arrays are needed, one of them will be freezed into the result vector. The merge sort only begin at tile size larger than mergeTileSize, each tile will be sorted with insertSort, then iteratively merged into larger array, until all elements are sorted.

The mergesort tile size, mergeTileSize = 8.

O(n^2) Sort vector based on element's Ord instance with simple insertion-sort algorithm.

This is a stable sort. O(n) extra space are needed, which will be freezed into result vector.

The Down type allows you to reverse sort order conveniently. A value of type Down a contains a value of type a (represented as Down a). If a has an Ord instance associated with it then comparing two values thus wrapped will give you the opposite of their normal sort order. This is particularly useful when sorting in generalised list comprehensions, as in: then sortWith by Down x

Since: base-4.6.0.0

O(n) Sort vector based on element's Radix instance with radix-sort, (Least significant digit radix sorts variation).

This is a stable sort, one or two extra O(n) worker array are need depend on how many passes shall be performed, and a bucketSize counting bucket are also needed. This sort algorithms performed extremly well on small byte size types such as Int8 or Word8, while on larger type, constant passes may render this algorithm not suitable for small vectors (turning point around 2^(2*passes)).

Types contain radixs, which can be inspected with radix during different passes.

The default instances share a same bucketSize 256, which seems to be a good default.

Similar to Down newtype for Ord, this newtype can inverse the order of a Radix instance when used in radixSort.

Pair type to help GHC unpack in some loops, useful when write fast folds.