CString package:bytestring

A null-terminated ASCII encoded CString. Null characters are not representable.

A null-terminated UTF-8 encoded CString. Null characters can be encoded as 0xc0 0x80.

O(n). Construct a new ByteString from a CString. The resulting ByteString is an immutable copy of the original CString, and is managed on the Haskell heap. The original CString must be null terminated.

O(n). Construct a new ByteString from a CStringLen. The resulting ByteString is an immutable copy of the original CStringLen. The ByteString is a normal Haskell value and will be managed on the Haskell heap.

O(n) construction Use a ByteString with a function requiring a null-terminated CString. The CString is a copy and will be freed automatically; it must not be stored or used after the subcomputation finishes.

O(n) construction Use a ByteString with a function requiring a CStringLen. As for useAsCString this function makes a copy of the original ByteString. It must not be stored or used after the subcomputation finishes. Beware that this function is not required to add a terminating NUL byte at the end of the CStringLen it provides. If you need to construct a pointer to a null-terminated sequence, use useAsCString (and measure length independently if desired).

O(n). Construct a new ShortByteString from a CString. The resulting ShortByteString is an immutable copy of the original CString, and is managed on the Haskell heap. The original CString must be null terminated.

O(n). Construct a new ShortByteString from a CStringLen. The resulting ShortByteString is an immutable copy of the original CStringLen. The ShortByteString is a normal Haskell value and will be managed on the Haskell heap.

O(n) construction. Use a ShortByteString with a function requiring a null-terminated CString. The CString is a copy and will be freed automatically; it must not be stored or used after the subcomputation finishes.

O(n) construction. Use a ShortByteString with a function requiring a CStringLen. As for useAsCString this function makes a copy of the original ShortByteString. It must not be stored or used after the subcomputation finishes. Beware that this function does not add a terminating NUL byte at the end of CStringLen. If you need to construct a pointer to a null-terminated sequence, use useAsCString (and measure length independently if desired).

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.

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 ByteStrings 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.
• CStrings 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.

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