Data.ByteString.Internal



Copyright
(c) Don Stewart 2006-2008(c) Duncan Coutts 2006-2012


License
BSD-style


Maintainer
hallkimberly@example.net, hallkimberly@example.net


Stability
unstable


Portability
non-portable


Safe Haskell
Unsafe


Language
Haskell98



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.

The ByteString type and representationdata 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
Instances details


Eq ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
(==) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> Bool Source 
(/=) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> Bool Source 



Data ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
gfoldl 8b7c:f320:99b9:690f:4595:cd17:293a:c069 (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ByteString -> c ByteString Source 
gunfold 8b7c:f320:99b9:690f:4595:cd17:293a:c069 (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ByteString Source 
toConstr 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> Constr Source 
dataTypeOf 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> DataType Source 
dataCast1 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ByteString) Source 
dataCast2 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ByteString) Source 
gmapT 8b7c:f320:99b9:690f:4595:cd17:293a:c069 (forall b. Data b => b -> b) -> ByteString -> ByteString Source 
gmapQl 8b7c:f320:99b9:690f:4595:cd17:293a:c069 (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ByteString -> r Source 
gmapQr 8b7c:f320:99b9:690f:4595:cd17:293a:c069 forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ByteString -> r Source 
gmapQ 8b7c:f320:99b9:690f:4595:cd17:293a:c069 (forall d. Data d => d -> u) -> ByteString -> [u] Source 
gmapQi 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> (forall d. Data d => d -> u) -> ByteString -> u Source 
gmapM 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Monad m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString Source 
gmapMp 8b7c:f320:99b9:690f:4595:cd17:293a:c069 MonadPlus m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString Source 
gmapMo 8b7c:f320:99b9:690f:4595:cd17:293a:c069 MonadPlus m => (forall d. Data d => d -> m d) -> ByteString -> m ByteString Source 



Ord ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
compare 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> Ordering Source 
(<) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> Bool Source 
(<=) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> Bool Source 
(>) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> Bool Source 
(>=) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> Bool Source 
max 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> ByteString Source 
min 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> ByteString Source 



Read ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
readsPrec 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> ReadS ByteString Source 
readList 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ReadS [ByteString] Source 
readPrec 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ReadPrec ByteString Source 
readListPrec 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ReadPrec [ByteString] Source 



Show ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
showsPrec 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> ByteString -> ShowS Source 
show 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> String Source 
showList 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [ByteString] -> ShowS Source 



IsString ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
fromString 8b7c:f320:99b9:690f:4595:cd17:293a:c069 String -> ByteString Source 



Semigroup ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
(<>) 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> ByteString Source 
sconcat 8b7c:f320:99b9:690f:4595:cd17:293a:c069 NonEmpty ByteString -> ByteString Source 
stimes 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Integral b => b -> ByteString -> ByteString Source 



Monoid ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
mempty 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString Source 
mappend 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> ByteString -> ByteString Source 
mconcat 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [ByteString] -> ByteString Source 



NFData ByteString 
 

Instance detailsDefined in Data.ByteString.Internal 
Methods
rnf 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> () Source 



Conversion with lists: packing and unpackingpackBytes 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [Word8] -> ByteString Source 
packUptoLenBytes 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> [Word8] -> (ByteString, [Word8]) Source 
unsafePackLenBytes 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> [Word8] -> ByteString Source 
packChars 8b7c:f320:99b9:690f:4595:cd17:293a:c069 [Char] -> ByteString Source 
packUptoLenChars 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> [Char] -> (ByteString, [Char]) Source 
unsafePackLenChars 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> [Char] -> ByteString Source 
unpackBytes 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> [Word8] Source 
unpackAppendBytesLazy 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> [Word8] -> [Word8] Source 
unpackAppendBytesStrict 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> [Word8] -> [Word8] Source 
unpackChars 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> [Char] Source 
unpackAppendCharsLazy 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> [Char] -> [Char] Source 
unpackAppendCharsStrict 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString -> [Char] -> [Char] Source 
unsafePackAddress 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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 constructioncreate 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> (Ptr Word8 -> IO ()) -> IO ByteString Source 
Create ByteString of size l and use action f to fill it's contents.
createUptoN 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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' 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> (Ptr Word8 -> IO (Int, Int, a)) -> IO (ByteString, a) Source 
unsafeCreate 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Int -> IO (ForeignPtr a) Source 
Wrapper of mallocForeignPtrBytes with faster implementation for GHC
Conversion to and from ForeignPtrsfromForeignPtr Source 

Arguments


8b7c:f320:99b9:690f:4595:cd17:293a:c069 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


8b7c:f320:99b9:690f:4595:cd17:293a:c069 ByteString

 


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



O(1) Deconstruct a ForeignPtr from a ByteString
UtilitiesnullForeignPtr 8b7c:f320:99b9:690f:4595:cd17:293a:c069 ForeignPtr Word8 Source 
The 0 pointer. Used to indicate the empty Bytestring.
checkedAdd 8b7c:f320:99b9:690f:4595:cd17:293a:c069 String -> Int -> Int -> Int Source 
Add two non-negative numbers. Errors out on overflow.
Standard C Functionsc_strlen 8b7c:f320:99b9:690f:4595:cd17:293a:c069 CString -> IO CSize Source 
c_free_finalizer 8b7c:f320:99b9:690f:4595:cd17:293a:c069 FunPtr (Ptr Word8 -> IO ()) Source 
memchr 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8) Source 
memcmp 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> Ptr Word8 -> Int -> IO CInt Source 
memcpy 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> Ptr Word8 -> Int -> IO () Source 
memset 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8) Source 
cbits functionsc_reverse 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> Ptr Word8 -> CULong -> IO () Source 
c_intersperse 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> Ptr Word8 -> CULong -> Word8 -> IO () Source 
c_maximum 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> CULong -> IO Word8 Source 
c_minimum 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> CULong -> IO Word8 Source 
c_count 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Ptr Word8 -> CULong -> Word8 -> IO CULong Source 
Charsw2c 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Word8 -> Char Source 
Conversion between Word8 and Char. Should compile to a no-op.
c2w 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Word8 -> Bool Source 
Selects words corresponding to white-space characters in the Latin-1 range ordered by frequency.
isSpaceChar8 8b7c:f320:99b9:690f:4595:cd17:293a:c069 Char -> Bool Source 
Selects white-space characters in the Latin-1 range
Deprecated and unmentionableaccursedUnutterablePerformIO 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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:

https://github.com/haskell/bytestring/commit/71c4b438c675aa360c79d79acc9a491e7bbc26e7
https://github.com/haskell/bytestring/commit/210c656390ae617d9ee3b8bcff5c88dd17cef8da
https://ghc.haskell.org/trac/ghc/ticket/3486
https://ghc.haskell.org/trac/ghc/ticket/3487
https://ghc.haskell.org/trac/ghc/ticket/7270

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 8b7c:f320:99b9:690f:4595:cd17:293a:c069 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.


    
{'path': 'public/docs/haskell~8/libraries/bytestring-0.10.10.0/data-bytestring-internal.html', 'source': 'DevDocs.IO'}