-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Fast, packed, strict and lazy byte arrays with a list interface -- -- A time and space-efficient implementation of byte vectors using packed -- Word8 arrays, suitable for high performance use, both in terms of -- large data quantities, or high speed requirements. Byte vectors are -- encoded as strict <a>Word8</a> arrays of bytes, and lazy lists of -- strict chunks, held in a <a>ForeignPtr</a>, and can be passed between -- C and Haskell with little effort. -- -- Test coverage data for this library is available at: -- <a>http://code.haskell.org/~dons/tests/bytestring/hpc_index.html</a> @package bytestring @version 0.9.2.1 -- | A module containing unsafe <a>ByteString</a> operations. -- -- While these functions have a stable API and you may use these -- functions in applications, do carefully consider the documented -- pre-conditions; incorrect use can break referential transparency or -- worse. module Data.ByteString.Unsafe -- | A variety of <a>head</a> for non-empty ByteStrings. <a>unsafeHead</a> -- omits the check for the empty case, so there is an obligation on the -- programmer to provide a proof that the ByteString is non-empty. unsafeHead :: ByteString -> Word8 -- | A variety of <a>tail</a> for non-empty ByteStrings. <a>unsafeTail</a> -- omits the check for the empty case. As with <a>unsafeHead</a>, the -- programmer must provide a separate proof that the ByteString is -- non-empty. unsafeTail :: ByteString -> ByteString -- | Unsafe <a>ByteString</a> index (subscript) operator, starting from 0, -- returning a <a>Word8</a> This omits the bounds check, which means -- there is an accompanying obligation on the programmer to ensure the -- bounds are checked in some other way. unsafeIndex :: ByteString -> Int -> Word8 -- | A variety of <a>take</a> which omits the checks on <tt>n</tt> so there -- is an obligation on the programmer to provide a proof that <tt>0 <= -- n <= <a>length</a> xs</tt>. unsafeTake :: Int -> ByteString -> ByteString -- | A variety of <a>drop</a> which omits the checks on <tt>n</tt> so there -- is an obligation on the programmer to provide a proof that <tt>0 <= -- n <= <a>length</a> xs</tt>. unsafeDrop :: Int -> ByteString -> ByteString -- | <i>O(1) construction</i> Use a <tt>ByteString</tt> with a function -- requiring a <tt>CString</tt>. -- -- This function does zero copying, and merely unwraps a -- <tt>ByteString</tt> to appear as a <tt>CString</tt>. It is -- <i>unsafe</i> in two ways: -- -- <ul> -- <li>After calling this function the <tt>CString</tt> shares the -- underlying byte buffer with the original <tt>ByteString</tt>. Thus -- modifying the <tt>CString</tt>, either in C, or using poke, will cause -- the contents of the <tt>ByteString</tt> to change, breaking -- referential transparency. Other <tt>ByteStrings</tt> created by -- sharing (such as those produced via <a>take</a> or <a>drop</a>) will -- also reflect these changes. Modifying the <tt>CString</tt> will break -- referential transparency. To avoid this, use <tt>useAsCString</tt>, -- which makes a copy of the original <tt>ByteString</tt>.</li> -- <li><tt>CStrings</tt> are often passed to functions that require them -- to be null-terminated. If the original <tt>ByteString</tt> wasn't null -- terminated, neither will the <tt>CString</tt> be. It is the -- programmers responsibility to guarantee that the <tt>ByteString</tt> -- is indeed null terminated. If in doubt, use -- <tt>useAsCString</tt>.</li> -- </ul> unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a -- | <i>O(1) construction</i> Use a <tt>ByteString</tt> with a function -- requiring a <tt>CStringLen</tt>. -- -- This function does zero copying, and merely unwraps a -- <tt>ByteString</tt> to appear as a <tt>CStringLen</tt>. It is -- <i>unsafe</i>: -- -- <ul> -- <li>After calling this function the <tt>CStringLen</tt> shares the -- underlying byte buffer with the original <tt>ByteString</tt>. Thus -- modifying the <tt>CStringLen</tt>, either in C, or using poke, will -- cause the contents of the <tt>ByteString</tt> to change, breaking -- referential transparency. Other <tt>ByteStrings</tt> created by -- sharing (such as those produced via <a>take</a> or <a>drop</a>) will -- also reflect these changes. Modifying the <tt>CStringLen</tt> will -- break referential transparency. To avoid this, use -- <tt>useAsCStringLen</tt>, which makes a copy of the original -- <tt>ByteString</tt>.</li> -- </ul> unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a -- | <i>O(n)</i> Build a <tt>ByteString</tt> from a <tt>CString</tt>. This -- value will have <i>no</i> finalizer associated to it, and will not be -- garbage collected by Haskell. The ByteString length is calculated -- using <i>strlen(3)</i>, and thus the complexity is a <i>O(n)</i>. -- -- This function is <i>unsafe</i>. If the <tt>CString</tt> is later -- modified, this change will be reflected in the resulting -- <tt>ByteString</tt>, breaking referential transparency. unsafePackCString :: CString -> IO ByteString -- | <i>O(1)</i> Build a <tt>ByteString</tt> from a <tt>CStringLen</tt>. -- This value will have <i>no</i> finalizer associated with it, and will -- not be garbage collected by Haskell. This operation has <i>O(1)</i> -- complexity as we already know the final size, so no <i>strlen(3)</i> -- is required. -- -- This funtion is <i>unsafe</i>. If the original <tt>CStringLen</tt> is -- later modified, this change will be reflected in the resulting -- <tt>ByteString</tt>, breaking referential transparency. unsafePackCStringLen :: CStringLen -> IO ByteString -- | <i>O(n)</i> Build a <tt>ByteString</tt> from a malloced -- <tt>CString</tt>. This value will have a <tt>free(3)</tt> finalizer -- associated to it. -- -- This funtion is <i>unsafe</i>. If the original <tt>CString</tt> is -- later modified, this change will be reflected in the resulting -- <tt>ByteString</tt>, breaking referential transparency. -- -- This function is also unsafe if you call its finalizer twice, which -- will result in a <i>double free</i> error, or if you pass it a CString -- not allocated with <tt>malloc</tt>. unsafePackMallocCString :: CString -> IO ByteString -- | <i>O(n)</i> 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 <tt>ByteString</tt>. 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 -- <tt>char []</tt> by GHC. Establishing the length of the string -- requires a call to <tt>strlen(3)</tt>, so the Addr# must point to a -- null-terminated buffer (as is the case with <a>string</a># literals in -- GHC). Use <a>unsafePackAddressLen</a> if you know the length of the -- string statically. -- -- An example: -- -- <pre> -- literalFS = unsafePackAddress "literal"# -- </pre> -- -- This function is <i>unsafe</i>. If you modify the buffer pointed to by -- the original Addr# this modification will be reflected in the -- resulting <tt>ByteString</tt>, breaking referential transparency. -- -- Note this also won't work if you Add# has embedded '\0' characters in -- the string (strlen will fail). unsafePackAddress :: Addr# -> IO ByteString -- | <i>O(1)</i> <a>unsafePackAddressLen</a> provides constant-time -- construction of <tt>ByteStrings</tt> which is ideal for string -- literals. It packs a sequence of bytes into a <a>ByteString</a>, given -- a raw <a>Addr#</a> to the string, and the length of the string. -- -- This function is <i>unsafe</i> in two ways: -- -- <ul> -- <li>the length argument is assumed to be correct. If the length -- argument is incorrect, it is possible to overstep the end of the byte -- array.</li> -- <li>if the underying Addr# is later modified, this change will be -- reflected in resulting <tt>ByteString</tt>, breaking referential -- transparency.</li> -- </ul> -- -- If in doubt, don't use these functions. unsafePackAddressLen :: Int -> Addr# -> IO ByteString -- | <i>O(1)</i> Construct a <a>ByteString</a> given a Ptr Word8 to a -- buffer, a length, and an IO action representing a finalizer. This -- function is not available on Hugs. -- -- This function is <i>unsafe</i>, it is possible to break referential -- transparency by modifying the underlying buffer pointed to by the -- first argument. Any changes to the original buffer will be reflected -- in the resulting <tt>ByteString</tt>. unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString -- | Explicitly run the finaliser associated with a <a>ByteString</a>. -- References to this value after finalisation may generate invalid -- memory references. -- -- This function is <i>unsafe</i>, as there may be other -- <tt>ByteStrings</tt> referring to the same underlying pages. If you -- use this, you need to have a proof of some kind that all -- <a>ByteString</a>s ever generated from the underlying byte array are -- no longer live. unsafeFinalize :: ByteString -> IO () -- | A time and space-efficient implementation of byte vectors using packed -- Word8 arrays, suitable for high performance use, both in terms of -- large data quantities, or high speed requirements. Byte vectors are -- encoded as strict <a>Word8</a> arrays of bytes, held in a -- <a>ForeignPtr</a>, and can be passed between C and Haskell with little -- effort. -- -- This module is intended to be imported <tt>qualified</tt>, to avoid -- name clashes with <a>Prelude</a> functions. eg. -- -- <pre> -- import qualified Data.ByteString as B -- </pre> -- -- Original GHC implementation by Bryan O'Sullivan. Rewritten to use -- <a>UArray</a> by Simon Marlow. Rewritten to support slices and use -- <a>ForeignPtr</a> by David Roundy. Polished and extended by Don -- Stewart. module Data.ByteString -- | A space-efficient representation of a Word8 vector, supporting many -- efficient operations. A <a>ByteString</a> contains 8-bit characters -- only. -- -- Instances of Eq, Ord, Read, Show, Data, Typeable data ByteString -- | <i>O(1)</i> The empty <a>ByteString</a> empty :: ByteString -- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a> singleton :: Word8 -> ByteString -- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>. -- -- For applications with large numbers of string literals, pack can be a -- bottleneck. In such cases, consider using packAddress (GHC only). pack :: [Word8] -> ByteString -- | <i>O(n)</i> Converts a <a>ByteString</a> to a '[Word8]'. unpack :: ByteString -> [Word8] -- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of -- different complexity, as it requires a memcpy. cons :: Word8 -> ByteString -> ByteString -- | <i>O(n)</i> Append a byte to the end of a <a>ByteString</a> snoc :: ByteString -> Word8 -> ByteString -- | <i>O(n)</i> Append two ByteStrings append :: ByteString -> ByteString -> ByteString -- | <i>O(1)</i> Extract the first element of a ByteString, which must be -- non-empty. An exception will be thrown in the case of an empty -- ByteString. head :: ByteString -> Word8 -- | <i>O(1)</i> Extract the head and tail of a ByteString, returning -- Nothing if it is empty. uncons :: ByteString -> Maybe (Word8, ByteString) -- | <i>O(1)</i> Extract the last element of a ByteString, which must be -- finite and non-empty. An exception will be thrown in the case of an -- empty ByteString. last :: ByteString -> Word8 -- | <i>O(1)</i> Extract the elements after the head of a ByteString, which -- must be non-empty. An exception will be thrown in the case of an empty -- ByteString. tail :: ByteString -> ByteString -- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the -- last one. An exception will be thrown in the case of an empty -- ByteString. init :: ByteString -> ByteString -- | <i>O(1)</i> Test whether a ByteString is empty. null :: ByteString -> Bool -- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an -- <a>Int</a>. length :: ByteString -> Int -- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by -- applying <tt>f</tt> to each element of <tt>xs</tt>. This function is -- subject to array fusion. map :: (Word8 -> Word8) -> ByteString -> ByteString -- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the -- elements of <tt>xs</tt> in reverse order. reverse :: ByteString -> ByteString -- | <i>O(n)</i> The <a>intersperse</a> function takes a <a>Word8</a> and a -- <a>ByteString</a> and `intersperses' that byte between the elements of -- the <a>ByteString</a>. It is analogous to the intersperse function on -- Lists. intersperse :: Word8 -> ByteString -> ByteString -- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a> -- and a list of <a>ByteString</a>s and concatenates the list after -- interspersing the first argument between each element of the list. intercalate :: ByteString -> [ByteString] -> ByteString -- | The <a>transpose</a> function transposes the rows and columns of its -- <a>ByteString</a> argument. transpose :: [ByteString] -> [ByteString] -- | <a>foldl</a>, applied to a binary operator, a starting value -- (typically the left-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from left to right. -- -- This function is subject to array fusion. foldl :: (a -> Word8 -> a) -> a -> ByteString -> a -- | 'foldl\'' is like <a>foldl</a>, but strict in the accumulator. -- However, for ByteStrings, all left folds are strict in the -- accumulator. foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a -- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value -- argument, and thus must be applied to non-empty <tt>ByteStrings</tt>. -- This function is subject to array fusion. An exception will be thrown -- in the case of an empty ByteString. foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator. An -- exception will be thrown in the case of an empty ByteString. foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | <a>foldr</a>, applied to a binary operator, a starting value -- (typically the right-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from right to left. foldr :: (Word8 -> a -> a) -> a -> ByteString -> a -- | 'foldr\'' is like <a>foldr</a>, but strict in the accumulator. foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a -- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value -- argument, and thus must be applied to non-empty <a>ByteString</a>s An -- exception will be thrown in the case of an empty ByteString. foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | 'foldr1\'' is a variant of <a>foldr1</a>, but is strict in the -- accumulator. foldr1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | <i>O(n)</i> Concatenate a list of ByteStrings. concat :: [ByteString] -> ByteString -- | Map a function over a <a>ByteString</a> and concatenate the results concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString -- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a> -- determines if any element of the <a>ByteString</a> satisfies the -- predicate. any :: (Word8 -> Bool) -> ByteString -> Bool -- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a> -- determines if all elements of the <a>ByteString</a> satisfy the -- predicate. all :: (Word8 -> Bool) -> ByteString -> Bool -- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a -- <a>ByteString</a> This function will fuse. An exception will be thrown -- in the case of an empty ByteString. maximum :: ByteString -> Word8 -- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a -- <a>ByteString</a> This function will fuse. An exception will be thrown -- in the case of an empty ByteString. minimum :: ByteString -> Word8 -- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of -- successive reduced values from the left. This function will fuse. -- -- <pre> -- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...] -- </pre> -- -- Note that -- -- <pre> -- last (scanl f z xs) == foldl f z xs. -- </pre> scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString -- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value -- argument. This function will fuse. -- -- <pre> -- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...] -- </pre> scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -- | scanr is the right-to-left dual of scanl. scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString -- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value -- argument. scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a> -- and <a>foldl</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from left to right, and -- returning a final value of this accumulator together with the new -- list. mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) -- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a> -- and <a>foldr</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from right to left, and -- returning a final value of this accumulator together with the new -- ByteString. mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) -- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length -- <tt>n</tt> with <tt>x</tt> the value of every element. The following -- holds: -- -- <pre> -- replicate w c = unfoldr w (\u -> Just (u,u)) c -- </pre> -- -- This implemenation uses <tt>memset(3)</tt> replicate :: Int -> Word8 -> ByteString -- | <i>O(n)</i>, where <i>n</i> is the length of the result. The -- <a>unfoldr</a> function is analogous to the List 'unfoldr'. -- <a>unfoldr</a> builds a ByteString from a seed value. The function -- takes the element and returns <a>Nothing</a> if it is done producing -- the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case, -- <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed -- value for further production. -- -- Examples: -- -- <pre> -- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0 -- == pack [0, 1, 2, 3, 4, 5] -- </pre> unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString -- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString -- from a seed value. However, the length of the result is limited by the -- first argument to <a>unfoldrN</a>. This function is more efficient -- than <a>unfoldr</a> when the maximum length of the result is known. -- -- The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>: -- -- <pre> -- snd (unfoldrN n f s) == take n (unfoldr f s) -- </pre> unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ByteString, Maybe a) -- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString -- <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>, -- or <tt>xs</tt> itself if <tt>n > <a>length</a> xs</tt>. take :: Int -> ByteString -> ByteString -- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of -- <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if -- <tt>n > <a>length</a> xs</tt>. drop :: Int -> ByteString -> ByteString -- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to -- <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>. splitAt :: Int -> ByteString -> (ByteString, ByteString) -- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString -- <tt>xs</tt>, returns the longest prefix (possibly empty) of -- <tt>xs</tt> of elements that satisfy <tt>p</tt>. takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString -- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after -- <a>takeWhile</a> <tt>p xs</tt>. dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString -- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It -- is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p -- xs)</tt> span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the -- <a>ByteString</a>. We have -- -- <pre> -- spanEnd (not.isSpace) "x y z" == ("x y ","z") -- </pre> -- -- and -- -- <pre> -- spanEnd (not . isSpace) ps -- == -- let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x) -- </pre> spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> . -- p)</tt>. -- -- Under GHC, a rewrite rule will transform break (==) into a call to the -- specialised breakByte: -- -- <pre> -- break ((==) x) = breakByte x -- break (==x) = breakByte x -- </pre> break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the -- <a>ByteString</a> -- -- breakEnd p == spanEnd (not.p) breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | The <a>group</a> 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, -- -- <pre> -- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"] -- </pre> -- -- It is a special case of <a>groupBy</a>, which allows the programmer to -- supply their own equality test. It is about 40% faster than <i>groupBy -- (==)</i> group :: ByteString -> [ByteString] -- | The <a>groupBy</a> function is the non-overloaded version of -- <a>group</a>. groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString] -- | <i>O(n)</i> Return all initial segments of the given -- <a>ByteString</a>, shortest first. inits :: ByteString -> [ByteString] -- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>, -- longest first. tails :: ByteString -> [ByteString] -- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the -- byte argument, consuming the delimiter. I.e. -- -- <pre> -- split '\n' "a\nb\nd\ne" == ["a","b","d","e"] -- split 'a' "aXaXaXa" == ["","X","X","X",""] -- split 'x' "x" == ["",""] -- </pre> -- -- and -- -- <pre> -- intercalate [c] . split c == id -- split == splitWith . (==) -- </pre> -- -- As for all splitting functions in this library, this function does not -- copy the substrings, it just constructs new <tt>ByteStrings</tt> that -- are slices of the original. split :: Word8 -> ByteString -> [ByteString] -- | <i>O(n)</i> Splits a <a>ByteString</a> 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. -- -- <pre> -- splitWith (=='a') "aabbaca" == ["","","bb","c",""] -- splitWith (=='a') [] == [] -- </pre> splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString] -- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and -- returns <a>True</a> iff the first is a prefix of the second. isPrefixOf :: ByteString -> ByteString -> Bool -- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and -- returns <a>True</a> iff the first is a suffix of the second. -- -- The following holds: -- -- <pre> -- isSuffixOf x y == reverse x `isPrefixOf` reverse y -- </pre> -- -- However, the real implemenation uses memcmp to compare the end of the -- string only, with no reverse required.. isSuffixOf :: ByteString -> ByteString -> Bool -- | Check whether one string is a substring of another. <tt>isInfixOf p -- s</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>. isInfixOf :: ByteString -> ByteString -> Bool -- | Break a string on a substring, returning a pair of the part of the -- string prior to the match, and the rest of the string. -- -- The following relationships hold: -- -- <pre> -- break (== c) l == breakSubstring (singleton c) l -- </pre> -- -- and: -- -- <pre> -- findSubstring s l == -- if null s then Just 0 -- else case breakSubstring s l of -- (x,y) | null y -> Nothing -- | otherwise -> Just (length x) -- </pre> -- -- For example, to tokenise a string, dropping delimiters: -- -- <pre> -- tokenise x y = h : if null t then [] else tokenise x (drop (length x) t) -- where (h,t) = breakSubstring x y -- </pre> -- -- To skip to the first occurence of a string: -- -- <pre> -- snd (breakSubstring x y) -- </pre> -- -- To take the parts of a string before a delimiter: -- -- <pre> -- fst (breakSubstring x y) -- </pre> breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString) -- | Get the first index of a substring in another string, or -- <a>Nothing</a> if the string is not found. <tt>findSubstring p s</tt> -- is equivalent to <tt>listToMaybe (findSubstrings p s)</tt>. -- | <i>Deprecated: findSubstring is deprecated in favour of -- breakSubstring.</i> findSubstring :: ByteString -> ByteString -> Maybe Int -- | Find the indexes of all (possibly overlapping) occurances of a -- substring in a string. -- | <i>Deprecated: findSubstrings is deprecated in favour of -- breakSubstring.</i> findSubstrings :: ByteString -> ByteString -> [Int] -- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate. elem :: Word8 -> ByteString -> Bool -- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a> notElem :: Word8 -> ByteString -> Bool -- | <i>O(n)</i> The <a>find</a> function takes a predicate and a -- ByteString, and returns the first element in matching the predicate, -- or <a>Nothing</a> if there is no such element. -- -- <pre> -- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing -- </pre> find :: (Word8 -> Bool) -> ByteString -> Maybe Word8 -- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString, -- returns a ByteString containing those characters that satisfy the -- predicate. This function is subject to array fusion. filter :: (Word8 -> Bool) -> ByteString -> ByteString -- | <i>O(n)</i> The <a>partition</a> function takes a predicate a -- ByteString and returns the pair of ByteStrings with elements which do -- and do not satisfy the predicate, respectively; i.e., -- -- <pre> -- partition p bs == (filter p xs, filter (not . p) xs) -- </pre> partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting -- from 0. index :: ByteString -> Int -> Word8 -- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the -- first element in the given <a>ByteString</a> which is equal to the -- query element, or <a>Nothing</a> if there is no such element. This -- implementation uses memchr(3). elemIndex :: Word8 -> ByteString -> Maybe Int -- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>, -- by returning the indices of all elements equal to the query element, -- in ascending order. This implementation uses memchr(3). elemIndices :: Word8 -> ByteString -> [Int] -- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of -- the element in the given <a>ByteString</a> which is equal to the query -- element, or <a>Nothing</a> if there is no such element. The following -- holds: -- -- <pre> -- elemIndexEnd c xs == -- (-) (length xs - 1) `fmap` elemIndex c (reverse xs) -- </pre> elemIndexEnd :: Word8 -> ByteString -> Maybe Int -- | The <a>findIndex</a> function takes a predicate and a -- <a>ByteString</a> and returns the index of the first element in the -- ByteString satisfying the predicate. findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int -- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning -- the indices of all elements satisfying the predicate, in ascending -- order. findIndices :: (Word8 -> Bool) -> ByteString -> [Int] -- | count returns the number of times its argument appears in the -- ByteString -- -- <pre> -- count = length . elemIndices -- </pre> -- -- But more efficiently than using length on the intermediate list. count :: Word8 -> ByteString -> Int -- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of -- corresponding pairs of bytes. If one input ByteString is short, excess -- elements of the longer ByteString are discarded. This is equivalent to -- a pair of <a>unpack</a> operations. zip :: ByteString -> ByteString -> [(Word8, Word8)] -- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function -- given as the first argument, instead of a tupling function. For -- example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to -- produce the list of corresponding sums. zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a] -- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a -- pair of ByteStrings. Note that this performs two <a>pack</a> -- operations. unzip :: [(Word8, Word8)] -> (ByteString, ByteString) -- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort. sort :: ByteString -> ByteString -- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage. -- This is mainly useful to allow the rest of the data pointed to by the -- <a>ByteString</a> to be garbage collected, for example if a large -- string has been read in, and only a small part of it is needed in the -- rest of the program. copy :: ByteString -> ByteString -- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a -- <tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable -- copy of the original <tt>CString</tt>, and is managed on the Haskell -- heap. The original <tt>CString</tt> must be null terminated. packCString :: CString -> IO ByteString -- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a -- <tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable -- copy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a -- normal Haskell value and will be managed on the Haskell heap. packCStringLen :: CStringLen -> IO ByteString -- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function -- requiring a null-terminated <tt>CString</tt>. The <tt>CString</tt> -- will be freed automatically. This is a memcpy(3). useAsCString :: ByteString -> (CString -> IO a) -> IO a -- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function -- requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this -- function makes a copy of the original <tt>ByteString</tt>. useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a -- | Read a line from stdin. getLine :: IO ByteString -- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The -- <a>Handle</a> is closed after the contents have been read. getContents :: IO ByteString -- | Write a ByteString to stdout putStr :: ByteString -> IO () -- | Write a ByteString to stdout, appending a newline byte -- | <i>Deprecated: Use Data.ByteString.Char8.putStrLn instead. (Functions -- that rely on ASCII encodings belong in Data.ByteString.Char8)</i> putStrLn :: ByteString -> IO () -- | The interact function takes a function of type <tt>ByteString -> -- ByteString</tt> as its argument. The entire input from the standard -- input device is passed to this function as its argument, and the -- resulting string is output on the standard output device. interact :: (ByteString -> ByteString) -> IO () -- | Read an entire file strictly into a <a>ByteString</a>. This is far -- more efficient than reading the characters into a <a>String</a> and -- then using <a>pack</a>. It also may be more efficient than opening the -- file and reading it using hGet. Files are read using 'binary mode' on -- Windows, for 'text mode' use the Char8 version of this function. readFile :: FilePath -> IO ByteString -- | Write a <a>ByteString</a> to a file. writeFile :: FilePath -> ByteString -> IO () -- | Append a <a>ByteString</a> to a file. appendFile :: FilePath -> ByteString -> IO () -- | Read a line from a handle hGetLine :: Handle -> IO ByteString -- | Read entire handle contents strictly into a <a>ByteString</a>. -- -- This function reads chunks at a time, doubling the chunksize on each -- read. The final buffer is then realloced to the appropriate size. For -- files > half of available memory, this may lead to memory -- exhaustion. Consider using <a>readFile</a> in this case. -- -- As with <a>hGet</a>, the string representation in the file is assumed -- to be ISO-8859-1. -- -- The Handle is closed once the contents have been read, or if an -- exception is thrown. hGetContents :: Handle -> IO ByteString -- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>. -- This is far more efficient than reading the characters into a -- <a>String</a> and then using <a>pack</a>. First argument is the Handle -- to read from, and the second is the number of bytes to read. It -- returns the bytes read, up to n, or <a>null</a> if EOF has been -- reached. -- -- <a>hGet</a> is implemented in terms of <a>hGetBuf</a>. -- -- If the handle is a pipe or socket, and the writing end is closed, -- <a>hGet</a> will behave as if EOF was reached. hGet :: Handle -> Int -> IO ByteString -- | Like <a>hGet</a>, except that a shorter <a>ByteString</a> may be -- returned if there are not enough bytes immediately available to -- satisfy the whole request. <a>hGetSome</a> only blocks if there is no -- data available, and EOF has not yet been reached. hGetSome :: Handle -> Int -> IO ByteString -- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never -- block waiting for data to become available, instead it returns only -- whatever data is available. If there is no data available to be read, -- <a>hGetNonBlocking</a> returns <a>empty</a>. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hGet</a>. hGetNonBlocking :: Handle -> Int -> IO ByteString -- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>. hPut :: Handle -> ByteString -> IO () -- | Similar to <a>hPut</a> except that it will never block. Instead it -- returns any tail that did not get written. This tail may be -- <a>empty</a> in the case that the whole string was written, or the -- whole original string if nothing was written. Partial writes are also -- possible. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hPut</a>. hPutNonBlocking :: Handle -> ByteString -> IO ByteString -- | A synonym for <tt>hPut</tt>, for compatibility hPutStr :: Handle -> ByteString -> IO () -- | Write a ByteString to a handle, appending a newline byte -- | <i>Deprecated: Use Data.ByteString.Char8.hPutStrLn instead. (Functions -- that rely on ASCII encodings belong in Data.ByteString.Char8)</i> hPutStrLn :: Handle -> ByteString -> IO () -- | <a>breakByte</a> breaks its ByteString argument at the first occurence -- of the specified byte. It is more efficient than <a>break</a> as it is -- implemented with <tt>memchr(3)</tt>. I.e. -- -- <pre> -- break (=='c') "abcd" == breakByte 'c' "abcd" -- </pre> breakByte :: Word8 -> ByteString -> (ByteString, ByteString) instance Monoid ByteString instance Ord ByteString instance Eq ByteString -- | Manipulate <a>ByteString</a>s using <a>Char</a> operations. All Chars -- will be truncated to 8 bits. It can be expected that these functions -- will run at identical speeds to their <a>Word8</a> equivalents in -- <a>Data.ByteString</a>. -- -- 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: -- -- <ul> -- <li><a>http://www.unicode.org/charts/</a></li> -- <li><a>http://www.unicode.org/charts/PDF/U0000.pdf</a></li> -- <li><a>http://www.unicode.org/charts/PDF/U0080.pdf</a></li> -- </ul> -- -- This module is intended to be imported <tt>qualified</tt>, to avoid -- name clashes with <a>Prelude</a> functions. eg. -- -- <pre> -- import qualified Data.ByteString.Char8 as B -- </pre> -- -- The Char8 interface to bytestrings provides an instance of IsString -- for the ByteString type, enabling you to use string literals, and have -- them implicitly packed to ByteStrings. Use -XOverloadedStrings to -- enable this. module Data.ByteString.Char8 -- | A space-efficient representation of a Word8 vector, supporting many -- efficient operations. A <a>ByteString</a> contains 8-bit characters -- only. -- -- Instances of Eq, Ord, Read, Show, Data, Typeable data ByteString -- | <i>O(1)</i> The empty <a>ByteString</a> empty :: ByteString -- | <i>O(1)</i> Convert a <a>Char</a> into a <a>ByteString</a> singleton :: Char -> ByteString -- | <i>O(n)</i> Convert a <a>String</a> into a <a>ByteString</a> -- -- For applications with large numbers of string literals, pack can be a -- bottleneck. pack :: String -> ByteString -- | <i>O(n)</i> Converts a <a>ByteString</a> to a <a>String</a>. unpack :: ByteString -> [Char] -- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of -- different complexity, as it requires a memcpy. cons :: Char -> ByteString -> ByteString -- | <i>O(n)</i> Append a Char to the end of a <a>ByteString</a>. Similar -- to <a>cons</a>, this function performs a memcpy. snoc :: ByteString -> Char -> ByteString -- | <i>O(n)</i> Append two ByteStrings append :: ByteString -> ByteString -> ByteString -- | <i>O(1)</i> Extract the first element of a ByteString, which must be -- non-empty. head :: ByteString -> Char -- | <i>O(1)</i> Extract the head and tail of a ByteString, returning -- Nothing if it is empty. uncons :: ByteString -> Maybe (Char, ByteString) -- | <i>O(1)</i> Extract the last element of a packed string, which must be -- non-empty. last :: ByteString -> Char -- | <i>O(1)</i> Extract the elements after the head of a ByteString, which -- must be non-empty. An exception will be thrown in the case of an empty -- ByteString. tail :: ByteString -> ByteString -- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the -- last one. An exception will be thrown in the case of an empty -- ByteString. init :: ByteString -> ByteString -- | <i>O(1)</i> Test whether a ByteString is empty. null :: ByteString -> Bool -- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an -- <a>Int</a>. length :: ByteString -> Int -- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by -- applying <tt>f</tt> to each element of <tt>xs</tt> map :: (Char -> Char) -> ByteString -> ByteString -- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the -- elements of <tt>xs</tt> in reverse order. reverse :: ByteString -> ByteString -- | <i>O(n)</i> The <a>intersperse</a> function takes a Char and a -- <a>ByteString</a> and `intersperses' that Char between the elements of -- the <a>ByteString</a>. It is analogous to the intersperse function on -- Lists. intersperse :: Char -> ByteString -> ByteString -- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a> -- and a list of <a>ByteString</a>s and concatenates the list after -- interspersing the first argument between each element of the list. intercalate :: ByteString -> [ByteString] -> ByteString -- | The <a>transpose</a> function transposes the rows and columns of its -- <a>ByteString</a> argument. transpose :: [ByteString] -> [ByteString] -- | <a>foldl</a>, applied to a binary operator, a starting value -- (typically the left-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from left to right. foldl :: (a -> Char -> a) -> a -> ByteString -> a -- | 'foldl\'' is like foldl, but strict in the accumulator. foldl' :: (a -> Char -> a) -> a -> ByteString -> a -- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value -- argument, and thus must be applied to non-empty <tt>ByteStrings</tt>. foldl1 :: (Char -> Char -> Char) -> ByteString -> Char -- | A strict version of <a>foldl1</a> foldl1' :: (Char -> Char -> Char) -> ByteString -> Char -- | <a>foldr</a>, applied to a binary operator, a starting value -- (typically the right-identity of the operator), and a packed string, -- reduces the packed string using the binary operator, from right to -- left. foldr :: (Char -> a -> a) -> a -> ByteString -> a -- | 'foldr\'' is a strict variant of foldr foldr' :: (Char -> a -> a) -> a -> ByteString -> a -- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value -- argument, and thus must be applied to non-empty <a>ByteString</a>s foldr1 :: (Char -> Char -> Char) -> ByteString -> Char -- | A strict variant of foldr1 foldr1' :: (Char -> Char -> Char) -> ByteString -> Char -- | <i>O(n)</i> Concatenate a list of ByteStrings. concat :: [ByteString] -> ByteString -- | Map a function over a <a>ByteString</a> and concatenate the results concatMap :: (Char -> ByteString) -> ByteString -> ByteString -- | Applied to a predicate and a ByteString, <a>any</a> determines if any -- element of the <a>ByteString</a> satisfies the predicate. any :: (Char -> Bool) -> ByteString -> Bool -- | Applied to a predicate and a <a>ByteString</a>, <a>all</a> determines -- if all elements of the <a>ByteString</a> satisfy the predicate. all :: (Char -> Bool) -> ByteString -> Bool -- | <a>maximum</a> returns the maximum value from a <a>ByteString</a> maximum :: ByteString -> Char -- | <a>minimum</a> returns the minimum value from a <a>ByteString</a> minimum :: ByteString -> Char -- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of -- successive reduced values from the left: -- -- <pre> -- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...] -- </pre> -- -- Note that -- -- <pre> -- last (scanl f z xs) == foldl f z xs. -- </pre> scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString -- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value -- argument: -- -- <pre> -- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...] -- </pre> scanl1 :: (Char -> Char -> Char) -> ByteString -> ByteString -- | scanr is the right-to-left dual of scanl. scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString -- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value -- argument. scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString -- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a> -- and <a>foldl</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from left to right, and -- returning a final value of this accumulator together with the new -- list. mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString) -- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a> -- and <a>foldr</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from right to left, and -- returning a final value of this accumulator together with the new -- ByteString. mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString) -- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length -- <tt>n</tt> with <tt>x</tt> the value of every element. The following -- holds: -- -- <pre> -- replicate w c = unfoldr w (\u -> Just (u,u)) c -- </pre> -- -- This implemenation uses <tt>memset(3)</tt> replicate :: Int -> Char -> ByteString -- | <i>O(n)</i>, where <i>n</i> is the length of the result. The -- <a>unfoldr</a> function is analogous to the List 'unfoldr'. -- <a>unfoldr</a> builds a ByteString from a seed value. The function -- takes the element and returns <a>Nothing</a> if it is done producing -- the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case, -- <tt>a</tt> is the next character in the string, and <tt>b</tt> is the -- seed value for further production. -- -- Examples: -- -- <pre> -- unfoldr (\x -> if x <= '9' then Just (x, succ x) else Nothing) '0' == "0123456789" -- </pre> unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString -- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString -- from a seed value. However, the length of the result is limited by the -- first argument to <a>unfoldrN</a>. This function is more efficient -- than <a>unfoldr</a> when the maximum length of the result is known. -- -- The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>: -- -- <pre> -- unfoldrN n f s == take n (unfoldr f s) -- </pre> unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> (ByteString, Maybe a) -- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString -- <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>, -- or <tt>xs</tt> itself if <tt>n > <a>length</a> xs</tt>. take :: Int -> ByteString -> ByteString -- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of -- <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if -- <tt>n > <a>length</a> xs</tt>. drop :: Int -> ByteString -> ByteString -- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to -- <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>. splitAt :: Int -> ByteString -> (ByteString, ByteString) -- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString -- <tt>xs</tt>, returns the longest prefix (possibly empty) of -- <tt>xs</tt> of elements that satisfy <tt>p</tt>. takeWhile :: (Char -> Bool) -> ByteString -> ByteString -- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after -- <a>takeWhile</a> <tt>p xs</tt>. dropWhile :: (Char -> Bool) -> ByteString -> ByteString -- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It -- is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p -- xs)</tt> span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the -- <a>ByteString</a>. We have -- -- <pre> -- spanEnd (not.isSpace) "x y z" == ("x y ","z") -- </pre> -- -- and -- -- <pre> -- spanEnd (not . isSpace) ps -- == -- let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x) -- </pre> spanEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> . -- p)</tt>. break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the -- <a>ByteString</a> -- -- breakEnd p == spanEnd (not.p) breakEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) -- | The <a>group</a> 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, -- -- <pre> -- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"] -- </pre> -- -- It is a special case of <a>groupBy</a>, which allows the programmer to -- supply their own equality test. It is about 40% faster than <i>groupBy -- (==)</i> group :: ByteString -> [ByteString] -- | The <a>groupBy</a> function is the non-overloaded version of -- <a>group</a>. groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString] -- | <i>O(n)</i> Return all initial segments of the given -- <a>ByteString</a>, shortest first. inits :: ByteString -> [ByteString] -- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>, -- longest first. tails :: ByteString -> [ByteString] -- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the -- byte argument, consuming the delimiter. I.e. -- -- <pre> -- split '\n' "a\nb\nd\ne" == ["a","b","d","e"] -- split 'a' "aXaXaXa" == ["","X","X","X",""] -- split 'x' "x" == ["",""] -- </pre> -- -- and -- -- <pre> -- intercalate [c] . split c == id -- split == splitWith . (==) -- </pre> -- -- As for all splitting functions in this library, this function does not -- copy the substrings, it just constructs new <tt>ByteStrings</tt> that -- are slices of the original. split :: Char -> ByteString -> [ByteString] -- | <i>O(n)</i> Splits a <a>ByteString</a> 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. -- -- <pre> -- splitWith (=='a') "aabbaca" == ["","","bb","c",""] -- </pre> splitWith :: (Char -> Bool) -> ByteString -> [ByteString] -- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at -- newline Chars. The resulting strings do not contain newlines. lines :: ByteString -> [ByteString] -- | <a>words</a> breaks a ByteString up into a list of words, which were -- delimited by Chars representing white space. words :: ByteString -> [ByteString] -- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins -- lines, after appending a terminating newline to each. unlines :: [ByteString] -> ByteString -- | The <a>unwords</a> function is analogous to the <a>unlines</a> -- function, on words. unwords :: [ByteString] -> ByteString -- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and -- returns <a>True</a> iff the first is a prefix of the second. isPrefixOf :: ByteString -> ByteString -> Bool -- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and -- returns <a>True</a> iff the first is a suffix of the second. -- -- The following holds: -- -- <pre> -- isSuffixOf x y == reverse x `isPrefixOf` reverse y -- </pre> -- -- However, the real implemenation uses memcmp to compare the end of the -- string only, with no reverse required.. isSuffixOf :: ByteString -> ByteString -> Bool -- | Check whether one string is a substring of another. <tt>isInfixOf p -- s</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>. isInfixOf :: ByteString -> ByteString -> Bool -- | Break a string on a substring, returning a pair of the part of the -- string prior to the match, and the rest of the string. -- -- The following relationships hold: -- -- <pre> -- break (== c) l == breakSubstring (singleton c) l -- </pre> -- -- and: -- -- <pre> -- findSubstring s l == -- if null s then Just 0 -- else case breakSubstring s l of -- (x,y) | null y -> Nothing -- | otherwise -> Just (length x) -- </pre> -- -- For example, to tokenise a string, dropping delimiters: -- -- <pre> -- tokenise x y = h : if null t then [] else tokenise x (drop (length x) t) -- where (h,t) = breakSubstring x y -- </pre> -- -- To skip to the first occurence of a string: -- -- <pre> -- snd (breakSubstring x y) -- </pre> -- -- To take the parts of a string before a delimiter: -- -- <pre> -- fst (breakSubstring x y) -- </pre> breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString) -- | Get the first index of a substring in another string, or -- <a>Nothing</a> if the string is not found. <tt>findSubstring p s</tt> -- is equivalent to <tt>listToMaybe (findSubstrings p s)</tt>. findSubstring :: ByteString -> ByteString -> Maybe Int -- | Find the indexes of all (possibly overlapping) occurances of a -- substring in a string. findSubstrings :: ByteString -> ByteString -> [Int] -- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate. -- This implementation uses <tt>memchr(3)</tt>. elem :: Char -> ByteString -> Bool -- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a> notElem :: Char -> ByteString -> Bool -- | <i>O(n)</i> The <a>find</a> function takes a predicate and a -- ByteString, and returns the first element in matching the predicate, -- or <a>Nothing</a> if there is no such element. find :: (Char -> Bool) -> ByteString -> Maybe Char -- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString, -- returns a ByteString containing those characters that satisfy the -- predicate. filter :: (Char -> Bool) -> ByteString -> ByteString -- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting -- from 0. index :: ByteString -> Int -> Char -- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the -- first element in the given <a>ByteString</a> which is equal (by -- memchr) to the query element, or <a>Nothing</a> if there is no such -- element. elemIndex :: Char -> ByteString -> Maybe Int -- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>, -- by returning the indices of all elements equal to the query element, -- in ascending order. elemIndices :: Char -> ByteString -> [Int] -- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of -- the element in the given <a>ByteString</a> which is equal to the query -- element, or <a>Nothing</a> if there is no such element. The following -- holds: -- -- <pre> -- elemIndexEnd c xs == -- (-) (length xs - 1) `fmap` elemIndex c (reverse xs) -- </pre> elemIndexEnd :: Char -> ByteString -> Maybe Int -- | The <a>findIndex</a> function takes a predicate and a -- <a>ByteString</a> and returns the index of the first element in the -- ByteString satisfying the predicate. findIndex :: (Char -> Bool) -> ByteString -> Maybe Int -- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning -- the indices of all elements satisfying the predicate, in ascending -- order. findIndices :: (Char -> Bool) -> ByteString -> [Int] -- | count returns the number of times its argument appears in the -- ByteString -- -- <pre> -- count = length . elemIndices -- </pre> -- -- Also -- -- <pre> -- count '\n' == length . lines -- </pre> -- -- But more efficiently than using length on the intermediate list. count :: Char -> ByteString -> Int -- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of -- corresponding pairs of Chars. If one input ByteString is short, excess -- elements of the longer ByteString are discarded. This is equivalent to -- a pair of <a>unpack</a> operations, and so space usage may be large -- for multi-megabyte ByteStrings zip :: ByteString -> ByteString -> [(Char, Char)] -- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function -- given as the first argument, instead of a tupling function. For -- example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to -- produce the list of corresponding sums. zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a] -- | <a>unzip</a> transforms a list of pairs of Chars into a pair of -- ByteStrings. Note that this performs two <a>pack</a> operations. unzip :: [(Char, Char)] -> (ByteString, ByteString) -- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort. sort :: ByteString -> ByteString -- | readInt reads an Int from the beginning of the ByteString. If there is -- no integer at the beginning of the string, it returns Nothing, -- otherwise it just returns the int read, and the rest of the string. readInt :: ByteString -> Maybe (Int, ByteString) -- | readInteger reads an Integer from the beginning of the ByteString. If -- there is no integer at the beginning of the string, it returns -- Nothing, otherwise it just returns the int read, and the rest of the -- string. readInteger :: ByteString -> Maybe (Integer, ByteString) -- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage. -- This is mainly useful to allow the rest of the data pointed to by the -- <a>ByteString</a> to be garbage collected, for example if a large -- string has been read in, and only a small part of it is needed in the -- rest of the program. copy :: ByteString -> ByteString -- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a -- <tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable -- copy of the original <tt>CString</tt>, and is managed on the Haskell -- heap. The original <tt>CString</tt> must be null terminated. packCString :: CString -> IO ByteString -- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a -- <tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable -- copy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a -- normal Haskell value and will be managed on the Haskell heap. packCStringLen :: CStringLen -> IO ByteString -- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function -- requiring a null-terminated <tt>CString</tt>. The <tt>CString</tt> -- will be freed automatically. This is a memcpy(3). useAsCString :: ByteString -> (CString -> IO a) -> IO a -- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function -- requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this -- function makes a copy of the original <tt>ByteString</tt>. useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a -- | Read a line from stdin. getLine :: IO ByteString -- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The -- <a>Handle</a> is closed after the contents have been read. getContents :: IO ByteString -- | Write a ByteString to stdout putStr :: ByteString -> IO () -- | Write a ByteString to stdout, appending a newline byte putStrLn :: ByteString -> IO () -- | The interact function takes a function of type <tt>ByteString -> -- ByteString</tt> as its argument. The entire input from the standard -- input device is passed to this function as its argument, and the -- resulting string is output on the standard output device. interact :: (ByteString -> ByteString) -> IO () -- | Read an entire file strictly into a <a>ByteString</a>. This is far -- more efficient than reading the characters into a <a>String</a> and -- then using <a>pack</a>. It also may be more efficient than opening the -- file and reading it using hGet. readFile :: FilePath -> IO ByteString -- | Write a <a>ByteString</a> to a file. writeFile :: FilePath -> ByteString -> IO () -- | Append a <a>ByteString</a> to a file. appendFile :: FilePath -> ByteString -> IO () -- | Read a line from a handle hGetLine :: Handle -> IO ByteString -- | Read entire handle contents strictly into a <a>ByteString</a>. -- -- This function reads chunks at a time, doubling the chunksize on each -- read. The final buffer is then realloced to the appropriate size. For -- files > half of available memory, this may lead to memory -- exhaustion. Consider using <a>readFile</a> in this case. -- -- As with <a>hGet</a>, the string representation in the file is assumed -- to be ISO-8859-1. -- -- The Handle is closed once the contents have been read, or if an -- exception is thrown. hGetContents :: Handle -> IO ByteString -- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>. -- This is far more efficient than reading the characters into a -- <a>String</a> and then using <a>pack</a>. First argument is the Handle -- to read from, and the second is the number of bytes to read. It -- returns the bytes read, up to n, or <a>null</a> if EOF has been -- reached. -- -- <a>hGet</a> is implemented in terms of <a>hGetBuf</a>. -- -- If the handle is a pipe or socket, and the writing end is closed, -- <a>hGet</a> will behave as if EOF was reached. hGet :: Handle -> Int -> IO ByteString -- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never -- block waiting for data to become available, instead it returns only -- whatever data is available. If there is no data available to be read, -- <a>hGetNonBlocking</a> returns <a>empty</a>. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hGet</a>. hGetNonBlocking :: Handle -> Int -> IO ByteString -- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>. hPut :: Handle -> ByteString -> IO () -- | Similar to <a>hPut</a> except that it will never block. Instead it -- returns any tail that did not get written. This tail may be -- <a>empty</a> in the case that the whole string was written, or the -- whole original string if nothing was written. Partial writes are also -- possible. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hPut</a>. hPutNonBlocking :: Handle -> ByteString -> IO ByteString -- | A synonym for <tt>hPut</tt>, for compatibility hPutStr :: Handle -> ByteString -> IO () -- | Write a ByteString to a handle, appending a newline byte hPutStrLn :: Handle -> ByteString -> IO () instance IsString ByteString -- | A time and space-efficient implementation of lazy byte vectors using -- lists of packed <a>Word8</a> arrays, suitable for high performance -- use, both in terms of large data quantities, or high speed -- requirements. Byte vectors are encoded as lazy lists of strict -- <a>Word8</a> arrays of bytes. They provide a means to manipulate large -- byte vectors without requiring the entire vector be resident in -- memory. -- -- Some operations, such as concat, append, reverse and cons, have better -- complexity than their <a>Data.ByteString</a> equivalents, due to -- optimisations resulting from the list spine structure. And for other -- operations lazy ByteStrings are usually within a few percent of strict -- ones, but with better heap usage. For data larger than the available -- memory, or if you have tight memory constraints, this module will be -- the only option. The default chunk size is 64k, which should be good -- in most circumstances. For people with large L2 caches, you may want -- to increase this to fit your cache. -- -- This module is intended to be imported <tt>qualified</tt>, to avoid -- name clashes with <a>Prelude</a> functions. eg. -- -- <pre> -- import qualified Data.ByteString.Lazy as B -- </pre> -- -- Original GHC implementation by Bryan O'Sullivan. Rewritten to use -- <a>UArray</a> by Simon Marlow. Rewritten to support slices and use -- <a>ForeignPtr</a> by David Roundy. Polished and extended by Don -- Stewart. Lazy variant by Duncan Coutts and Don Stewart. module Data.ByteString.Lazy -- | A space-efficient representation of a Word8 vector, supporting many -- efficient operations. A <a>ByteString</a> contains 8-bit characters -- only. -- -- Instances of Eq, Ord, Read, Show, Data, Typeable data ByteString -- | <i>O(1)</i> The empty <a>ByteString</a> empty :: ByteString -- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a> singleton :: Word8 -> ByteString -- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>. pack :: [Word8] -> ByteString -- | <i>O(n)</i> Converts a <a>ByteString</a> to a '[Word8]'. unpack :: ByteString -> [Word8] -- | <i>O(c)</i> Convert a list of strict <a>ByteString</a> into a lazy -- <a>ByteString</a> fromChunks :: [ByteString] -> ByteString -- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a list of strict -- <a>ByteString</a> toChunks :: ByteString -> [ByteString] -- | <i>O(1)</i> <a>cons</a> is analogous to '(:)' for lists. cons :: Word8 -> ByteString -> ByteString -- | <i>O(1)</i> Unlike <a>cons</a>, 'cons\'' is strict in the ByteString -- that we are consing onto. More precisely, it forces the head and the -- first chunk. It does this because, for space efficiency, it may -- coalesce the new byte onto the first 'chunk' rather than starting a -- new 'chunk'. -- -- So that means you can't use a lazy recursive contruction like this: -- -- <pre> -- let xs = cons\' c xs in xs -- </pre> -- -- You can however use <a>cons</a>, as well as <a>repeat</a> and -- <a>cycle</a>, to build infinite lazy ByteStrings. cons' :: Word8 -> ByteString -> ByteString -- | <i>O(n\</i>c)/ Append a byte to the end of a <a>ByteString</a> snoc :: ByteString -> Word8 -> ByteString -- | <i>O(n\</i>c)/ Append two ByteStrings append :: ByteString -> ByteString -> ByteString -- | <i>O(1)</i> Extract the first element of a ByteString, which must be -- non-empty. head :: ByteString -> Word8 -- | <i>O(1)</i> Extract the head and tail of a ByteString, returning -- Nothing if it is empty. uncons :: ByteString -> Maybe (Word8, ByteString) -- | <i>O(n\</i>c)/ Extract the last element of a ByteString, which must be -- finite and non-empty. last :: ByteString -> Word8 -- | <i>O(1)</i> Extract the elements after the head of a ByteString, which -- must be non-empty. tail :: ByteString -> ByteString -- | <i>O(n\</i>c)/ Return all the elements of a <a>ByteString</a> except -- the last one. init :: ByteString -> ByteString -- | <i>O(1)</i> Test whether a ByteString is empty. null :: ByteString -> Bool -- | <i>O(n\</i>c)/ <a>length</a> returns the length of a ByteString as an -- <a>Int64</a> length :: ByteString -> Int64 -- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by -- applying <tt>f</tt> to each element of <tt>xs</tt>. map :: (Word8 -> Word8) -> ByteString -> ByteString -- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> returns the elements of -- <tt>xs</tt> in reverse order. reverse :: ByteString -> ByteString -- | The <a>intersperse</a> function takes a <a>Word8</a> and a -- <a>ByteString</a> and `intersperses' that byte between the elements of -- the <a>ByteString</a>. It is analogous to the intersperse function on -- Lists. intersperse :: Word8 -> ByteString -> ByteString -- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a> -- and a list of <a>ByteString</a>s and concatenates the list after -- interspersing the first argument between each element of the list. intercalate :: ByteString -> [ByteString] -> ByteString -- | The <a>transpose</a> function transposes the rows and columns of its -- <a>ByteString</a> argument. transpose :: [ByteString] -> [ByteString] -- | <a>foldl</a>, applied to a binary operator, a starting value -- (typically the left-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from left to right. foldl :: (a -> Word8 -> a) -> a -> ByteString -> a -- | 'foldl\'' is like <a>foldl</a>, but strict in the accumulator. foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a -- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value -- argument, and thus must be applied to non-empty <tt>ByteStrings</tt>. -- This function is subject to array fusion. foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator. foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | <a>foldr</a>, applied to a binary operator, a starting value -- (typically the right-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from right to left. foldr :: (Word8 -> a -> a) -> a -> ByteString -> a -- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value -- argument, and thus must be applied to non-empty <a>ByteString</a>s foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | <i>O(n)</i> Concatenate a list of ByteStrings. concat :: [ByteString] -> ByteString -- | Map a function over a <a>ByteString</a> and concatenate the results concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString -- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a> -- determines if any element of the <a>ByteString</a> satisfies the -- predicate. any :: (Word8 -> Bool) -> ByteString -> Bool -- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a> -- determines if all elements of the <a>ByteString</a> satisfy the -- predicate. all :: (Word8 -> Bool) -> ByteString -> Bool -- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a -- <a>ByteString</a> maximum :: ByteString -> Word8 -- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a -- <a>ByteString</a> minimum :: ByteString -> Word8 -- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of -- successive reduced values from the left. This function will fuse. -- -- <pre> -- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...] -- </pre> -- -- Note that -- -- <pre> -- last (scanl f z xs) == foldl f z xs. -- </pre> scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString -- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a> -- and <a>foldl</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from left to right, and -- returning a final value of this accumulator together with the new -- ByteString. mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) -- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a> -- and <a>foldr</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from right to left, and -- returning a final value of this accumulator together with the new -- ByteString. mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) -- | <tt><a>repeat</a> x</tt> is an infinite ByteString, with <tt>x</tt> -- the value of every element. repeat :: Word8 -> ByteString -- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length -- <tt>n</tt> with <tt>x</tt> the value of every element. replicate :: Int64 -> Word8 -> ByteString -- | <a>cycle</a> ties a finite ByteString into a circular one, or -- equivalently, the infinite repetition of the original ByteString. cycle :: ByteString -> ByteString -- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated -- applications of <tt>f</tt> to <tt>x</tt>: -- -- <pre> -- iterate f x == [x, f x, f (f x), ...] -- </pre> iterate :: (Word8 -> Word8) -> Word8 -> ByteString -- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the List -- 'unfoldr'. <a>unfoldr</a> builds a ByteString from a seed value. The -- function takes the element and returns <a>Nothing</a> if it is done -- producing the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in -- which case, <tt>a</tt> is a prepending to the ByteString and -- <tt>b</tt> is used as the next element in a recursive call. unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString -- | <i>O(n\</i>c)/ <a>take</a> <tt>n</tt>, applied to a ByteString -- <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>, -- or <tt>xs</tt> itself if <tt>n > <a>length</a> xs</tt>. take :: Int64 -> ByteString -> ByteString -- | <i>O(n\</i>c)/ <a>drop</a> <tt>n xs</tt> returns the suffix of -- <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if -- <tt>n > <a>length</a> xs</tt>. drop :: Int64 -> ByteString -> ByteString -- | <i>O(n\</i>c)/ <a>splitAt</a> <tt>n xs</tt> is equivalent to -- <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>. splitAt :: Int64 -> ByteString -> (ByteString, ByteString) -- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString -- <tt>xs</tt>, returns the longest prefix (possibly empty) of -- <tt>xs</tt> of elements that satisfy <tt>p</tt>. takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString -- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after -- <a>takeWhile</a> <tt>p xs</tt>. dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString -- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It -- is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p -- xs)</tt> span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> . -- p)</tt>. break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | The <a>group</a> 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, -- -- <pre> -- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"] -- </pre> -- -- It is a special case of <a>groupBy</a>, which allows the programmer to -- supply their own equality test. group :: ByteString -> [ByteString] -- | The <a>groupBy</a> function is the non-overloaded version of -- <a>group</a>. groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString] -- | <i>O(n)</i> Return all initial segments of the given -- <a>ByteString</a>, shortest first. inits :: ByteString -> [ByteString] -- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>, -- longest first. tails :: ByteString -> [ByteString] -- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the -- byte argument, consuming the delimiter. I.e. -- -- <pre> -- split '\n' "a\nb\nd\ne" == ["a","b","d","e"] -- split 'a' "aXaXaXa" == ["","X","X","X",""] -- split 'x' "x" == ["",""] -- </pre> -- -- and -- -- <pre> -- intercalate [c] . split c == id -- split == splitWith . (==) -- </pre> -- -- As for all splitting functions in this library, this function does not -- copy the substrings, it just constructs new <tt>ByteStrings</tt> that -- are slices of the original. split :: Word8 -> ByteString -> [ByteString] -- | <i>O(n)</i> Splits a <a>ByteString</a> 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. -- -- <pre> -- splitWith (=='a') "aabbaca" == ["","","bb","c",""] -- splitWith (=='a') [] == [] -- </pre> splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString] -- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and -- returns <a>True</a> iff the first is a prefix of the second. isPrefixOf :: ByteString -> ByteString -> Bool -- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and -- returns <a>True</a> iff the first is a suffix of the second. -- -- The following holds: -- -- <pre> -- isSuffixOf x y == reverse x `isPrefixOf` reverse y -- </pre> isSuffixOf :: ByteString -> ByteString -> Bool -- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate. elem :: Word8 -> ByteString -> Bool -- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a> notElem :: Word8 -> ByteString -> Bool -- | <i>O(n)</i> The <a>find</a> function takes a predicate and a -- ByteString, and returns the first element in matching the predicate, -- or <a>Nothing</a> if there is no such element. -- -- <pre> -- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing -- </pre> find :: (Word8 -> Bool) -> ByteString -> Maybe Word8 -- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString, -- returns a ByteString containing those characters that satisfy the -- predicate. filter :: (Word8 -> Bool) -> ByteString -> ByteString -- | <i>O(n)</i> The <a>partition</a> function takes a predicate a -- ByteString and returns the pair of ByteStrings with elements which do -- and do not satisfy the predicate, respectively; i.e., -- -- <pre> -- partition p bs == (filter p xs, filter (not . p) xs) -- </pre> partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | <i>O(c)</i> <a>ByteString</a> index (subscript) operator, starting -- from 0. index :: ByteString -> Int64 -> Word8 -- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the -- first element in the given <a>ByteString</a> which is equal to the -- query element, or <a>Nothing</a> if there is no such element. This -- implementation uses memchr(3). elemIndex :: Word8 -> ByteString -> Maybe Int64 -- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>, -- by returning the indices of all elements equal to the query element, -- in ascending order. This implementation uses memchr(3). elemIndices :: Word8 -> ByteString -> [Int64] -- | The <a>findIndex</a> function takes a predicate and a -- <a>ByteString</a> and returns the index of the first element in the -- ByteString satisfying the predicate. findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int64 -- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning -- the indices of all elements satisfying the predicate, in ascending -- order. findIndices :: (Word8 -> Bool) -> ByteString -> [Int64] -- | count returns the number of times its argument appears in the -- ByteString -- -- <pre> -- count = length . elemIndices -- </pre> -- -- But more efficiently than using length on the intermediate list. count :: Word8 -> ByteString -> Int64 -- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of -- corresponding pairs of bytes. If one input ByteString is short, excess -- elements of the longer ByteString are discarded. This is equivalent to -- a pair of <a>unpack</a> operations. zip :: ByteString -> ByteString -> [(Word8, Word8)] -- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function -- given as the first argument, instead of a tupling function. For -- example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to -- produce the list of corresponding sums. zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a] -- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a -- pair of ByteStrings. Note that this performs two <a>pack</a> -- operations. unzip :: [(Word8, Word8)] -> (ByteString, ByteString) -- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage. -- This is mainly useful to allow the rest of the data pointed to by the -- <a>ByteString</a> to be garbage collected, for example if a large -- string has been read in, and only a small part of it is needed in the -- rest of the program. copy :: ByteString -> ByteString -- | getContents. Equivalent to hGetContents stdin. Will read <i>lazily</i> getContents :: IO ByteString -- | Write a ByteString to stdout putStr :: ByteString -> IO () -- | Write a ByteString to stdout, appending a newline byte -- | <i>Deprecated: Use Data.ByteString.Lazy.Char8.putStrLn instead. -- (Functions that rely on ASCII encodings belong in -- Data.ByteString.Lazy.Char8)</i> putStrLn :: ByteString -> IO () -- | The interact function takes a function of type <tt>ByteString -> -- ByteString</tt> as its argument. The entire input from the standard -- input device is passed to this function as its argument, and the -- resulting string is output on the standard output device. interact :: (ByteString -> ByteString) -> IO () -- | Read an entire file <i>lazily</i> into a <a>ByteString</a>. The Handle -- will be held open until EOF is encountered. readFile :: FilePath -> IO ByteString -- | Write a <a>ByteString</a> to a file. writeFile :: FilePath -> ByteString -> IO () -- | Append a <a>ByteString</a> to a file. appendFile :: FilePath -> ByteString -> IO () -- | Read entire handle contents <i>lazily</i> into a <a>ByteString</a>. -- Chunks are read on demand, using the default chunk size. -- -- Once EOF is encountered, the Handle is closed. -- -- Note: the <a>Handle</a> should be placed in binary mode with -- <a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly. hGetContents :: Handle -> IO ByteString -- | Read <tt>n</tt> bytes into a <a>ByteString</a>, directly from the -- specified <a>Handle</a>. hGet :: Handle -> Int -> IO ByteString -- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never -- block waiting for data to become available, instead it returns only -- whatever data is available. If there is no data available to be read, -- <a>hGetNonBlocking</a> returns <a>empty</a>. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hGet</a>. hGetNonBlocking :: Handle -> Int -> IO ByteString -- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>. hPut :: Handle -> ByteString -> IO () -- | Similar to <a>hPut</a> except that it will never block. Instead it -- returns any tail that did not get written. This tail may be -- <a>empty</a> in the case that the whole string was written, or the -- whole original string if nothing was written. Partial writes are also -- possible. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hPut</a>. hPutNonBlocking :: Handle -> ByteString -> IO ByteString -- | A synonym for <tt>hPut</tt>, for compatibility hPutStr :: Handle -> ByteString -> IO () instance Monoid ByteString instance Ord ByteString instance Eq ByteString -- | Manipulate <i>lazy</i> <a>ByteString</a>s using <a>Char</a> -- operations. All Chars will be truncated to 8 bits. It can be expected -- that these functions will run at identical speeds to their -- <a>Word8</a> equivalents in <a>Data.ByteString.Lazy</a>. -- -- This module is intended to be imported <tt>qualified</tt>, to avoid -- name clashes with <a>Prelude</a> functions. eg. -- -- <pre> -- import qualified Data.ByteString.Lazy.Char8 as C -- </pre> module Data.ByteString.Lazy.Char8 -- | A space-efficient representation of a Word8 vector, supporting many -- efficient operations. A <a>ByteString</a> contains 8-bit characters -- only. -- -- Instances of Eq, Ord, Read, Show, Data, Typeable data ByteString -- | <i>O(1)</i> The empty <a>ByteString</a> empty :: ByteString -- | <i>O(1)</i> Convert a <a>Char</a> into a <a>ByteString</a> singleton :: Char -> ByteString -- | <i>O(n)</i> Convert a <a>String</a> into a <a>ByteString</a>. pack :: [Char] -> ByteString -- | <i>O(n)</i> Converts a <a>ByteString</a> to a <a>String</a>. unpack :: ByteString -> [Char] -- | <i>O(c)</i> Convert a list of strict <a>ByteString</a> into a lazy -- <a>ByteString</a> fromChunks :: [ByteString] -> ByteString -- | <i>O(n)</i> Convert a lazy <a>ByteString</a> into a list of strict -- <a>ByteString</a> toChunks :: ByteString -> [ByteString] -- | <i>O(1)</i> <a>cons</a> is analogous to '(:)' for lists. cons :: Char -> ByteString -> ByteString -- | <i>O(1)</i> Unlike <a>cons</a>, 'cons\'' is strict in the ByteString -- that we are consing onto. More precisely, it forces the head and the -- first chunk. It does this because, for space efficiency, it may -- coalesce the new byte onto the first 'chunk' rather than starting a -- new 'chunk'. -- -- So that means you can't use a lazy recursive contruction like this: -- -- <pre> -- let xs = cons\' c xs in xs -- </pre> -- -- You can however use <a>cons</a>, as well as <a>repeat</a> and -- <a>cycle</a>, to build infinite lazy ByteStrings. cons' :: Char -> ByteString -> ByteString -- | <i>O(n)</i> Append a Char to the end of a <a>ByteString</a>. Similar -- to <a>cons</a>, this function performs a memcpy. snoc :: ByteString -> Char -> ByteString -- | <i>O(n\</i>c)/ Append two ByteStrings append :: ByteString -> ByteString -> ByteString -- | <i>O(1)</i> Extract the first element of a ByteString, which must be -- non-empty. head :: ByteString -> Char -- | <i>O(1)</i> Extract the head and tail of a ByteString, returning -- Nothing if it is empty. uncons :: ByteString -> Maybe (Char, ByteString) -- | <i>O(1)</i> Extract the last element of a packed string, which must be -- non-empty. last :: ByteString -> Char -- | <i>O(1)</i> Extract the elements after the head of a ByteString, which -- must be non-empty. tail :: ByteString -> ByteString -- | <i>O(n\</i>c)/ Return all the elements of a <a>ByteString</a> except -- the last one. init :: ByteString -> ByteString -- | <i>O(1)</i> Test whether a ByteString is empty. null :: ByteString -> Bool -- | <i>O(n\</i>c)/ <a>length</a> returns the length of a ByteString as an -- <a>Int64</a> length :: ByteString -> Int64 -- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by -- applying <tt>f</tt> to each element of <tt>xs</tt> map :: (Char -> Char) -> ByteString -> ByteString -- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> returns the elements of -- <tt>xs</tt> in reverse order. reverse :: ByteString -> ByteString -- | <i>O(n)</i> The <a>intersperse</a> function takes a Char and a -- <a>ByteString</a> and `intersperses' that Char between the elements of -- the <a>ByteString</a>. It is analogous to the intersperse function on -- Lists. intersperse :: Char -> ByteString -> ByteString -- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a> -- and a list of <a>ByteString</a>s and concatenates the list after -- interspersing the first argument between each element of the list. intercalate :: ByteString -> [ByteString] -> ByteString -- | The <a>transpose</a> function transposes the rows and columns of its -- <a>ByteString</a> argument. transpose :: [ByteString] -> [ByteString] -- | <a>foldl</a>, applied to a binary operator, a starting value -- (typically the left-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from left to right. foldl :: (a -> Char -> a) -> a -> ByteString -> a -- | 'foldl\'' is like foldl, but strict in the accumulator. foldl' :: (a -> Char -> a) -> a -> ByteString -> a -- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value -- argument, and thus must be applied to non-empty <tt>ByteStrings</tt>. foldl1 :: (Char -> Char -> Char) -> ByteString -> Char -- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator. foldl1' :: (Char -> Char -> Char) -> ByteString -> Char -- | <a>foldr</a>, applied to a binary operator, a starting value -- (typically the right-identity of the operator), and a packed string, -- reduces the packed string using the binary operator, from right to -- left. foldr :: (Char -> a -> a) -> a -> ByteString -> a -- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value -- argument, and thus must be applied to non-empty <a>ByteString</a>s foldr1 :: (Char -> Char -> Char) -> ByteString -> Char -- | <i>O(n)</i> Concatenate a list of ByteStrings. concat :: [ByteString] -> ByteString -- | Map a function over a <a>ByteString</a> and concatenate the results concatMap :: (Char -> ByteString) -> ByteString -> ByteString -- | Applied to a predicate and a ByteString, <a>any</a> determines if any -- element of the <a>ByteString</a> satisfies the predicate. any :: (Char -> Bool) -> ByteString -> Bool -- | Applied to a predicate and a <a>ByteString</a>, <a>all</a> determines -- if all elements of the <a>ByteString</a> satisfy the predicate. all :: (Char -> Bool) -> ByteString -> Bool -- | <a>maximum</a> returns the maximum value from a <a>ByteString</a> maximum :: ByteString -> Char -- | <a>minimum</a> returns the minimum value from a <a>ByteString</a> minimum :: ByteString -> Char -- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of -- successive reduced values from the left. This function will fuse. -- -- <pre> -- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...] -- </pre> -- -- Note that -- -- <pre> -- last (scanl f z xs) == foldl f z xs. -- </pre> scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString -- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a> -- and <a>foldl</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from left to right, and -- returning a final value of this accumulator together with the new -- ByteString. mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString) -- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a> -- and <a>foldr</a>; it applies a function to each element of a -- ByteString, passing an accumulating parameter from right to left, and -- returning a final value of this accumulator together with the new -- ByteString. mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString) -- | <tt><a>repeat</a> x</tt> is an infinite ByteString, with <tt>x</tt> -- the value of every element. repeat :: Char -> ByteString -- | <i>O(n)</i> <tt><a>replicate</a> n x</tt> is a ByteString of length -- <tt>n</tt> with <tt>x</tt> the value of every element. replicate :: Int64 -> Char -> ByteString -- | <a>cycle</a> ties a finite ByteString into a circular one, or -- equivalently, the infinite repetition of the original ByteString. cycle :: ByteString -> ByteString -- | <tt><a>iterate</a> f x</tt> returns an infinite ByteString of repeated -- applications of <tt>f</tt> to <tt>x</tt>: -- -- <pre> -- iterate f x == [x, f x, f (f x), ...] -- </pre> iterate :: (Char -> Char) -> Char -> ByteString -- | <i>O(n)</i> The <a>unfoldr</a> function is analogous to the List -- 'unfoldr'. <a>unfoldr</a> builds a ByteString from a seed value. The -- function takes the element and returns <a>Nothing</a> if it is done -- producing the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in -- which case, <tt>a</tt> is a prepending to the ByteString and -- <tt>b</tt> is used as the next element in a recursive call. unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString -- | <i>O(n\</i>c)/ <a>take</a> <tt>n</tt>, applied to a ByteString -- <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>, -- or <tt>xs</tt> itself if <tt>n > <a>length</a> xs</tt>. take :: Int64 -> ByteString -> ByteString -- | <i>O(n\</i>c)/ <a>drop</a> <tt>n xs</tt> returns the suffix of -- <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if -- <tt>n > <a>length</a> xs</tt>. drop :: Int64 -> ByteString -> ByteString -- | <i>O(n\</i>c)/ <a>splitAt</a> <tt>n xs</tt> is equivalent to -- <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>. splitAt :: Int64 -> ByteString -> (ByteString, ByteString) -- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString -- <tt>xs</tt>, returns the longest prefix (possibly empty) of -- <tt>xs</tt> of elements that satisfy <tt>p</tt>. takeWhile :: (Char -> Bool) -> ByteString -> ByteString -- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after -- <a>takeWhile</a> <tt>p xs</tt>. dropWhile :: (Char -> Bool) -> ByteString -> ByteString -- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It -- is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p -- xs)</tt> span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) -- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> . -- p)</tt>. break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) -- | The <a>group</a> 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, -- -- <pre> -- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"] -- </pre> -- -- It is a special case of <a>groupBy</a>, which allows the programmer to -- supply their own equality test. group :: ByteString -> [ByteString] -- | The <a>groupBy</a> function is the non-overloaded version of -- <a>group</a>. groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString] -- | <i>O(n)</i> Return all initial segments of the given -- <a>ByteString</a>, shortest first. inits :: ByteString -> [ByteString] -- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>, -- longest first. tails :: ByteString -> [ByteString] -- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the -- byte argument, consuming the delimiter. I.e. -- -- <pre> -- split '\n' "a\nb\nd\ne" == ["a","b","d","e"] -- split 'a' "aXaXaXa" == ["","X","X","X"] -- split 'x' "x" == ["",""] -- </pre> -- -- and -- -- <pre> -- intercalate [c] . split c == id -- split == splitWith . (==) -- </pre> -- -- As for all splitting functions in this library, this function does not -- copy the substrings, it just constructs new <tt>ByteStrings</tt> that -- are slices of the original. split :: Char -> ByteString -> [ByteString] -- | <i>O(n)</i> Splits a <a>ByteString</a> 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. -- -- <pre> -- splitWith (=='a') "aabbaca" == ["","","bb","c",""] -- </pre> splitWith :: (Char -> Bool) -> ByteString -> [ByteString] -- | <a>lines</a> breaks a ByteString up into a list of ByteStrings at -- newline Chars. The resulting strings do not contain newlines. -- -- As of bytestring 0.9.0.3, this function is stricter than its list -- cousin. lines :: ByteString -> [ByteString] -- | <a>words</a> breaks a ByteString up into a list of words, which were -- delimited by Chars representing white space. And -- -- <pre> -- tokens isSpace = words -- </pre> words :: ByteString -> [ByteString] -- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins -- lines, after appending a terminating newline to each. unlines :: [ByteString] -> ByteString -- | The <a>unwords</a> function is analogous to the <a>unlines</a> -- function, on words. unwords :: [ByteString] -> ByteString -- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and -- returns <a>True</a> iff the first is a prefix of the second. isPrefixOf :: ByteString -> ByteString -> Bool -- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate. -- This implementation uses <tt>memchr(3)</tt>. elem :: Char -> ByteString -> Bool -- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a> notElem :: Char -> ByteString -> Bool -- | <i>O(n)</i> The <a>find</a> function takes a predicate and a -- ByteString, and returns the first element in matching the predicate, -- or <a>Nothing</a> if there is no such element. find :: (Char -> Bool) -> ByteString -> Maybe Char -- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString, -- returns a ByteString containing those characters that satisfy the -- predicate. filter :: (Char -> Bool) -> ByteString -> ByteString -- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting -- from 0. index :: ByteString -> Int64 -> Char -- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the -- first element in the given <a>ByteString</a> which is equal (by -- memchr) to the query element, or <a>Nothing</a> if there is no such -- element. elemIndex :: Char -> ByteString -> Maybe Int64 -- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>, -- by returning the indices of all elements equal to the query element, -- in ascending order. elemIndices :: Char -> ByteString -> [Int64] -- | The <a>findIndex</a> function takes a predicate and a -- <a>ByteString</a> and returns the index of the first element in the -- ByteString satisfying the predicate. findIndex :: (Char -> Bool) -> ByteString -> Maybe Int64 -- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning -- the indices of all elements satisfying the predicate, in ascending -- order. findIndices :: (Char -> Bool) -> ByteString -> [Int64] -- | count returns the number of times its argument appears in the -- ByteString -- -- <pre> -- count == length . elemIndices -- count '\n' == length . lines -- </pre> -- -- But more efficiently than using length on the intermediate list. count :: Char -> ByteString -> Int64 -- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of -- corresponding pairs of Chars. If one input ByteString is short, excess -- elements of the longer ByteString are discarded. This is equivalent to -- a pair of <a>unpack</a> operations, and so space usage may be large -- for multi-megabyte ByteStrings zip :: ByteString -> ByteString -> [(Char, Char)] -- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function -- given as the first argument, instead of a tupling function. For -- example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to -- produce the list of corresponding sums. zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a] -- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage. -- This is mainly useful to allow the rest of the data pointed to by the -- <a>ByteString</a> to be garbage collected, for example if a large -- string has been read in, and only a small part of it is needed in the -- rest of the program. copy :: ByteString -> ByteString -- | readInt reads an Int from the beginning of the ByteString. If there is -- no integer at the beginning of the string, it returns Nothing, -- otherwise it just returns the int read, and the rest of the string. readInt :: ByteString -> Maybe (Int, ByteString) -- | readInteger reads an Integer from the beginning of the ByteString. If -- there is no integer at the beginning of the string, it returns -- Nothing, otherwise it just returns the int read, and the rest of the -- string. readInteger :: ByteString -> Maybe (Integer, ByteString) -- | getContents. Equivalent to hGetContents stdin. Will read <i>lazily</i> getContents :: IO ByteString -- | Write a ByteString to stdout putStr :: ByteString -> IO () -- | Write a ByteString to stdout, appending a newline byte putStrLn :: ByteString -> IO () -- | The interact function takes a function of type <tt>ByteString -> -- ByteString</tt> as its argument. The entire input from the standard -- input device is passed to this function as its argument, and the -- resulting string is output on the standard output device. interact :: (ByteString -> ByteString) -> IO () -- | Read an entire file <i>lazily</i> into a <a>ByteString</a>. Use 'text -- mode' on Windows to interpret newlines readFile :: FilePath -> IO ByteString -- | Write a <a>ByteString</a> to a file. writeFile :: FilePath -> ByteString -> IO () -- | Append a <a>ByteString</a> to a file. appendFile :: FilePath -> ByteString -> IO () -- | Read entire handle contents <i>lazily</i> into a <a>ByteString</a>. -- Chunks are read on demand, using the default chunk size. -- -- Once EOF is encountered, the Handle is closed. -- -- Note: the <a>Handle</a> should be placed in binary mode with -- <a>hSetBinaryMode</a> for <a>hGetContents</a> to work correctly. hGetContents :: Handle -> IO ByteString -- | Read <tt>n</tt> bytes into a <a>ByteString</a>, directly from the -- specified <a>Handle</a>. hGet :: Handle -> Int -> IO ByteString -- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never -- block waiting for data to become available, instead it returns only -- whatever data is available. If there is no data available to be read, -- <a>hGetNonBlocking</a> returns <a>empty</a>. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hGet</a>. hGetNonBlocking :: Handle -> Int -> IO ByteString -- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>. hPut :: Handle -> ByteString -> IO () -- | Similar to <a>hPut</a> except that it will never block. Instead it -- returns any tail that did not get written. This tail may be -- <a>empty</a> in the case that the whole string was written, or the -- whole original string if nothing was written. Partial writes are also -- possible. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- <a>hPut</a>. hPutNonBlocking :: Handle -> ByteString -> IO ByteString -- | A synonym for <tt>hPut</tt>, for compatibility hPutStr :: Handle -> ByteString -> IO () -- | Write a ByteString to a handle, appending a newline byte hPutStrLn :: Handle -> ByteString -> IO () instance IsString ByteString