vector-bytestring- ByteStrings as type synonyms of Storable Vectors of Word8s

MaintainerBas van Dijk <>
Safe HaskellUnsafe




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.Vector.Storable.ByteString.Unsafe. Packages that extend the ByteString system at a low level will need to use this module.


The ByteString type and representation

type ByteString = Vector Word8Source

A space-efficient representation of a Word8 vector, supporting many efficient operations. A ByteString contains 8-bit characters only.

Low level introduction and elimination

create :: Int -> (Ptr Word8 -> IO ()) -> IO ByteStringSource

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

createAndTrim :: Int -> (Ptr Word8 -> IO Int) -> IO ByteStringSource

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.

unsafeCreate :: Int -> (Ptr Word8 -> IO ()) -> ByteStringSource

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.

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

Wrapper of mallocForeignPtrBytes with faster implementation for GHC.

Conversion to and from ForeignPtrs



:: ForeignPtr Word8 
-> Int


-> Int


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



:: ByteString 
-> (ForeignPtr Word8, Int, Int)

(ptr, offset, length)

O(1) Deconstruct a ForeignPtr from a ByteString


inlinePerformIO :: IO a -> aSource

Just like unsafePerformIO, but we inline it. Big performance gains as it exposes lots of things to further inlining. Very unsafe. In particular, you should do no memory allocation inside an inlinePerformIO block. On Hugs this is just unsafePerformIO.

nullForeignPtr :: ForeignPtr Word8Source

The 0 pointer. Used to indicate the empty Bytestring.

Standard C Functions

cbits functions


w2c :: Word8 -> CharSource

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

c2w :: Char -> Word8Source

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 -> BoolSource

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

isSpaceChar8 :: Char -> BoolSource

Selects white-space characters in the Latin-1 range