{-# LANGUAGE Unsafe #-}-- |-- Module : Data.ByteString.Unsafe-- 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---- 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.--moduleData.ByteString.Unsafe(-- * Unchecked accessunsafeHead ,unsafeTail ,unsafeInit ,unsafeLast ,unsafeIndex ,unsafeTake ,unsafeDrop ,-- * Low level interaction with CStrings-- ** Using ByteStrings with functions for CStringsunsafeUseAsCString ,unsafeUseAsCStringLen ,-- ** Converting CStrings to ByteStringsunsafePackCString ,unsafePackCStringLen ,unsafePackMallocCString ,unsafePackMallocCStringLen ,unsafePackAddress ,unsafePackAddressLen ,unsafePackCStringFinalizer ,unsafeFinalize ,)whereimportData.ByteString.Internal importForeign.ForeignPtr(newForeignPtr_,newForeignPtr,withForeignPtr)importForeign.Storable(Storable(..))importForeign.C.String(CString,CStringLen)importControl.Exception(assert)importData.Word(Word8)importqualifiedForeign.ForeignPtrasFC(finalizeForeignPtr)importqualifiedForeign.ConcurrentasFC(newForeignPtr)importGHC.Exts(Addr#)importGHC.Ptr(Ptr(..),castPtr)-- ------------------------------------------------------------------------- Extensions to the basic interface---- | 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.unsafeHead ::ByteString ->Word8unsafeHead :: ByteString -> Word8
unsafeHead (BS ForeignPtr Word8
x Int
l )=Bool -> Word8 -> Word8
forall a. (?callStack::CallStack) => Bool -> a -> a
assert(Int
l Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
>Int
0)(Word8 -> Word8) -> Word8 -> Word8
forall a b. (a -> b) -> a -> b
$IO Word8 -> Word8
forall a. IO a -> a
accursedUnutterablePerformIO (IO Word8 -> Word8) -> IO Word8 -> Word8
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> (Ptr Word8 -> IO Word8) -> IO Word8
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtrForeignPtr Word8
x ((Ptr Word8 -> IO Word8) -> IO Word8)
-> (Ptr Word8 -> IO Word8) -> IO Word8
forall a b. (a -> b) -> a -> b
$\Ptr Word8
p ->Ptr Word8 -> IO Word8
forall a. Storable a => Ptr a -> IO a
peekPtr Word8
p {-# INLINEunsafeHead #-}-- | 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.unsafeTail ::ByteString ->ByteString unsafeTail :: ByteString -> ByteString
unsafeTail (BS ForeignPtr Word8
ps Int
l )=Bool -> ByteString -> ByteString
forall a. (?callStack::CallStack) => Bool -> a -> a
assert(Int
l Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
>Int
0)(ByteString -> ByteString) -> ByteString -> ByteString
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> Int -> ByteString
BS (ForeignPtr Word8 -> Int -> ForeignPtr Word8
forall a b. ForeignPtr a -> Int -> ForeignPtr b
plusForeignPtrForeignPtr Word8
ps Int
1)(Int
l Int -> Int -> Int
forall a. Num a => a -> a -> a
-Int
1){-# INLINEunsafeTail #-}-- | 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.unsafeInit ::ByteString ->ByteString unsafeInit :: ByteString -> ByteString
unsafeInit (BS ForeignPtr Word8
ps Int
l )=Bool -> ByteString -> ByteString
forall a. (?callStack::CallStack) => Bool -> a -> a
assert(Int
l Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
>Int
0)(ByteString -> ByteString) -> ByteString -> ByteString
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
ps (Int
l Int -> Int -> Int
forall a. Num a => a -> a -> a
-Int
1){-# INLINEunsafeInit #-}-- | 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.unsafeLast ::ByteString ->Word8unsafeLast :: ByteString -> Word8
unsafeLast (BS ForeignPtr Word8
x Int
l )=Bool -> Word8 -> Word8
forall a. (?callStack::CallStack) => Bool -> a -> a
assert(Int
l Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
>Int
0)(Word8 -> Word8) -> Word8 -> Word8
forall a b. (a -> b) -> a -> b
$IO Word8 -> Word8
forall a. IO a -> a
accursedUnutterablePerformIO (IO Word8 -> Word8) -> IO Word8 -> Word8
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> (Ptr Word8 -> IO Word8) -> IO Word8
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtrForeignPtr Word8
x ((Ptr Word8 -> IO Word8) -> IO Word8)
-> (Ptr Word8 -> IO Word8) -> IO Word8
forall a b. (a -> b) -> a -> b
$\Ptr Word8
p ->Ptr Word8 -> Int -> IO Word8
forall b. Ptr b -> Int -> IO Word8
forall a b. Storable a => Ptr b -> Int -> IO a
peekByteOffPtr Word8
p (Int
l Int -> Int -> Int
forall a. Num a => a -> a -> a
-Int
1){-# INLINEunsafeLast #-}-- | 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.unsafeIndex ::ByteString ->Int->Word8unsafeIndex :: ByteString -> Int -> Word8
unsafeIndex (BS ForeignPtr Word8
x Int
l )Int
i =Bool -> Word8 -> Word8
forall a. (?callStack::CallStack) => Bool -> a -> a
assert(Int
i Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
>=Int
0Bool -> Bool -> Bool
&&Int
i Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
<Int
l )(Word8 -> Word8) -> Word8 -> Word8
forall a b. (a -> b) -> a -> b
$IO Word8 -> Word8
forall a. IO a -> a
accursedUnutterablePerformIO (IO Word8 -> Word8) -> IO Word8 -> Word8
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> (Ptr Word8 -> IO Word8) -> IO Word8
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
unsafeWithForeignPtrForeignPtr Word8
x ((Ptr Word8 -> IO Word8) -> IO Word8)
-> (Ptr Word8 -> IO Word8) -> IO Word8
forall a b. (a -> b) -> a -> b
$\Ptr Word8
p ->Ptr Word8 -> Int -> IO Word8
forall b. Ptr b -> Int -> IO Word8
forall a b. Storable a => Ptr b -> Int -> IO a
peekByteOffPtr Word8
p Int
i {-# INLINEunsafeIndex #-}-- | 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@.unsafeTake ::Int->ByteString ->ByteString unsafeTake :: Int -> ByteString -> ByteString
unsafeTake Int
n (BS ForeignPtr Word8
x Int
l )=Bool -> ByteString -> ByteString
forall a. (?callStack::CallStack) => Bool -> a -> a
assert(Int
0Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
<=Int
n Bool -> Bool -> Bool
&&Int
n Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
<=Int
l )(ByteString -> ByteString) -> ByteString -> ByteString
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
x Int
n {-# INLINEunsafeTake #-}-- | 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@.unsafeDrop ::Int->ByteString ->ByteString unsafeDrop :: Int -> ByteString -> ByteString
unsafeDrop Int
n (BS ForeignPtr Word8
x Int
l )=Bool -> ByteString -> ByteString
forall a. (?callStack::CallStack) => Bool -> a -> a
assert(Int
0Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
<=Int
n Bool -> Bool -> Bool
&&Int
n Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
<=Int
l )(ByteString -> ByteString) -> ByteString -> ByteString
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> Int -> ByteString
BS (ForeignPtr Word8 -> Int -> ForeignPtr Word8
forall a b. ForeignPtr a -> Int -> ForeignPtr b
plusForeignPtrForeignPtr Word8
x Int
n )(Int
l Int -> Int -> Int
forall a. Num a => a -> a -> a
-Int
n ){-# INLINEunsafeDrop #-}-- | /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.--unsafePackAddressLen ::Int->Addr#->IOByteString unsafePackAddressLen :: Int -> Addr# -> IO ByteString
unsafePackAddressLen Int
len Addr#
addr# =doForeignPtr Word8
p <-Ptr Word8 -> IO (ForeignPtr Word8)
forall a. Ptr a -> IO (ForeignPtr a)
newForeignPtr_(Addr# -> Ptr Word8
forall a. Addr# -> Ptr a
PtrAddr#
addr# )ByteString -> IO ByteString
forall a. a -> IO a
forall (m :: * -> *) a. Monad m => a -> m a
return(ByteString -> IO ByteString) -> ByteString -> IO ByteString
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
p Int
len {-# INLINEunsafePackAddressLen #-}-- | /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'.--unsafePackCStringFinalizer ::PtrWord8->Int->IO()->IOByteString unsafePackCStringFinalizer :: Ptr Word8 -> Int -> IO () -> IO ByteString
unsafePackCStringFinalizer Ptr Word8
p Int
l IO ()
f =doForeignPtr Word8
fp <-Ptr Word8 -> IO () -> IO (ForeignPtr Word8)
forall a. Ptr a -> IO () -> IO (ForeignPtr a)
FC.newForeignPtrPtr Word8
p IO ()
f ByteString -> IO ByteString
forall a. a -> IO a
forall (m :: * -> *) a. Monad m => a -> m a
return(ByteString -> IO ByteString) -> ByteString -> IO ByteString
forall a b. (a -> b) -> a -> b
$ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
fp Int
l -- | 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.--unsafeFinalize ::ByteString ->IO()unsafeFinalize :: ByteString -> IO ()
unsafeFinalize (BS ForeignPtr Word8
p Int
_)=ForeignPtr Word8 -> IO ()
forall a. ForeignPtr a -> IO ()
FC.finalizeForeignPtrForeignPtr Word8
p -------------------------------------------------------------------------- Packing CStrings into ByteStrings-- | /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.--unsafePackCString ::CString->IOByteString unsafePackCString :: CString -> IO ByteString
unsafePackCString CString
cstr =doForeignPtr Word8
fp <-Ptr Word8 -> IO (ForeignPtr Word8)
forall a. Ptr a -> IO (ForeignPtr a)
newForeignPtr_(CString -> Ptr Word8
forall a b. Ptr a -> Ptr b
castPtrCString
cstr )CSize
l <-CString -> IO CSize
c_strlen CString
cstr ByteString -> IO ByteString
forall a. a -> IO a
forall (m :: * -> *) a. Monad m => a -> m a
return(ByteString -> IO ByteString) -> ByteString -> IO ByteString
forall a b. (a -> b) -> a -> b
$!ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
fp (CSize -> Int
forall a b. (Integral a, Num b) => a -> b
fromIntegralCSize
l )-- | /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.--unsafePackCStringLen ::CStringLen->IOByteString unsafePackCStringLen :: CStringLen -> IO ByteString
unsafePackCStringLen (CString
ptr ,Int
len )=doForeignPtr Word8
fp <-Ptr Word8 -> IO (ForeignPtr Word8)
forall a. Ptr a -> IO (ForeignPtr a)
newForeignPtr_(CString -> Ptr Word8
forall a b. Ptr a -> Ptr b
castPtrCString
ptr )ByteString -> IO ByteString
forall a. a -> IO a
forall (m :: * -> *) a. Monad m => a -> m a
return(ByteString -> IO ByteString) -> ByteString -> IO ByteString
forall a b. (a -> b) -> a -> b
$!ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
fp (Int -> Int
forall a b. (Integral a, Num b) => a -> b
fromIntegralInt
len )-- | /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 'Foreign.Marshal.Alloc.malloc'.--unsafePackMallocCString ::CString->IOByteString unsafePackMallocCString :: CString -> IO ByteString
unsafePackMallocCString CString
cstr =doForeignPtr Word8
fp <-FinalizerPtr Word8 -> Ptr Word8 -> IO (ForeignPtr Word8)
forall a. FinalizerPtr a -> Ptr a -> IO (ForeignPtr a)
newForeignPtrFinalizerPtr Word8
c_free_finalizer (CString -> Ptr Word8
forall a b. Ptr a -> Ptr b
castPtrCString
cstr )CSize
len <-CString -> IO CSize
c_strlen CString
cstr ByteString -> IO ByteString
forall a. a -> IO a
forall (m :: * -> *) a. Monad m => a -> m a
return(ByteString -> IO ByteString) -> ByteString -> IO ByteString
forall a b. (a -> b) -> a -> b
$!ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
fp (CSize -> Int
forall a b. (Integral a, Num b) => a -> b
fromIntegralCSize
len )-- | /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 'Foreign.Marshal.Alloc.malloc'.--unsafePackMallocCStringLen ::CStringLen->IOByteString unsafePackMallocCStringLen :: CStringLen -> IO ByteString
unsafePackMallocCStringLen (CString
cstr ,Int
len )=doForeignPtr Word8
fp <-FinalizerPtr Word8 -> Ptr Word8 -> IO (ForeignPtr Word8)
forall a. FinalizerPtr a -> Ptr a -> IO (ForeignPtr a)
newForeignPtrFinalizerPtr Word8
c_free_finalizer (CString -> Ptr Word8
forall a b. Ptr a -> Ptr b
castPtrCString
cstr )ByteString -> IO ByteString
forall a. a -> IO a
forall (m :: * -> *) a. Monad m => a -> m a
return(ByteString -> IO ByteString) -> ByteString -> IO ByteString
forall a b. (a -> b) -> a -> b
$!ForeignPtr Word8 -> Int -> ByteString
BS ForeignPtr Word8
fp Int
len -- ----------------------------------------------------------------------- | /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-- 'Data.ByteString.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 'Data.ByteString.useAsCString'.---- * The memory may freed at any point after the subcomputation-- terminates, so the pointer to the storage must *not* be used-- after this.--unsafeUseAsCString ::ByteString ->(CString->IOa )->IOa unsafeUseAsCString :: forall a. ByteString -> (CString -> IO a) -> IO a
unsafeUseAsCString (BS ForeignPtr Word8
ps Int
_)CString -> IO a
action =ForeignPtr Word8 -> (Ptr Word8 -> IO a) -> IO a
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtrForeignPtr Word8
ps ((Ptr Word8 -> IO a) -> IO a) -> (Ptr Word8 -> IO a) -> IO a
forall a b. (a -> b) -> a -> b
$\Ptr Word8
p ->CString -> IO a
action (Ptr Word8 -> CString
forall a b. Ptr a -> Ptr b
castPtrPtr Word8
p )-- Cannot use unsafeWithForeignPtr, because action can diverge-- | /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-- 'Data.ByteString.useAsCStringLen', which makes a copy of the original 'ByteString'.---- If 'Data.ByteString.empty' is given, it will pass @('Foreign.Ptr.nullPtr', 0)@.unsafeUseAsCStringLen ::ByteString ->(CStringLen->IOa )->IOa unsafeUseAsCStringLen :: forall a. ByteString -> (CStringLen -> IO a) -> IO a
unsafeUseAsCStringLen (BS ForeignPtr Word8
ps Int
l )CStringLen -> IO a
action =ForeignPtr Word8 -> (Ptr Word8 -> IO a) -> IO a
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtrForeignPtr Word8
ps ((Ptr Word8 -> IO a) -> IO a) -> (Ptr Word8 -> IO a) -> IO a
forall a b. (a -> b) -> a -> b
$\Ptr Word8
p ->CStringLen -> IO a
action (Ptr Word8 -> CString
forall a b. Ptr a -> Ptr b
castPtrPtr Word8
p ,Int
l )-- Cannot use unsafeWithForeignPtr, because action can diverge