| Haskell Hierarchical Libraries (base package) | Source code | Contents | Index

Data.ByteString.Base

Contents

The `ByteString` type and representation
Unchecked access
Low level introduction and elimination
Utilities
Standard C Functions
cbits functions
Internal GHC magic
Chars

Description
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.
Synopsis

data ByteString = PS !(ForeignPtr Word8) !Int !Int
newtype LazyByteString = LPS [ByteString]
unsafeHead :: ByteString -> Word8
unsafeTail :: ByteString -> ByteString
unsafeIndex :: ByteString -> Int -> Word8
unsafeTake :: Int -> ByteString -> ByteString
unsafeDrop :: Int -> ByteString -> ByteString
empty :: ByteString
create :: Int -> (Ptr Word8 -> IO ()) -> IO ByteString
createAndTrim :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString
createAndTrim' :: Int -> (Ptr Word8 -> IO (Int, Int, a)) -> IO (ByteString, a)
mallocByteString :: Int -> IO (ForeignPtr a)
unsafeCreate :: Int -> (Ptr Word8 -> IO ()) -> ByteString
unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a
unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
fromForeignPtr :: ForeignPtr Word8 -> Int -> ByteString
toForeignPtr :: ByteString -> (ForeignPtr Word8, Int, Int)
packCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString
packAddress :: Addr# -> ByteString
unsafePackAddress :: Int -> Addr# -> ByteString
unsafeFinalize :: ByteString -> IO ()
inlinePerformIO :: IO a -> a
nullForeignPtr :: ForeignPtr Word8
countOccurrences :: (Storable a, Num a) => Ptr a -> Ptr Word8 -> Int -> IO ()
c_strlen :: CString -> IO CSize
c_malloc :: CSize -> IO (Ptr Word8)
c_free :: Ptr Word8 -> IO ()
c_free_finalizer :: FunPtr (Ptr Word8 -> IO ())
memchr :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
memcmp :: Ptr Word8 -> Ptr Word8 -> CSize -> IO CInt
memcpy :: Ptr Word8 -> Ptr Word8 -> CSize -> IO ()
memmove :: Ptr Word8 -> Ptr Word8 -> CSize -> 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
memcpy_ptr_baoff :: Ptr a -> RawBuffer -> CInt -> CSize -> IO (Ptr ())
w2c :: Word8 -> Char
c2w :: Char -> Word8
isSpaceWord8 :: Word8 -> Bool

The `ByteString` type and representation
data ByteString

A space-efficient representation of a Word8 vector, supporting many efficient operations. A `ByteString` contains 8-bit characters only. Instances of Eq, Ord, Read, Show, Data, Typeable
Constructors

PS !(ForeignPtr Word8) !Int !Int |

Instances

Data ByteString
Eq ByteString
Monoid ByteString
Ord ByteString
Read ByteString
Show ByteString
Typeable ByteString

newtype LazyByteString

A space-efficient representation of a Word8 vector, supporting many efficient operations. A `ByteString` contains 8-bit characters only. Instances of Eq, Ord, Read, Show, Data, Typeable
Constructors

LPS [ByteString] |

Instances

Data LazyByteString
Read LazyByteString
Show LazyByteString
Typeable LazyByteString

Unchecked access
unsafeHead :: ByteString -> Word8
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.
unsafeTail :: ByteString -> ByteString
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.
unsafeIndex :: ByteString -> Int -> 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.
unsafeTake :: Int -> ByteString -> ByteString
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`.
unsafeDrop :: 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`.
Low level introduction and elimination
empty :: ByteString
O(1) The empty `ByteString`
create :: Int -> (Ptr Word8 -> IO ()) -> IO ByteString
Create ByteString of size `l` and use action `f` to fill it's contents.
createAndTrim :: Int -> (Ptr Word8 -> IO Int) -> IO ByteString
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)
mallocByteString :: Int -> IO (ForeignPtr a)
Wrapper of mallocForeignPtrBytes with faster implementation for GHC 6.5 builds newer than 060606
unsafeCreate :: Int -> (Ptr Word8 -> IO ()) -> ByteString
A way of creating ByteStrings outside the IO monad. The `Int` argument gives the final size of the ByteString. Unlike `createAndTrim` the ByteString is not reallocated if the final size is less than the estimated size.
unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a
O(1) construction Use a `ByteString` with a function requiring a `CString`. Warning: modifying the `CString` will affect the `ByteString`. Why is this function unsafe? It relies on the null byte at the end of the ByteString to be there. Unless you can guarantee the null byte, you should use the safe version, which will copy the string first.
unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
O(1) construction Use a `ByteString` with a function requiring a `CStringLen`.
fromForeignPtr :: ForeignPtr Word8 -> Int -> ByteString
O(1) Build a ByteString from a ForeignPtr
toForeignPtr :: ByteString -> (ForeignPtr Word8, Int, Int)
O(1) Deconstruct a ForeignPtr from a ByteString
packCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString
O(1) Construct a `ByteString` given a C Ptr Word8 buffer, a length, and an IO action representing a finalizer. This function is not available on Hugs.
packAddress :: Addr# -> 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 `unsafePackAddress` if you know the length of the string statically.

An example:

     literalFS = packAddress "literal"#

unsafePackAddress :: Int -> Addr# -> ByteString
O(1) `unsafePackAddress` provides constant-time construction of ByteStrings -- which is ideal for string literals. It packs a null-terminated sequence of bytes into a `ByteString`, given a raw Addr to the string, and the length of the string. Make sure the length is correct, otherwise use the safer `packAddress` (where the length will be calculated once at runtime).
unsafeFinalize :: ByteString -> IO ()
Explicitly run the finaliser associated with a `ByteString`. Further references to this value may generate invalid memory references. This operation 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 `ByteString`s ever generated from the underlying byte array are no longer live.
Utilities
inlinePerformIO :: IO a -> a
Just like unsafePerformIO, but we inline it. Big performance gains as it exposes lots of things to further inlining
nullForeignPtr :: ForeignPtr Word8
countOccurrences :: (Storable a, Num a) => Ptr a -> Ptr Word8 -> Int -> IO ()
Count the number of occurrences of each byte.
Standard C Functions
c_strlen :: CString -> IO CSize
c_malloc :: CSize -> IO (Ptr Word8)
c_free :: Ptr Word8 -> IO ()
c_free_finalizer :: FunPtr (Ptr Word8 -> IO ())
memchr :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
memcmp :: Ptr Word8 -> Ptr Word8 -> CSize -> IO CInt
memcpy :: Ptr Word8 -> Ptr Word8 -> CSize -> IO ()
memmove :: Ptr Word8 -> Ptr Word8 -> CSize -> IO ()
memset :: Ptr Word8 -> Word8 -> CSize -> IO (Ptr Word8)
cbits functions
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
Internal GHC magic
memcpy_ptr_baoff :: Ptr a -> RawBuffer -> CInt -> CSize -> IO (Ptr ())
Chars
w2c :: Word8 -> Char
Conversion between `Word8` and Char. Should compile to a no-op.
c2w :: Char -> Word8
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
Produced by Haddock version 0.8