unsafe package:bytestring

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.

A way of creating ByteStrings outside the IO monad. The Int argument gives the final size of the ByteString.

Like unsafeCreate but instead of giving the final size of the ByteString, it is just an upper bound. The inner action returns the actual size. Unlike createAndTrim the ByteString is not reallocated if the final size is less than the estimated size.

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.

See unsafePackAddress. This function is similar, but takes an additional length argument rather then computing it with strlen. Therefore embedding '\0' characters is possible.

See unsafePackLiteral. This function is similar, but takes an additional length argument rather then computing it with strlen. Therefore embedding '\0' characters is possible.

See unsafePackAddress. This function has similar behavior. Prefer this function when the address in known to be an Addr# literal. In that context, there is no need for the sequencing guarantees that IO provides. On GHC 9.0 and up, this function uses the FinalPtr data constructor for ForeignPtrContents.

This is similar to withForeignPtr but comes with an important caveat: the user must guarantee that the continuation does not diverge (e.g. loop or throw an exception). In exchange for this loss of generality, this function offers the ability of GHC to optimise more aggressively. Specifically, applications of the form: unsafeWithForeignPtr fptr (forever something) See GHC issue #17760 for more information about the unsoundness behavior that this function can result in.

O(1) Unsafe indexing without bounds checking.

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.

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.

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.

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.

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.

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.

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 resulting ByteString, breaking referential transparency.

If in doubt, don't use this function.

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.

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.

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.

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.

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.

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.