bytestring-0.12.2.0: Fast, compact, strict and lazy byte strings with a list interface

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

Data.ByteString.Unsafe

Contents

- Unchecked access
- Low level interaction with CStrings
  - Using ByteStrings with functions for CStrings
  - Converting CStrings to ByteStrings

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 interaction with CStrings

## Using ByteStrings with functions for CStrings

unsafeUseAsCString :: ByteString -> (CString -> IO a) -> IO a Source #

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 `CString` shares the underlying byte buffer with the original `ByteString`. Thus modifying the `CString`, either in C, or using poke, will cause the contents of the `ByteString` to change, breaking referential transparency. Other `ByteString`s created by sharing (such as those produced via `take` or `drop`) will also reflect these changes. Modifying the `CString` will break referential transparency. To avoid this, use `useAsCString`, which makes a copy of the original `ByteString`.
- `CString`s are often passed to functions that require them to be null-terminated. If the original `ByteString` wasn't null terminated, neither will the `CString` be. It is the programmers responsibility to guarantee that the `ByteString` is 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 Source #

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 `CStringLen` shares the underlying byte buffer with the original `ByteString`. Thus modifying the `CStringLen`, either in C, or using poke, will cause the contents of the `ByteString` to change, breaking referential transparency. Other `ByteString`s created by sharing (such as those produced via `take` or `drop`) will also reflect these changes. Modifying the `CStringLen` will break referential transparency. To avoid this, use `useAsCStringLen`, which makes a copy of the original `ByteString`.

If `empty` is given, it will pass `(`nullPtr`, 0)`.

## Converting CStrings to ByteStrings

unsafePackCString :: CString -> IO ByteString Source #

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 Source #

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 Source #

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 Source #

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

unsafePackAddressLen :: Int -> Addr# -> IO ByteString Source #

O(1) `unsafePackAddressLen` provides constant-time construction of `ByteString`s, 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 resulting `ByteString`, breaking referential transparency.

If in doubt, don't use this function.

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

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 () Source #

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 `ByteString`s 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.