Data.ByteString.Char8

bytestring-0.12.1.0: Fast, compact, strict and lazy byte strings with a list interface

Copyright | (c) Don Stewart 2006-2008 (c) Duncan Coutts 2006-2011
License | BSD-style
Maintainer | dons00@gmail.com, duncan@community.haskell.org
Stability | stable
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

Data.ByteString.Char8

Contents

- The `ByteString` type
- Introducing and eliminating `ByteString`s
- Basic interface
- Transforming ByteStrings
- Reducing `ByteString`s (folds)
  - Special folds
- Building ByteStrings
  - Scans
  - Accumulating maps
  - Generating and unfolding ByteStrings
- Substrings
  - Breaking strings
  - Breaking into many substrings
  - Breaking into lines and words
- Predicates
  - Search for arbitrary substrings
- Searching ByteStrings
  - Searching by equality
  - Searching with a predicate
- Indexing ByteStrings
- Zipping and unzipping ByteStrings
- Ordered ByteStrings
- Reading from ByteStrings
- Low level CString conversions
  - Copying ByteStrings
  - Packing CStrings and pointers
  - Using ByteStrings as CStrings
- I/O with `ByteString`s
  - Standard input and output
  - Files
  - I/O with Handles

Description

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

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

See:

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

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

    import qualified Data.ByteString.Char8 as C

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 `{-# LANGUAGE OverloadedStrings #-}` to enable this.

Synopsis

- data ByteString
- empty :: ByteString
- singleton :: Char -> ByteString
- pack :: String -> ByteString
- unpack :: ByteString -> [Char]
- fromStrict :: StrictByteString -> LazyByteString
- toStrict :: LazyByteString -> StrictByteString
- cons :: Char -> ByteString -> ByteString
- snoc :: ByteString -> Char -> ByteString
- append :: ByteString -> ByteString -> ByteString
- head :: ByteString -> Char
- uncons :: ByteString -> Maybe (Char, ByteString)
- unsnoc :: ByteString -> Maybe (ByteString, Char)
- last :: ByteString -> Char
- tail :: HasCallStack => ByteString -> ByteString
- init :: HasCallStack => ByteString -> ByteString
- null :: ByteString -> Bool
- length :: ByteString -> Int
- map :: (Char -> Char) -> ByteString -> ByteString
- reverse :: ByteString -> ByteString
- intersperse :: Char -> ByteString -> ByteString
- intercalate :: ByteString -> [ByteString] -> ByteString
- transpose :: [ByteString] -> [ByteString]
- foldl :: (a -> Char -> a) -> a -> ByteString -> a
- foldl' :: (a -> Char -> a) -> a -> ByteString -> a
- foldl1 :: (Char -> Char -> Char) -> ByteString -> Char
- foldl1' :: (Char -> Char -> Char) -> ByteString -> Char
- foldr :: (Char -> a -> a) -> a -> ByteString -> a
- foldr' :: (Char -> a -> a) -> a -> ByteString -> a
- foldr1 :: (Char -> Char -> Char) -> ByteString -> Char
- foldr1' :: (Char -> Char -> Char) -> ByteString -> Char
- concat :: [ByteString] -> ByteString
- concatMap :: (Char -> ByteString) -> ByteString -> ByteString
- any :: (Char -> Bool) -> ByteString -> Bool
- all :: (Char -> Bool) -> ByteString -> Bool
- maximum :: ByteString -> Char
- minimum :: ByteString -> Char
- scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString
- scanl1 :: (Char -> Char -> Char) -> ByteString -> ByteString
- scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString
- scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString
- mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)
- mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)
- replicate :: Int -> Char -> ByteString
- unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString
- unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> (ByteString, Maybe a)
- take :: Int -> ByteString -> ByteString
- takeEnd :: Int -> ByteString -> ByteString
- drop :: Int -> ByteString -> ByteString
- dropEnd :: Int -> ByteString -> ByteString
- splitAt :: Int -> ByteString -> (ByteString, ByteString)
- takeWhile :: (Char -> Bool) -> ByteString -> ByteString
- takeWhileEnd :: (Char -> Bool) -> ByteString -> ByteString
- dropWhile :: (Char -> Bool) -> ByteString -> ByteString
- dropWhileEnd :: (Char -> Bool) -> ByteString -> ByteString
- dropSpace :: ByteString -> ByteString
- span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
- spanEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
- break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
- breakEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
- group :: ByteString -> [ByteString]
- groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString]
- inits :: ByteString -> [ByteString]
- tails :: ByteString -> [ByteString]
- initsNE :: ByteString -> NonEmpty ByteString
- tailsNE :: ByteString -> NonEmpty ByteString
- strip :: ByteString -> ByteString
- stripPrefix :: ByteString -> ByteString -> Maybe ByteString
- stripSuffix :: ByteString -> ByteString -> Maybe ByteString
- split :: Char -> ByteString -> [ByteString]
- splitWith :: (Char -> Bool) -> ByteString -> [ByteString]
- lines :: ByteString -> [ByteString]
- words :: ByteString -> [ByteString]
- unlines :: [ByteString] -> ByteString
- unwords :: [ByteString] -> ByteString
- isPrefixOf :: ByteString -> ByteString -> Bool
- isSuffixOf :: ByteString -> ByteString -> Bool
- isInfixOf :: ByteString -> ByteString -> Bool
- breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)
- elem :: Char -> ByteString -> Bool
- notElem :: Char -> ByteString -> Bool
- find :: (Char -> Bool) -> ByteString -> Maybe Char
- filter :: (Char -> Bool) -> ByteString -> ByteString
- partition :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
- index :: ByteString -> Int -> Char
- indexMaybe :: ByteString -> Int -> Maybe Char
- (!?) :: ByteString -> Int -> Maybe Char
- elemIndex :: Char -> ByteString -> Maybe Int
- elemIndices :: Char -> ByteString -> [Int]
- elemIndexEnd :: Char -> ByteString -> Maybe Int
- findIndex :: (Char -> Bool) -> ByteString -> Maybe Int
- findIndices :: (Char -> Bool) -> ByteString -> [Int]
- findIndexEnd :: (Char -> Bool) -> ByteString -> Maybe Int
- count :: Char -> ByteString -> Int
- zip :: ByteString -> ByteString -> [(Char, Char)]
- zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a]
- packZipWith :: (Char -> Char -> Char) -> ByteString -> ByteString -> ByteString
- unzip :: [(Char, Char)] -> (ByteString, ByteString)
- sort :: ByteString -> ByteString
- readInt :: ByteString -> Maybe (Int, ByteString)
- readInt64 :: ByteString -> Maybe (Int64, ByteString)
- readInt32 :: ByteString -> Maybe (Int32, ByteString)
- readInt16 :: ByteString -> Maybe (Int16, ByteString)
- readInt8 :: ByteString -> Maybe (Int8, ByteString)
- readWord :: ByteString -> Maybe (Word, ByteString)
- readWord64 :: ByteString -> Maybe (Word64, ByteString)
- readWord32 :: ByteString -> Maybe (Word32, ByteString)
- readWord16 :: ByteString -> Maybe (Word16, ByteString)
- readWord8 :: ByteString -> Maybe (Word8, ByteString)
- readInteger :: ByteString -> Maybe (Integer, ByteString)
- readNatural :: ByteString -> Maybe (Natural, ByteString)
- copy :: ByteString -> ByteString
- packCString :: CString -> IO ByteString
- packCStringLen :: CStringLen -> IO ByteString
- useAsCString :: ByteString -> (CString -> IO a) -> IO a
- useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
- getLine :: IO ByteString
- getContents :: IO ByteString
- putStr :: ByteString -> IO ()
- putStrLn :: ByteString -> IO ()
- interact :: (ByteString -> ByteString) -> IO ()
- readFile :: FilePath -> IO ByteString
- writeFile :: FilePath -> ByteString -> IO ()
- appendFile :: FilePath -> ByteString -> IO ()
- hGetLine :: Handle -> IO ByteString
- hGetContents :: Handle -> IO ByteString
- hGet :: Handle -> Int -> IO ByteString
- hGetSome :: Handle -> Int -> IO ByteString
- hGetNonBlocking :: Handle -> Int -> IO ByteString
- hPut :: Handle -> ByteString -> IO ()
- hPutNonBlocking :: Handle -> ByteString -> IO ByteString
- hPutStr :: Handle -> ByteString -> IO ()
- hPutStrLn :: Handle -> ByteString -> IO ()

# The `ByteString` type

data ByteString Source #

A space-efficient representation of a `Word8` vector, supporting many efficient operations.

A `ByteString` contains 8-bit bytes, or by using the operations from Data.ByteString.Char8 it can be interpreted as containing 8-bit characters.

#### Instances

Instances details

NFData ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods rnf :: ByteString -> () Source #
Monoid ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods mempty :: ByteString # mappend :: ByteString -> ByteString -> ByteString # mconcat :: [ByteString] -> ByteString #
Semigroup ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods (<>) :: ByteString -> ByteString -> ByteString # sconcat :: NonEmpty ByteString -> ByteString # stimes :: Integral b => b -> ByteString -> ByteString #
Data ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ByteString -> c ByteString # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ByteString # toConstr :: ByteString -> Constr # dataTypeOf :: ByteString -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ByteString) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ByteString) # gmapT :: (forall b. Data b => b -> b) -> ByteString -> ByteString # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ByteString -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ByteString -> r # gmapQ :: (forall d. Data d => d -> u) -> ByteString -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> ByteString -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString #
IsString ByteString Source # | Beware: `fromString` truncates multi-byte characters to octets. e.g. "枯朶に烏のとまりけり秋の暮" becomes �6k�nh~�Q��n�
Instance details Defined in Data.ByteString.Internal.Type Methods fromString :: String -> ByteString #
IsList ByteString Source # | Since: bytestring-0.10.12.0
Instance details Defined in Data.ByteString.Internal.Type Associated Types
type Item ByteString |
Instance details Defined in Data.ByteString.Internal.Type type Item ByteString = Word8
Methods fromList :: [Item ByteString] -> ByteString # fromListN :: Int -> [Item ByteString] -> ByteString # toList :: ByteString -> [Item ByteString] #
Read ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods readsPrec :: Int -> ReadS ByteString # readList :: ReadS [ByteString] # readPrec :: ReadPrec ByteString # readListPrec :: ReadPrec [ByteString] #
Show ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods showsPrec :: Int -> ByteString -> ShowS # show :: ByteString -> String # showList :: [ByteString] -> ShowS #
Eq ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods (==) :: ByteString -> ByteString -> Bool Source # (/=) :: ByteString -> ByteString -> Bool Source #
Ord ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type Methods compare :: ByteString -> ByteString -> Ordering Source # (<) :: ByteString -> ByteString -> Bool Source # (<=) :: ByteString -> ByteString -> Bool Source # (>) :: ByteString -> ByteString -> Bool Source # (>=) :: ByteString -> ByteString -> Bool Source # max :: ByteString -> ByteString -> ByteString Source # min :: ByteString -> ByteString -> ByteString Source #
Lift ByteString Source # | Since: bytestring-0.11.2.0
Instance details Defined in Data.ByteString.Internal.Type Methods lift :: Quote m => ByteString -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => ByteString -> Code m ByteString Source #
type Item ByteString Source # |
Instance details Defined in Data.ByteString.Internal.Type type Item ByteString = Word8

# Introducing and eliminating `ByteString`s

empty :: ByteString Source #

O(1) The empty `ByteString`

singleton :: Char -> ByteString Source #

O(1) Convert a `Char` into a `ByteString`

pack :: String -> ByteString Source #

O(n) Convert a `String` into a `ByteString`

For applications with large numbers of string literals, pack can be a bottleneck.

unpack :: ByteString -> [Char] Source #

O(n) Converts a `ByteString` to a `String`.

fromStrict :: StrictByteString -> LazyByteString Source #

O(1) Convert a `StrictByteString` into a `LazyByteString`.

toStrict :: LazyByteString -> StrictByteString Source #

O(n) Convert a `LazyByteString` into a `StrictByteString`.

Note that this is an expensive operation that forces the whole `LazyByteString` into memory and then copies all the data. If possible, try to avoid converting back and forth between strict and lazy bytestrings.

# Basic interface

cons :: Char -> ByteString -> ByteString infixr 5 Source #

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

snoc :: ByteString -> Char -> ByteString infixl 5 Source #

O(n) Append a Char to the end of a `ByteString`. Similar to `cons`, this function performs a memcpy.

append :: ByteString -> ByteString -> ByteString Source #

O(n) Append two ByteStrings

head :: ByteString -> Char Source #

O(1) Extract the first element of a ByteString, which must be non-empty.

uncons :: ByteString -> Maybe (Char, ByteString) Source #

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

unsnoc :: ByteString -> Maybe (ByteString, Char) Source #

O(1) Extract the `init` and `last` of a ByteString, returning Nothing if it is empty.

last :: ByteString -> Char Source #

O(1) Extract the last element of a packed string, which must be non-empty.

tail :: HasCallStack => ByteString -> ByteString Source #

O(1) 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.

This is a partial function, consider using `uncons` instead.

init :: HasCallStack => ByteString -> ByteString Source #

O(1) Returns all the elements of a `ByteString` except the last one. An exception will be thrown in the case of an empty ByteString.

This is a partial function, consider using `unsnoc` instead.

null :: ByteString -> Bool Source #

O(1) Test whether a ByteString is empty.

length :: ByteString -> Int Source #

O(1) `length` returns the length of a ByteString as an `Int`.

# Transforming ByteStrings

map :: (Char -> Char) -> ByteString -> ByteString Source #

O(n) `map` `f xs` is the ByteString obtained by applying `f` to each element of `xs`

reverse :: ByteString -> ByteString Source #

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

intersperse :: Char -> ByteString -> ByteString Source #

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

intercalate :: ByteString -> [ByteString] -> ByteString Source #

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

transpose :: [ByteString] -> [ByteString] Source #

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

# Reducing `ByteString`s (folds)

foldl :: (a -> Char -> a) -> a -> ByteString -> a Source #

`foldl`, 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 Source #

`foldl'` is like foldl, but strict in the accumulator.

foldl1 :: (Char -> Char -> Char) -> ByteString -> Char Source #

`foldl1` is a variant of `foldl` that has no starting value argument, and thus must be applied to non-empty `ByteString`s.

foldl1' :: (Char -> Char -> Char) -> ByteString -> Char Source #

A strict version of `foldl1`

foldr :: (Char -> a -> a) -> a -> ByteString -> a Source #

`foldr`, 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 Source #

`foldr'` is a strict variant of foldr

foldr1 :: (Char -> Char -> Char) -> ByteString -> Char Source #

`foldr1` is a variant of `foldr` that has no starting value argument, and thus must be applied to non-empty `ByteString`s

foldr1' :: (Char -> Char -> Char) -> ByteString -> Char Source #

A strict variant of foldr1

## Special folds

concat :: [ByteString] -> ByteString Source #

O(n) Concatenate a list of ByteStrings.

concatMap :: (Char -> ByteString) -> ByteString -> ByteString Source #

Map a function over a `ByteString` and concatenate the results

any :: (Char -> Bool) -> ByteString -> Bool Source #

Applied to a predicate and a ByteString, `any` determines if any element of the `ByteString` satisfies the predicate.

all :: (Char -> Bool) -> ByteString -> Bool Source #

Applied to a predicate and a `ByteString`, `all` determines if all elements of the `ByteString` satisfy the predicate.

maximum :: ByteString -> Char Source #

`maximum` returns the maximum value from a `ByteString`

minimum :: ByteString -> Char Source #

`minimum` returns the minimum value from a `ByteString`

# Building ByteStrings

## Scans

scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString Source #

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

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

Note that

    last (scanl f z xs) == foldl f z xs.

scanl1 :: (Char -> Char -> Char) -> ByteString -> ByteString Source #

`scanl1` is a variant of `scanl` that has no starting value argument:

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

scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString Source #

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

scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString Source #

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

## Accumulating maps

mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString) Source #

The `mapAccumL` function behaves like a combination of `map` and `foldl`; 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.

mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString) Source #

The `mapAccumR` function behaves like a combination of `map` and `foldr`; 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.

## Generating and unfolding ByteStrings

replicate :: Int -> Char -> ByteString Source #

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

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

This implementation uses `memset(3)`

unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString Source #

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

Examples:

    unfoldr (\x -> if x <= '9' then Just (x, succ x) else Nothing) '0' == "0123456789"

unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> (ByteString, Maybe a) Source #

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

The following equation relates `unfoldrN` and `unfoldr`:

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

# Substrings

## Breaking strings

take :: Int -> ByteString -> ByteString Source #

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

takeEnd :: Int -> ByteString -> ByteString Source #

O(1) ``takeEnd` n xs` is equivalent to ``drop` (`length` xs - n) xs`. Takes `n` elements from end of bytestring.

    >>> takeEnd 3 "abcdefg"
    "efg"
    >>> takeEnd 0 "abcdefg"
    ""
    >>> takeEnd 4 "abc"
    "abc"

Since: bytestring-0.11.1.0

drop :: Int -> ByteString -> ByteString Source #

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

dropEnd :: Int -> ByteString -> ByteString Source #

O(1) ``dropEnd` n xs` is equivalent to ``take` (`length` xs - n) xs`. Drops `n` elements from end of bytestring.

    >>> dropEnd 3 "abcdefg"
    "abcd"
    >>> dropEnd 0 "abcdefg"
    "abcdefg"
    >>> dropEnd 4 "abc"
    ""

Since: bytestring-0.11.1.0

splitAt :: Int -> ByteString -> (ByteString, ByteString) Source #

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

takeWhile :: (Char -> Bool) -> ByteString -> ByteString Source #

`takeWhile`, applied to a predicate `p` and a ByteString `xs`, returns the longest prefix (possibly empty) of `xs` of elements that satisfy `p`.

takeWhileEnd :: (Char -> Bool) -> ByteString -> ByteString Source #

`takeWhileEnd`, applied to a predicate `p` and a ByteString `xs`, returns the longest suffix (possibly empty) of `xs` of elements that satisfy `p`.

Since: bytestring-0.10.12.0

dropWhile :: (Char -> Bool) -> ByteString -> ByteString Source #

`dropWhile` `p xs` returns the suffix remaining after `takeWhile` `p xs`.

dropWhileEnd :: (Char -> Bool) -> ByteString -> ByteString Source #

`dropWhileEnd` `p xs` returns the prefix remaining after `takeWhileEnd` `p xs`.

Since: bytestring-0.10.12.0

dropSpace :: ByteString -> ByteString Source #

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

    dropWhile isSpace == dropSpace

Since: bytestring-0.10.12.0

span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) Source #

`span` `p xs` breaks the ByteString into two segments. It is equivalent to `(`takeWhile` p xs, `dropWhile` p xs)`

spanEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) Source #

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

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

and

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

break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) Source #

`break` `p` is equivalent to ``span` (`not` . p)`.

breakEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) Source #

`breakEnd` behaves like `break` but from the end of the `ByteString`

breakEnd p == spanEnd (not.p)

group :: ByteString -> [ByteString] Source #

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

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

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

groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString] Source #

The `groupBy` function is the non-overloaded version of `group`.

inits :: ByteString -> [ByteString] Source #

O(n) Returns all initial segments of the given `ByteString`, shortest first.

tails :: ByteString -> [ByteString] Source #

O(n) Returns all final segments of the given `ByteString`, longest first.

initsNE :: ByteString -> NonEmpty ByteString Source #

O(n) Returns all initial segments of the given `ByteString`, shortest first.

Since: bytestring-0.11.4.0

tailsNE :: ByteString -> NonEmpty ByteString Source #

O(n) Returns all final segments of the given `ByteString`, longest first.

Since: bytestring-0.11.4.0

strip :: ByteString -> ByteString Source #

Remove leading and trailing white space from a `ByteString`.

Since: bytestring-0.10.12.0

stripPrefix :: ByteString -> ByteString -> Maybe ByteString Source #

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

Since: bytestring-0.10.8.0

stripSuffix :: ByteString -> ByteString -> Maybe ByteString Source #

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

## Breaking into many substrings

split :: Char -> ByteString -> [ByteString] Source #

O(n) Break a `ByteString` into pieces separated by the byte argument, consuming the delimiter. I.e.

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

and

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

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

splitWith :: (Char -> Bool) -> ByteString -> [ByteString] Source #

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

    splitWith (=='a') "aabbaca" == ["","","bb","c",""]
    splitWith undefined ""      == []  -- and not [""]

## Breaking into lines and words

lines :: ByteString -> [ByteString] Source #

`lines` breaks a ByteString up into a list of ByteStrings at newline Chars (`'\n'`). The resulting strings do not contain newlines.

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

words :: ByteString -> [ByteString] Source #

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

unlines :: [ByteString] -> ByteString Source #

`unlines` joins lines, appending a terminating newline after each.

Equivalent to ``concat` . Data.List.concatMap (\x -> [x, `singleton` '\n'])`.

unwords :: [ByteString] -> ByteString Source #

The `unwords` function is analogous to the `unlines` function, on words.

# Predicates

isPrefixOf :: ByteString -> ByteString -> Bool Source #

O(n) The `isPrefixOf` function takes two ByteStrings and returns `True` if the first is a prefix of the second.

isSuffixOf :: ByteString -> ByteString -> Bool Source #

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

The following holds:

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

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

isInfixOf :: ByteString -> ByteString -> Bool Source #

Check whether one string is a substring of another.

## Search for arbitrary substrings

breakSubstring Source #

Arguments

:: ByteString | String to search for
-> ByteString | String to search in
-> (ByteString, ByteString) | Head and tail of string broken at substring

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:

    break (== c) l == breakSubstring (singleton c) l

For example, to tokenise a string, dropping delimiters:

    tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
        where (h,t) = breakSubstring x y

To skip to the first occurrence of a string:

    snd (breakSubstring x y)

To take the parts of a string before a delimiter:

    fst (breakSubstring x y)

Note that calling `breakSubstring x` does some preprocessing work, so you should avoid unnecessarily duplicating breakSubstring calls with the same pattern.

# Searching ByteStrings

## Searching by equality

elem :: Char -> ByteString -> Bool Source #

O(n) `elem` is the `ByteString` membership predicate. This implementation uses `memchr(3)`.

notElem :: Char -> ByteString -> Bool Source #

O(n) `notElem` is the inverse of `elem`

## Searching with a predicate

find :: (Char -> Bool) -> ByteString -> Maybe Char Source #

O(n) The `find` function takes a predicate and a ByteString, and returns the first element in matching the predicate, or `Nothing` if there is no such element.

filter :: (Char -> Bool) -> ByteString -> ByteString Source #

O(n) `filter`, applied to a predicate and a ByteString, returns a ByteString containing those characters that satisfy the predicate.

partition :: (Char -> Bool) -> ByteString -> (ByteString, ByteString) Source #

Since: bytestring-0.10.12.0

# Indexing ByteStrings

index :: ByteString -> Int -> Char Source #

O(1) `ByteString` index (subscript) operator, starting from 0.

indexMaybe :: ByteString -> Int -> Maybe Char Source #

O(1) `ByteString` index, starting from 0, that returns `Just` if:

    0 <= n < length bs

Since: bytestring-0.11.0.0

(!?) :: ByteString -> Int -> Maybe Char Source #

O(1) `ByteString` index, starting from 0, that returns `Just` if:

    0 <= n < length bs

Since: bytestring-0.11.0.0

elemIndex :: Char -> ByteString -> Maybe Int Source #

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

elemIndices :: Char -> ByteString -> [Int] Source #

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

elemIndexEnd :: Char -> ByteString -> Maybe Int Source #

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

    elemIndexEnd c xs = case elemIndex c (reverse xs) of
      Nothing -> Nothing
      Just i  -> Just (length xs - 1 - i)

findIndex :: (Char -> Bool) -> ByteString -> Maybe Int Source #

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

findIndices :: (Char -> Bool) -> ByteString -> [Int] Source #

The `findIndices` function extends `findIndex`, by returning the indices of all elements satisfying the predicate, in ascending order.

findIndexEnd :: (Char -> Bool) -> ByteString -> Maybe Int Source #

O(n) The `findIndexEnd` function takes a predicate and a `ByteString` and returns the index of the last element in the ByteString satisfying the predicate.

Since: bytestring-0.11.1.0

count :: Char -> ByteString -> Int Source #

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

    count = length . elemIndices

Also

    count '\n' == length . lines

But more efficiently than using length on the intermediate list.

# Zipping and unzipping ByteStrings

zip :: ByteString -> ByteString -> [(Char, Char)] Source #

O(n) `zip` 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 `unpack` operations, and so space usage may be large for multi-megabyte ByteStrings

zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a] Source #

`zipWith` generalises `zip` by zipping with the function given as the first argument, instead of a tupling function. For example, ``zipWith` (+)` is applied to two ByteStrings to produce the list of corresponding sums.

packZipWith :: (Char -> Char -> Char) -> ByteString -> ByteString -> ByteString Source #

A specialised version of `zipWith` for the common case of a simultaneous map over two ByteStrings, to build a 3rd.

Since: bytestring-0.11.1.0

unzip :: [(Char, Char)] -> (ByteString, ByteString) Source #

`unzip` transforms a list of pairs of Chars into a pair of ByteStrings. Note that this performs two `pack` operations.

# Ordered ByteStrings

sort :: ByteString -> ByteString Source #

O(n) Sort a ByteString efficiently, using counting sort.

# Reading from ByteStrings

readInt :: ByteString -> Maybe (Int, ByteString) Source #

Try to read a signed `Int` value from the `ByteString`, returning `Just (val, str)` on success, where `val` is the value read and `str` is the rest of the input string. If the sequence of digits decodes to a value larger than can be represented by an `Int`, the returned value will be `Nothing`.

`readInt` does not ignore leading whitespace, the value must start immediately at the beginning of the input string.

#### Examples

Expand

    >>> readInt "-1729 sum of cubes"
    Just (-1729," sum of cubes")
    >>> readInt "+1: readInt also accepts a leading '+'"
    Just (1, ": readInt also accepts a leading '+'")
    >>> readInt "not a decimal number"
    Nothing
    >>> readInt "12345678901234567890 overflows maxBound"
    Nothing
    >>> readInt "-12345678901234567890 underflows minBound"
    Nothing

readInt64 :: ByteString -> Maybe (Int64, ByteString) Source #

A variant of `readInt` specialised to `Int64`.

readInt32 :: ByteString -> Maybe (Int32, ByteString) Source #

A variant of `readInt` specialised to `Int32`.

readInt16 :: ByteString -> Maybe (Int16, ByteString) Source #

A variant of `readInt` specialised to `Int16`.

readInt8 :: ByteString -> Maybe (Int8, ByteString) Source #

A variant of `readInt` specialised to `Int8`.

readWord :: ByteString -> Maybe (Word, ByteString) Source #

Try to read a `Word` value from the `ByteString`, returning `Just (val, str)` on success, where `val` is the value read and `str` is the rest of the input string. If the sequence of digits decodes to a value larger than can be represented by a `Word`, the returned value will be `Nothing`.

`readWord` does not ignore leading whitespace, the value must start with a decimal digit immediately at the beginning of the input string. Leading `+` signs are not accepted.

#### Examples

Expand

    >>> readWord "1729 sum of cubes"
    Just (1729," sum of cubes")
    >>> readWord "+1729 has an explicit sign"
    Nothing
    >>> readWord "not a decimal number"
    Nothing
    >>> readWord "98765432109876543210 overflows maxBound"
    Nothing

readWord64 :: ByteString -> Maybe (Word64, ByteString) Source #

A variant of `readWord` specialised to `Word64`.

readWord32 :: ByteString -> Maybe (Word32, ByteString) Source #

A variant of `readWord` specialised to `Word32`.

readWord16 :: ByteString -> Maybe (Word16, ByteString) Source #

A variant of `readWord` specialised to `Word16`.

readWord8 :: ByteString -> Maybe (Word8, ByteString) Source #

A variant of `readWord` specialised to `Word8`.

readInteger :: ByteString -> Maybe (Integer, ByteString) Source #

`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 `Integer` read, and the rest of the string.

`readInteger` does not ignore leading whitespace, the value must start immediately at the beginning of the input string.

#### Examples

Expand

    >>> readInteger "-000111222333444555666777888999 all done"
    Just (-111222333444555666777888999," all done")
    >>> readInteger "+1: readInteger also accepts a leading '+'"
    Just (1, ": readInteger also accepts a leading '+'")
    >>> readInteger "not a decimal number"
    Nothing

readNatural :: ByteString -> Maybe (Natural, ByteString) Source #

`readNatural` reads a `Natural` number from the beginning of the `ByteString`. If there is no `Natural` number at the beginning of the string, it returns `Nothing`, otherwise it just returns the number read, and the rest of the string.

`readNatural` does not ignore leading whitespace, the value must start with a decimal digit immediately at the beginning of the input string. Leading `+` signs are not accepted.

#### Examples

Expand

    >>> readNatural "000111222333444555666777888999 all done"
    Just (111222333444555666777888999," all done")
    >>> readNatural "+000111222333444555666777888999 explicit sign"
    Nothing
    >>> readNatural "not a decimal number"
    Nothing

# Low level CString conversions

## Copying ByteStrings

copy :: ByteString -> ByteString Source #

O(n) Make a copy of the `ByteString` with its own storage. This is mainly useful to allow the rest of the data pointed to by the `ByteString` 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.

## Packing CStrings and pointers

packCString :: CString -> IO ByteString Source #

O(n). Construct a new `ByteString` from a `CString`. The resulting `ByteString` is an immutable copy of the original `CString`, and is managed on the Haskell heap. The original `CString` must be null terminated.

packCStringLen :: CStringLen -> IO ByteString Source #

O(n). Construct a new `ByteString` from a `CStringLen`. The resulting `ByteString` is an immutable copy of the original `CStringLen`. The `ByteString` is a normal Haskell value and will be managed on the Haskell heap.

## Using ByteStrings as CStrings

useAsCString :: ByteString -> (CString -> IO a) -> IO a Source #

O(n) construction Use a `ByteString` with a function requiring a null-terminated `CString`. The `CString` is a copy and will be freed automatically; it must not be stored or used after the subcomputation finishes.

useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a Source #

O(n) construction Use a `ByteString` with a function requiring a `CStringLen`. As for `useAsCString` this function makes a copy of the original `ByteString`. It must not be stored or used after the subcomputation finishes.

Beware that this function is not required to add a terminating `NUL` byte at the end of the `CStringLen` it provides. If you need to construct a pointer to a null-terminated sequence, use `useAsCString` (and measure length independently if desired).

# I/O with `ByteString`s

ByteString I/O uses binary mode, without any character decoding or newline conversion. The fact that it does not respect the Handle newline mode is considered a flaw and may be changed in a future version.

## Standard input and output

getLine :: IO ByteString Source #

Read a line from stdin.

getContents :: IO ByteString Source #

getContents. Read stdin strictly. Equivalent to hGetContents stdin The `Handle` is closed after the contents have been read.

putStr :: ByteString -> IO () Source #

Write a ByteString to `stdout`.

putStrLn :: ByteString -> IO () Source #

Write a ByteString to `stdout`, appending a newline byte.

Unlike `putStr`, this is not atomic: other threads might write to `stdout` between writing of the bytestring and the newline.

interact :: (ByteString -> ByteString) -> IO () Source #

The interact function takes a function of type `ByteString -> ByteString` 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.

## Files

readFile :: FilePath -> IO ByteString Source #

Read an entire file strictly into a `ByteString`.

writeFile :: FilePath -> ByteString -> IO () Source #

Write a `ByteString` to a file.

appendFile :: FilePath -> ByteString -> IO () Source #

Append a `ByteString` to a file.

## I/O with Handles

hGetLine :: Handle -> IO ByteString Source #

Read a line from a handle

hGetContents :: Handle -> IO ByteString Source #

Read a handle's entire contents strictly into a `ByteString`.

This function reads chunks at a time, increasing the chunk size on each read. The final string is then reallocated to the appropriate size. For files > half of available memory, this may lead to memory exhaustion. Consider using `readFile` in this case.

The Handle is closed once the contents have been read, or if an exception is thrown.

hGet :: Handle -> Int -> IO ByteString Source #

Read a `ByteString` directly from the specified `Handle`. This is far more efficient than reading the characters into a `String` and then using `pack`. 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 `empty` if EOF has been reached.

`hGet` is implemented in terms of `hGetBuf`.

If the handle is a pipe or socket, and the writing end is closed, `hGet` will behave as if EOF was reached.

hGetSome :: Handle -> Int -> IO ByteString Source #

Like `hGet`, except that a shorter `ByteString` may be returned if there are not enough bytes immediately available to satisfy the whole request. `hGetSome` only blocks if there is no data available, and EOF has not yet been reached.

hGetNonBlocking :: Handle -> Int -> IO ByteString Source #

hGetNonBlocking is similar to `hGet`, 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, `hGetNonBlocking` returns `empty`.

Note: on Windows and with Haskell implementation other than GHC, this function does not work correctly; it behaves identically to `hGet`.

hPut :: Handle -> ByteString -> IO () Source #

Outputs a `ByteString` to the specified `Handle`.

hPutNonBlocking :: Handle -> ByteString -> IO ByteString Source #

Similar to `hPut` except that it will never block. Instead it returns any tail that did not get written. This tail may be `empty` 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 `hPut`.

hPutStr :: Handle -> ByteString -> IO () Source #

A synonym for `hPut`, for compatibility

hPutStrLn :: Handle -> ByteString -> IO () Source #

Write a ByteString to a handle, appending a newline byte.

Unlike `hPutStr`, this is not atomic: other threads might write to the handle between writing of the bytestring and the newline.