| Copyright | (c) Don Stewart 2006-2008 (c) Duncan Coutts 2006-2011 | 
|---|---|
| License | BSD-style | 
| Maintainer | dons00@gmail.com, duncan@community.haskell.org | 
| Stability | provisional | 
| Portability | non-portable | 
| Safe Haskell | Unsafe | 
| Language | Haskell98 | 
Data.ByteString.Unsafe
Description
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.
Synopsis
- unsafeHead :: ByteString -> Word8
- unsafeTail :: ByteString -> ByteString
- unsafeInit :: ByteString -> ByteString
- unsafeLast :: ByteString -> Word8
- unsafeIndex :: ByteString -> Int -> Word8
- unsafeTake :: Int -> ByteString -> ByteString
- unsafeDrop :: Int -> ByteString -> ByteString
- unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a
- unsafeUseAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a
- unsafePackCString :: CString -> IO ByteString
- unsafePackCStringLen :: CStringLen -> IO ByteString
- unsafePackMallocCString :: CString -> IO ByteString
- unsafePackMallocCStringLen :: CStringLen -> IO ByteString
- unsafePackAddress :: Addr# -> IO ByteString
- unsafePackAddressLen :: Int -> Addr# -> IO ByteString
- unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString
- unsafeFinalize :: ByteString -> IO ()
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.
unsafeInit :: 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.
unsafeLast :: ByteString -> Word8 #
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.
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 #
unsafeDrop :: Int -> ByteString -> ByteString #
Low level interaction with CStrings
Using ByteStrings with functions for CStrings
unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a #
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 CStringshares the underlying byte buffer with the originalByteString. Thus modifying theCString, either in C, or using poke, will cause the contents of theByteStringto change, breaking referential transparency. OtherByteStrings created by sharing (such as those produced viatakeordrop) will also reflect these changes. Modifying theCStringwill break referential transparency. To avoid this, useuseAsCString, which makes a copy of the originalByteString.
- CStrings are often passed to functions that require them to be null-terminated. If the original- ByteStringwasn't null terminated, neither will the- CStringbe. It is the programmers responsibility to guarantee that the- ByteStringis 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.
unsafeUseAsCStringLen :: ByteString -> (CStringLen -> 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 CStringLenshares the underlying byte buffer with the originalByteString. Thus modifying theCStringLen, either in C, or using poke, will cause the contents of theByteStringto change, breaking referential transparency. OtherByteStrings created by sharing (such as those produced viatakeordrop) will also reflect these changes. Modifying theCStringLenwill break referential transparency. To avoid this, useuseAsCStringLen, which makes a copy of the originalByteString.
Converting CStrings to ByteStrings
unsafePackCString :: CString -> IO ByteString #
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.
unsafePackCStringLen :: CStringLen -> 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.
unsafePackMallocCString :: CString -> 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.
unsafePackMallocCStringLen :: CStringLen -> 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.
unsafePackAddress :: Addr# -> 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.
unsafePackAddressLen :: Int -> 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 resultingByteString, breaking referential transparency.
If in doubt, don't use this function.
unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> 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.
unsafeFinalize :: ByteString -> IO () #
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.