<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Data.ByteString.Unsafe</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Data-ByteString-Unsafe.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">bytestring-0.9.2.1: Fast, packed, strict and lazy byte arrays with a list interface</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>portable</td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Maintainer</th><td>dons@cse.unsw.edu.au, duncan@haskell.org</td></tr><tr><th>Safe Haskell</th><td>None</td></tr></table><p class="caption">Data.ByteString.Unsafe</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Unchecked access
</a></li><li><a href="#g:2">Low level interaction with CStrings
</a><ul><li><a href="#g:3">Using ByteStrings with functions for CStrings
</a></li><li><a href="#g:4">Converting CStrings to ByteStrings
</a></li></ul></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>A module containing unsafe <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code> operations.
</p><p>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.
</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:unsafeHead">unsafeHead</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></li><li class="src short"><a href="#v:unsafeTail">unsafeTail</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeIndex">unsafeIndex</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></li><li class="src short"><a href="#v:unsafeTake">unsafeTake</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeDrop">unsafeDrop</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeUseAsCString">unsafeUseAsCString</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:unsafeUseAsCStringLen">unsafeUseAsCStringLen</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:unsafePackCString">unsafePackCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackCStringLen">unsafePackCStringLen</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackMallocCString">unsafePackMallocCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackAddress">unsafePackAddress</a> :: <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackAddressLen">unsafePackAddressLen</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafePackCStringFinalizer">unsafePackCStringFinalizer</a> :: <a href="../base-4.5.1.0/Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:unsafeFinalize">unsafeFinalize</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></li></ul></div><div id="interface"><h1 id="g:1">Unchecked access
</h1><div class="top"><p class="src"><a name="v:unsafeHead" class="def">unsafeHead</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:head">head</a></code> for non-empty ByteStrings. <code><a href="Data-ByteString-Unsafe.html#v:unsafeHead">unsafeHead</a></code> 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.
</p></div></div><div class="top"><p class="src"><a name="v:unsafeTail" class="def">unsafeTail</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:tail">tail</a></code> for non-empty ByteStrings. <code><a href="Data-ByteString-Unsafe.html#v:unsafeTail">unsafeTail</a></code> omits the
check for the empty case. As with <code><a href="Data-ByteString-Unsafe.html#v:unsafeHead">unsafeHead</a></code>, the programmer must
provide a separate proof that the ByteString is non-empty.
</p></div></div><div class="top"><p class="src"><a name="v:unsafeIndex" class="def">unsafeIndex</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></p><div class="doc"><p>Unsafe <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code> index (subscript) operator, starting from 0, returning a <code><a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a></code>
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.
</p></div></div><div class="top"><p class="src"><a name="v:unsafeTake" class="def">unsafeTake</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:take">take</a></code> which omits the checks on <code>n</code> so there is an
obligation on the programmer to provide a proof that <code>0 <= n <= <code><a href="../base-4.5.1.0/Data-List.html#v:length">length</a></code> xs</code>.
</p></div></div><div class="top"><p class="src"><a name="v:unsafeDrop" class="def">unsafeDrop</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p>A variety of <code><a href="../base-4.5.1.0/Data-List.html#v:drop">drop</a></code> which omits the checks on <code>n</code> so there is an
obligation on the programmer to provide a proof that <code>0 <= n <= <code><a href="../base-4.5.1.0/Data-List.html#v:length">length</a></code> xs</code>.
</p></div></div><h1 id="g:2">Low level interaction with CStrings
</h1><h2 id="g:3">Using ByteStrings with functions for CStrings
</h2><div class="top"><p class="src"><a name="v:unsafeUseAsCString" class="def">unsafeUseAsCString</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</p><div class="doc"><p><em>O(1) construction</em> Use a <code>ByteString</code> with a function requiring a
<code>CString</code>.
</p><p>This function does zero copying, and merely unwraps a <code>ByteString</code> to
appear as a <code>CString</code>. It is <em>unsafe</em> in two ways:
</p><ul><li> After calling this function the <code>CString</code> shares the underlying
byte buffer with the original <code>ByteString</code>. Thus modifying the
<code>CString</code>, either in C, or using poke, will cause the contents of the
<code>ByteString</code> to change, breaking referential transparency. Other
<code>ByteStrings</code> created by sharing (such as those produced via <code><a href="../base-4.5.1.0/Data-List.html#v:take">take</a></code>
or <code><a href="../base-4.5.1.0/Data-List.html#v:drop">drop</a></code>) will also reflect these changes. Modifying the <code>CString</code>
will break referential transparency. To avoid this, use
<code>useAsCString</code>, which makes a copy of the original <code>ByteString</code>.
</li><li> <code>CStrings</code> are often passed to functions that require them to be
null-terminated. If the original <code>ByteString</code> wasn't null terminated,
neither will the <code>CString</code> be. It is the programmers responsibility
to guarantee that the <code>ByteString</code> is indeed null terminated. If in
doubt, use <code>useAsCString</code>.
</li></ul></div></div><div class="top"><p class="src"><a name="v:unsafeUseAsCStringLen" class="def">unsafeUseAsCStringLen</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> (<a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a) -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> a</p><div class="doc"><p><em>O(1) construction</em> Use a <code>ByteString</code> with a function requiring a
<code>CStringLen</code>.
</p><p>This function does zero copying, and merely unwraps a <code>ByteString</code> to
appear as a <code>CStringLen</code>. It is <em>unsafe</em>:
</p><ul><li> After calling this function the <code>CStringLen</code> shares the underlying
byte buffer with the original <code>ByteString</code>. Thus modifying the
<code>CStringLen</code>, either in C, or using poke, will cause the contents of the
<code>ByteString</code> to change, breaking referential transparency. Other
<code>ByteStrings</code> created by sharing (such as those produced via <code><a href="../base-4.5.1.0/Data-List.html#v:take">take</a></code>
or <code><a href="../base-4.5.1.0/Data-List.html#v:drop">drop</a></code>) will also reflect these changes. Modifying the <code>CStringLen</code>
will break referential transparency. To avoid this, use
<code>useAsCStringLen</code>, which makes a copy of the original <code>ByteString</code>.
</li></ul></div></div><h2 id="g:4">Converting CStrings to ByteStrings
</h2><div class="top"><p class="src"><a name="v:unsafePackCString" class="def">unsafePackCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(n)</em> Build a <code>ByteString</code> from a <code>CString</code>. This value will have <em>no</em>
finalizer associated to it, and will not be garbage collected by
Haskell. The ByteString length is calculated using <em>strlen(3)</em>,
and thus the complexity is a <em>O(n)</em>.
</p><p>This function is <em>unsafe</em>. If the <code>CString</code> is later modified, this
change will be reflected in the resulting <code>ByteString</code>, breaking
referential transparency.
</p></div></div><div class="top"><p class="src"><a name="v:unsafePackCStringLen" class="def">unsafePackCStringLen</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CStringLen">CStringLen</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(1)</em> Build a <code>ByteString</code> from a <code>CStringLen</code>. This value will
have <em>no</em> finalizer associated with it, and will not be garbage
collected by Haskell. This operation has <em>O(1)</em> complexity as we
already know the final size, so no <em>strlen(3)</em> is required.
</p><p>This funtion is <em>unsafe</em>. If the original <code>CStringLen</code> is later
modified, this change will be reflected in the resulting <code>ByteString</code>,
breaking referential transparency.
</p></div></div><div class="top"><p class="src"><a name="v:unsafePackMallocCString" class="def">unsafePackMallocCString</a> :: <a href="../base-4.5.1.0/Foreign-C-String.html#t:CString">CString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(n)</em> Build a <code>ByteString</code> from a malloced <code>CString</code>. This value will
have a <code>free(3)</code> finalizer associated to it.
</p><p>This funtion is <em>unsafe</em>. If the original <code>CString</code> is later
modified, this change will be reflected in the resulting <code>ByteString</code>,
breaking referential transparency.
</p><p>This function is also unsafe if you call its finalizer twice,
which will result in a <em>double free</em> error, or if you pass it
a CString not allocated with <code>malloc</code>.
</p></div></div><div class="top"><p class="src"><a name="v:unsafePackAddress" class="def">unsafePackAddress</a> :: <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(n)</em> 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 <code>ByteString</code>. 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 <code>char
[]</code> by GHC. Establishing the length of the string requires a call to
<code>strlen(3)</code>, so the Addr# must point to a null-terminated buffer (as
is the case with <a href="string.html">string</a># literals in GHC). Use <code><a href="Data-ByteString-Unsafe.html#v:unsafePackAddressLen">unsafePackAddressLen</a></code>
if you know the length of the string statically.
</p><p>An example:
</p><pre> literalFS = unsafePackAddress "literal"#
</pre><p>This function is <em>unsafe</em>. If you modify the buffer pointed to by the
original Addr# this modification will be reflected in the resulting
<code>ByteString</code>, breaking referential transparency.
</p><p>Note this also won't work if you Add# has embedded '\0' characters in
the string (strlen will fail).
</p></div></div><div class="top"><p class="src"><a name="v:unsafePackAddressLen" class="def">unsafePackAddressLen</a> :: <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(1)</em> <code><a href="Data-ByteString-Unsafe.html#v:unsafePackAddressLen">unsafePackAddressLen</a></code> provides constant-time construction of
<code>ByteStrings</code> which is ideal for string literals. It packs a sequence
of bytes into a <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code>, given a raw <code><a href="../ghc-prim-0.2.0.0/GHC-Prim.html#t:Addr-35-">Addr#</a></code> to the string, and
the length of the string.
</p><p>This function is <em>unsafe</em> in two ways:
</p><ul><li> 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.
</li><li> if the underying Addr# is later modified, this change will be
reflected in resulting <code>ByteString</code>, breaking referential
transparency.
</li></ul><p>If in doubt, don't use these functions.
</p></div></div><div class="top"><p class="src"><a name="v:unsafePackCStringFinalizer" class="def">unsafePackCStringFinalizer</a> :: <a href="../base-4.5.1.0/Foreign-Ptr.html#t:Ptr">Ptr</a> <a href="../base-4.5.1.0/Data-Word.html#t:Word8">Word8</a> -> <a href="../base-4.5.1.0/Data-Int.html#t:Int">Int</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="Data-ByteString.html#t:ByteString">ByteString</a></p><div class="doc"><p><em>O(1)</em> Construct a <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code> given a Ptr Word8 to a buffer, a
length, and an IO action representing a finalizer. This function is
not available on Hugs.
</p><p>This function is <em>unsafe</em>, 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 <code>ByteString</code>.
</p></div></div><div class="top"><p class="src"><a name="v:unsafeFinalize" class="def">unsafeFinalize</a> :: <a href="Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="../base-4.5.1.0/System-IO.html#t:IO">IO</a> <a href="../ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></p><div class="doc"><p>Explicitly run the finaliser associated with a <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code>.
References to this value after finalisation may generate invalid memory
references.
</p><p>This function is <em>unsafe</em>, as there may be other
<code>ByteStrings</code> referring to the same underlying pages. If you use
this, you need to have a proof of some kind that all <code><a href="Data-ByteString.html#t:ByteString">ByteString</a></code>s
ever generated from the underlying byte array are no longer live.
</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.11.0</p></div></body></html>
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-release
>
by-pkgid
>
956c458aa5fe9afc4d2c00cb7b491287
>
files
>
2568
