Manipulate ByteStrings using Char operations. All Chars will be truncated to 8 bits. It can be expected that these functions will run at identical speeds to their Word8 equivalents in Data.ByteString.

More specifically these byte strings are taken to be in the subset of Unicode covered by code points 0-255. This covers Unicode Basic Latin, Latin-1 Supplement and C0+C1 Controls.

See:

• http://www.unicode.org/charts/
• http://www.unicode.org/charts/PDF/U0000.pdf
• http://www.unicode.org/charts/PDF/U0080.pdf

This module is intended to be imported qualified, to avoid name clashes with Prelude functions. eg.

 import qualified Data.ByteString.Char8 as B

O(n) Convert a String into a ByteString

For applications with large numbers of string literals, pack can be a bottleneck. In such cases, consider using packAddress (GHC only).

O(n) replicate n x is a ByteString of length n with x the value of every element. The following holds:

 replicate w c = unfoldr w (\u -> Just (u,u)) c

This implemenation uses memset(3)

O(n) The unfoldrN function is analogous to the List 'unfoldr'. unfoldrN builds a ByteString from a seed value. The function takes the element and returns Nothing if it is done producing the ByteString or returns Just (a,b), in which case, a is a prepending to the ByteString and b is used as the next element in a recursive call.

To preven unfoldrN having O(n^2) complexity (as prepending a character to a ByteString is O(n), this unfoldr requires a maximum final size of the ByteString as an argument. cons can then be implemented in O(1) (i.e. a poke), and the unfoldr itself has linear complexity. The depth of the recursion is limited to this size, but may be less. For lazy, infinite unfoldr, use unfoldr (from List).

Examples:

 unfoldrN 10 (\x -> Just (x, chr (ord x + 1))) '0' == "0123456789"

The following equation connects the depth-limited unfoldr to the List unfoldr:

 unfoldrN n == take n $ List.unfoldr

spanEnd behaves like span but from the end of the ByteString. We have

 spanEnd (not.isSpace) "x y z" == ("x y ","z")

and

 spanEnd (not . isSpace) ps
    == 
 let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x) 

breakChar breaks its ByteString argument at the first occurence of the specified Char. It is more efficient than break as it is implemented with memchr(3). I.e.

 break (=='c') "abcd" == breakChar 'c' "abcd"

spanChar breaks its ByteString argument at the first occurence of a Char other than its argument. It is more efficient than 'span (==)'

 span  (=='c') "abcd" == spanByte 'c' "abcd"

O(n) breakFirst breaks the given ByteString on the first occurence of w. It behaves like break, except the delimiter is not returned, and Nothing is returned if the delimiter is not in the ByteString. I.e.

 breakFirst 'b' "aabbcc" == Just ("aa","bcc")

 breakFirst c xs ==
 let (x,y) = break (== c) xs 
 in if null y then Nothing else Just (x, drop 1 y))

O(n) breakLast behaves like breakFirst, but from the end of the ByteString.

 breakLast ('b') (pack "aabbcc") == Just ("aab","cc")

and the following are equivalent:

 breakLast 'c' "abcdef"
 let (x,y) = break (=='c') (reverse "abcdef") 
 in if null x then Nothing else Just (reverse (drop 1 y), reverse x)

breakSpace returns the pair of ByteStrings when the argument is broken at the first whitespace byte. I.e.

 break isSpace == breakSpace

dropSpace efficiently returns the ByteString argument with white space Chars removed from the front. It is more efficient than calling dropWhile for removing whitespace. I.e.

 dropWhile isSpace == dropSpace

dropSpaceEnd efficiently returns the ByteString argument with white space removed from the end. I.e.

 reverse . (dropWhile isSpace) . reverse == dropSpaceEnd

but it is more efficient than using multiple reverses.

O(n) Break a ByteString into pieces separated by the byte argument, 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

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

As for all splitting functions in this library, this function does not copy the substrings, it just constructs new ByteStrings that are slices of the original.

O(n) Splits a ByteString 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",""]

Like splitWith, except that sequences of adjacent separators are treated as a single separator. eg.

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

The group function takes a ByteString and returns a list of ByteStrings such that the concatenation of the result is equal to the argument. Moreover, each sublist in the result contains only equal elements. For example,

 group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]

It is a special case of groupBy, which allows the programmer to supply their own equality test. It is about 40% faster than groupBy (==)

words breaks a ByteString up into a list of words, which were delimited by Chars representing white space. And

 tokens isSpace = words

lines behaves like lines, in that it breaks a ByteString on newline Chars. However, unlike the Prelude functions, lines and unlines correctly reconstruct lines that are missing terminating newlines characters. I.e.

 unlines  (lines "a\nb\nc")  == "a\nb\nc\n"
 unlines' (lines' "a\nb\nc") == "a\nb\nc"

Note that this means:

 lines  "a\nb\nc\n" == ["a","b","c"]
 lines' "a\nb\nc\n" == ["a","b","c",""]

words behaves like words, with the exception that it produces output on ByteStrings with trailing whitespace that can be correctly inverted by unwords. I.e.

 words  "a b c " == ["a","b","c"]
 words' "a b c " == ["a","b","c",""]

 unwords $ words  "a b c " == "a b c"
 unwords $ words' "a b c " == "a b c "

O(n) Indicies of newlines. Shorthand for

 elemIndices '\n'

O(n) The elemIndexLast function returns the last index of the element in the given ByteString which is equal to the query element, or Nothing if there is no such element. The following holds:

 elemIndexLast c xs == 
 (-) (length xs - 1) `fmap` elemIndex c (reverse xs)

count returns the number of times its argument appears in the ByteString

 count = length . elemIndices

Also

 count '\n' == length . lines

But more efficiently than using length on the intermediate list.

O(n) A first order equivalent of filter . (==), for the common case of filtering a single Char. It is more efficient to use filterChar in this case.

 filterChar == filter . (==)

filterChar is around 10x faster, and uses much less space, than its filter equivalent

O(n) A first order equivalent of filter . (/=), for the common case of filtering a single Char out of a list. It is more efficient to use filterNotChar in this case.

 filterNotChar == filter . (/=)

filterNotChar is around 3x faster, and uses much less space, than its filter equivalent

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

The following holds:

 isSuffixOf x y == reverse x `isPrefixOf` reverse y

However, the real implemenation uses memcmp to compare the end of the string only, with no reverse required..

Read entire handle contents into a ByteString.

As with hGet, the string representation in the file is assumed to be ISO-8859-1.

O(n) Pack a null-terminated sequence of bytes, pointed to by an Addr# (an arbitrary machine address assumed to point outside the garbage-collected heap) into a ByteString. A much faster way to create an Addr# is with an unboxed string literal, than to pack a boxed string. A unboxed string literal is compiled to a static char [] by GHC. Establishing the length of the string requires a call to strlen(3), so the Addr# must point to a null-terminated buffer (as is the case with string# literals in GHC). Use unsafePackAddress if you know the length of the string statically.

An example:

 literalFS = packAddress "literal"#

Special forms of loop arguments

• These are common special cases for the three function arguments of gen and loop; we give them special names to make it easier to trigger RULES applying in the special cases represented by these arguments. The INLINE [1] makes sure that these functions are only inlined in the last two simplifier phases.
• In the case where the accumulator is not needed, it is better to always explicitly return a value `()', rather than just copy the input to the output, as the former gives GHC better local information.

Element function expressing a mapping only