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 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 #
unsafeDrop :: Int -> ByteString -> ByteString Source #
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 originalByteString
. Thus modifying theCString
, either in C, or using poke, will cause the contents of theByteString
to change, breaking referential transparency. OtherByteString
s created by sharing (such as those produced viatake
ordrop
) will also reflect these changes. Modifying theCString
will break referential transparency. To avoid this, useuseAsCString
, which makes a copy of the originalByteString
. -
CString
s are often passed to functions that require them to be null-terminated. If the originalByteString
wasn't null terminated, neither will theCString
be. It is the programmers responsibility to guarantee that theByteString
is indeed null terminated. If in doubt, useuseAsCString
. - 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 originalByteString
. Thus modifying theCStringLen
, either in C, or using poke, will cause the contents of theByteString
to change, breaking referential transparency. OtherByteString
s created by sharing (such as those produced viatake
ordrop
) will also reflect these changes. Modifying theCStringLen
will break referential transparency. To avoid this, useuseAsCStringLen
, which makes a copy of the originalByteString
.
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 resultingByteString
, 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.