-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Fast, compact, strict and lazy byte strings with a list interface
--
-- An efficient compact, immutable byte string type (both strict and
-- lazy) suitable for binary or 8-bit character data.
--
-- The ByteString type represents sequences of bytes or 8-bit
-- characters. It is suitable for high performance use, both in terms of
-- large data quantities, or high speed requirements. The
-- ByteString functions follow the same style as Haskell's
-- ordinary lists, so it is easy to convert code from using String
-- to ByteString.
--
-- Two ByteString variants are provided:
--
--
-- - Strict ByteStrings keep the string as a single large array.
-- This makes them convenient for passing data between C and
-- Haskell.
-- - Lazy ByteStrings use a lazy list of strict chunks which
-- makes it suitable for I/O streaming tasks.
--
--
-- The Char8 modules provide a character-based view of the same
-- underlying ByteString types. This makes it convenient to handle
-- mixed binary and 8-bit character content (which is common in many file
-- formats and network protocols).
--
-- The Builder module provides an efficient way to build up
-- ByteStrings in an ad-hoc way by repeated concatenation. This is
-- ideal for fast serialisation or pretty printing.
--
-- There is also a ShortByteString type which has a lower memory
-- overhead and can be converted to or from a ByteString. It is
-- suitable for keeping many short strings in memory, especially
-- long-term, without incurring any possible heap fragmentation costs.
--
-- ByteStrings are not designed for Unicode. For Unicode strings
-- you should use the Text type from the text package.
--
-- These modules are intended to be imported qualified, to avoid name
-- clashes with Prelude functions, e.g.
--
--
-- import qualified Data.ByteString as BS
--
@package bytestring
@version 0.12.2.0
-- |
-- - Warning:* this module is internal. If you find that you need it
-- please contact the maintainers and explain what you are trying to do
-- and discuss what you would need in the public API. It is important
-- that you do this as the module may not be exposed at all in future
-- releases.
--
--
-- The maintainers are glad to accept patches for further standard
-- encodings of standard Haskell values.
--
-- If you need to write your own builder primitives, then be aware that
-- you are writing code with all safety belts off; i.e., *this is
-- the code that might make your application vulnerable to
-- buffer-overflow attacks!* The
-- Data.ByteString.Builder.Prim.Tests module provides you with
-- utilities for testing your encodings thoroughly.
module Data.ByteString.Builder.Prim.Internal
-- | The type used for sizes and sizeBounds of sizes.
type Size = Int
-- | A builder primitive that always results in a sequence of bytes of a
-- pre-determined, fixed size.
data FixedPrim a
fixedPrim :: Int -> (a -> Ptr Word8 -> IO ()) -> FixedPrim a
-- | The size of the sequences of bytes generated by this FixedPrim.
size :: FixedPrim a -> Int
runF :: FixedPrim a -> a -> Ptr Word8 -> IO ()
-- | The FixedPrim that always results in the zero-length sequence.
emptyF :: FixedPrim a
-- | Change a primitives such that it first applies a function to the value
-- to be encoded.
--
-- Note that primitives are Contravariant
-- http://hackage.haskell.org/package/contravariant. Hence, the
-- following laws hold.
--
--
-- contramapF id = id
-- contramapF f . contramapF g = contramapF (g . f)
--
contramapF :: (b -> a) -> FixedPrim a -> FixedPrim b
-- | Encode a pair by encoding its first component and then its second
-- component.
pairF :: FixedPrim a -> FixedPrim b -> FixedPrim (a, b)
-- | Deprecated: Deprecated since bytestring-0.12.1.0. This
-- function is dangerous in the presence of internal padding and makes
-- naive assumptions about alignment. * For a primitive Haskell type like
-- Int64, use the corresponding primitive like int64Host. *
-- For other types, it is recommended to manually write a small function
-- that performs the necessary unaligned write and zeroes or removes any
-- internal padding bits.
storableToF :: Storable a => FixedPrim a
-- | A builder primitive that always results in sequence of bytes that is
-- no longer than a pre-determined bound.
data BoundedPrim a
boundedPrim :: Int -> (a -> Ptr Word8 -> IO (Ptr Word8)) -> BoundedPrim a
-- | The bound on the size of sequences of bytes generated by this
-- BoundedPrim.
sizeBound :: BoundedPrim a -> Int
runB :: BoundedPrim a -> a -> Ptr Word8 -> IO (Ptr Word8)
-- | The BoundedPrim that always results in the zero-length
-- sequence.
emptyB :: BoundedPrim a
-- | Change a BoundedPrim such that it first applies a function to
-- the value to be encoded.
--
-- Note that BoundedPrims are Contravariant
-- http://hackage.haskell.org/package/contravariant. Hence, the
-- following laws hold.
--
--
-- contramapB id = id
-- contramapB f . contramapB g = contramapB (g . f)
--
contramapB :: (b -> a) -> BoundedPrim a -> BoundedPrim b
-- | Encode a pair by encoding its first component and then its second
-- component.
pairB :: BoundedPrim a -> BoundedPrim b -> BoundedPrim (a, b)
-- | Encode an Either value using the first BoundedPrim for
-- Left values and the second BoundedPrim for Right
-- values.
--
-- Note that the functions eitherB, pairB, and
-- contramapB (written below using >$<) suffice to
-- construct BoundedPrims for all non-recursive algebraic
-- datatypes. For example,
--
--
-- maybeB :: BoundedPrim () -> BoundedPrim a -> BoundedPrim (Maybe a)
-- maybeB nothing just = maybe (Left ()) Right >$< eitherB nothing just
--
--
eitherB :: BoundedPrim a -> BoundedPrim b -> BoundedPrim (Either a b)
-- | Conditionally select a BoundedPrim. For example, we can
-- implement the ASCII primitive that drops characters with Unicode
-- codepoints above 127 as follows.
--
--
-- charASCIIDrop = condB (< '\128') (liftFixedToBounded char7) emptyB
--
--
condB :: (a -> Bool) -> BoundedPrim a -> BoundedPrim a -> BoundedPrim a
-- | Convert a FixedPrim to a BoundedPrim.
toB :: FixedPrim a -> BoundedPrim a
-- | Lift a FixedPrim to a BoundedPrim.
liftFixedToBounded :: FixedPrim a -> BoundedPrim a
-- | A fmap-like operator for builder primitives, both bounded and fixed
-- size.
--
-- Builder primitives are contravariant so it's like the normal fmap, but
-- backwards (look at the type). (If it helps to remember, the operator
-- symbol is like ($) but backwards.)
--
-- We can use it for example to prepend and/or append fixed values to an
-- primitive.
--
--
-- import Data.ByteString.Builder.Prim as P
-- showEncoding ((\x -> ('\'', (x, '\''))) >$< fixed3) 'x' = "'x'"
-- where
-- fixed3 = P.char7 >*< P.char7 >*< P.char7
--
--
-- Note that the rather verbose syntax for composition stems from the
-- requirement to be able to compute the size / size bound at compile
-- time.
(>$<) :: Contravariant f => (b -> a) -> f a -> f b
infixl 4 >$<
-- | A pairing/concatenation operator for builder primitives, both bounded
-- and fixed size.
--
-- For example,
--
--
-- toLazyByteString (primFixed (char7 >*< char7) ('x','y')) = "xy"
--
--
-- We can combine multiple primitives using >*< multiple
-- times.
--
--
-- toLazyByteString (primFixed (char7 >*< char7 >*< char7) ('x',('y','z'))) = "xyz"
--
(>*<) :: Monoidal f => f a -> f b -> f (a, b)
infixr 5 >*<
-- | Select an implementation depending on bitness. Throw a compile time
-- error if bitness is neither 32 nor 64.
caseWordSize_32_64 :: a -> a -> a
-- | Deprecated: Use boundedPrim instead
boudedPrim :: Int -> (a -> Ptr Word8 -> IO (Ptr Word8)) -> BoundedPrim a
instance Data.ByteString.Builder.Prim.Internal.Contravariant Data.ByteString.Builder.Prim.Internal.BoundedPrim
instance Data.ByteString.Builder.Prim.Internal.Contravariant Data.ByteString.Builder.Prim.Internal.FixedPrim
instance Data.ByteString.Builder.Prim.Internal.Monoidal Data.ByteString.Builder.Prim.Internal.BoundedPrim
instance Data.ByteString.Builder.Prim.Internal.Monoidal Data.ByteString.Builder.Prim.Internal.FixedPrim
-- | A module containing semi-public ByteString internals. This
-- exposes the ByteString representation and low level
-- construction functions. As such all the functions in this module are
-- unsafe. The API is also not stable.
--
-- Where possible application should instead use the functions from the
-- normal public interface modules, such as
-- Data.ByteString.Unsafe. Packages that extend the ByteString
-- system at a low level will need to use this module.
module Data.ByteString.Internal
-- | 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.
data ByteString
BS :: {-# UNPACK #-} !ForeignPtr Word8 -> {-# UNPACK #-} !Int -> ByteString
-- | PS foreignPtr offset length represents a
-- ByteString with data backed by a given foreignPtr,
-- starting at a given offset in bytes and of a specified
-- length.
--
-- This pattern is used to emulate the legacy ByteString data
-- constructor, so that pre-existing code generally doesn't need to
-- change to benefit from the simplified BS constructor and can
-- continue to function unchanged.
--
-- Note: Matching with this constructor will always be given a 0
-- offset, as the base will be manipulated by plusForeignPtr
-- instead.
pattern PS :: ForeignPtr Word8 -> Int -> Int -> ByteString
-- | Type synonym for the strict flavour of ByteString.
type StrictByteString = ByteString
-- | findIndexOrLength is a variant of findIndex, that returns the
-- length of the string if no element is found, rather than Nothing.
findIndexOrLength :: (Word8 -> Bool) -> ByteString -> Int
packBytes :: [Word8] -> ByteString
packUptoLenBytes :: Int -> [Word8] -> (ByteString, [Word8])
unsafePackLenBytes :: Int -> [Word8] -> ByteString
packChars :: [Char] -> ByteString
packUptoLenChars :: Int -> [Char] -> (ByteString, [Char])
unsafePackLenChars :: Int -> [Char] -> ByteString
unpackBytes :: ByteString -> [Word8]
unpackAppendBytesLazy :: ByteString -> [Word8] -> [Word8]
unpackAppendBytesStrict :: ByteString -> [Word8] -> [Word8]
unpackChars :: ByteString -> [Char]
unpackAppendCharsLazy :: ByteString -> [Char] -> [Char]
unpackAppendCharsStrict :: ByteString -> [Char] -> [Char]
-- | O(n) Pack a null-terminated sequence of bytes, pointed to by an
-- Addr# (an arbitrary machine address assumed to point outside the
-- garbage-collected heap) into a ByteString. A much faster way
-- to create an Addr# is with an unboxed string literal, than to
-- pack a boxed string. A unboxed string literal is compiled to a static
-- char [] by GHC. Establishing the length of the string
-- requires a call to strlen(3), so the Addr# must point
-- to a null-terminated buffer (as is the case with "string"#
-- literals in GHC). Use unsafePackAddressLen if you know the
-- length of the string statically.
--
-- An example:
--
--
-- literalFS = unsafePackAddress "literal"#
--
--
-- This function is unsafe. If you modify the buffer pointed to by
-- the original Addr# this modification will be reflected in the
-- resulting ByteString, breaking referential transparency.
--
-- Note this also won't work if your Addr# has embedded
-- '\0' characters in the string, as strlen will return
-- too short a length.
unsafePackAddress :: Addr# -> IO ByteString
-- | See unsafePackAddress. This function is similar, but takes an
-- additional length argument rather then computing it with
-- strlen. Therefore embedding '\0' characters is
-- possible.
unsafePackLenAddress :: Int -> Addr# -> IO ByteString
-- | See unsafePackAddress. This function has similar behavior.
-- Prefer this function when the address in known to be an Addr#
-- literal. In that context, there is no need for the sequencing
-- guarantees that IO provides. On GHC 9.0 and up, this function
-- uses the FinalPtr data constructor for
-- ForeignPtrContents.
unsafePackLiteral :: Addr# -> ByteString
-- | See unsafePackLiteral. This function is similar, but takes an
-- additional length argument rather then computing it with
-- strlen. Therefore embedding '\0' characters is
-- possible.
unsafePackLenLiteral :: Int -> Addr# -> ByteString
-- | O(1) The empty ByteString
empty :: ByteString
-- | Create ByteString of size l and use action f to fill
-- its contents.
create :: Int -> (Ptr Word8 -> IO ()) -> IO ByteString
-- | Given a maximum size l and an action f that fills
-- the ByteString starting at the given Ptr and returns the
-- actual utilized length, createUptoN' l f returns the
-- filled ByteString.
createUptoN :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString
-- | Like createUptoN, but also returns an additional value created
-- by the action.
createUptoN' :: Int -> (Ptr Word8 -> IO (Int, a)) -> IO (ByteString, a)
-- | Given the maximum size needed and a function to make the contents of a
-- ByteString, createAndTrim makes the ByteString. The generating
-- function is required to return the actual final size (<= the
-- maximum size), and the resulting byte array is reallocated to this
-- size.
--
-- createAndTrim is the main mechanism for creating custom, efficient
-- ByteString functions, using Haskell or C functions to fill the space.
createAndTrim :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString
createAndTrim' :: Int -> (Ptr Word8 -> IO (Int, Int, a)) -> IO (ByteString, a)
-- | A way of creating ByteStrings outside the IO monad. The Int
-- argument gives the final size of the ByteString.
unsafeCreate :: Int -> (Ptr Word8 -> IO ()) -> ByteString
-- | Like unsafeCreate but instead of giving the final size of the
-- ByteString, it is just an upper bound. The inner action returns the
-- actual size. Unlike createAndTrim the ByteString is not
-- reallocated if the final size is less than the estimated size.
unsafeCreateUptoN :: Int -> (Ptr Word8 -> IO Int) -> ByteString
unsafeCreateUptoN' :: Int -> (Ptr Word8 -> IO (Int, a)) -> (ByteString, a)
-- | Wrapper of mallocForeignPtrBytes with faster implementation for
-- GHC
mallocByteString :: Int -> IO (ForeignPtr a)
-- | Variant of fromForeignPtr0 that calls
-- deferForeignPtrAvailability
mkDeferredByteString :: ForeignPtr Word8 -> Int -> IO ByteString
-- | O(1) Build a ByteString from a ForeignPtr.
--
-- If you do not need the offset parameter then you should be using
-- unsafePackCStringLen or unsafePackCStringFinalizer
-- instead.
fromForeignPtr :: ForeignPtr Word8 -> Int -> Int -> ByteString
-- | O(1) Deconstruct a ForeignPtr from a ByteString
toForeignPtr :: ByteString -> (ForeignPtr Word8, Int, Int)
fromForeignPtr0 :: ForeignPtr Word8 -> Int -> ByteString
-- | O(1) Deconstruct a ForeignPtr from a ByteString
toForeignPtr0 :: ByteString -> (ForeignPtr Word8, Int)
-- | The 0 pointer. Used to indicate the empty Bytestring.
nullForeignPtr :: ForeignPtr Word8
-- | Most operations on a ByteString need to read from the buffer
-- given by its ForeignPtr Word8 field. But since most
-- operations on ByteString are (nominally) pure, their
-- implementations cannot see the IO state thread that was used to
-- initialize the contents of that buffer. This means that under some
-- circumstances, these buffer-reads may be executed before the writes
-- used to initialize the buffer are executed, with unpredictable
-- results.
--
-- deferForeignPtrAvailability exists to help solve this problem.
-- At runtime, a call deferForeignPtrAvailability x is
-- equivalent to pure $! x, but the former is more opaque to the
-- simplifier, so that reads from the pointer in its result cannot be
-- executed until the deferForeignPtrAvailability x call
-- is complete.
--
-- The opaque bits evaporate during CorePrep, so using
-- deferForeignPtrAvailability incurs no direct overhead.
deferForeignPtrAvailability :: ForeignPtr a -> IO (ForeignPtr a)
-- | The type of exception raised by overflowError and on failure by
-- overflow-checked arithmetic operations.
data SizeOverflowException
-- | Raises a SizeOverflowException, with a message using the given
-- function name.
overflowError :: String -> a
-- | Add two non-negative numbers. Calls overflowError on overflow.
checkedAdd :: String -> Int -> Int -> Int
-- | Multiplies two non-negative numbers. Calls overflowError on
-- overflow.
checkedMultiply :: String -> Int -> Int -> Int
c_strlen :: CString -> IO CSize
c_free_finalizer :: FunPtr (Ptr Word8 -> IO ())
memchr :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
memcmp :: Ptr Word8 -> Ptr Word8 -> Int -> IO CInt
-- | deprecated since bytestring-0.11.5.0
-- | Deprecated: Use Foreign.Marshal.Utils.copyBytes instead
memcpy :: Ptr Word8 -> Ptr Word8 -> Int -> IO ()
-- | deprecated since bytestring-0.11.5.0
-- | Deprecated: Use Foreign.Marshal.Utils.fillBytes instead
memset :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
c_reverse :: Ptr Word8 -> Ptr Word8 -> CSize -> IO ()
c_intersperse :: Ptr Word8 -> Ptr Word8 -> CSize -> Word8 -> IO ()
c_maximum :: Ptr Word8 -> CSize -> IO Word8
c_minimum :: Ptr Word8 -> CSize -> IO Word8
c_count :: Ptr Word8 -> CSize -> Word8 -> IO CSize
c_sort :: Ptr Word8 -> CSize -> IO ()
-- | Conversion between Word8 and Char. Should compile to a
-- no-op.
w2c :: Word8 -> Char
-- | Unsafe conversion between Char and Word8. This is a
-- no-op and silently truncates to 8 bits Chars > '255'. It is
-- provided as convenience for ByteString construction.
c2w :: Char -> Word8
-- | Selects words corresponding to white-space characters in the Latin-1
-- range
isSpaceWord8 :: Word8 -> Bool
-- | Selects white-space characters in the Latin-1 range
isSpaceChar8 :: Char -> Bool
-- | This "function" has a superficial similarity to unsafePerformIO
-- but it is in fact a malevolent agent of chaos. It unpicks the seams of
-- reality (and the IO monad) so that the normal rules no longer
-- apply. It lulls you into thinking it is reasonable, but when you are
-- not looking it stabs you in the back and aliases all of your mutable
-- buffers. The carcass of many a seasoned Haskell programmer lie strewn
-- at its feet.
--
-- Witness the trail of destruction:
--
--
--
-- Do not talk about "safe"! You do not know what is safe!
--
-- Yield not to its blasphemous call! Flee traveller! Flee or you will be
-- corrupted and devoured!
accursedUnutterablePerformIO :: IO a -> a
plusForeignPtr :: ForeignPtr a -> Int -> ForeignPtr b
unsafeWithForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b
-- | A module containing semi-public ByteString internals. This
-- exposes the ByteString representation and low level
-- construction functions. Modules which extend the ByteString
-- system will need to use this module while ideally most users will be
-- able to make do with the public interface modules.
module Data.ByteString.Lazy.Internal
-- | A space-efficient representation of a Word8 vector, supporting
-- many efficient operations.
--
-- A LazyByteString contains 8-bit bytes, or by using the
-- operations from Data.ByteString.Lazy.Char8 it can be
-- interpreted as containing 8-bit characters.
data ByteString
Empty :: ByteString
Chunk :: {-# UNPACK #-} !StrictByteString -> ByteString -> ByteString
-- | Type synonym for the lazy flavour of ByteString.
type LazyByteString = ByteString
-- | Smart constructor for Chunk. Guarantees the data type
-- invariant.
chunk :: StrictByteString -> ByteString -> ByteString
-- | Consume the chunks of a lazy ByteString with a natural right fold.
foldrChunks :: (StrictByteString -> a -> a) -> a -> ByteString -> a
-- | Consume the chunks of a lazy ByteString with a strict, tail-recursive,
-- accumulating left fold.
foldlChunks :: (a -> StrictByteString -> a) -> a -> ByteString -> a
-- | The data type invariant: Every ByteString is either Empty or
-- consists of non-null StrictByteStrings. All functions must
-- preserve this.
invariant :: ByteString -> Bool
-- | Lazily checks that the given ByteString satisfies the data
-- type's "no empty chunks" invariant, raising an exception in place of
-- the first chunk that does not satisfy the invariant.
checkInvariant :: ByteString -> ByteString
-- | The chunk size used for I/O. Currently set to 32k, less the memory
-- management overhead
defaultChunkSize :: Int
-- | The recommended chunk size. Currently set to 4k, less the memory
-- management overhead
smallChunkSize :: Int
-- | The memory management overhead. Currently this is tuned for GHC only.
chunkOverhead :: Int
packBytes :: [Word8] -> ByteString
packChars :: [Char] -> ByteString
unpackBytes :: ByteString -> [Word8]
unpackChars :: ByteString -> [Char]
-- | O(1) Convert a StrictByteString into a
-- LazyByteString.
fromStrict :: StrictByteString -> LazyByteString
-- | 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.
toStrict :: LazyByteString -> StrictByteString
instance GHC.Internal.Data.Data.Data Data.ByteString.Lazy.Internal.ByteString
instance GHC.Classes.Eq Data.ByteString.Lazy.Internal.ByteString
instance GHC.Internal.IsList.IsList Data.ByteString.Lazy.Internal.ByteString
instance GHC.Internal.Data.String.IsString Data.ByteString.Lazy.Internal.ByteString
instance Language.Haskell.TH.Syntax.Lift Data.ByteString.Lazy.Internal.ByteString
instance GHC.Internal.Base.Monoid Data.ByteString.Lazy.Internal.ByteString
instance Control.DeepSeq.NFData Data.ByteString.Lazy.Internal.ByteString
instance GHC.Classes.Ord Data.ByteString.Lazy.Internal.ByteString
instance GHC.Internal.Read.Read Data.ByteString.Lazy.Internal.ByteString
instance GHC.Internal.Base.Semigroup Data.ByteString.Lazy.Internal.ByteString
instance GHC.Internal.Show.Show Data.ByteString.Lazy.Internal.ByteString
-- | Internal representation of ShortByteString
module Data.ByteString.Short.Internal
-- | A compact representation of a Word8 vector.
--
-- It has a lower memory overhead than a ByteString and does not
-- contribute to heap fragmentation. It can be converted to or from a
-- ByteString (at the cost of copying the string data). It
-- supports very few other operations.
newtype ShortByteString
ShortByteString :: ByteArray -> ShortByteString
[unShortByteString] :: ShortByteString -> ByteArray
-- | Prior to bytestring-0.12 SBS was a genuine constructor
-- of ShortByteString, but now it is a bundled pattern synonym,
-- provided as a compatibility shim.
pattern SBS :: ByteArray# -> ShortByteString
-- | O(1). The empty ShortByteString.
empty :: ShortByteString
-- | O(1) Convert a Word8 into a ShortByteString
singleton :: Word8 -> ShortByteString
-- | O(n). Convert a list into a ShortByteString
pack :: [Word8] -> ShortByteString
-- | O(n). Convert a ShortByteString into a list.
unpack :: ShortByteString -> [Word8]
-- | O(n). Convert a ShortByteString into a
-- ByteString.
fromShort :: ShortByteString -> ByteString
-- | O(n). Convert a ByteString into a
-- ShortByteString.
--
-- This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString
-- | O(n) Append a byte to the end of a ShortByteString
--
-- Note: copies the entire byte array
snoc :: ShortByteString -> Word8 -> ShortByteString
infixl 5 `snoc`
-- | O(n) cons is analogous to (:) for lists.
--
-- Note: copies the entire byte array
cons :: Word8 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString
-- | O(1) Extract the last element of a ShortByteString, which must
-- be finite and non-empty. An exception will be thrown in the case of an
-- empty ShortByteString.
--
-- This is a partial function, consider using unsnoc instead.
last :: HasCallStack => ShortByteString -> Word8
-- | O(n) Extract the elements after the head of a ShortByteString,
-- which must be non-empty. An exception will be thrown in the case of an
-- empty ShortByteString.
--
-- This is a partial function, consider using uncons instead.
--
-- Note: copies the entire byte array
tail :: HasCallStack => ShortByteString -> ShortByteString
-- | O(n) Extract the head and tail of a
-- ShortByteString, returning Nothing if it is empty.
uncons :: ShortByteString -> Maybe (Word8, ShortByteString)
-- | O(1) Extract the first element of a ShortByteString, which must
-- be non-empty. An exception will be thrown in the case of an empty
-- ShortByteString.
--
-- This is a partial function, consider using uncons instead.
head :: HasCallStack => ShortByteString -> Word8
-- | O(n) Return all the elements of a ShortByteString except
-- the last one. An exception will be thrown in the case of an empty
-- ShortByteString.
--
-- This is a partial function, consider using unsnoc instead.
--
-- Note: copies the entire byte array
init :: HasCallStack => ShortByteString -> ShortByteString
-- | O(n) Extract the init and last of a
-- ShortByteString, returning Nothing if it is empty.
unsnoc :: ShortByteString -> Maybe (ShortByteString, Word8)
-- | O(1) Test whether a ShortByteString is empty.
null :: ShortByteString -> Bool
-- | O(1) The length of a ShortByteString.
length :: ShortByteString -> Int
-- | O(n) map f xs is the ShortByteString obtained
-- by applying f to each element of xs.
map :: (Word8 -> Word8) -> ShortByteString -> ShortByteString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: ShortByteString -> ShortByteString
-- | O(n) The intercalate function takes a
-- ShortByteString and a list of ShortByteStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: ShortByteString -> [ShortByteString] -> ShortByteString
-- | foldl, applied to a binary operator, a starting value
-- (typically the left-identity of the operator), and a ShortByteString,
-- reduces the ShortByteString using the binary operator, from left to
-- right.
foldl :: (a -> Word8 -> a) -> a -> ShortByteString -> a
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ShortByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings. An exception will be thrown in the case of an
-- empty ShortByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a ShortByteString,
-- reduces the ShortByteString using the binary operator, from right to
-- left.
foldr :: (Word8 -> a -> a) -> a -> ShortByteString -> a
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ShortByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings An exception will be thrown in the case of an
-- empty ShortByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | O(n) Applied to a predicate and a ShortByteString,
-- all determines if all elements of the ShortByteString
-- satisfy the predicate.
all :: (Word8 -> Bool) -> ShortByteString -> Bool
-- | O(n) Applied to a predicate and a ShortByteString,
-- any determines if any element of the ShortByteString
-- satisfies the predicate.
any :: (Word8 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString
-- | O(n) replicate n x is a ShortByteString of
-- length n with x the value of every element. The
-- following holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> Word8 -> ShortByteString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ShortByteString from a seed value. The
-- function takes the element and returns Nothing if it is done
-- producing the ShortByteString or returns Just (a,b),
-- in which case, a is the next byte in the string, and
-- b is the seed value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word8] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- ShortByteString.
--
-- If you know the maximum length, consider using unfoldrN.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ShortByteString
-- | O(n) Like unfoldr, unfoldrN builds a
-- ShortByteString from a seed value. However, the length of the result
-- is limited by the first argument to unfoldrN. This function is
-- more efficient than unfoldr when the maximum length of the
-- result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ShortByteString, Maybe a)
-- | O(n) take n, applied to a ShortByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
--
-- Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString
-- | O(n) 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"
--
takeEnd :: Int -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if n >
-- length xs.
--
-- Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString
-- | O(n) 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"
-- ""
--
dropEnd :: Int -> ShortByteString -> ShortByteString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
--
-- Note: copies the entire byte array
dropWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) sbs
-- ==
-- let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--
spanEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) splitAt n sbs is equivalent to
-- (take n sbs, drop n sbs).
--
-- Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) Break a ShortByteString into pieces separated by
-- the byte argument, consuming the delimiter. I.e.
--
--
-- split 10 "a\nb\nd\ne" == ["a","b","d","e"] -- fromEnum '\n' == 10
-- split 97 "aXaXaXa" == ["","X","X","X",""] -- fromEnum 'a' == 97
-- split 120 "x" == ["",""] -- fromEnum 'x' == 120
-- split undefined "" == [] -- and not [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- Note: copies the substrings
split :: Word8 -> ShortByteString -> [ShortByteString]
-- | O(n) Splits a ShortByteString 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 (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (Word8 -> Bool) -> ShortByteString -> [ShortByteString]
-- | O(n) The stripSuffix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its suffix, and otherwise Nothing.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | O(n) The stripPrefix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its prefix, and otherwise Nothing.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isPrefixOf function takes two ShortByteStrings
-- and returns True iff the first is a prefix of the second.
isPrefixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isSuffixOf function takes two ShortByteStrings
-- and returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
isSuffixOf :: ShortByteString -> ShortByteString -> 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:
--
--
-- 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.
breakSubstring :: ShortByteString -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) elem is the ShortByteString membership
-- predicate.
elem :: Word8 -> ShortByteString -> Bool
-- | O(n) The find function takes a predicate and a
-- ShortByteString, and returns the first element in matching the
-- predicate, or Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (Word8 -> Bool) -> ShortByteString -> Maybe Word8
-- | O(n) filter, applied to a predicate and a
-- ShortByteString, returns a ShortByteString containing those characters
-- that satisfy the predicate.
filter :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) The partition function takes a predicate a
-- ShortByteString and returns the pair of ShortByteStrings with elements
-- which do and do not satisfy the predicate, respectively; i.e.,
--
--
-- partition p bs == (filter p sbs, filter (not . p) sbs)
--
partition :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(1) ShortByteString index (subscript) operator,
-- starting from 0.
--
-- This is a partial function, consider using indexMaybe instead.
index :: HasCallStack => ShortByteString -> Int -> Word8
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ShortByteString -> Int -> Maybe Word8
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ShortByteString -> Int -> Maybe Word8
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ShortByteString which is equal to
-- the query element, or Nothing if there is no such element.
elemIndex :: Word8 -> ShortByteString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- by returning the indices of all elements equal to the query element,
-- in ascending order.
elemIndices :: Word8 -> ShortByteString -> [Int]
-- | count returns the number of times its argument appears in the
-- ShortByteString
count :: Word8 -> ShortByteString -> Int
-- | O(n) The findIndex function takes a predicate and a
-- ShortByteString and returns the index of the first element in
-- the ShortByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ShortByteString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- by returning the indices of all elements satisfying the predicate, in
-- ascending order.
findIndices :: (Word8 -> Bool) -> ShortByteString -> [Int]
-- | O(1) Unsafe indexing without bounds checking.
unsafeIndex :: ShortByteString -> Int -> Word8
createFromPtr :: Ptr a -> Int -> IO ShortByteString
copyToPtr :: ShortByteString -> Int -> Ptr a -> Int -> IO ()
-- | O(n) Check whether a ShortByteString represents valid
-- UTF-8.
isValidUtf8 :: ShortByteString -> Bool
-- | O(n). Construct a new ShortByteString from a
-- CString. The resulting ShortByteString is an
-- immutable copy of the original CString, and is managed on the
-- Haskell heap. The original CString must be null terminated.
packCString :: CString -> IO ShortByteString
-- | O(n). Construct a new ShortByteString from a
-- CStringLen. The resulting ShortByteString is an
-- immutable copy of the original CStringLen. The
-- ShortByteString is a normal Haskell value and will be managed
-- on the Haskell heap.
packCStringLen :: CStringLen -> IO ShortByteString
-- | O(n) construction. Use a ShortByteString 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.
useAsCString :: ShortByteString -> (CString -> IO a) -> IO a
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a CStringLen. As for useAsCString
-- this function makes a copy of the original ShortByteString.
-- It must not be stored or used after the subcomputation finishes.
--
-- Beware that this function does not add a terminating NUL byte
-- at the end of CStringLen. If you need to construct a pointer to
-- a null-terminated sequence, use useAsCString (and measure
-- length independently if desired).
useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a
instance GHC.Internal.Data.Data.Data Data.ByteString.Short.Internal.ShortByteString
instance GHC.Classes.Eq Data.ByteString.Short.Internal.ShortByteString
instance GHC.Internal.Generics.Generic Data.ByteString.Short.Internal.ShortByteString
instance GHC.Internal.IsList.IsList Data.ByteString.Short.Internal.ShortByteString
instance GHC.Internal.Data.String.IsString Data.ByteString.Short.Internal.ShortByteString
instance Language.Haskell.TH.Syntax.Lift Data.ByteString.Short.Internal.ShortByteString
instance GHC.Internal.Base.Monoid Data.ByteString.Short.Internal.ShortByteString
instance Control.DeepSeq.NFData Data.ByteString.Short.Internal.ShortByteString
instance GHC.Classes.Ord Data.ByteString.Short.Internal.ShortByteString
instance GHC.Internal.Read.Read Data.ByteString.Short.Internal.ShortByteString
instance GHC.Internal.Base.Semigroup Data.ByteString.Short.Internal.ShortByteString
instance GHC.Internal.Show.Show Data.ByteString.Short.Internal.ShortByteString
-- | A compact representation suitable for storing short byte strings in
-- memory.
--
-- In typical use cases it can be imported alongside
-- Data.ByteString, e.g.
--
--
-- import qualified Data.ByteString as B
-- import qualified Data.ByteString.Short as B
-- (ShortByteString, toShort, fromShort)
--
--
-- Other ShortByteString operations clash with
-- Data.ByteString or Prelude functions however, so they
-- should be imported qualified with a different alias e.g.
--
--
-- import qualified Data.ByteString.Short as B.Short
--
module Data.ByteString.Short
-- | A compact representation of a Word8 vector.
--
-- It has a lower memory overhead than a ByteString and does not
-- contribute to heap fragmentation. It can be converted to or from a
-- ByteString (at the cost of copying the string data). It
-- supports very few other operations.
newtype ShortByteString
ShortByteString :: ByteArray -> ShortByteString
[unShortByteString] :: ShortByteString -> ByteArray
-- | Prior to bytestring-0.12 SBS was a genuine constructor
-- of ShortByteString, but now it is a bundled pattern synonym,
-- provided as a compatibility shim.
pattern SBS :: ByteArray# -> ShortByteString
-- | O(1). The empty ShortByteString.
empty :: ShortByteString
-- | O(1) Convert a Word8 into a ShortByteString
singleton :: Word8 -> ShortByteString
-- | O(n). Convert a list into a ShortByteString
pack :: [Word8] -> ShortByteString
-- | O(n). Convert a ShortByteString into a list.
unpack :: ShortByteString -> [Word8]
-- | O(n). Convert a ShortByteString into a
-- ByteString.
fromShort :: ShortByteString -> ByteString
-- | O(n). Convert a ByteString into a
-- ShortByteString.
--
-- This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString
-- | O(n) Append a byte to the end of a ShortByteString
--
-- Note: copies the entire byte array
snoc :: ShortByteString -> Word8 -> ShortByteString
infixl 5 `snoc`
-- | O(n) cons is analogous to (:) for lists.
--
-- Note: copies the entire byte array
cons :: Word8 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString
-- | O(1) Extract the last element of a ShortByteString, which must
-- be finite and non-empty. An exception will be thrown in the case of an
-- empty ShortByteString.
--
-- This is a partial function, consider using unsnoc instead.
last :: HasCallStack => ShortByteString -> Word8
-- | O(n) Extract the elements after the head of a ShortByteString,
-- which must be non-empty. An exception will be thrown in the case of an
-- empty ShortByteString.
--
-- This is a partial function, consider using uncons instead.
--
-- Note: copies the entire byte array
tail :: HasCallStack => ShortByteString -> ShortByteString
-- | O(n) Extract the head and tail of a
-- ShortByteString, returning Nothing if it is empty.
uncons :: ShortByteString -> Maybe (Word8, ShortByteString)
-- | O(1) Extract the first element of a ShortByteString, which must
-- be non-empty. An exception will be thrown in the case of an empty
-- ShortByteString.
--
-- This is a partial function, consider using uncons instead.
head :: HasCallStack => ShortByteString -> Word8
-- | O(n) Return all the elements of a ShortByteString except
-- the last one. An exception will be thrown in the case of an empty
-- ShortByteString.
--
-- This is a partial function, consider using unsnoc instead.
--
-- Note: copies the entire byte array
init :: HasCallStack => ShortByteString -> ShortByteString
-- | O(n) Extract the init and last of a
-- ShortByteString, returning Nothing if it is empty.
unsnoc :: ShortByteString -> Maybe (ShortByteString, Word8)
-- | O(1) Test whether a ShortByteString is empty.
null :: ShortByteString -> Bool
-- | O(1) The length of a ShortByteString.
length :: ShortByteString -> Int
-- | O(n) Check whether a ShortByteString represents valid
-- UTF-8.
isValidUtf8 :: ShortByteString -> Bool
-- | O(n) map f xs is the ShortByteString obtained
-- by applying f to each element of xs.
map :: (Word8 -> Word8) -> ShortByteString -> ShortByteString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: ShortByteString -> ShortByteString
-- | O(n) The intercalate function takes a
-- ShortByteString and a list of ShortByteStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: ShortByteString -> [ShortByteString] -> ShortByteString
-- | foldl, applied to a binary operator, a starting value
-- (typically the left-identity of the operator), and a ShortByteString,
-- reduces the ShortByteString using the binary operator, from left to
-- right.
foldl :: (a -> Word8 -> a) -> a -> ShortByteString -> a
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ShortByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings. An exception will be thrown in the case of an
-- empty ShortByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a ShortByteString,
-- reduces the ShortByteString using the binary operator, from right to
-- left.
foldr :: (Word8 -> a -> a) -> a -> ShortByteString -> a
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ShortByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings An exception will be thrown in the case of an
-- empty ShortByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | O(n) Applied to a predicate and a ShortByteString,
-- all determines if all elements of the ShortByteString
-- satisfy the predicate.
all :: (Word8 -> Bool) -> ShortByteString -> Bool
-- | O(n) Applied to a predicate and a ShortByteString,
-- any determines if any element of the ShortByteString
-- satisfies the predicate.
any :: (Word8 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString
-- | O(n) replicate n x is a ShortByteString of
-- length n with x the value of every element. The
-- following holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> Word8 -> ShortByteString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ShortByteString from a seed value. The
-- function takes the element and returns Nothing if it is done
-- producing the ShortByteString or returns Just (a,b),
-- in which case, a is the next byte in the string, and
-- b is the seed value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word8] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- ShortByteString.
--
-- If you know the maximum length, consider using unfoldrN.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ShortByteString
-- | O(n) Like unfoldr, unfoldrN builds a
-- ShortByteString from a seed value. However, the length of the result
-- is limited by the first argument to unfoldrN. This function is
-- more efficient than unfoldr when the maximum length of the
-- result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ShortByteString, Maybe a)
-- | O(n) take n, applied to a ShortByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
--
-- Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString
-- | O(n) 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"
--
takeEnd :: Int -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if n >
-- length xs.
--
-- Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString
-- | O(n) 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"
-- ""
--
dropEnd :: Int -> ShortByteString -> ShortByteString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
--
-- Note: copies the entire byte array
dropWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) sbs
-- ==
-- let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--
spanEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) splitAt n sbs is equivalent to
-- (take n sbs, drop n sbs).
--
-- Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) Break a ShortByteString into pieces separated by
-- the byte argument, consuming the delimiter. I.e.
--
--
-- split 10 "a\nb\nd\ne" == ["a","b","d","e"] -- fromEnum '\n' == 10
-- split 97 "aXaXaXa" == ["","X","X","X",""] -- fromEnum 'a' == 97
-- split 120 "x" == ["",""] -- fromEnum 'x' == 120
-- split undefined "" == [] -- and not [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- Note: copies the substrings
split :: Word8 -> ShortByteString -> [ShortByteString]
-- | O(n) Splits a ShortByteString 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 (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (Word8 -> Bool) -> ShortByteString -> [ShortByteString]
-- | O(n) The stripSuffix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its suffix, and otherwise Nothing.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | O(n) The stripPrefix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its prefix, and otherwise Nothing.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isPrefixOf function takes two ShortByteStrings
-- and returns True iff the first is a prefix of the second.
isPrefixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isSuffixOf function takes two ShortByteStrings
-- and returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
isSuffixOf :: ShortByteString -> ShortByteString -> 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:
--
--
-- 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.
breakSubstring :: ShortByteString -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) elem is the ShortByteString membership
-- predicate.
elem :: Word8 -> ShortByteString -> Bool
-- | O(n) The find function takes a predicate and a
-- ShortByteString, and returns the first element in matching the
-- predicate, or Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (Word8 -> Bool) -> ShortByteString -> Maybe Word8
-- | O(n) filter, applied to a predicate and a
-- ShortByteString, returns a ShortByteString containing those characters
-- that satisfy the predicate.
filter :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) The partition function takes a predicate a
-- ShortByteString and returns the pair of ShortByteStrings with elements
-- which do and do not satisfy the predicate, respectively; i.e.,
--
--
-- partition p bs == (filter p sbs, filter (not . p) sbs)
--
partition :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(1) ShortByteString index (subscript) operator,
-- starting from 0.
--
-- This is a partial function, consider using indexMaybe instead.
index :: HasCallStack => ShortByteString -> Int -> Word8
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ShortByteString -> Int -> Maybe Word8
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ShortByteString -> Int -> Maybe Word8
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ShortByteString which is equal to
-- the query element, or Nothing if there is no such element.
elemIndex :: Word8 -> ShortByteString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- by returning the indices of all elements equal to the query element,
-- in ascending order.
elemIndices :: Word8 -> ShortByteString -> [Int]
-- | count returns the number of times its argument appears in the
-- ShortByteString
count :: Word8 -> ShortByteString -> Int
-- | O(n) The findIndex function takes a predicate and a
-- ShortByteString and returns the index of the first element in
-- the ShortByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ShortByteString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- by returning the indices of all elements satisfying the predicate, in
-- ascending order.
findIndices :: (Word8 -> Bool) -> ShortByteString -> [Int]
-- | O(n). Construct a new ShortByteString from a
-- CString. The resulting ShortByteString is an
-- immutable copy of the original CString, and is managed on the
-- Haskell heap. The original CString must be null terminated.
packCString :: CString -> IO ShortByteString
-- | O(n). Construct a new ShortByteString from a
-- CStringLen. The resulting ShortByteString is an
-- immutable copy of the original CStringLen. The
-- ShortByteString is a normal Haskell value and will be managed
-- on the Haskell heap.
packCStringLen :: CStringLen -> IO ShortByteString
-- | O(n) construction. Use a ShortByteString 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.
useAsCString :: ShortByteString -> (CString -> IO a) -> IO a
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a CStringLen. As for useAsCString
-- this function makes a copy of the original ShortByteString.
-- It must not be stored or used after the subcomputation finishes.
--
-- Beware that this function does not add a terminating NUL byte
-- at the end of CStringLen. If you need to construct a pointer to
-- a null-terminated sequence, use useAsCString (and measure
-- length independently if desired).
useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a
-- | A module containing unsafe ByteString 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 head for non-empty ByteStrings. unsafeHead
-- 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 tail for non-empty ByteStrings. unsafeTail
-- omits the check for the empty case. As with unsafeHead, the
-- programmer must provide a separate proof that the ByteString is
-- non-empty.
unsafeTail :: ByteString -> ByteString
-- | A variety of init for non-empty ByteStrings. unsafeInit
-- omits the check for the empty case. As with unsafeHead, the
-- programmer must provide a separate proof that the ByteString is
-- non-empty.
unsafeInit :: ByteString -> ByteString
-- | A variety of last for non-empty ByteStrings. unsafeLast
-- omits the check for the empty case. As with unsafeHead, the
-- programmer must provide a separate proof that the ByteString is
-- non-empty.
unsafeLast :: ByteString -> Word8
-- | Unsafe ByteString index (subscript) operator, starting from 0,
-- returning a Word8 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 take which omits the checks on n so there
-- is an obligation on the programmer to provide a proof that 0 <=
-- n <= length xs.
unsafeTake :: Int -> ByteString -> ByteString
-- | A variety of drop which omits the checks on n so there
-- is an obligation on the programmer to provide a proof that 0 <=
-- n <= length xs.
unsafeDrop :: Int -> ByteString -> ByteString
-- | O(1) construction Use a ByteString with a function
-- requiring a CString.
--
-- This function does zero copying, and merely unwraps a
-- ByteString to appear as a CString. It is unsafe
-- in two ways:
--
--
-- - After calling this function the CString shares the
-- underlying byte buffer with the original ByteString. Thus
-- modifying the CString, either in C, or using poke, will cause
-- the contents of the ByteString to change, breaking referential
-- transparency. Other ByteStrings created by sharing (such as
-- those produced via take or drop) will also reflect these
-- changes. Modifying the CString will break referential
-- transparency. To avoid this, use useAsCString, which makes a
-- copy of the original ByteString.
-- - CStrings are often passed to functions that require them to
-- be null-terminated. If the original ByteString wasn't null
-- terminated, neither will the CString be. It is the programmers
-- responsibility to guarantee that the ByteString is indeed null
-- terminated. If in doubt, use useAsCString.
-- - The memory may freed at any point after the subcomputation
-- terminates, so the pointer to the storage must *not* be used after
-- this.
--
unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a
-- | O(1) construction Use a ByteString with a function
-- requiring a CStringLen.
--
-- This function does zero copying, and merely unwraps a
-- ByteString to appear as a CStringLen. It is
-- unsafe:
--
--
-- - After calling this function the CStringLen shares the
-- underlying byte buffer with the original ByteString. Thus
-- modifying the CStringLen, either in C, or using poke, will
-- cause the contents of the ByteString to change, breaking
-- referential transparency. Other ByteStrings created by sharing
-- (such as those produced via take or drop) will also
-- reflect these changes. Modifying the CStringLen will break
-- referential transparency. To avoid this, use useAsCStringLen,
-- which makes a copy of the original ByteString.
--
--
-- If empty is given, it will pass (nullPtr, 0).
unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
-- | O(n) Build a ByteString from a CString. This
-- value will have no finalizer associated to it, and will not be
-- garbage collected by Haskell. The ByteString length is calculated
-- using strlen(3), and thus the complexity is a O(n).
--
-- This function is unsafe. If the CString is later
-- modified, this change will be reflected in the resulting
-- ByteString, breaking referential transparency.
unsafePackCString :: CString -> IO ByteString
-- | O(1) Build a ByteString from a CStringLen. This
-- value will have no finalizer associated with it, and will not
-- be garbage collected by Haskell. This operation has O(1)
-- complexity as we already know the final size, so no strlen(3)
-- is required.
--
-- This function is unsafe. If the original CStringLen is
-- later modified, this change will be reflected in the resulting
-- ByteString, breaking referential transparency.
unsafePackCStringLen :: CStringLen -> IO ByteString
-- | O(n) Build a ByteString from a malloced CString.
-- This value will have a free(3) finalizer associated to it.
--
-- This function is unsafe. If the original CString is
-- later modified, this change will be reflected in the resulting
-- ByteString, breaking referential transparency.
--
-- This function is also unsafe if you call its finalizer twice, which
-- will result in a double free error, or if you pass it a
-- CString not allocated with malloc.
unsafePackMallocCString :: CString -> IO ByteString
-- | O(1) Build a ByteString from a malloced
-- CStringLen. This value will have a free(3) finalizer
-- associated to it.
--
-- This function is unsafe. If the original CString is
-- later modified, this change will be reflected in the resulting
-- ByteString, breaking referential transparency.
--
-- This function is also unsafe if you call its finalizer twice, which
-- will result in a double free error, or if you pass it a
-- CString not allocated with malloc.
unsafePackMallocCStringLen :: CStringLen -> IO ByteString
-- | O(n) Pack a null-terminated sequence of bytes, pointed to by an
-- Addr# (an arbitrary machine address assumed to point outside the
-- garbage-collected heap) into a ByteString. A much faster way
-- to create an Addr# is with an unboxed string literal, than to
-- pack a boxed string. A unboxed string literal is compiled to a static
-- char [] by GHC. Establishing the length of the string
-- requires a call to strlen(3), so the Addr# must point
-- to a null-terminated buffer (as is the case with "string"#
-- literals in GHC). Use unsafePackAddressLen if you know the
-- length of the string statically.
--
-- An example:
--
--
-- literalFS = unsafePackAddress "literal"#
--
--
-- This function is unsafe. If you modify the buffer pointed to by
-- the original Addr# this modification will be reflected in the
-- resulting ByteString, breaking referential transparency.
--
-- Note this also won't work if your Addr# has embedded
-- '\0' characters in the string, as strlen will return
-- too short a length.
unsafePackAddress :: Addr# -> IO ByteString
-- | O(1) unsafePackAddressLen provides constant-time
-- construction of ByteStrings, which is ideal for string
-- literals. It packs a sequence of bytes into a ByteString, given
-- a raw Addr# to the string, and the length of the string.
--
-- This function is unsafe in two ways:
--
--
-- - 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.
-- - if the underlying Addr# is later modified, this change will
-- be reflected in the resulting ByteString, breaking referential
-- transparency.
--
--
-- If in doubt, don't use this function.
unsafePackAddressLen :: Int -> Addr# -> IO ByteString
-- | O(1) Construct a ByteString 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 unsafe, 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 ByteString.
unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString
-- | Explicitly run the finaliser associated with a ByteString.
-- References to this value after finalisation may generate invalid
-- memory references.
--
-- This function is unsafe, as there may be other
-- ByteStrings referring to the same underlying pages. If you use
-- this, you need to have a proof of some kind that all
-- ByteStrings 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 and high speed requirements. Byte vectors are
-- encoded as strict Word8 arrays of bytes, held in a
-- ForeignPtr, and can be passed between C and Haskell with little
-- effort.
--
-- The recomended way to assemble ByteStrings from smaller parts is to
-- use the builder monoid from Data.ByteString.Builder.
--
-- This module is intended to be imported qualified, to avoid
-- name clashes with Prelude functions. eg.
--
--
-- import qualified Data.ByteString as B
--
--
-- Original GHC implementation by Bryan O'Sullivan. Rewritten to use
-- UArray by Simon Marlow. Rewritten to support slices and use
-- ForeignPtr by David Roundy. Rewritten again and extended by Don
-- Stewart and Duncan Coutts.
module Data.ByteString
-- | 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.
data ByteString
-- | Type synonym for the strict flavour of ByteString.
type StrictByteString = ByteString
-- | O(1) The empty ByteString
empty :: ByteString
-- | O(1) Convert a Word8 into a ByteString
singleton :: Word8 -> ByteString
-- | O(n) Convert a [Word8] into a
-- ByteString.
--
-- For applications with large numbers of string literals, pack
-- can be a bottleneck. In such cases, consider using
-- unsafePackAddress (GHC only).
pack :: [Word8] -> ByteString
-- | O(n) Converts a ByteString to a [Word8].
unpack :: ByteString -> [Word8]
-- | O(1) Convert a StrictByteString into a
-- LazyByteString.
fromStrict :: StrictByteString -> LazyByteString
-- | 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.
toStrict :: LazyByteString -> StrictByteString
-- | Convert a FilePath to a ByteString.
--
-- The FilePath type is expected to use the file system encoding
-- as reported by getFileSystemEncoding. This encoding allows for
-- round-tripping of arbitrary data on platforms that allow arbitrary
-- bytes in their paths. This conversion function does the same thing
-- that openFile would do when decoding the FilePath.
--
-- This function is in IO because the file system encoding can be
-- changed. If the encoding can be assumed to be constant in your use
-- case, you may invoke this function via unsafePerformIO.
fromFilePath :: FilePath -> IO ByteString
-- | Convert a ByteString to a FilePath.
--
-- This function uses the file system encoding, and resulting
-- FilePaths can be safely used with standard IO functions and
-- will reference the correct path in the presence of arbitrary non-UTF-8
-- encoded paths.
--
-- This function is in IO because the file system encoding can be
-- changed. If the encoding can be assumed to be constant in your use
-- case, you may invoke this function via unsafePerformIO.
toFilePath :: ByteString -> IO FilePath
-- | O(n) cons is analogous to (:) for lists, but of
-- different complexity, as it requires making a copy.
cons :: Word8 -> ByteString -> ByteString
infixr 5 `cons`
-- | O(n) Append a byte to the end of a ByteString
snoc :: ByteString -> Word8 -> ByteString
infixl 5 `snoc`
-- | O(n) Append two ByteStrings
append :: ByteString -> ByteString -> ByteString
-- | O(1) Extract the first element 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.
head :: HasCallStack => ByteString -> Word8
-- | O(1) Extract the head and tail of a ByteString,
-- returning Nothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)
-- | O(1) Extract the init and last of a ByteString,
-- returning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Word8)
-- | O(1) 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.
--
-- This is a partial function, consider using unsnoc instead.
last :: HasCallStack => ByteString -> Word8
-- | 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.
tail :: HasCallStack => ByteString -> ByteString
-- | 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.
init :: HasCallStack => ByteString -> ByteString
-- | O(1) Test whether a ByteString is empty.
null :: ByteString -> Bool
-- | O(1) length returns the length of a ByteString as an
-- Int.
length :: ByteString -> Int
-- | O(n) map f xs is the ByteString obtained by
-- applying f to each element of xs.
map :: (Word8 -> Word8) -> ByteString -> ByteString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: ByteString -> ByteString
-- | O(n) The intersperse function takes a Word8 and a
-- ByteString and `intersperses' that byte between the elements of
-- the ByteString. It is analogous to the intersperse function on
-- Lists.
intersperse :: Word8 -> ByteString -> ByteString
-- | O(n) The intercalate function takes a ByteString
-- and a list of ByteStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString
-- | The transpose function transposes the rows and columns of its
-- ByteString argument.
transpose :: [ByteString] -> [ByteString]
-- | 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 -> Word8 -> a) -> a -> ByteString -> a
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings. An
-- exception will be thrown in the case of an empty ByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty ByteString.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | foldr, 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 foldr, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings An
-- exception will be thrown in the case of an empty ByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | O(n) Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString
-- | Map a function over a ByteString and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString
-- | O(n) Applied to a predicate and a ByteString, any
-- determines if any element of the ByteString satisfies the
-- predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool
-- | O(n) Applied to a predicate and a ByteString, all
-- determines if all elements of the ByteString satisfy the
-- predicate.
all :: (Word8 -> Bool) -> ByteString -> Bool
-- | O(n) maximum returns the maximum value from a
-- ByteString An exception will be thrown in the case of an empty
-- ByteString.
maximum :: HasCallStack => ByteString -> Word8
-- | O(n) minimum returns the minimum value from a
-- ByteString An exception will be thrown in the case of an empty
-- ByteString.
minimum :: HasCallStack => ByteString -> Word8
-- | 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
--
--
-- head (scanl f z xs) == z
-- last (scanl f z xs) == foldl f z xs
--
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString
-- | scanl1 is a variant of scanl that has no starting value
-- argument.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString
-- | scanr is similar to foldr, but returns a list of
-- successive reduced values from the right.
--
--
-- scanr f z [..., x{n-1}, xn] == [..., x{n-1} `f` (xn `f` z), xn `f` z, z]
--
--
-- Note that
--
--
-- head (scanr f z xs) == foldr f z xs
-- last (scanr f z xs) == z
--
scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString
-- | 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.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)
-- | 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.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)
-- | O(n) replicate n x is a ByteString of length
-- n with x the value of every element. The following
-- holds:
--
--
-- replicate w c = fst (unfoldrN w (\u -> Just (u,u)) c)
--
replicate :: Int -> Word8 -> ByteString
-- | 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 byte in the string, and b is the seed
-- value for further production.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString
-- | 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:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ByteString, Maybe a)
-- | O(1) take n, applied to a ByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Int -> ByteString -> ByteString
-- | 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"
--
takeEnd :: Int -> ByteString -> ByteString
-- | O(1) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Int -> ByteString -> ByteString
-- | 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"
-- ""
--
dropEnd :: Int -> ByteString -> ByteString
-- | O(1) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Int -> ByteString -> (ByteString, ByteString)
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (dropWhileEnd p &&&
-- takeWhileEnd p).
--
-- 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)
--
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
--
-- Under GHC, a rewrite rule will transform break (==) into a call to the
-- specialised breakByte:
--
--
-- break ((==) x) = breakByte x
-- break (==x) = breakByte x
--
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (dropWhileEnd (not . p) &&&
-- takeWhileEnd (not . p)).
breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | 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
-- (==)
group :: ByteString -> [ByteString]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString]
-- | O(n) Returns all initial segments of the given
-- ByteString, shortest first.
inits :: ByteString -> [ByteString]
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tails :: ByteString -> [ByteString]
-- | O(n) Returns all initial segments of the given
-- ByteString, shortest first.
initsNE :: ByteString -> NonEmpty ByteString
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tailsNE :: ByteString -> NonEmpty ByteString
-- | 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.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString
-- | 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.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString
-- | O(n) Break a ByteString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- split 10 "a\nb\nd\ne" == ["a","b","d","e"] -- fromEnum '\n' == 10
-- split 97 "aXaXaXa" == ["","X","X","X",""] -- fromEnum 'a' == 97
-- split 120 "x" == ["",""] -- fromEnum 'x' == 120
-- 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 ByteStrings that
-- are slices of the original.
split :: Word8 -> ByteString -> [ByteString]
-- | 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 (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]
-- | O(n) The isPrefixOf function takes two ByteStrings and
-- returns True if the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool
-- | 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..
isSuffixOf :: ByteString -> ByteString -> Bool
-- | Check whether one string is a substring of another.
isInfixOf :: ByteString -> ByteString -> Bool
-- | O(n) Check whether a ByteString represents valid UTF-8.
isValidUtf8 :: 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:
--
--
-- 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.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)
-- | O(n) elem is the ByteString membership predicate.
elem :: Word8 -> ByteString -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Word8 -> ByteString -> Bool
-- | 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.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8
-- | O(n) filter, applied to a predicate and a ByteString,
-- returns a ByteString containing those characters that satisfy the
-- predicate.
filter :: (Word8 -> Bool) -> ByteString -> ByteString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p xs, filter (not . p) xs)
--
partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | O(1) ByteString index (subscript) operator, starting
-- from 0.
--
-- This is a partial function, consider using indexMaybe instead.
index :: HasCallStack => ByteString -> Int -> Word8
-- | O(1) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ByteString -> Int -> Maybe Word8
-- | O(1) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ByteString -> Int -> Maybe Word8
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ByteString which is equal to the
-- query element, or Nothing if there is no such element. This
-- implementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- by returning the indices of all elements equal to the query element,
-- in ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int]
-- | 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)
--
elemIndexEnd :: Word8 -> ByteString -> Maybe Int
-- | O(n) The findIndex function takes a predicate and a
-- ByteString and returns the index of the first element in the
-- ByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- by returning the indices of all elements satisfying the predicate, in
-- ascending order.
findIndices :: (Word8 -> Bool) -> ByteString -> [Int]
-- | 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.
findIndexEnd :: (Word8 -> Bool) -> ByteString -> Maybe Int
-- | count returns the number of times its argument appears in the
-- ByteString
--
--
-- count = length . elemIndices
--
--
-- But more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int
-- | O(n) zip 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 unpack operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]
-- | 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.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -> ByteString
-- | O(n) unzip transforms a list of pairs of bytes into a
-- pair of ByteStrings. Note that this performs two pack
-- operations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)
-- | O(n) Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString
-- | 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.
copy :: ByteString -> ByteString
-- | 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.
packCString :: CString -> IO ByteString
-- | 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.
packCStringLen :: CStringLen -> IO ByteString
-- | 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.
useAsCString :: ByteString -> (CString -> IO a) -> IO a
-- | 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).
useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
-- | Read a line from stdin.
-- | Deprecated: Deprecated since bytestring-0.12. Use
-- getLine instead. (Functions that rely on ASCII encodings belong
-- in Data.ByteString.Char8)
getLine :: IO ByteString
-- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The
-- Handle is closed after the contents have been read.
getContents :: IO ByteString
-- | Write a ByteString to stdout.
putStr :: ByteString -> IO ()
-- | 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.
interact :: (ByteString -> ByteString) -> IO ()
-- | Read an entire file strictly into a ByteString.
readFile :: FilePath -> IO ByteString
-- | Write a ByteString to a file.
writeFile :: FilePath -> ByteString -> IO ()
-- | Append a ByteString to a file.
appendFile :: FilePath -> ByteString -> IO ()
-- | Read a line from a handle
-- | Deprecated: Deprecated since bytestring-0.12. Use
-- hGetLine instead. (Functions that rely on ASCII encodings
-- belong in Data.ByteString.Char8)
hGetLine :: Handle -> IO ByteString
-- | 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.
hGetContents :: Handle -> IO ByteString
-- | 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.
hGet :: Handle -> Int -> IO ByteString
-- | 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.
hGetSome :: Handle -> Int -> IO ByteString
-- | 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.
hGetNonBlocking :: Handle -> Int -> IO ByteString
-- | Outputs a ByteString to the specified Handle.
hPut :: Handle -> ByteString -> IO ()
-- | 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.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString
-- | A synonym for hPut, for compatibility
hPutStr :: Handle -> ByteString -> IO ()
-- | A time and space-efficient implementation of lazy byte vectors using
-- lists of packed Word8 arrays, suitable for high performance
-- use, both in terms of large data quantities, or high speed
-- requirements. Lazy ByteStrings are encoded as lazy lists of strict
-- chunks of bytes.
--
-- A key feature of lazy ByteStrings is the means to manipulate large or
-- unbounded streams of data without requiring the entire sequence to be
-- resident in memory. To take advantage of this you have to write your
-- functions in a lazy streaming style, e.g. classic pipeline
-- composition. The default I/O chunk size is 32k, which should be good
-- in most circumstances.
--
-- Some operations, such as concat, append, reverse
-- and cons, have better complexity than their
-- Data.ByteString equivalents, due to optimisations resulting
-- from the list spine structure. For other operations lazy ByteStrings
-- are usually within a few percent of strict ones.
--
-- The recomended way to assemble lazy ByteStrings from smaller parts is
-- to use the builder monoid from Data.ByteString.Builder.
--
-- This module is intended to be imported qualified, to avoid
-- name clashes with Prelude functions. eg.
--
--
-- import qualified Data.ByteString.Lazy as B
--
--
-- Original GHC implementation by Bryan O'Sullivan. Rewritten to use
-- UArray by Simon Marlow. Rewritten to support slices and use
-- ForeignPtr by David Roundy. Rewritten again and extended by Don
-- Stewart and Duncan Coutts. 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 LazyByteString contains 8-bit bytes, or by using the
-- operations from Data.ByteString.Lazy.Char8 it can be
-- interpreted as containing 8-bit characters.
data ByteString
-- | Type synonym for the lazy flavour of ByteString.
type LazyByteString = ByteString
-- | O(1) The empty ByteString
empty :: ByteString
-- | O(1) Convert a Word8 into a ByteString
singleton :: Word8 -> ByteString
-- | O(n) Convert a '[Word8]' into a ByteString.
pack :: [Word8] -> ByteString
-- | O(n) Converts a ByteString to a '[Word8]'.
unpack :: ByteString -> [Word8]
-- | O(1) Convert a StrictByteString into a
-- LazyByteString.
fromStrict :: StrictByteString -> LazyByteString
-- | 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.
toStrict :: LazyByteString -> StrictByteString
-- | O(c) Convert a list of StrictByteString into a
-- LazyByteString
fromChunks :: [StrictByteString] -> LazyByteString
-- | O(c) Convert a LazyByteString into a list of
-- StrictByteString
toChunks :: LazyByteString -> [StrictByteString]
-- | Consume the chunks of a lazy ByteString with a natural right fold.
foldrChunks :: (StrictByteString -> a -> a) -> a -> ByteString -> a
-- | Consume the chunks of a lazy ByteString with a strict, tail-recursive,
-- accumulating left fold.
foldlChunks :: (a -> StrictByteString -> a) -> a -> ByteString -> a
-- | O(1) cons is analogous to (:) for lists.
cons :: Word8 -> ByteString -> ByteString
infixr 5 `cons`
-- | O(1) Unlike cons, 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:
--
--
-- let xs = cons' c xs in xs
--
--
-- You can however use cons, as well as repeat and
-- cycle, to build infinite lazy ByteStrings.
cons' :: Word8 -> ByteString -> ByteString
infixr 5 `cons'`
-- | O(n/c) Append a byte to the end of a ByteString
snoc :: ByteString -> Word8 -> ByteString
infixl 5 `snoc`
-- | O(n/c) Append two ByteStrings
append :: ByteString -> ByteString -> ByteString
-- | O(1) Extract the first element of a ByteString, which must be
-- non-empty.
--
-- This is a partial function, consider using uncons instead.
head :: HasCallStack => ByteString -> Word8
-- | O(1) Extract the head and tail of a ByteString,
-- returning Nothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)
-- | O(n/c) Extract the init and last of a ByteString,
-- returning Nothing if it is empty.
--
--
-- - It is no faster than using init and last
--
unsnoc :: ByteString -> Maybe (ByteString, Word8)
-- | O(n/c) Extract the last element of a ByteString, which must be
-- finite and non-empty.
--
-- This is a partial function, consider using unsnoc instead.
last :: HasCallStack => ByteString -> Word8
-- | O(1) Extract the elements after the head of a ByteString, which
-- must be non-empty.
--
-- This is a partial function, consider using uncons instead.
tail :: HasCallStack => ByteString -> ByteString
-- | O(n/c) Returns all the elements of a ByteString except
-- the last one.
--
-- This is a partial function, consider using unsnoc instead.
init :: HasCallStack => ByteString -> ByteString
-- | O(1) Test whether a ByteString is empty.
null :: ByteString -> Bool
-- | O(c) length returns the length of a ByteString as an
-- Int64
length :: ByteString -> Int64
-- | O(n) map f xs is the ByteString obtained by
-- applying f to each element of xs.
map :: (Word8 -> Word8) -> ByteString -> ByteString
-- | O(n) reverse xs returns the elements of
-- xs in reverse order.
reverse :: ByteString -> ByteString
-- | The intersperse function takes a Word8 and a
-- ByteString and `intersperses' that byte between the elements of
-- the ByteString. It is analogous to the intersperse function on
-- Lists.
intersperse :: Word8 -> ByteString -> ByteString
-- | O(n) The intercalate function takes a ByteString
-- and a list of ByteStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString
-- | The transpose function transposes the rows and columns of its
-- ByteString argument.
transpose :: [ByteString] -> [ByteString]
-- | 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 -> Word8 -> a) -> a -> ByteString -> a
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | foldl1' is like foldl1, but strict in the accumulator.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | foldr, 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 foldr, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | foldr1' is like foldr1, but strict in the accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ByteString -> Word8
-- | O(n) Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString
-- | Map a function over a ByteString and concatenate the results
concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString
-- | O(n) Applied to a predicate and a ByteString, any
-- determines if any element of the ByteString satisfies the
-- predicate.
any :: (Word8 -> Bool) -> ByteString -> Bool
-- | O(n) Applied to a predicate and a ByteString, all
-- determines if all elements of the ByteString satisfy the
-- predicate.
all :: (Word8 -> Bool) -> ByteString -> Bool
-- | O(n) maximum returns the maximum value from a
-- ByteString
maximum :: HasCallStack => ByteString -> Word8
-- | O(n) minimum returns the minimum value from a
-- ByteString
minimum :: HasCallStack => ByteString -> Word8
-- | O(c) compareLength compares the length of a
-- ByteString to an Int64
compareLength :: ByteString -> Int64 -> Ordering
-- | 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
--
--
-- head (scanl f z xs) == z
-- last (scanl f z xs) == foldl f z xs
--
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString
-- | scanl1 is a variant of scanl that has no starting value
-- argument.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString
-- | scanr is similar to foldr, but returns a list of
-- successive reduced values from the right.
--
--
-- scanr f z [..., x{n-1}, xn] == [..., x{n-1} `f` (xn `f` z), xn `f` z, z]
--
--
-- Note that
--
--
-- head (scanr f z xs) == foldr f z xs
-- last (scanr f z xs) == z
--
scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString
-- | 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.
mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)
-- | 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.
mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString)
-- | repeat x is an infinite ByteString, with x
-- the value of every element.
repeat :: Word8 -> ByteString
-- | O(n) replicate n x is a ByteString of length
-- n with x the value of every element.
replicate :: Int64 -> Word8 -> ByteString
-- | cycle ties a finite ByteString into a circular one, or
-- equivalently, the infinite repetition of the original ByteString.
cycle :: HasCallStack => ByteString -> ByteString
-- | iterate f x returns an infinite ByteString of repeated
-- applications of f to x:
--
--
-- iterate f x == [x, f x, f (f x), ...]
--
iterate :: (Word8 -> Word8) -> Word8 -> ByteString
-- | O(n) 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 a prepending to the ByteString and
-- b is used as the next element in a recursive call.
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString
-- | O(n/c) take n, applied to a ByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Int64 -> ByteString -> ByteString
-- | O(c) 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"
--
takeEnd :: Int64 -> ByteString -> ByteString
-- | O(n/c) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Int64 -> ByteString -> ByteString
-- | O(n) 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"
-- ""
--
dropEnd :: Int64 -> ByteString -> ByteString
-- | O(n/c) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Int64 -> ByteString -> (ByteString, ByteString)
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
--
--
-- >>> {-# LANGUAGE OverloadedLists #-)
--
-- >>> takeWhileEnd even [1,2,3,4,6]
-- [4,6]
--
takeWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
--
--
-- >>> {-# LANGUAGE OverloadedLists #-)
--
-- >>> dropWhileEnd even [1,2,3,4,6]
-- [1,2,3]
--
dropWhileEnd :: (Word8 -> Bool) -> ByteString -> ByteString
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (dropWhileEnd p &&&
-- takeWhileEnd p).
--
-- 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)
--
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (dropWhileEnd (not . p) &&&
-- takeWhileEnd (not . p)).
breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | 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.
group :: ByteString -> [ByteString]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString]
-- | Returns all initial segments of the given ByteString, shortest
-- first.
inits :: ByteString -> [ByteString]
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tails :: ByteString -> [ByteString]
-- | Returns all initial segments of the given ByteString, shortest
-- first.
initsNE :: ByteString -> NonEmpty ByteString
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tailsNE :: ByteString -> NonEmpty ByteString
-- | 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.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString
-- | 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.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString
-- | O(n) Break a ByteString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- split 10 "a\nb\nd\ne" == ["a","b","d","e"] -- fromEnum '\n' == 10
-- split 97 "aXaXaXa" == ["","X","X","X",""] -- fromEnum 'a' == 97
-- split 120 "x" == ["",""] -- fromEnum 'x' == 120
-- 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 ByteStrings that
-- are slices of the original.
split :: Word8 -> ByteString -> [ByteString]
-- | 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 (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString]
-- | O(n) The isPrefixOf function takes two ByteStrings and
-- returns True iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool
-- | 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
--
isSuffixOf :: ByteString -> ByteString -> Bool
-- | O(n) elem is the ByteString membership predicate.
elem :: Word8 -> ByteString -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Word8 -> ByteString -> Bool
-- | 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.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8
-- | O(n) filter, applied to a predicate and a ByteString,
-- returns a ByteString containing those characters that satisfy the
-- predicate.
filter :: (Word8 -> Bool) -> ByteString -> ByteString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p xs, filter (not . p) xs)
--
partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)
-- | O(c) ByteString index (subscript) operator, starting
-- from 0.
--
-- This is a partial function, consider using indexMaybe instead.
index :: HasCallStack => ByteString -> Int64 -> Word8
-- | O(c) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ByteString -> Int64 -> Maybe Word8
-- | O(1) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ByteString -> Int64 -> Maybe Word8
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ByteString which is equal to the
-- query element, or Nothing if there is no such element. This
-- implementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int64
-- | 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)
--
elemIndexEnd :: Word8 -> ByteString -> Maybe Int64
-- | O(n) The elemIndices function extends elemIndex,
-- 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 findIndex function takes a predicate and a
-- ByteString and returns the index of the first element in the
-- ByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int64
-- | The findIndexEnd function takes a predicate and a
-- ByteString and returns the index of the last element in the
-- ByteString satisfying the predicate.
findIndexEnd :: (Word8 -> Bool) -> ByteString -> Maybe Int64
-- | The findIndices function extends findIndex, 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
--
--
-- count = length . elemIndices
--
--
-- But more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int64
-- | O(n) zip 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 unpack operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]
-- | 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.
zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -> ByteString
-- | O(n) unzip transforms a list of pairs of bytes into a
-- pair of ByteStrings. Note that this performs two pack
-- operations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)
-- | 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.
copy :: ByteString -> ByteString
-- | getContents. Equivalent to hGetContents stdin. Will read lazily
getContents :: IO ByteString
-- | Write a ByteString to stdout.
--
-- The chunks will be written one at a time. Other threads might write to
-- the stdout in between, and hence putStr alone is not
-- suitable for concurrent writes.
putStr :: ByteString -> IO ()
-- | 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.
interact :: (ByteString -> ByteString) -> IO ()
-- | Read an entire file lazily into a ByteString.
--
-- The Handle will be held open until EOF is encountered.
--
-- Note that this function's implementation relies on
-- hGetContents. The reader is advised to read its documentation.
readFile :: FilePath -> IO ByteString
-- | Write a ByteString to a file.
writeFile :: FilePath -> ByteString -> IO ()
-- | Append a ByteString to a file.
appendFile :: FilePath -> ByteString -> IO ()
-- | Read entire handle contents lazily into a ByteString.
-- Chunks are read on demand, using the default chunk size.
--
-- File handles are closed on EOF if all the file is read, or through
-- garbage collection otherwise.
hGetContents :: Handle -> IO ByteString
-- | Read n bytes into a ByteString, directly from the
-- specified Handle.
hGet :: Handle -> Int -> IO ByteString
-- | 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.
hGetNonBlocking :: Handle -> Int -> IO ByteString
-- | Outputs a ByteString to the specified Handle.
--
-- The chunks will be written one at a time. Other threads might write to
-- the Handle in between, and hence hPut alone is not
-- suitable for concurrent writes.
hPut :: Handle -> ByteString -> IO ()
-- | 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.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString
-- | A synonym for hPut, for compatibility
hPutStr :: Handle -> ByteString -> IO ()
-- | Manipulate lazy ByteStrings using Char
-- operations. All Chars will be truncated to 8 bits. It can be expected
-- that these functions will run at identical speeds to their
-- Word8 equivalents in Data.ByteString.Lazy.
--
-- This module is intended to be imported qualified, to avoid
-- name clashes with Prelude functions. eg.
--
--
-- import qualified Data.ByteString.Lazy.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.
module Data.ByteString.Lazy.Char8
-- | A space-efficient representation of a Word8 vector, supporting
-- many efficient operations.
--
-- A LazyByteString contains 8-bit bytes, or by using the
-- operations from Data.ByteString.Lazy.Char8 it can be
-- interpreted as containing 8-bit characters.
data ByteString
-- | O(1) The empty ByteString
empty :: ByteString
-- | O(1) Convert a Char into a ByteString
singleton :: Char -> ByteString
-- | O(n) Convert a String into a ByteString.
pack :: [Char] -> ByteString
-- | O(n) Converts a ByteString to a String.
unpack :: ByteString -> [Char]
-- | O(c) Convert a list of StrictByteString into a
-- LazyByteString
fromChunks :: [StrictByteString] -> LazyByteString
-- | O(c) Convert a LazyByteString into a list of
-- StrictByteString
toChunks :: LazyByteString -> [StrictByteString]
-- | O(1) Convert a StrictByteString into a
-- LazyByteString.
fromStrict :: StrictByteString -> LazyByteString
-- | 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.
toStrict :: LazyByteString -> StrictByteString
-- | O(1) cons is analogous to (:) for lists.
cons :: Char -> ByteString -> ByteString
infixr 5 `cons`
-- | O(1) Unlike cons, 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:
--
--
-- let xs = cons' c xs in xs
--
--
-- You can however use cons, as well as repeat and
-- cycle, to build infinite lazy ByteStrings.
cons' :: Char -> ByteString -> ByteString
infixr 5 `cons'`
-- | O(n) Append a Char to the end of a ByteString. Similar
-- to cons, this function performs a memcpy.
snoc :: ByteString -> Char -> ByteString
infixl 5 `snoc`
-- | O(n/c) Append two ByteStrings
append :: ByteString -> ByteString -> ByteString
-- | O(1) Extract the first element of a ByteString, which must be
-- non-empty.
head :: ByteString -> Char
-- | O(1) Extract the head and tail of a ByteString, returning
-- Nothing if it is empty.
uncons :: ByteString -> Maybe (Char, ByteString)
-- | O(1) Extract the last element of a packed string, which must be
-- non-empty.
last :: ByteString -> Char
-- | O(1) Extract the elements after the head of a ByteString, which
-- must be non-empty.
--
-- This is a partial function, consider using uncons instead.
tail :: HasCallStack => ByteString -> ByteString
-- | O(n/c) Extract the init and last of a ByteString,
-- returning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Char)
-- | O(n/c) Returns all the elements of a ByteString except
-- the last one.
--
-- This is a partial function, consider using unsnoc instead.
init :: HasCallStack => ByteString -> ByteString
-- | O(1) Test whether a ByteString is empty.
null :: ByteString -> Bool
-- | O(c) length returns the length of a ByteString as an
-- Int64
length :: ByteString -> Int64
-- | O(n) map f xs is the ByteString obtained by
-- applying f to each element of xs
map :: (Char -> Char) -> ByteString -> ByteString
-- | O(n) reverse xs returns the elements of
-- xs in reverse order.
reverse :: ByteString -> ByteString
-- | 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.
intersperse :: Char -> ByteString -> ByteString
-- | O(n) The intercalate function takes a ByteString
-- and a list of ByteStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString
-- | The transpose function transposes the rows and columns of its
-- ByteString argument.
transpose :: [ByteString] -> [ByteString]
-- | 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Char -> a) -> a -> ByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings.
foldl1 :: (Char -> Char -> Char) -> ByteString -> Char
-- | foldl1' is like foldl1, but strict in the accumulator.
foldl1' :: (Char -> Char -> Char) -> ByteString -> Char
-- | 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
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (Char -> a -> a) -> a -> ByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings
foldr1 :: (Char -> Char -> Char) -> ByteString -> Char
-- | foldr1' is like foldr1, but strict in the accumulator.
foldr1' :: (Char -> Char -> Char) -> ByteString -> Char
-- | O(n) Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString
-- | Map a function over a ByteString and concatenate the results
concatMap :: (Char -> ByteString) -> ByteString -> ByteString
-- | Applied to a predicate and a ByteString, any determines if any
-- element of the ByteString satisfies the predicate.
any :: (Char -> Bool) -> ByteString -> Bool
-- | Applied to a predicate and a ByteString, all determines
-- if all elements of the ByteString satisfy the predicate.
all :: (Char -> Bool) -> ByteString -> Bool
-- | maximum returns the maximum value from a ByteString
maximum :: ByteString -> Char
-- | minimum returns the minimum value from a ByteString
minimum :: ByteString -> Char
-- | O(c) compareLength compares the length of a
-- ByteString to an Int64
compareLength :: ByteString -> Int64 -> Ordering
-- | 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.
--
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString
-- | scanl1 is a variant of scanl that has no starting value
-- argument.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Char -> Char -> Char) -> ByteString -> ByteString
-- | scanr is similar to foldr, but returns a list of
-- successive reduced values from the right.
--
--
-- scanr f z [..., x{n-1}, xn] == [..., x{n-1} `f` (xn `f` z), xn `f` z, z]
--
--
-- Note that
--
--
-- head (scanr f z xs) == foldr f z xs
-- last (scanr f z xs) == z
--
scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString
-- | 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.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)
-- | 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.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)
-- | repeat x is an infinite ByteString, with x
-- the value of every element.
repeat :: Char -> ByteString
-- | O(n) replicate n x is a ByteString of length
-- n with x the value of every element.
replicate :: Int64 -> Char -> ByteString
-- | cycle ties a finite ByteString into a circular one, or
-- equivalently, the infinite repetition of the original ByteString.
cycle :: HasCallStack => ByteString -> ByteString
-- | iterate f x returns an infinite ByteString of repeated
-- applications of f to x:
--
--
-- iterate f x == [x, f x, f (f x), ...]
--
iterate :: (Char -> Char) -> Char -> ByteString
-- | O(n) 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 a prepending to the ByteString and
-- b is used as the next element in a recursive call.
unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString
-- | O(n/c) take n, applied to a ByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Int64 -> ByteString -> ByteString
-- | O(c) 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"
--
takeEnd :: Int64 -> ByteString -> ByteString
-- | O(n/c) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Int64 -> ByteString -> ByteString
-- | O(n) 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"
-- ""
--
dropEnd :: Int64 -> ByteString -> ByteString
-- | O(n/c) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Int64 -> ByteString -> (ByteString, ByteString)
-- | takeWhile, applied to a predicate p and a ByteString
-- xs, returns the longest prefix (possibly empty) of
-- xs of elements that satisfy p.
takeWhile :: (Char -> Bool) -> ByteString -> ByteString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (Char -> Bool) -> ByteString -> ByteString
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs.
dropWhile :: (Char -> Bool) -> ByteString -> ByteString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (Char -> Bool) -> ByteString -> ByteString
-- | span p xs breaks the ByteString into two segments. It
-- is equivalent to (takeWhile p xs, dropWhile p
-- xs)
span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | 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)
--
spanEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | break p is equivalent to span (not .
-- p).
break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | breakEnd behaves like break but from the end of the
-- ByteString
--
-- breakEnd p == spanEnd (not.p)
breakEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | 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.
group :: ByteString -> [ByteString]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString]
-- | Returns all initial segments of the given ByteString, shortest
-- first.
inits :: ByteString -> [ByteString]
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tails :: ByteString -> [ByteString]
-- | Returns all initial segments of the given ByteString, shortest
-- first.
initsNE :: ByteString -> NonEmpty ByteString
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tailsNE :: ByteString -> NonEmpty ByteString
-- | 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.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString
-- | 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.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString
-- | 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 ByteStrings that
-- are slices of the original.
split :: Char -> ByteString -> [ByteString]
-- | 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 [""]
--
splitWith :: (Char -> Bool) -> ByteString -> [ByteString]
-- | lines lazily splits a ByteString into a list of ByteStrings at
-- newline Chars ('\n'). The resulting strings do not contain
-- newlines. The first chunk of the result is only strict in the first
-- chunk of the input.
--
-- Note that it does not regard CR ('\r') as a newline
-- character.
lines :: ByteString -> [ByteString]
-- | words breaks a ByteString up into a list of words, which were
-- delimited by Chars representing white space. And
--
--
-- tokens isSpace = words
--
words :: ByteString -> [ByteString]
-- | unlines joins lines, appending a terminating newline after
-- each.
--
-- Equivalent to concat . Data.List.concatMap (\x -> [x,
-- singleton '\n']).
unlines :: [ByteString] -> ByteString
-- | The unwords function is analogous to the unlines
-- function, on words.
unwords :: [ByteString] -> ByteString
-- | O(n) The isPrefixOf function takes two ByteStrings and
-- returns True iff the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool
-- | 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
--
isSuffixOf :: ByteString -> ByteString -> Bool
-- | O(n) elem is the ByteString membership predicate.
-- This implementation uses memchr(3).
elem :: Char -> ByteString -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Char -> ByteString -> Bool
-- | 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.
find :: (Char -> Bool) -> ByteString -> Maybe Char
-- | O(n) filter, applied to a predicate and a ByteString,
-- returns a ByteString containing those characters that satisfy the
-- predicate.
filter :: (Char -> Bool) -> ByteString -> ByteString
partition :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | O(1) ByteString index (subscript) operator, starting
-- from 0.
index :: ByteString -> Int64 -> Char
-- | O(1) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ByteString -> Int64 -> Maybe Char
-- | O(1) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ByteString -> Int64 -> Maybe Char
-- | 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.
elemIndex :: Char -> ByteString -> Maybe Int64
-- | 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)
--
elemIndexEnd :: Char -> ByteString -> Maybe Int64
-- | O(n) The elemIndices function extends elemIndex,
-- by returning the indices of all elements equal to the query element,
-- in ascending order.
elemIndices :: Char -> ByteString -> [Int64]
-- | The findIndex function takes a predicate and a
-- ByteString and returns the index of the first element in the
-- ByteString satisfying the predicate.
findIndex :: (Char -> Bool) -> ByteString -> Maybe Int64
-- | The findIndexEnd function takes a predicate and a
-- ByteString and returns the index of the last element in the
-- ByteString satisfying the predicate.
findIndexEnd :: (Char -> Bool) -> ByteString -> Maybe Int64
-- | The findIndices function extends findIndex, 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
--
--
-- count == length . elemIndices
-- count '\n' == length . lines
--
--
-- But more efficiently than using length on the intermediate list.
count :: Char -> ByteString -> Int64
-- | 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
zip :: ByteString -> ByteString -> [(Char, Char)]
-- | 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.
zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Char -> Char -> Char) -> ByteString -> ByteString -> ByteString
-- | O(n) unzip transforms a list of pairs of chars into a
-- pair of ByteStrings. Note that this performs two pack
-- operations.
unzip :: [(Char, Char)] -> (ByteString, ByteString)
-- | 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.
copy :: ByteString -> ByteString
-- | 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
--
--
-- >>> 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
--
readInt :: ByteString -> Maybe (Int, ByteString)
-- | A variant of readInt specialised to Int64.
readInt64 :: ByteString -> Maybe (Int64, ByteString)
-- | A variant of readInt specialised to Int32.
readInt32 :: ByteString -> Maybe (Int32, ByteString)
-- | A variant of readInt specialised to Int16.
readInt16 :: ByteString -> Maybe (Int16, ByteString)
-- | A variant of readInt specialised to Int8.
readInt8 :: ByteString -> Maybe (Int8, ByteString)
-- | 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
--
--
-- >>> 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
--
readWord :: ByteString -> Maybe (Word, ByteString)
-- | A variant of readWord specialised to Word64.
readWord64 :: ByteString -> Maybe (Word64, ByteString)
-- | A variant of readWord specialised to Word32.
readWord32 :: ByteString -> Maybe (Word32, ByteString)
-- | A variant of readWord specialised to Word16.
readWord16 :: ByteString -> Maybe (Word16, ByteString)
-- | A variant of readWord specialised to Word8.
readWord8 :: ByteString -> Maybe (Word8, 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
-- 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
--
--
-- >>> 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
--
readInteger :: ByteString -> Maybe (Integer, ByteString)
-- | 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
--
--
-- >>> readNatural "000111222333444555666777888999 all done"
-- Just (111222333444555666777888999," all done")
--
-- >>> readNatural "+000111222333444555666777888999 explicit sign"
-- Nothing
--
-- >>> readNatural "not a decimal number"
-- Nothing
--
readNatural :: ByteString -> Maybe (Natural, ByteString)
-- | getContents. Equivalent to hGetContents stdin. Will read lazily
getContents :: IO ByteString
-- | Write a ByteString to stdout.
--
-- The chunks will be written one at a time. Other threads might write to
-- the stdout in between, and hence putStr alone is not
-- suitable for concurrent writes.
putStr :: ByteString -> IO ()
-- | Write a ByteString to stdout, appending a newline byte.
--
-- The chunks will be written one at a time, followed by a newline. Other
-- threads might write to the stdout in between, and hence
-- putStrLn alone is not suitable for concurrent writes.
putStrLn :: ByteString -> IO ()
-- | 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.
interact :: (ByteString -> ByteString) -> IO ()
-- | Read an entire file lazily into a ByteString.
--
-- The Handle will be held open until EOF is encountered.
--
-- Note that this function's implementation relies on
-- hGetContents. The reader is advised to read its documentation.
readFile :: FilePath -> IO ByteString
-- | Write a ByteString to a file.
writeFile :: FilePath -> ByteString -> IO ()
-- | Append a ByteString to a file.
appendFile :: FilePath -> ByteString -> IO ()
-- | Read entire handle contents lazily into a ByteString.
-- Chunks are read on demand, using the default chunk size.
--
-- File handles are closed on EOF if all the file is read, or through
-- garbage collection otherwise.
hGetContents :: Handle -> IO ByteString
-- | Read n bytes into a ByteString, directly from the
-- specified Handle.
hGet :: Handle -> Int -> IO ByteString
-- | 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.
hGetNonBlocking :: Handle -> Int -> IO ByteString
-- | Outputs a ByteString to the specified Handle.
--
-- The chunks will be written one at a time. Other threads might write to
-- the Handle in between, and hence hPut alone is not
-- suitable for concurrent writes.
hPut :: Handle -> ByteString -> IO ()
-- | 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.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString
-- | A synonym for hPut, for compatibility
hPutStr :: Handle -> ByteString -> IO ()
-- | Write a ByteString to a handle, appending a newline byte.
--
-- The chunks will be written one at a time, followed by a newline. Other
-- threads might write to the Handle in between, and hence
-- hPutStrLn alone is not suitable for concurrent writes.
hPutStrLn :: Handle -> ByteString -> IO ()
-- | Manipulate ByteStrings using Char operations. All Chars
-- will be truncated to 8 bits. It can be expected that these functions
-- will run at identical speeds to their Word8 equivalents in
-- Data.ByteString.
--
-- More specifically these byte strings are taken to be in the subset of
-- Unicode covered by code points 0-255. This covers Unicode Basic Latin,
-- Latin-1 Supplement and C0+C1 Controls.
--
-- See:
--
--
--
-- 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.
module Data.ByteString.Char8
-- | 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.
data ByteString
-- | O(1) The empty ByteString
empty :: ByteString
-- | O(1) Convert a Char into a ByteString
singleton :: Char -> ByteString
-- | O(n) Convert a String into a ByteString
--
-- For applications with large numbers of string literals, pack can be a
-- bottleneck.
pack :: String -> ByteString
-- | O(n) Converts a ByteString to a String.
unpack :: ByteString -> [Char]
-- | O(1) Convert a StrictByteString into a
-- LazyByteString.
fromStrict :: StrictByteString -> LazyByteString
-- | 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.
toStrict :: LazyByteString -> StrictByteString
-- | O(n) cons is analogous to (:) for lists, but of
-- different complexity, as it requires a memcpy.
cons :: Char -> ByteString -> ByteString
infixr 5 `cons`
-- | O(n) Append a Char to the end of a ByteString. Similar
-- to cons, this function performs a memcpy.
snoc :: ByteString -> Char -> ByteString
infixl 5 `snoc`
-- | O(n) Append two ByteStrings
append :: ByteString -> ByteString -> ByteString
-- | O(1) Extract the first element of a ByteString, which must be
-- non-empty.
head :: ByteString -> Char
-- | O(1) Extract the head and tail of a ByteString, returning
-- Nothing if it is empty.
uncons :: ByteString -> Maybe (Char, ByteString)
-- | O(1) Extract the init and last of a ByteString,
-- returning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Char)
-- | O(1) Extract the last element of a packed string, which must be
-- non-empty.
last :: ByteString -> Char
-- | 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.
tail :: HasCallStack => ByteString -> ByteString
-- | 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.
init :: HasCallStack => ByteString -> ByteString
-- | O(1) Test whether a ByteString is empty.
null :: ByteString -> Bool
-- | O(1) length returns the length of a ByteString as an
-- Int.
length :: ByteString -> Int
-- | O(n) map f xs is the ByteString obtained by
-- applying f to each element of xs
map :: (Char -> Char) -> ByteString -> ByteString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: ByteString -> ByteString
-- | 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.
intersperse :: Char -> ByteString -> ByteString
-- | O(n) The intercalate function takes a ByteString
-- and a list of ByteStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString
-- | The transpose function transposes the rows and columns of its
-- ByteString argument.
transpose :: [ByteString] -> [ByteString]
-- | 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Char -> a) -> a -> ByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings.
foldl1 :: (Char -> Char -> Char) -> ByteString -> Char
-- | A strict version of foldl1
foldl1' :: (Char -> Char -> Char) -> ByteString -> Char
-- | 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
-- | foldr' is a strict variant of foldr
foldr' :: (Char -> a -> a) -> a -> ByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty ByteStrings
foldr1 :: (Char -> Char -> Char) -> ByteString -> Char
-- | A strict variant of foldr1
foldr1' :: (Char -> Char -> Char) -> ByteString -> Char
-- | O(n) Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString
-- | Map a function over a ByteString and concatenate the results
concatMap :: (Char -> ByteString) -> ByteString -> ByteString
-- | Applied to a predicate and a ByteString, any determines if any
-- element of the ByteString satisfies the predicate.
any :: (Char -> Bool) -> ByteString -> Bool
-- | Applied to a predicate and a ByteString, all determines
-- if all elements of the ByteString satisfy the predicate.
all :: (Char -> Bool) -> ByteString -> Bool
-- | maximum returns the maximum value from a ByteString
maximum :: ByteString -> Char
-- | minimum returns the minimum value from a ByteString
minimum :: ByteString -> Char
-- | 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.
--
scanl :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString
-- | scanl1 is a variant of scanl that has no starting value
-- argument:
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Char -> Char -> Char) -> ByteString -> ByteString
-- | scanr is the right-to-left dual of scanl.
scanr :: (Char -> Char -> Char) -> Char -> ByteString -> ByteString
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: (Char -> Char -> Char) -> ByteString -> ByteString
-- | 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.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)
-- | 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.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> ByteString -> (acc, ByteString)
-- | 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)
replicate :: Int -> Char -> ByteString
-- | 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"
--
unfoldr :: (a -> Maybe (Char, a)) -> a -> ByteString
-- | 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)
--
unfoldrN :: Int -> (a -> Maybe (Char, a)) -> a -> (ByteString, Maybe a)
-- | O(1) take n, applied to a ByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Int -> ByteString -> ByteString
-- | 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"
--
takeEnd :: Int -> ByteString -> ByteString
-- | O(1) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Int -> ByteString -> ByteString
-- | 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"
-- ""
--
dropEnd :: Int -> ByteString -> ByteString
-- | O(1) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Int -> ByteString -> (ByteString, ByteString)
-- | takeWhile, applied to a predicate p and a ByteString
-- xs, returns the longest prefix (possibly empty) of
-- xs of elements that satisfy p.
takeWhile :: (Char -> Bool) -> ByteString -> ByteString
-- | takeWhileEnd, applied to a predicate p and a
-- ByteString xs, returns the longest suffix (possibly empty) of
-- xs of elements that satisfy p.
takeWhileEnd :: (Char -> Bool) -> ByteString -> ByteString
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs.
dropWhile :: (Char -> Bool) -> ByteString -> ByteString
-- | dropWhileEnd p xs returns the prefix remaining after
-- takeWhileEnd p xs.
dropWhileEnd :: (Char -> Bool) -> ByteString -> ByteString
-- | 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
--
dropSpace :: ByteString -> ByteString
-- | span p xs breaks the ByteString into two segments. It
-- is equivalent to (takeWhile p xs, dropWhile p
-- xs)
span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | 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)
--
spanEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | break p is equivalent to span (not .
-- p).
break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | breakEnd behaves like break but from the end of the
-- ByteString
--
-- breakEnd p == spanEnd (not.p)
breakEnd :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | 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
-- (==)
group :: ByteString -> [ByteString]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: (Char -> Char -> Bool) -> ByteString -> [ByteString]
-- | O(n) Returns all initial segments of the given
-- ByteString, shortest first.
inits :: ByteString -> [ByteString]
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tails :: ByteString -> [ByteString]
-- | O(n) Returns all initial segments of the given
-- ByteString, shortest first.
initsNE :: ByteString -> NonEmpty ByteString
-- | O(n) Returns all final segments of the given ByteString,
-- longest first.
tailsNE :: ByteString -> NonEmpty ByteString
-- | Remove leading and trailing white space from a ByteString.
strip :: ByteString -> ByteString
-- | 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.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString
-- | 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.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString
-- | 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 ByteStrings that
-- are slices of the original.
split :: Char -> ByteString -> [ByteString]
-- | 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 [""]
--
splitWith :: (Char -> Bool) -> ByteString -> [ByteString]
-- | 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.
lines :: ByteString -> [ByteString]
-- | words breaks a ByteString up into a list of words, which were
-- delimited by Chars representing white space.
words :: ByteString -> [ByteString]
-- | unlines joins lines, appending a terminating newline after
-- each.
--
-- Equivalent to concat . Data.List.concatMap (\x -> [x,
-- singleton '\n']).
unlines :: [ByteString] -> ByteString
-- | The unwords function is analogous to the unlines
-- function, on words.
unwords :: [ByteString] -> ByteString
-- | O(n) The isPrefixOf function takes two ByteStrings and
-- returns True if the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool
-- | 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..
isSuffixOf :: ByteString -> ByteString -> Bool
-- | Check whether one string is a substring of another.
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:
--
--
-- 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.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)
-- | O(n) elem is the ByteString membership predicate.
-- This implementation uses memchr(3).
elem :: Char -> ByteString -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Char -> ByteString -> Bool
-- | 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.
find :: (Char -> Bool) -> ByteString -> Maybe Char
-- | O(n) filter, applied to a predicate and a ByteString,
-- returns a ByteString containing those characters that satisfy the
-- predicate.
filter :: (Char -> Bool) -> ByteString -> ByteString
partition :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)
-- | O(1) ByteString index (subscript) operator, starting
-- from 0.
index :: ByteString -> Int -> Char
-- | O(1) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ByteString -> Int -> Maybe Char
-- | O(1) ByteString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ByteString -> Int -> Maybe Char
-- | 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.
elemIndex :: Char -> ByteString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- by returning the indices of all elements equal to the query element,
-- in ascending order.
elemIndices :: Char -> ByteString -> [Int]
-- | 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)
--
elemIndexEnd :: Char -> ByteString -> Maybe Int
-- | The findIndex function takes a predicate and a
-- ByteString and returns the index of the first element in the
-- ByteString satisfying the predicate.
findIndex :: (Char -> Bool) -> ByteString -> Maybe Int
-- | The findIndices function extends findIndex, by returning
-- the indices of all elements satisfying the predicate, in ascending
-- order.
findIndices :: (Char -> Bool) -> ByteString -> [Int]
-- | 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.
findIndexEnd :: (Char -> Bool) -> ByteString -> Maybe Int
-- | 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.
count :: Char -> ByteString -> Int
-- | 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
zip :: ByteString -> ByteString -> [(Char, Char)]
-- | 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.
zipWith :: (Char -> Char -> a) -> ByteString -> ByteString -> [a]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two ByteStrings, to build a 3rd.
packZipWith :: (Char -> Char -> Char) -> ByteString -> ByteString -> ByteString
-- | unzip transforms a list of pairs of Chars into a pair of
-- ByteStrings. Note that this performs two pack operations.
unzip :: [(Char, Char)] -> (ByteString, ByteString)
-- | O(n) Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString
-- | 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
--
--
-- >>> 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
--
readInt :: ByteString -> Maybe (Int, ByteString)
-- | A variant of readInt specialised to Int64.
readInt64 :: ByteString -> Maybe (Int64, ByteString)
-- | A variant of readInt specialised to Int32.
readInt32 :: ByteString -> Maybe (Int32, ByteString)
-- | A variant of readInt specialised to Int16.
readInt16 :: ByteString -> Maybe (Int16, ByteString)
-- | A variant of readInt specialised to Int8.
readInt8 :: ByteString -> Maybe (Int8, ByteString)
-- | 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
--
--
-- >>> 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
--
readWord :: ByteString -> Maybe (Word, ByteString)
-- | A variant of readWord specialised to Word64.
readWord64 :: ByteString -> Maybe (Word64, ByteString)
-- | A variant of readWord specialised to Word32.
readWord32 :: ByteString -> Maybe (Word32, ByteString)
-- | A variant of readWord specialised to Word16.
readWord16 :: ByteString -> Maybe (Word16, ByteString)
-- | A variant of readWord specialised to Word8.
readWord8 :: ByteString -> Maybe (Word8, 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
-- 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
--
--
-- >>> 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
--
readInteger :: ByteString -> Maybe (Integer, ByteString)
-- | 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
--
--
-- >>> readNatural "000111222333444555666777888999 all done"
-- Just (111222333444555666777888999," all done")
--
-- >>> readNatural "+000111222333444555666777888999 explicit sign"
-- Nothing
--
-- >>> readNatural "not a decimal number"
-- Nothing
--
readNatural :: ByteString -> Maybe (Natural, ByteString)
-- | 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.
copy :: ByteString -> ByteString
-- | 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.
packCString :: CString -> IO ByteString
-- | 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.
packCStringLen :: CStringLen -> IO ByteString
-- | 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.
useAsCString :: ByteString -> (CString -> IO a) -> IO a
-- | 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).
useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
-- | Read a line from stdin.
getLine :: IO ByteString
-- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The
-- Handle 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.
--
-- Unlike putStr, this is not atomic: other threads might write to
-- stdout between writing of the bytestring and the newline.
putStrLn :: ByteString -> IO ()
-- | 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.
interact :: (ByteString -> ByteString) -> IO ()
-- | Read an entire file strictly into a ByteString.
readFile :: FilePath -> IO ByteString
-- | Write a ByteString to a file.
writeFile :: FilePath -> ByteString -> IO ()
-- | Append a ByteString to a file.
appendFile :: FilePath -> ByteString -> IO ()
-- | Read a line from a handle
hGetLine :: Handle -> IO ByteString
-- | 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.
hGetContents :: Handle -> IO ByteString
-- | 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.
hGet :: Handle -> Int -> IO ByteString
-- | 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.
hGetSome :: Handle -> Int -> IO ByteString
-- | 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.
hGetNonBlocking :: Handle -> Int -> IO ByteString
-- | Outputs a ByteString to the specified Handle.
hPut :: Handle -> ByteString -> IO ()
-- | 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.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString
-- | A synonym for hPut, for compatibility
hPutStr :: Handle -> ByteString -> IO ()
-- | 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.
hPutStrLn :: Handle -> ByteString -> IO ()
-- |
-- - Warning:* this module is internal. If you find that you need it
-- then please contact the maintainers and explain what you are trying to
-- do and discuss what you would need in the public API. It is important
-- that you do this as the module may not be exposed at all in future
-- releases.
--
--
-- Core types and functions for the Builder monoid and its
-- generalization, the Put monad.
--
-- The design of the Builder monoid is optimized such that
--
--
-- - buffers of arbitrary size can be filled as efficiently as possible
-- and
-- - sequencing of Builders is as cheap as possible.
--
--
-- We achieve (1) by completely handing over control over writing to the
-- buffer to the BuildStep implementing the Builder. This
-- BuildStep is just told the start and the end of the buffer
-- (represented as a BufferRange). Then, the BuildStep can
-- write to as big a prefix of this BufferRange in any way it
-- desires. If the BuildStep is done, the BufferRange is
-- full, or a long sequence of bytes should be inserted directly, then
-- the BuildStep signals this to its caller using a
-- BuildSignal.
--
-- We achieve (2) by requiring that every Builder is implemented
-- by a BuildStep that takes a continuation BuildStep,
-- which it calls with the updated BufferRange after it is done.
-- Therefore, only two pointers have to be passed in a function call to
-- implement concatenation of Builders. Moreover, many
-- Builders are completely inlined, which enables the compiler to
-- sequence them without a function call and with no boxing at all.
--
-- This design gives the implementation of a Builder full access
-- to the IO monad. Therefore, utmost care has to be taken to not
-- overwrite anything outside the given BufferRanges. Moreover,
-- further care has to be taken to ensure that Builders and
-- Puts are referentially transparent. See the comments of the
-- builder and put functions for further information. Note
-- that there are no safety belts at all, when implementing a
-- Builder using an IO action: you are writing code that
-- might enable the next buffer-overflow attack on a Haskell server!
module Data.ByteString.Builder.Internal
-- | A Buffer together with the BufferRange of free bytes.
-- The filled space starts at offset 0 and ends at the first free byte.
data Buffer
Buffer :: {-# UNPACK #-} !ForeignPtr Word8 -> {-# UNPACK #-} !BufferRange -> Buffer
-- | A range of bytes in a buffer represented by the pointer to the first
-- byte of the range and the pointer to the first byte after the
-- range.
data BufferRange
BufferRange :: {-# UNPACK #-} !Ptr Word8 -> {-# UNPACK #-} !Ptr Word8 -> BufferRange
-- | Allocate a new buffer of the given size.
newBuffer :: Int -> IO Buffer
-- | Combined size of the filled and free space in the buffer.
bufferSize :: Buffer -> Int
-- | Convert the filled part of a Buffer to a
-- StrictByteString.
byteStringFromBuffer :: Buffer -> StrictByteString
-- | A stream of chunks that are constructed in the IO monad.
--
-- This datatype serves as the common interface for the buffer-by-buffer
-- execution of a BuildStep by buildStepToCIOS. Typical
-- users of this interface are ciosToLazyByteString or
-- iteratee-style libraries like enumerator.
data ChunkIOStream a
-- | The partially filled last buffer together with the result.
Finished :: Buffer -> a -> ChunkIOStream a
-- | Yield a non-empty StrictByteString.
Yield1 :: StrictByteString -> IO (ChunkIOStream a) -> ChunkIOStream a
-- | Convert a BuildStep to a ChunkIOStream stream by
-- executing it on Buffers allocated according to the given
-- AllocationStrategy.
buildStepToCIOS :: AllocationStrategy -> BuildStep a -> IO (ChunkIOStream a)
-- | Convert a ChunkIOStream () to a LazyByteString
-- using unsafeDupablePerformIO.
ciosUnitToLazyByteString :: AllocationStrategy -> LazyByteString -> ChunkIOStream () -> LazyByteString
-- | Convert a ChunkIOStream to a lazy tuple of the result and the
-- written LazyByteString using unsafeDupablePerformIO.
ciosToLazyByteString :: AllocationStrategy -> (a -> (b, LazyByteString)) -> ChunkIOStream a -> (b, LazyByteString)
-- | BuildSignals abstract signals to the caller of a
-- BuildStep. There are three signals: done,
-- bufferFull, or 'insertChunks signals
data BuildSignal a
-- | BuildSteps may be called *multiple times* and they must not
-- rise an async. exception.
type BuildStep a = BufferRange -> IO BuildSignal a
-- | The final build step that returns the done signal.
finalBuildStep :: BuildStep ()
-- | Signal that the current BuildStep is done and has computed a
-- value.
done :: Ptr Word8 -> a -> BuildSignal a
-- | Signal that the current buffer is full.
bufferFull :: Int -> Ptr Word8 -> BuildStep a -> BuildSignal a
-- | Signal that a StrictByteString chunk should be inserted
-- directly.
insertChunk :: Ptr Word8 -> StrictByteString -> BuildStep a -> BuildSignal a
-- | Fill a BufferRange using a BuildStep.
fillWithBuildStep :: BuildStep a -> (Ptr Word8 -> a -> IO b) -> (Ptr Word8 -> Int -> BuildStep a -> IO b) -> (Ptr Word8 -> StrictByteString -> BuildStep a -> IO b) -> BufferRange -> IO b
-- | Builders denote sequences of bytes. They are Monoids
-- where mempty is the zero-length sequence and mappend is
-- concatenation, which runs in O(1).
data Builder
-- | Construct a Builder. In contrast to BuildSteps,
-- Builders are referentially transparent.
builder :: (forall r. () => BuildStep r -> BuildStep r) -> Builder
-- | Run a Builder with the finalBuildStep.
runBuilder :: Builder -> BuildStep ()
-- | Run a Builder.
runBuilderWith :: Builder -> BuildStep a -> BuildStep a
-- | The Builder denoting a zero-length sequence of bytes. This
-- function is only exported for use in rewriting rules. Use
-- mempty otherwise.
empty :: Builder
-- | Concatenate two Builders. This function is only exported for
-- use in rewriting rules. Use mappend otherwise.
append :: Builder -> Builder -> Builder
-- | Flush the current buffer. This introduces a chunk boundary.
flush :: Builder
-- | ensureFree n ensures that there are at least
-- n free bytes for the following Builder.
ensureFree :: Int -> Builder
-- | Construct a Builder that copies the StrictByteString.
--
-- Use this function to create Builders from smallish (<=
-- 4kb) StrictByteStrings or if you need to guarantee that
-- the StrictByteString is not shared with the chunks generated by
-- the Builder.
byteStringCopy :: StrictByteString -> Builder
-- | Construct a Builder that always inserts the
-- StrictByteString directly as a chunk.
--
-- This implies flushing the output buffer, even if it contains just a
-- single byte. You should therefore use byteStringInsert only for
-- large (> 8kb) StrictByteStrings. Otherwise, the
-- generated chunks are too fragmented to be processed efficiently
-- afterwards.
byteStringInsert :: StrictByteString -> Builder
-- | Construct a Builder that copies the StrictByteStrings,
-- if it is smaller than the treshold, and inserts it directly otherwise.
--
-- For example, byteStringThreshold 1024 copies
-- StrictByteStrings whose size is less or equal to 1kb, and
-- inserts them directly otherwise. This implies that the average
-- chunk-size of the generated LazyByteString may be as low as 513
-- bytes, as there could always be just a single byte between the
-- directly inserted 1025 byte, StrictByteStrings.
byteStringThreshold :: Int -> StrictByteString -> Builder
-- | Construct a Builder that copies the LazyByteString.
lazyByteStringCopy :: LazyByteString -> Builder
-- | Construct a Builder that inserts all chunks of the
-- LazyByteString directly.
lazyByteStringInsert :: LazyByteString -> Builder
-- | Construct a Builder that uses the thresholding strategy of
-- byteStringThreshold for each chunk of the
-- LazyByteString.
lazyByteStringThreshold :: Int -> LazyByteString -> Builder
-- | Construct a Builder that copies the ShortByteString.
shortByteString :: ShortByteString -> Builder
-- | The maximal size of a StrictByteString that is copied. 2 *
-- smallChunkSize to guarantee that on average a chunk is of
-- smallChunkSize.
maximalCopySize :: Int
-- | Create a Builder denoting the same sequence of bytes as a
-- StrictByteString. The Builder inserts large
-- StrictByteStrings directly, but copies small ones to ensure
-- that the generated chunks are large on average.
byteString :: StrictByteString -> Builder
-- | Create a Builder denoting the same sequence of bytes as a lazy
-- LazyByteString. The Builder inserts large chunks of the
-- LazyByteString directly, but copies small ones to ensure that
-- the generated chunks are large on average.
lazyByteString :: LazyByteString -> Builder
-- | Execute a Builder and return the generated chunks as a
-- LazyByteString. The work is performed lazy, i.e., only when a
-- chunk of the LazyByteString is forced.
toLazyByteString :: Builder -> LazyByteString
-- | Heavy inlining. Execute a Builder with custom execution
-- parameters.
--
-- This function is inlined despite its heavy code-size to allow fusing
-- with the allocation strategy. For example, the default Builder
-- execution function toLazyByteString is defined as follows.
--
--
-- {-# NOINLINE toLazyByteString #-}
-- toLazyByteString =
-- toLazyByteStringWith (safeStrategy smallChunkSize defaultChunkSize) L.Empty
--
--
-- where L.Empty is the zero-length LazyByteString.
--
-- In most cases, the parameters used by toLazyByteString give
-- good performance. A sub-performing case of toLazyByteString is
-- executing short (<128 bytes) Builders. In this case, the
-- allocation overhead for the first 4kb buffer and the trimming cost
-- dominate the cost of executing the Builder. You can avoid this
-- problem using
--
--
-- toLazyByteStringWith (safeStrategy 128 smallChunkSize) L.Empty
--
--
-- This reduces the allocation and trimming overhead, as all generated
-- LazyByteStrings fit into the first buffer and there is no
-- trimming required, if more than 64 bytes and less than 128 bytes are
-- written.
toLazyByteStringWith :: AllocationStrategy -> LazyByteString -> Builder -> LazyByteString
-- | A buffer allocation strategy for executing Builders.
data AllocationStrategy
-- | Use this strategy for generating LazyByteStrings whose chunks
-- are likely to survive one garbage collection. This strategy trims
-- buffers that are filled less than half in order to avoid spilling too
-- much memory.
safeStrategy :: Int -> Int -> AllocationStrategy
-- | Use this strategy for generating LazyByteStrings whose chunks
-- are discarded right after they are generated. For example, if you just
-- generate them to write them to a network socket.
untrimmedStrategy :: Int -> Int -> AllocationStrategy
-- | Create a custom allocation strategy. See the code for
-- safeStrategy and untrimmedStrategy for examples.
customStrategy :: (Maybe (Buffer, Int) -> IO Buffer) -> Int -> (Int -> Int -> Bool) -> AllocationStrategy
-- | The recommended chunk size. Currently set to 4k, less the memory
-- management overhead
smallChunkSize :: Int
-- | The chunk size used for I/O. Currently set to 32k, less the memory
-- management overhead
defaultChunkSize :: Int
-- | The memory management overhead. Currently this is tuned for GHC only.
chunkOverhead :: Int
-- | A Put action denotes a computation of a value that writes a
-- stream of bytes as a side-effect. Puts are strict in their
-- side-effect; i.e., the stream of bytes will always be written before
-- the computed value is returned.
--
-- Puts are a generalization of Builders. The typical use
-- case is the implementation of an encoding that might fail (e.g., an
-- interface to the zlib compression library or the conversion
-- from Base64 encoded data to 8-bit data). For a Builder, the
-- only way to handle and report such a failure is ignore it or call
-- error. In contrast, Put actions are expressive enough to
-- allow reporting and handling such a failure in a pure fashion.
--
-- Put () actions are isomorphic to Builders. The
-- functions putBuilder and fromPut convert between these
-- two types. Where possible, you should use Builders, as
-- sequencing them is slightly cheaper than sequencing Puts
-- because they do not carry around a computed value.
data Put a
-- | Construct a Put action. In contrast to BuildSteps,
-- Puts are referentially transparent in the sense that sequencing
-- the same Put multiple times yields every time the same value
-- with the same side-effect.
put :: (forall r. () => (a -> BuildStep r) -> BuildStep r) -> Put a
-- | Run a Put.
runPut :: Put a -> BuildStep a
-- | Execute a Put and return the computed result and the bytes
-- written during the computation as a LazyByteString.
--
-- This function is strict in the computed result and lazy in the writing
-- of the bytes. For example, given
--
--
-- infinitePut = sequence_ (repeat (putBuilder (word8 1))) >> return 0
--
--
--
-- evaluating the expression
--
--
-- fst $ putToLazyByteString infinitePut
--
--
--
-- does not terminate, while evaluating the expression
--
--
-- L.head $ snd $ putToLazyByteString infinitePut
--
--
--
-- does terminate and yields the value 1 :: Word8.
--
-- An illustrative example for these strictness properties is the
-- implementation of Base64 decoding
-- (http://en.wikipedia.org/wiki/Base64).
--
--
-- type DecodingState = ...
--
-- decodeBase64 :: StrictByteString -> DecodingState -> Put (Maybe DecodingState)
-- decodeBase64 = ...
--
--
--
-- The above function takes a StrictByteString supposed to
-- represent Base64 encoded data and the current decoding state. It
-- writes the decoded bytes as the side-effect of the Put and
-- returns the new decoding state, if the decoding of all data in the
-- StrictByteString was successful. The checking if the
-- StrictByteString represents Base64 encoded data and the actual
-- decoding are fused. This makes the common case, where all data
-- represents Base64 encoded data, more efficient. It also implies that
-- all data must be decoded before the final decoding state can be
-- returned. Puts are intended for implementing such fused
-- checking and decoding/encoding, which is reflected in their strictness
-- properties.
putToLazyByteString :: Put a -> (a, LazyByteString)
-- | Execute a Put with a buffer-allocation strategy and a
-- continuation. For example, putToLazyByteString is implemented
-- as follows.
--
--
-- putToLazyByteString = putToLazyByteStringWith
-- (safeStrategy smallChunkSize defaultChunkSize) (x -> (x, L.empty))
--
--
putToLazyByteStringWith :: AllocationStrategy -> (a -> (b, LazyByteString)) -> Put a -> (b, LazyByteString)
-- | Run a Put action redirecting the produced output to a
-- Handle.
--
-- The output is buffered using the Handles associated buffer. If
-- this buffer is too small to execute one step of the Put action,
-- then it is replaced with a large enough buffer.
hPut :: Handle -> Put a -> IO a
-- | Run a Builder as a side-effect of a Put ()
-- action.
putBuilder :: Builder -> Put ()
-- | Convert a Put () action to a Builder.
fromPut :: Put () -> Builder
instance GHC.Internal.Base.Applicative Data.ByteString.Builder.Internal.Put
instance GHC.Internal.Base.Functor Data.ByteString.Builder.Internal.Put
instance GHC.Internal.IsList.IsList Data.ByteString.Builder.Internal.Builder
instance GHC.Internal.Base.Monad Data.ByteString.Builder.Internal.Put
instance GHC.Internal.Base.Monoid Data.ByteString.Builder.Internal.Builder
instance Control.DeepSeq.NFData Data.ByteString.Builder.Internal.Buffer
instance Control.DeepSeq.NFData Data.ByteString.Builder.Internal.BufferRange
instance GHC.Internal.Base.Semigroup Data.ByteString.Builder.Internal.Builder
-- | This module provides Builder primitives, which are lower
-- level building blocks for constructing Builders. You don't need
-- to go down to this level but it can be slightly faster.
--
-- Morally, builder primitives are like functions a ->
-- Builder, that is they take a value and encode it as a sequence of
-- bytes, represented as a Builder. Of course their implementation
-- is a bit more specialised.
--
-- Builder primitives come in two forms: fixed-size and bounded-size.
--
--
-- - Fixed(-size) primitives are builder primitives that always
-- result in a sequence of bytes of a fixed length. That is, the length
-- is independent of the value that is encoded. An example of a fixed
-- size primitive is the big-endian encoding of a Word64, which
-- always results in exactly 8 bytes.
-- - Bounded(-size) primitives are builder primitives that
-- always result in a sequence of bytes that is no larger than a
-- predetermined bound. That is, the bound is independent of the value
-- that is encoded but the actual length will depend on the value. An
-- example for a bounded primitive is the UTF-8 encoding of a
-- Char, which can be 1,2,3 or 4 bytes long, so the bound is 4
-- bytes.
--
--
-- Note that fixed primitives can be considered as a special case of
-- bounded primitives, and we can lift from fixed to bounded.
--
-- Because bounded primitives are the more general case, in this
-- documentation we only refer to fixed size primitives where it matters
-- that the resulting sequence of bytes is of a fixed length. Otherwise,
-- we just refer to bounded size primitives.
--
-- The purpose of using builder primitives is to improve the performance
-- of Builders. These improvements stem from making the two most
-- common steps performed by a Builder more efficient. We explain
-- these two steps in turn.
--
-- The first most common step is the concatenation of two
-- Builders. Internally, concatenation corresponds to function
-- composition. (Note that Builders can be seen as
-- difference-lists of buffer-filling functions; cf.
-- http://hackage.haskell.org/cgi-bin/hackage-scripts/package/dlist.
-- ) Function composition is a fast O(1) operation. However, we
-- can use bounded primitives to remove some of these function
-- compositions altogether, which is more efficient.
--
-- The second most common step performed by a Builder is to fill a
-- buffer using a bounded primitives, which works as follows. The
-- Builder checks whether there is enough space left to execute
-- the bounded primitive. If there is, then the Builder executes
-- the bounded primitive and calls the next Builder with the
-- updated buffer. Otherwise, the Builder signals its driver that
-- it requires a new buffer. This buffer must be at least as large as the
-- bound of the primitive. We can use bounded primitives to reduce the
-- number of buffer-free checks by fusing the buffer-free checks of
-- consecutive Builders. We can also use bounded primitives to
-- simplify the control flow for signalling that a buffer is full by
-- ensuring that we check first that there is enough space left and only
-- then decide on how to encode a given value.
--
-- Let us illustrate these improvements on the CSV-table rendering
-- example from Data.ByteString.Builder. Its "hot code" is the
-- rendering of a table's cells, which we implement as follows using only
-- the functions from the Builder API.
--
--
-- import Data.ByteString.Builder as B
--
-- renderCell :: Cell -> Builder
-- renderCell (StringC cs) = renderString cs
-- renderCell (IntC i) = B.intDec i
--
-- renderString :: String -> Builder
-- renderString cs = B.charUtf8 '"' <> foldMap escape cs <> B.charUtf8 '"'
-- where
-- escape '\\' = B.charUtf8 '\\' <> B.charUtf8 '\\'
-- escape '\"' = B.charUtf8 '\\' <> B.charUtf8 '\"'
-- escape c = B.charUtf8 c
--
--
-- Efficient encoding of Ints as decimal numbers is performed by
-- intDec. Optimization potential exists for the escaping of
-- Strings. The above implementation has two optimization
-- opportunities. First, the buffer-free checks of the Builders
-- for escaping double quotes and backslashes can be fused. Second, the
-- concatenations performed by foldMap can be eliminated. The
-- following implementation exploits these optimizations.
--
--
-- import qualified Data.ByteString.Builder.Prim as P
-- import Data.ByteString.Builder.Prim
-- ( condB, liftFixedToBounded, (>*<), (>$<) )
--
-- renderString :: String -> Builder
-- renderString cs =
-- B.charUtf8 '"' <> primMapListBounded escape cs <> B.charUtf8 '"'
-- where
-- escape :: BoundedPrim Char
-- escape =
-- condB (== '\\') (fixed2 ('\\', '\\')) $
-- condB (== '\"') (fixed2 ('\\', '\"')) $
-- charUtf8
--
-- {-# INLINE fixed2 #-}
-- fixed2 x = liftFixedToBounded $ const x >$< char7 >*< char7
--
--
-- The code should be mostly self-explanatory. The slightly awkward
-- syntax is because the combinators are written such that the size-bound
-- of the resulting BoundedPrim can be computed at compile time.
-- We also explicitly inline the fixed2 primitive, which encodes
-- a fixed tuple of characters, to ensure that the bound computation
-- happens at compile time. When encoding the following list of
-- Strings, the optimized implementation of renderString
-- is two times faster.
--
--
-- maxiStrings :: [String]
-- maxiStrings = take 1000 $ cycle ["hello", "\"1\"", "λ-wörld"]
--
--
-- Most of the performance gain stems from using
-- primMapListBounded, which encodes a list of values from
-- left-to-right with a BoundedPrim. It exploits the
-- Builder internals to avoid unnecessary function compositions
-- (i.e., concatenations). In the future, we might expect the compiler to
-- perform the optimizations implemented in primMapListBounded.
-- However, it seems that the code is currently to complicated for the
-- compiler to see through. Therefore, we provide the BoundedPrim
-- escape hatch, which allows data structures to provide very efficient
-- encoding traversals, like primMapListBounded for lists.
--
-- Note that BoundedPrims are a bit verbose, but quite versatile.
-- Here is an example of a BoundedPrim for combined HTML escaping
-- and UTF-8 encoding. It exploits that the escaped character with the
-- maximal Unicode codepoint is '>'.
--
--
-- {-# INLINE charUtf8HtmlEscaped #-}
-- charUtf8HtmlEscaped :: BoundedPrim Char
-- charUtf8HtmlEscaped =
-- condB (> '>' ) charUtf8 $
-- condB (== '<' ) (fixed4 ('&',('l',('t',';')))) $ -- <
-- condB (== '>' ) (fixed4 ('&',('g',('t',';')))) $ -- >
-- condB (== '&' ) (fixed5 ('&',('a',('m',('p',';'))))) $ -- &
-- condB (== '"' ) (fixed5 ('&',('#',('3',('4',';'))))) $ -- "
-- condB (== '\'') (fixed5 ('&',('#',('3',('9',';'))))) $ -- '
-- (liftFixedToBounded char7) -- fallback for Chars smaller than '>'
-- where
-- {-# INLINE fixed4 #-}
-- fixed4 x = liftFixedToBounded $ const x >$<
-- char7 >*< char7 >*< char7 >*< char7
--
-- {-# INLINE fixed5 #-}
-- fixed5 x = liftFixedToBounded $ const x >$<
-- char7 >*< char7 >*< char7 >*< char7 >*< char7
--
--
-- This module currently does not expose functions that require the
-- special properties of fixed-size primitives. They are useful for
-- prefixing Builders with their size or for implementing chunked
-- encodings. We will expose the corresponding functions in future
-- releases of this library.
module Data.ByteString.Builder.Prim
-- | A builder primitive that always results in sequence of bytes that is
-- no longer than a pre-determined bound.
data BoundedPrim a
-- | The BoundedPrim that always results in the zero-length
-- sequence.
emptyB :: BoundedPrim a
-- | A pairing/concatenation operator for builder primitives, both bounded
-- and fixed size.
--
-- For example,
--
--
-- toLazyByteString (primFixed (char7 >*< char7) ('x','y')) = "xy"
--
--
-- We can combine multiple primitives using >*< multiple
-- times.
--
--
-- toLazyByteString (primFixed (char7 >*< char7 >*< char7) ('x',('y','z'))) = "xyz"
--
(>*<) :: Monoidal f => f a -> f b -> f (a, b)
infixr 5 >*<
-- | A fmap-like operator for builder primitives, both bounded and fixed
-- size.
--
-- Builder primitives are contravariant so it's like the normal fmap, but
-- backwards (look at the type). (If it helps to remember, the operator
-- symbol is like ($) but backwards.)
--
-- We can use it for example to prepend and/or append fixed values to an
-- primitive.
--
--
-- import Data.ByteString.Builder.Prim as P
-- showEncoding ((\x -> ('\'', (x, '\''))) >$< fixed3) 'x' = "'x'"
-- where
-- fixed3 = P.char7 >*< P.char7 >*< P.char7
--
--
-- Note that the rather verbose syntax for composition stems from the
-- requirement to be able to compute the size / size bound at compile
-- time.
(>$<) :: Contravariant f => (b -> a) -> f a -> f b
infixl 4 >$<
-- | Encode an Either value using the first BoundedPrim for
-- Left values and the second BoundedPrim for Right
-- values.
--
-- Note that the functions eitherB, pairB, and
-- contramapB (written below using >$<) suffice to
-- construct BoundedPrims for all non-recursive algebraic
-- datatypes. For example,
--
--
-- maybeB :: BoundedPrim () -> BoundedPrim a -> BoundedPrim (Maybe a)
-- maybeB nothing just = maybe (Left ()) Right >$< eitherB nothing just
--
--
eitherB :: BoundedPrim a -> BoundedPrim b -> BoundedPrim (Either a b)
-- | Conditionally select a BoundedPrim. For example, we can
-- implement the ASCII primitive that drops characters with Unicode
-- codepoints above 127 as follows.
--
--
-- charASCIIDrop = condB (< '\128') (liftFixedToBounded char7) emptyB
--
--
condB :: (a -> Bool) -> BoundedPrim a -> BoundedPrim a -> BoundedPrim a
-- | Create a Builder that encodes values with the given
-- BoundedPrim.
--
-- We rewrite consecutive uses of primBounded such that the
-- bound-checks are fused. For example,
--
--
-- primBounded (word32 c1) `mappend` primBounded (word32 c2)
--
--
-- is rewritten such that the resulting Builder checks only once,
-- if ther are at 8 free bytes, instead of checking twice, if there are 4
-- free bytes. This optimization is not observationally equivalent in a
-- strict sense, as it influences the boundaries of the generated chunks.
-- However, for a user of this library it is observationally equivalent,
-- as chunk boundaries of a LazyByteString can only be observed
-- through the internal interface. Moreover, we expect that all
-- primitives write much fewer than 4kb (the default short buffer size).
-- Hence, it is safe to ignore the additional memory spilled due to the
-- more aggressive buffer wrapping introduced by this optimization.
primBounded :: BoundedPrim a -> a -> Builder
-- | Create a Builder that encodes a list of values consecutively
-- using a BoundedPrim for each element. This function is more
-- efficient than
--
--
-- mconcat . map (primBounded w)
--
--
-- or
--
--
-- foldMap (primBounded w)
--
--
-- because it moves several variables out of the inner loop.
primMapListBounded :: BoundedPrim a -> [a] -> Builder
-- | Create a Builder that encodes a sequence generated from a seed
-- value using a BoundedPrim for each sequence element.
primUnfoldrBounded :: BoundedPrim b -> (a -> Maybe (b, a)) -> a -> Builder
-- | Create a Builder that encodes each Word8 of a
-- StrictByteString using a BoundedPrim. For example, we
-- can write a Builder that filters a StrictByteString as
-- follows.
--
--
-- import qualified Data.ByteString.Builder.Prim as P
--
--
--
-- filterBS p = P.condB p (P.liftFixedToBounded P.word8) P.emptyB
--
primMapByteStringBounded :: BoundedPrim Word8 -> StrictByteString -> Builder
-- | Chunk-wise application of primMapByteStringBounded.
primMapLazyByteStringBounded :: BoundedPrim Word8 -> LazyByteString -> Builder
-- | A builder primitive that always results in a sequence of bytes of a
-- pre-determined, fixed size.
data FixedPrim a
-- | The FixedPrim that always results in the zero-length sequence.
emptyF :: FixedPrim a
-- | Lift a FixedPrim to a BoundedPrim.
liftFixedToBounded :: FixedPrim a -> BoundedPrim a
-- | Encode a value with a FixedPrim.
primFixed :: FixedPrim a -> a -> Builder
-- | Encode a list of values from left-to-right with a FixedPrim.
primMapListFixed :: FixedPrim a -> [a] -> Builder
-- | Encode a list of values represented as an unfoldr with a
-- FixedPrim.
primUnfoldrFixed :: FixedPrim b -> (a -> Maybe (b, a)) -> a -> Builder
-- | Heavy inlining. Encode all bytes of a StrictByteString
-- from left-to-right with a FixedPrim. This function is quite
-- versatile. For example, we can use it to construct a Builder
-- that maps every byte before copying it to the buffer to be filled.
--
--
-- mapToBuilder :: (Word8 -> Word8) -> S.StrictByteString -> Builder
-- mapToBuilder f = primMapByteStringFixed (contramapF f word8)
--
--
-- We can also use it to hex-encode a StrictByteString as shown by
-- the byteStringHex example above.
primMapByteStringFixed :: FixedPrim Word8 -> StrictByteString -> Builder
-- | Heavy inlining. Encode all bytes of a LazyByteString
-- from left-to-right with a FixedPrim.
primMapLazyByteStringFixed :: FixedPrim Word8 -> LazyByteString -> Builder
-- | Encoding single signed bytes as-is.
int8 :: FixedPrim Int8
-- | Encoding single unsigned bytes as-is.
word8 :: FixedPrim Word8
-- | Encoding Int16s in big endian format.
int16BE :: FixedPrim Int16
-- | Encoding Int32s in big endian format.
int32BE :: FixedPrim Int32
-- | Encoding Int64s in big endian format.
int64BE :: FixedPrim Int64
-- | Encoding Word16s in big endian format.
word16BE :: FixedPrim Word16
-- | Encoding Word32s in big endian format.
word32BE :: FixedPrim Word32
-- | Encoding Word64s in big endian format.
word64BE :: FixedPrim Word64
-- | Encode a Float in big endian format.
floatBE :: FixedPrim Float
-- | Encode a Double in big endian format.
doubleBE :: FixedPrim Double
-- | Encoding Int16s in little endian format.
int16LE :: FixedPrim Int16
-- | Encoding Int32s in little endian format.
int32LE :: FixedPrim Int32
-- | Encoding Int64s in little endian format.
int64LE :: FixedPrim Int64
-- | Encoding Word16s in little endian format.
word16LE :: FixedPrim Word16
-- | Encoding Word32s in little endian format.
word32LE :: FixedPrim Word32
-- | Encoding Word64s in little endian format.
word64LE :: FixedPrim Word64
-- | Encode a Float in little endian format.
floatLE :: FixedPrim Float
-- | Encode a Double in little endian format.
doubleLE :: FixedPrim Double
-- | Encode a single native machine Int. The Ints is encoded
-- in host order, host endian form, for the machine you are on. On a 64
-- bit machine the Int is an 8 byte value, on a 32 bit machine, 4
-- bytes. Values encoded this way are not portable to different endian or
-- integer sized machines, without conversion.
intHost :: FixedPrim Int
-- | Encoding Int16s in native host order and host endianness.
int16Host :: FixedPrim Int16
-- | Encoding Int32s in native host order and host endianness.
int32Host :: FixedPrim Int32
-- | Encoding Int64s in native host order and host endianness.
int64Host :: FixedPrim Int64
-- | Encode a single native machine Word. The Words is
-- encoded in host order, host endian form, for the machine you are on.
-- On a 64 bit machine the Word is an 8 byte value, on a 32 bit
-- machine, 4 bytes. Values encoded this way are not portable to
-- different endian or word sized machines, without conversion.
wordHost :: FixedPrim Word
-- | Encoding Word16s in native host order and host endianness.
word16Host :: FixedPrim Word16
-- | Encoding Word32s in native host order and host endianness.
word32Host :: FixedPrim Word32
-- | Encoding Word64s in native host order and host endianness.
word64Host :: FixedPrim Word64
-- | Encode a Float in native host order and host endianness. Values
-- written this way are not portable to different endian machines,
-- without conversion.
floatHost :: FixedPrim Float
-- | Encode a Double in native host order and host endianness.
doubleHost :: FixedPrim Double
-- | Encode the least 7-bits of a Char using the ASCII encoding.
char7 :: FixedPrim Char
-- | Decimal encoding of an Int8.
int8Dec :: BoundedPrim Int8
-- | Decimal encoding of an Int16.
int16Dec :: BoundedPrim Int16
-- | Decimal encoding of an Int32.
int32Dec :: BoundedPrim Int32
-- | Decimal encoding of an Int64.
int64Dec :: BoundedPrim Int64
-- | Decimal encoding of an Int.
intDec :: BoundedPrim Int
-- | Decimal encoding of a Word8.
word8Dec :: BoundedPrim Word8
-- | Decimal encoding of a Word16.
word16Dec :: BoundedPrim Word16
-- | Decimal encoding of a Word32.
word32Dec :: BoundedPrim Word32
-- | Decimal encoding of a Word64.
word64Dec :: BoundedPrim Word64
-- | Decimal encoding of a Word.
wordDec :: BoundedPrim Word
-- | Hexadecimal encoding of a Word8.
word8Hex :: BoundedPrim Word8
-- | Hexadecimal encoding of a Word16.
word16Hex :: BoundedPrim Word16
-- | Hexadecimal encoding of a Word32.
word32Hex :: BoundedPrim Word32
-- | Hexadecimal encoding of a Word64.
word64Hex :: BoundedPrim Word64
-- | Hexadecimal encoding of a Word.
wordHex :: BoundedPrim Word
-- | Encode a Int8 using 2 nibbles (hexadecimal digits).
int8HexFixed :: FixedPrim Int8
-- | Encode a Int16 using 4 nibbles.
int16HexFixed :: FixedPrim Int16
-- | Encode a Int32 using 8 nibbles.
int32HexFixed :: FixedPrim Int32
-- | Encode a Int64 using 16 nibbles.
int64HexFixed :: FixedPrim Int64
-- | Encode a Word8 using 2 nibbles (hexadecimal digits).
word8HexFixed :: FixedPrim Word8
-- | Encode a Word16 using 4 nibbles.
word16HexFixed :: FixedPrim Word16
-- | Encode a Word32 using 8 nibbles.
word32HexFixed :: FixedPrim Word32
-- | Encode a Word64 using 16 nibbles.
word64HexFixed :: FixedPrim Word64
-- | Encode an IEEE Float using 8 nibbles.
floatHexFixed :: FixedPrim Float
-- | Encode an IEEE Double using 16 nibbles.
doubleHexFixed :: FixedPrim Double
-- | Char8 encode a Char.
char8 :: FixedPrim Char
-- | UTF-8 encode a Char.
charUtf8 :: BoundedPrim Char
-- | A null-terminated ASCII encoded CString. Null characters are
-- not representable.
cstring :: Addr# -> Builder
-- | A null-terminated UTF-8 encoded CString. Null characters can be
-- encoded as 0xc0 0x80.
cstringUtf8 :: Addr# -> Builder
-- | Floating point formatting for Bytestring.Builder
--
-- This module primarily exposes floatDec and doubleDec
-- which do the equivalent of converting through string7 .
-- show.
--
-- It also exposes formatFloat and formatDouble with a
-- similar API as formatRealFloat.
--
-- NB: The float-to-string conversions exposed by this module match
-- show's output (specifically with respect to default rounding
-- and length). In particular, there are boundary cases where the closest
-- and 'shortest' string representations are not used. Mentions of
-- 'shortest' in the docs below are with this caveat.
--
-- For example, for fidelity, we match show on the output below.
--
--
-- >>> show (1.0e23 :: Float)
-- "1.0e23"
--
-- >>> show (1.0e23 :: Double)
-- "9.999999999999999e22"
--
-- >>> floatDec 1.0e23
-- "1.0e23"
--
-- >>> doubleDec 1.0e23
-- "9.999999999999999e22"
--
--
-- Simplifying, we can build a shorter, lossless representation by just
-- using "1.0e23" since the floating point values that are 1 ULP
-- away are
--
--
-- >>> showHex (castDoubleToWord64 1.0e23) []
-- "44b52d02c7e14af6"
--
-- >>> castWord64ToDouble 0x44b52d02c7e14af5
-- 9.999999999999997e22
--
-- >>> castWord64ToDouble 0x44b52d02c7e14af6
-- 9.999999999999999e22
--
-- >>> castWord64ToDouble 0x44b52d02c7e14af7
-- 1.0000000000000001e23
--
--
-- In particular, we could use the exact boundary if it is the shortest
-- representation and the original floating number is even. To experiment
-- with the shorter rounding, refer to acceptBounds. This will
-- give us
--
--
-- >>> floatDec 1.0e23
-- "1.0e23"
--
-- >>> doubleDec 1.0e23
-- "1.0e23"
--
--
-- For more details, please refer to the Ryu paper.
module Data.ByteString.Builder.RealFloat
-- | Returns a rendered Float. Matches show in displaying in
-- standard or scientific notation
--
--
-- floatDec = formatFloat generic
--
floatDec :: Float -> Builder
-- | Returns a rendered Double. Matches show in displaying in
-- standard or scientific notation
--
--
-- doubleDec = formatDouble generic
--
doubleDec :: Double -> Builder
-- | Returns a rendered Float. Returns the 'shortest' representation in
-- scientific notation and takes an optional precision argument in
-- standard notation. Also see floatDec.
--
-- With standard notation, the precision argument is used to truncate (or
-- extend with 0s) the 'shortest' rendered Float. The 'default precision'
-- does no such modifications and will return as many decimal places as
-- the representation demands.
--
-- e.g
--
--
-- >>> formatFloat (standard 1) 1.2345e-2
-- "0.0"
--
-- >>> formatFloat (standard 10) 1.2345e-2
-- "0.0123450000"
--
-- >>> formatFloat standardDefaultPrecision 1.2345e-2
-- "0.01234"
--
-- >>> formatFloat scientific 12.345
-- "1.2345e1"
--
-- >>> formatFloat generic 12.345
-- "12.345"
--
formatFloat :: FloatFormat -> Float -> Builder
-- | Returns a rendered Double. Returns the 'shortest' representation in
-- scientific notation and takes an optional precision argument in
-- standard notation. Also see doubleDec.
--
-- With standard notation, the precision argument is used to truncate (or
-- extend with 0s) the 'shortest' rendered Float. The 'default precision'
-- does no such modifications and will return as many decimal places as
-- the representation demands.
--
-- e.g
--
--
-- >>> formatDouble (standard 1) 1.2345e-2
-- "0.0"
--
-- >>> formatDouble (standard 10) 1.2345e-2
-- "0.0123450000"
--
-- >>> formatDouble standardDefaultPrecision 1.2345e-2
-- "0.01234"
--
-- >>> formatDouble scientific 12.345
-- "1.2345e1"
--
-- >>> formatDouble generic 12.345
-- "12.345"
--
formatDouble :: FloatFormat -> Double -> Builder
-- | Format type for use with formatFloat and formatDouble.
data FloatFormat
-- | Standard notation with n decimal places
standard :: Int -> FloatFormat
-- | Standard notation with the 'default precision' (decimal places
-- matching show)
standardDefaultPrecision :: FloatFormat
-- | Scientific notation with 'default precision' (decimal places matching
-- show)
scientific :: FloatFormat
-- | Standard or scientific notation depending on the exponent. Matches
-- show
generic :: FloatFormat
instance GHC.Internal.Show.Show Data.ByteString.Builder.RealFloat.FormatMode
-- | Extra functions for creating and executing Builders. They are
-- intended for application-specific fine-tuning the performance of
-- Builders.
module Data.ByteString.Builder.Extra
-- | Heavy inlining. Execute a Builder with custom execution
-- parameters.
--
-- This function is inlined despite its heavy code-size to allow fusing
-- with the allocation strategy. For example, the default Builder
-- execution function toLazyByteString is defined as follows.
--
--
-- {-# NOINLINE toLazyByteString #-}
-- toLazyByteString =
-- toLazyByteStringWith (safeStrategy smallChunkSize defaultChunkSize) L.Empty
--
--
-- where L.Empty is the zero-length LazyByteString.
--
-- In most cases, the parameters used by toLazyByteString give
-- good performance. A sub-performing case of toLazyByteString is
-- executing short (<128 bytes) Builders. In this case, the
-- allocation overhead for the first 4kb buffer and the trimming cost
-- dominate the cost of executing the Builder. You can avoid this
-- problem using
--
--
-- toLazyByteStringWith (safeStrategy 128 smallChunkSize) L.Empty
--
--
-- This reduces the allocation and trimming overhead, as all generated
-- LazyByteStrings fit into the first buffer and there is no
-- trimming required, if more than 64 bytes and less than 128 bytes are
-- written.
toLazyByteStringWith :: AllocationStrategy -> LazyByteString -> Builder -> LazyByteString
-- | A buffer allocation strategy for executing Builders.
data AllocationStrategy
-- | Use this strategy for generating LazyByteStrings whose chunks
-- are likely to survive one garbage collection. This strategy trims
-- buffers that are filled less than half in order to avoid spilling too
-- much memory.
safeStrategy :: Int -> Int -> AllocationStrategy
-- | Use this strategy for generating LazyByteStrings whose chunks
-- are discarded right after they are generated. For example, if you just
-- generate them to write them to a network socket.
untrimmedStrategy :: Int -> Int -> AllocationStrategy
-- | The recommended chunk size. Currently set to 4k, less the memory
-- management overhead
smallChunkSize :: Int
-- | The chunk size used for I/O. Currently set to 32k, less the memory
-- management overhead
defaultChunkSize :: Int
-- | Construct a Builder that copies the StrictByteString.
--
-- Use this function to create Builders from smallish (<=
-- 4kb) StrictByteStrings or if you need to guarantee that
-- the StrictByteString is not shared with the chunks generated by
-- the Builder.
byteStringCopy :: StrictByteString -> Builder
-- | Construct a Builder that always inserts the
-- StrictByteString directly as a chunk.
--
-- This implies flushing the output buffer, even if it contains just a
-- single byte. You should therefore use byteStringInsert only for
-- large (> 8kb) StrictByteStrings. Otherwise, the
-- generated chunks are too fragmented to be processed efficiently
-- afterwards.
byteStringInsert :: StrictByteString -> Builder
-- | Construct a Builder that copies the StrictByteStrings,
-- if it is smaller than the treshold, and inserts it directly otherwise.
--
-- For example, byteStringThreshold 1024 copies
-- StrictByteStrings whose size is less or equal to 1kb, and
-- inserts them directly otherwise. This implies that the average
-- chunk-size of the generated LazyByteString may be as low as 513
-- bytes, as there could always be just a single byte between the
-- directly inserted 1025 byte, StrictByteStrings.
byteStringThreshold :: Int -> StrictByteString -> Builder
-- | Construct a Builder that copies the LazyByteString.
lazyByteStringCopy :: LazyByteString -> Builder
-- | Construct a Builder that inserts all chunks of the
-- LazyByteString directly.
lazyByteStringInsert :: LazyByteString -> Builder
-- | Construct a Builder that uses the thresholding strategy of
-- byteStringThreshold for each chunk of the
-- LazyByteString.
lazyByteStringThreshold :: Int -> LazyByteString -> Builder
-- | Flush the current buffer. This introduces a chunk boundary.
flush :: Builder
-- | A BufferWriter represents the result of running a
-- Builder. It unfolds as a sequence of chunks of data. These
-- chunks come in two forms:
--
--
-- - an IO action for writing the Builder's data into a user-supplied
-- memory buffer.
-- - a pre-existing chunks of data represented by a
-- StrictByteString
--
--
-- While this is rather low level, it provides you with full flexibility
-- in how the data is written out.
--
-- The BufferWriter itself is an IO action: you supply it with a
-- buffer (as a pointer and length) and it will write data into the
-- buffer. It returns a number indicating how many bytes were actually
-- written (which can be 0). It also returns a Next which
-- describes what comes next.
type BufferWriter = Ptr Word8 -> Int -> IO (Int, Next)
-- | After running a BufferWriter action there are three
-- possibilities for what comes next:
data Next
-- | This means we're all done. All the builder data has now been written.
Done :: Next
-- | This indicates that there may be more data to write. It gives you the
-- next BufferWriter action. You should call that action with an
-- appropriate buffer. The int indicates the minimum buffer size
-- required by the next BufferWriter action. That is, if you call
-- the next action you must supply it with a buffer length of at
-- least this size.
More :: !Int -> BufferWriter -> Next
-- | In addition to the data that has just been written into your buffer by
-- the BufferWriter action, it gives you a pre-existing chunk of
-- data as a StrictByteString. It also gives you the following
-- BufferWriter action. It is safe to run this following action
-- using a buffer with as much free space as was left by the previous run
-- action.
Chunk :: !StrictByteString -> BufferWriter -> Next
-- | Turn a Builder into its initial BufferWriter action.
runBuilder :: Builder -> BufferWriter
-- | Encode a single native machine Int. The Int is encoded
-- in host order, host endian form, for the machine you're on. On a 64
-- bit machine the Int is an 8 byte value, on a 32 bit machine, 4
-- bytes. Values encoded this way are not portable to different endian or
-- int sized machines, without conversion.
intHost :: Int -> Builder
-- | Encode a Int16 in native host order and host endianness.
int16Host :: Int16 -> Builder
-- | Encode a Int32 in native host order and host endianness.
int32Host :: Int32 -> Builder
-- | Encode a Int64 in native host order and host endianness.
int64Host :: Int64 -> Builder
-- | Encode a single native machine Word. The Word is encoded
-- in host order, host endian form, for the machine you're on. On a 64
-- bit machine the Word is an 8 byte value, on a 32 bit machine, 4
-- bytes. Values encoded this way are not portable to different endian or
-- word sized machines, without conversion.
wordHost :: Word -> Builder
-- | Encode a Word16 in native host order and host endianness.
word16Host :: Word16 -> Builder
-- | Encode a Word32 in native host order and host endianness.
word32Host :: Word32 -> Builder
-- | Encode a Word64 in native host order and host endianness.
word64Host :: Word64 -> Builder
-- | Encode a Float in native host order. Values encoded this way
-- are not portable to different endian machines, without conversion.
floatHost :: Float -> Builder
-- | Encode a Double in native host order.
doubleHost :: Double -> Builder
-- | Builders are used to efficiently construct sequences of bytes
-- from smaller parts. Typically, such a construction is part of the
-- implementation of an encoding, i.e., a function for converting
-- Haskell values to sequences of bytes. Examples of encodings are the
-- generation of the sequence of bytes representing a HTML document to be
-- sent in a HTTP response by a web application or the serialization of a
-- Haskell value using a fixed binary format.
--
-- For an efficient implementation of an encoding, it is important
-- that (a) little time is spent on converting the Haskell values to the
-- resulting sequence of bytes and (b) that the representation of
-- the resulting sequence is such that it can be consumed efficiently.
-- Builders support (a) by providing an O(1) concatentation
-- operation and efficient implementations of basic encodings for
-- Chars, Ints, and other standard Haskell values. They
-- support (b) by providing their result as a LazyByteString,
-- which is internally just a linked list of pointers to chunks of
-- consecutive raw memory. LazyByteStrings can be efficiently
-- consumed by functions that write them to a file or send them over a
-- network socket. Note that each chunk boundary incurs expensive extra
-- work (e.g., a system call) that must be amortized over the work spent
-- on consuming the chunk body. Builders therefore take special
-- care to ensure that the average chunk size is large enough. The
-- precise meaning of large enough is application dependent. The current
-- implementation is tuned for an average chunk size between 4kb and
-- 32kb, which should suit most applications.
--
-- As a simple example of an encoding implementation, we show how to
-- efficiently convert the following representation of mixed-data tables
-- to an UTF-8 encoded Comma-Separated-Values (CSV) table.
--
--
-- data Cell = StringC String
-- | IntC Int
-- deriving( Eq, Ord, Show )
--
-- type Row = [Cell]
-- type Table = [Row]
--
--
-- We use the following imports.
--
--
-- import qualified Data.ByteString.Lazy as L
-- import Data.ByteString.Builder
-- import Data.List (intersperse)
--
--
-- CSV is a character-based representation of tables. For maximal
-- modularity, we could first render Tables as Strings
-- and then encode this String using some Unicode character
-- encoding. However, this sacrifices performance due to the intermediate
-- String representation being built and thrown away right
-- afterwards. We get rid of this intermediate String
-- representation by fixing the character encoding to UTF-8 and using
-- Builders to convert Tables directly to UTF-8 encoded
-- CSV tables represented as LazyByteStrings.
--
--
-- encodeUtf8CSV :: Table -> L.LazyByteString
-- encodeUtf8CSV = toLazyByteString . renderTable
--
-- renderTable :: Table -> Builder
-- renderTable rs = mconcat [renderRow r <> charUtf8 '\n' | r <- rs]
--
-- renderRow :: Row -> Builder
-- renderRow [] = mempty
-- renderRow (c:cs) =
-- renderCell c <> mconcat [ charUtf8 ',' <> renderCell c' | c' <- cs ]
--
-- renderCell :: Cell -> Builder
-- renderCell (StringC cs) = renderString cs
-- renderCell (IntC i) = intDec i
--
-- renderString :: String -> Builder
-- renderString cs = charUtf8 '"' <> foldMap escape cs <> charUtf8 '"'
-- where
-- escape '\\' = charUtf8 '\\' <> charUtf8 '\\'
-- escape '\"' = charUtf8 '\\' <> charUtf8 '\"'
-- escape c = charUtf8 c
--
--
-- Note that the ASCII encoding is a subset of the UTF-8 encoding, which
-- is why we can use the optimized function intDec to encode an
-- Int as a decimal number with UTF-8 encoded digits. Using
-- intDec is more efficient than stringUtf8 .
-- show, as it avoids constructing an intermediate
-- String. Avoiding this intermediate data structure significantly
-- improves performance because encoding Cells is the core
-- operation for rendering CSV-tables. See
-- Data.ByteString.Builder.Prim for further information on how to
-- improve the performance of renderString.
--
-- We demonstrate our UTF-8 CSV encoding function on the following table.
--
--
-- strings :: [String]
-- strings = ["hello", "\"1\"", "λ-wörld"]
--
-- table :: Table
-- table = [map StringC strings, map IntC [-3..3]]
--
--
-- The expression encodeUtf8CSV table results in the following
-- lazy LazyByteString.
--
--
-- Chunk "\"hello\",\"\\\"1\\\"\",\"\206\187-w\195\182rld\"\n-3,-2,-1,0,1,2,3\n" Empty
--
--
-- We can clearly see that we are converting to a binary format.
-- The 'λ' and 'ö' characters, which have a Unicode codepoint above 127,
-- are expanded to their corresponding UTF-8 multi-byte representation.
--
-- We use the criterion library
-- (http://hackage.haskell.org/package/criterion) to benchmark the
-- efficiency of our encoding function on the following table.
--
--
-- import Criterion.Main -- add this import to the ones above
--
-- maxiTable :: Table
-- maxiTable = take 1000 $ cycle table
--
-- main :: IO ()
-- main = defaultMain
-- [ bench "encodeUtf8CSV maxiTable (original)" $
-- whnf (L.length . encodeUtf8CSV) maxiTable
-- ]
--
--
-- On a Core2 Duo 2.20GHz on a 32-bit Linux, the above code takes 1ms to
-- generate the 22'500 bytes long LazyByteString. Looking again at
-- the definitions above, we see that we took care to avoid intermediate
-- data structures, as otherwise we would sacrifice performance. For
-- example, the following (arguably simpler) definition of
-- renderRow is about 20% slower.
--
--
-- renderRow :: Row -> Builder
-- renderRow = mconcat . intersperse (charUtf8 ',') . map renderCell
--
--
-- Similarly, using O(n) concatentations like ++ or the
-- equivalent concat operations on strict and
-- LazyByteStrings should be avoided. The following definition of
-- renderString is also about 20% slower.
--
--
-- renderString :: String -> Builder
-- renderString cs = charUtf8 $ "\"" ++ concatMap escape cs ++ "\""
-- where
-- escape '\\' = "\\"
-- escape '\"' = "\\\""
-- escape c = return c
--
--
-- Apart from removing intermediate data-structures, encodings can be
-- optimized further by fine-tuning their execution parameters using the
-- functions in Data.ByteString.Builder.Extra and their "inner
-- loops" using the functions in Data.ByteString.Builder.Prim.
module Data.ByteString.Builder
-- | Builders denote sequences of bytes. They are Monoids
-- where mempty is the zero-length sequence and mappend is
-- concatenation, which runs in O(1).
data Builder
-- | Execute a Builder and return the generated chunks as a
-- LazyByteString. The work is performed lazy, i.e., only when a
-- chunk of the LazyByteString is forced.
toLazyByteString :: Builder -> LazyByteString
-- | Output a Builder to a Handle. The Builder is
-- executed directly on the buffer of the Handle. If the buffer is
-- too small (or not present), then it is replaced with a large enough
-- buffer.
--
-- It is recommended that the Handle is set to binary and
-- BlockBuffering mode. See hSetBinaryMode and
-- hSetBuffering.
--
-- This function is more efficient than hPut .
-- toLazyByteString because in many cases no buffer
-- allocation has to be done. Moreover, the results of several executions
-- of short Builders are concatenated in the Handles
-- buffer, therefore avoiding unnecessary buffer flushes.
hPutBuilder :: Handle -> Builder -> IO ()
-- | Write a Builder to a file.
--
-- Similarly to hPutBuilder, this function is more efficient than
-- using hPut . toLazyByteString with a file handle.
writeFile :: FilePath -> Builder -> IO ()
-- | Create a Builder denoting the same sequence of bytes as a
-- StrictByteString. The Builder inserts large
-- StrictByteStrings directly, but copies small ones to ensure
-- that the generated chunks are large on average.
byteString :: StrictByteString -> Builder
-- | Create a Builder denoting the same sequence of bytes as a lazy
-- LazyByteString. The Builder inserts large chunks of the
-- LazyByteString directly, but copies small ones to ensure that
-- the generated chunks are large on average.
lazyByteString :: LazyByteString -> Builder
-- | Construct a Builder that copies the ShortByteString.
shortByteString :: ShortByteString -> Builder
-- | Encode a single signed byte as-is.
int8 :: Int8 -> Builder
-- | Encode a single unsigned byte as-is.
word8 :: Word8 -> Builder
-- | Encode an Int16 in big endian format.
int16BE :: Int16 -> Builder
-- | Encode an Int32 in big endian format.
int32BE :: Int32 -> Builder
-- | Encode an Int64 in big endian format.
int64BE :: Int64 -> Builder
-- | Encode a Word16 in big endian format.
word16BE :: Word16 -> Builder
-- | Encode a Word32 in big endian format.
word32BE :: Word32 -> Builder
-- | Encode a Word64 in big endian format.
word64BE :: Word64 -> Builder
-- | Encode a Float in big endian format.
floatBE :: Float -> Builder
-- | Encode a Double in big endian format.
doubleBE :: Double -> Builder
-- | Encode an Int16 in little endian format.
int16LE :: Int16 -> Builder
-- | Encode an Int32 in little endian format.
int32LE :: Int32 -> Builder
-- | Encode an Int64 in little endian format.
int64LE :: Int64 -> Builder
-- | Encode a Word16 in little endian format.
word16LE :: Word16 -> Builder
-- | Encode a Word32 in little endian format.
word32LE :: Word32 -> Builder
-- | Encode a Word64 in little endian format.
word64LE :: Word64 -> Builder
-- | Encode a Float in little endian format.
floatLE :: Float -> Builder
-- | Encode a Double in little endian format.
doubleLE :: Double -> Builder
-- | Char7 encode a Char.
char7 :: Char -> Builder
-- | Char7 encode a String.
string7 :: String -> Builder
-- | Char8 encode a Char.
char8 :: Char -> Builder
-- | Char8 encode a String.
string8 :: String -> Builder
-- | UTF-8 encode a Char.
charUtf8 :: Char -> Builder
-- | UTF-8 encode a String.
--
-- Note that stringUtf8 performs no codepoint validation and
-- consequently may emit invalid UTF-8 if asked (e.g. single surrogates).
stringUtf8 :: String -> Builder
-- | Decimal encoding of an Int8 using the ASCII digits.
--
-- e.g.
--
--
-- toLazyByteString (int8Dec 42) = "42"
-- toLazyByteString (int8Dec (-1)) = "-1"
--
int8Dec :: Int8 -> Builder
-- | Decimal encoding of an Int16 using the ASCII digits.
int16Dec :: Int16 -> Builder
-- | Decimal encoding of an Int32 using the ASCII digits.
int32Dec :: Int32 -> Builder
-- | Decimal encoding of an Int64 using the ASCII digits.
int64Dec :: Int64 -> Builder
-- | Decimal encoding of an Int using the ASCII digits.
intDec :: Int -> Builder
-- | Decimal encoding of an Integer using the ASCII digits.
integerDec :: Integer -> Builder
-- | Decimal encoding of a Word8 using the ASCII digits.
word8Dec :: Word8 -> Builder
-- | Decimal encoding of a Word16 using the ASCII digits.
word16Dec :: Word16 -> Builder
-- | Decimal encoding of a Word32 using the ASCII digits.
word32Dec :: Word32 -> Builder
-- | Decimal encoding of a Word64 using the ASCII digits.
word64Dec :: Word64 -> Builder
-- | Decimal encoding of a Word using the ASCII digits.
wordDec :: Word -> Builder
-- | Returns a rendered Float. Matches show in displaying in
-- standard or scientific notation
--
--
-- floatDec = formatFloat generic
--
floatDec :: Float -> Builder
-- | Returns a rendered Double. Matches show in displaying in
-- standard or scientific notation
--
--
-- doubleDec = formatDouble generic
--
doubleDec :: Double -> Builder
-- | Shortest hexadecimal encoding of a Word8 using lower-case
-- characters.
word8Hex :: Word8 -> Builder
-- | Shortest hexadecimal encoding of a Word16 using lower-case
-- characters.
word16Hex :: Word16 -> Builder
-- | Shortest hexadecimal encoding of a Word32 using lower-case
-- characters.
word32Hex :: Word32 -> Builder
-- | Shortest hexadecimal encoding of a Word64 using lower-case
-- characters.
word64Hex :: Word64 -> Builder
-- | Shortest hexadecimal encoding of a Word using lower-case
-- characters.
wordHex :: Word -> Builder
-- | Encode a Int8 using 2 nibbles (hexadecimal digits).
int8HexFixed :: Int8 -> Builder
-- | Encode a Int16 using 4 nibbles.
int16HexFixed :: Int16 -> Builder
-- | Encode a Int32 using 8 nibbles.
int32HexFixed :: Int32 -> Builder
-- | Encode a Int64 using 16 nibbles.
int64HexFixed :: Int64 -> Builder
-- | Encode a Word8 using 2 nibbles (hexadecimal digits).
word8HexFixed :: Word8 -> Builder
-- | Encode a Word16 using 4 nibbles.
word16HexFixed :: Word16 -> Builder
-- | Encode a Word32 using 8 nibbles.
word32HexFixed :: Word32 -> Builder
-- | Encode a Word64 using 16 nibbles.
word64HexFixed :: Word64 -> Builder
-- | Encode an IEEE Float using 8 nibbles.
floatHexFixed :: Float -> Builder
-- | Encode an IEEE Double using 16 nibbles.
doubleHexFixed :: Double -> Builder
-- | Encode each byte of a StrictByteString using its fixed-width
-- hex encoding.
byteStringHex :: StrictByteString -> Builder
-- | Encode each byte of a LazyByteString using its fixed-width hex
-- encoding.
lazyByteStringHex :: LazyByteString -> Builder
instance GHC.Internal.Data.String.IsString Data.ByteString.Builder.Internal.Builder
instance GHC.Internal.Show.Show Data.ByteString.Builder.Internal.Builder