Copyright	(c) Don Stewart 2006-2008 (c) Duncan Coutts 2006-2012
License	BSD-style
Maintainer	dons00@gmail.com, duncan@community.haskell.org
Stability	unstable
Portability	non-portable
Safe Haskell	Unsafe
Language	Haskell98

Data.ByteString.Internal

Contents

The ByteString type and representation
Conversion with lists: packing and unpacking
Low level imperative construction
Conversion to and from ForeignPtrs
Utilities
Standard C Functions
cbits functions
Chars
Deprecated and unmentionable

Description

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.

Synopsis

data ByteString = PS !(ForeignPtr Word8) !Int !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]
unsafePackAddress :: Addr# -> IO ByteString
create :: Int -> (Ptr Word8 -> IO ()) -> IO ByteString
createUptoN :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString
createAndTrim :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString
createAndTrim' :: Int -> (Ptr Word8 -> IO (Int, Int, a)) -> IO (ByteString, a)
unsafeCreate :: Int -> (Ptr Word8 -> IO ()) -> ByteString
unsafeCreateUptoN :: Int -> (Ptr Word8 -> IO Int) -> ByteString
mallocByteString :: Int -> IO (ForeignPtr a)
fromForeignPtr :: ForeignPtr Word8 -> Int -> Int -> ByteString
toForeignPtr :: ByteString -> (ForeignPtr Word8, Int, Int)
nullForeignPtr :: ForeignPtr Word8
checkedAdd :: 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
memcpy :: Ptr Word8 -> Ptr Word8 -> Int -> IO ()
memset :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
c_reverse :: Ptr Word8 -> Ptr Word8 -> CULong -> IO ()
c_intersperse :: Ptr Word8 -> Ptr Word8 -> CULong -> Word8 -> IO ()
c_maximum :: Ptr Word8 -> CULong -> IO Word8
c_minimum :: Ptr Word8 -> CULong -> IO Word8
c_count :: Ptr Word8 -> CULong -> Word8 -> IO CULong
w2c :: Word8 -> Char
c2w :: Char -> Word8
isSpaceWord8 :: Word8 -> Bool
isSpaceChar8 :: Char -> Bool
accursedUnutterablePerformIO :: IO a -> a
inlinePerformIO :: IO a -> a

The `ByteString` type and representation

data ByteString Source #

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

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

Constructors

PS !(ForeignPtr Word8) !Int !Int

Instances

Eq ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods (==) :: ByteString -> ByteString -> Bool # (/=) :: ByteString -> ByteString -> Bool #
Data ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ByteString -> c ByteString # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ByteString # toConstr :: ByteString -> Constr # dataTypeOf :: ByteString -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ByteString) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ByteString) # gmapT :: (forall b. Data b => b -> b) -> ByteString -> ByteString # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ByteString -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ByteString -> r # gmapQ :: (forall d. Data d => d -> u) -> ByteString -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> ByteString -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString #
Ord ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods compare :: ByteString -> ByteString -> Ordering # (<) :: ByteString -> ByteString -> Bool # (<=) :: ByteString -> ByteString -> Bool # (>) :: ByteString -> ByteString -> Bool # (>=) :: ByteString -> ByteString -> Bool # max :: ByteString -> ByteString -> ByteString # min :: ByteString -> ByteString -> ByteString #
Read ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods readsPrec :: Int -> ReadS ByteString # readList :: ReadS [ByteString] # readPrec :: ReadPrec ByteString # readListPrec :: ReadPrec [ByteString] #
Show ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods showsPrec :: Int -> ByteString -> ShowS # show :: ByteString -> String # showList :: [ByteString] -> ShowS #
IsString ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods fromString :: String -> ByteString #
Semigroup ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods (<>) :: ByteString -> ByteString -> ByteString # sconcat :: NonEmpty ByteString -> ByteString # stimes :: Integral b => b -> ByteString -> ByteString #
Monoid ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods mempty :: ByteString # mappend :: ByteString -> ByteString -> ByteString # mconcat :: [ByteString] -> ByteString #
NFData ByteString Source #
Instance details Defined in Data.ByteString.Internal Methods rnf :: ByteString -> () #

Conversion with lists: packing and unpacking

packBytes :: [Word8] -> ByteString Source #

packUptoLenBytes :: Int -> [Word8] -> (ByteString, [Word8]) Source #

unsafePackLenBytes :: Int -> [Word8] -> ByteString Source #

packChars :: [Char] -> ByteString Source #

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

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

unpackBytes :: ByteString -> [Word8] Source #

unpackAppendBytesLazy :: ByteString -> [Word8] -> [Word8] Source #

unpackAppendBytesStrict :: ByteString -> [Word8] -> [Word8] Source #

unpackChars :: ByteString -> [Char] Source #

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

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

unsafePackAddress :: Addr# -> IO ByteString Source #

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.

Low level imperative construction

create :: Int -> (Ptr Word8 -> IO ()) -> IO ByteString Source #

Create ByteString of size l and use action f to fill it's contents.

createUptoN :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString Source #

Create ByteString of up to size size l and use action f to fill it's contents which returns its true size.

createAndTrim :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString Source #

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 realloced 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, Int, a)) -> IO (ByteString, a) Source #

unsafeCreate :: Int -> (Ptr Word8 -> IO ()) -> ByteString Source #

A way of creating ByteStrings outside the IO monad. The Int argument gives the final size of the ByteString.

unsafeCreateUptoN :: Int -> (Ptr Word8 -> IO Int) -> ByteString Source #

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.

mallocByteString :: Int -> IO (ForeignPtr a) Source #

Wrapper of mallocForeignPtrBytes with faster implementation for GHC

Conversion to and from ForeignPtrs

fromForeignPtr Source #

Arguments

:: ForeignPtr Word8
-> Int	Offset
-> Int	Length
-> ByteString

O(1) Build a ByteString from a ForeignPtr.

If you do not need the offset parameter then you do should be using unsafePackCStringLen or unsafePackCStringFinalizer instead.

toForeignPtr Source #

Arguments

:: ByteString
-> (ForeignPtr Word8, Int, Int)	(ptr, offset, length)

O(1) Deconstruct a ForeignPtr from a ByteString

Utilities

nullForeignPtr :: ForeignPtr Word8 Source #

The 0 pointer. Used to indicate the empty Bytestring.

checkedAdd :: String -> Int -> Int -> Int Source #

Add two non-negative numbers. Errors out on overflow.

Standard C Functions

c_strlen :: CString -> IO CSize Source #

c_free_finalizer :: FunPtr (Ptr Word8 -> IO ()) Source #

memchr :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8) Source #

memcmp :: Ptr Word8 -> Ptr Word8 -> Int -> IO CInt Source #

memcpy :: Ptr Word8 -> Ptr Word8 -> Int -> IO () Source #

memset :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8) Source #

cbits functions

c_reverse :: Ptr Word8 -> Ptr Word8 -> CULong -> IO () Source #

c_intersperse :: Ptr Word8 -> Ptr Word8 -> CULong -> Word8 -> IO () Source #

c_maximum :: Ptr Word8 -> CULong -> IO Word8 Source #

c_minimum :: Ptr Word8 -> CULong -> IO Word8 Source #

c_count :: Ptr Word8 -> CULong -> Word8 -> IO CULong Source #

Chars

w2c :: Word8 -> Char Source #

Conversion between Word8 and Char. Should compile to a no-op.

c2w :: Char -> Word8 Source #

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.

isSpaceWord8 :: Word8 -> Bool Source #

Selects words corresponding to white-space characters in the Latin-1 range ordered by frequency.

isSpaceChar8 :: Char -> Bool Source #

Selects white-space characters in the Latin-1 range

Deprecated and unmentionable

accursedUnutterablePerformIO :: IO a -> a Source #

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!

inlinePerformIO :: IO a -> a Source #

Deprecated: If you think you know what you are doing, use unsafePerformIO. If you are sure you know what you are doing, use unsafeDupablePerformIO. If you enjoy sharing an address space with a malevolent agent of chaos, try accursedUnutterablePerformIO.

The ByteString type and representation