Z.Data.CBytes

This module provide CBytes with some useful instances / functions, A CBytes is a wrapper for immutable null-terminated string. The main design target of this type is to ease the bridging of C FFI APIs, since most of the unix APIs use null-terminated string. On windows you're encouraged to use a compatibility layer like 'WideCharToMultiByte/MultiByteToWideChar' and keep the same interface, e.g. libuv do this when deal with file paths.

We neither guarantee to store length info, nor support O(1) slice for CBytes: This will defeat the purpose of null-terminated string which is to save memory, We do save the length if it's created on GHC heap though. If you need advance editing, convert a CBytes to Bytes with toBytes and use vector combinators. Use fromBytes to convert it back.

It can be used with OverloadedString, literal encoding is UTF-8 with some modifications: NUL char is encoded to 'C0 80', and 'xD800' ~ 'xDFFF' is encoded as a three bytes normal utf-8 codepoint. This is also how ghc compile string literal into binaries, thus we can use rewrite-rules to construct CBytes value in O(1) without wasting runtime heap.

Note most of the unix API is not unicode awared though, you may find a scandir call return a filename which is not proper encoded in any unicode encoding at all. But still, UTF-8 is recommanded to be used everywhere, and we use UTF-8 assumption in various places, such as displaying CBytes and literals encoding above.

Documentation

data CBytes

A efficient wrapper for immutable null-terminated string which can be automatically freed by ghc garbage collector.

Instances

Eq CBytes

Defined in Z.Data.CBytes

Methods

(==) :: CBytes -> CBytes -> Bool

(/=) :: CBytes -> CBytes -> Bool

Ord CBytes

Defined in Z.Data.CBytes

Methods

compare :: CBytes -> CBytes -> Ordering

(<) :: CBytes -> CBytes -> Bool

(<=) :: CBytes -> CBytes -> Bool

(>) :: CBytes -> CBytes -> Bool

(>=) :: CBytes -> CBytes -> Bool

max :: CBytes -> CBytes -> CBytes

min :: CBytes -> CBytes -> CBytes

Read CBytes

Defined in Z.Data.CBytes

Methods

readsPrec :: Int -> ReadS CBytes

readList :: ReadS [CBytes]

readPrec :: ReadPrec CBytes

readListPrec :: ReadPrec [CBytes]

Show CBytes

Defined in Z.Data.CBytes

Methods

showsPrec :: Int -> CBytes -> ShowS

show :: CBytes -> String

showList :: [CBytes] -> ShowS

IsString CBytes

Defined in Z.Data.CBytes

Methods

fromString :: String -> CBytes

Semigroup CBytes

Defined in Z.Data.CBytes

Methods

(<>) :: CBytes -> CBytes -> CBytes

sconcat :: NonEmpty CBytes -> CBytes

stimes :: Integral b => b -> CBytes -> CBytes

Monoid CBytes

Defined in Z.Data.CBytes

Methods

mempty :: CBytes

mappend :: CBytes -> CBytes -> CBytes

mconcat :: [CBytes] -> CBytes

NFData CBytes

Defined in Z.Data.CBytes

Methods

rnf :: CBytes -> ()

Hashable CBytes

Defined in Z.Data.CBytes

Methods

hashWithSalt :: Int -> CBytes -> Int

hash :: CBytes -> Int

create

Arguments

:: HasCallStack

=> Int

capacity n, including the NUL terminator

-> (CString -> IO Int)

initialize function write the pointer, return the length (<= n-1)

-> IO CBytes

Create a CBytes with IO action.

User only have to do content initialization and return the content length, create takes the responsibility to add the NUL ternimator. If the initialize function write NUL terminator(most FFI functions for example), you should use allocCBytes.

If (<=0) capacity is provided, a nullPtr is passed to initialize function and empty will be returned. other than that, if length returned is larger than (capacity-1), a NULLTerminatorNotFound will be thrown.

pack :: String -> CBytes

Pack a String into null-terminated CBytes.

NUL is encoded as two bytes C0 80 , 'xD800' ~ 'xDFFF' is encoded as a three bytes normal UTF-8 codepoint.

unpack :: CBytes -> String

null :: CBytes -> Bool

length :: CBytes -> Int

empty :: CBytes

empty CBytes

Passing empty to C FFI is equivalent to passing a NULL pointer.

append :: CBytes -> CBytes -> CBytes

concat :: [CBytes] -> CBytes

intercalate :: CBytes -> [CBytes] -> CBytes

O(n) The intercalate function takes a CBytes and a list of CBytes s and concatenates the list after interspersing the first argument between each element of the list.

Note: intercalate will force the entire CBytes list.

intercalateElem :: Word8 -> [CBytes] -> CBytes

O(n) An efficient way to join CByte s with a byte.

toBytes :: CBytes -> Bytes

O(1), (O(n) in case of literal), convert to Bytes, which can be processed by vector combinators.

NOTE: the NUL ternimator is not included.

fromBytes :: Bytes -> CBytes

O(n), convert from Bytes, allocate pinned memory and add the NUL ternimator

toText :: CBytes -> Text

O(n), convert to Text using UTF8 encoding assumption.

Throw InvalidUTF8Exception in case of invalid codepoint.

toTextMaybe :: CBytes -> Maybe Text

O(n), convert to Text using UTF8 encoding assumption.

Return Nothing in case of invalid codepoint.

fromText :: Text -> CBytes

O(n), convert from Text, allocate pinned memory and add the NUL ternimator

fromCString :: CString -> IO CBytes

Copy a CString type into a CBytes, return empty if the pointer is NULL.

After copying you're free to free the CString 's memory.

fromCString' :: HasCallStack => CString -> IO (Maybe CBytes)

Same with fromCString, but throw NullPointerException when meet a null pointer.

fromCStringN :: CString -> Int -> IO CBytes

Same with fromCString, but only take N bytes (and append a null byte as terminator).

withCBytes :: CBytes -> (CString -> IO a) -> IO a

Pass CBytes to foreign function as a const char*.

Don't pass a forever loop to this function, see #14346.

allocCBytes

Arguments

:: HasCallStack

=> Int

capacity n, including the NUL terminator

-> (CString -> IO a)

initialization function,

-> IO (CBytes, a)

Create a CBytes with IO action.

If (<=0) capacity is provided, a nullPtr is passed to initialize function and empty will be returned. Other than that, User have to make sure a NUL ternimated string will be written, otherwise a NULLTerminatorNotFound will be thrown.

w2c :: Word8 -> Char

Conversion between Word8 and Char. Should compile to a no-op.

c2w :: Char -> Word8

Unsafe conversion between Char and Word8. This is a no-op and silently truncates to 8 bits Chars > '255'. It is provided as convenience for PrimVector construction.

exception

data NullPointerException

Constructors

NullPointerException CallStack

Instances

Show NullPointerException

Defined in Z.Data.CBytes

Methods

showsPrec :: Int -> NullPointerException -> ShowS

show :: NullPointerException -> String

showList :: [NullPointerException] -> ShowS

Exception NullPointerException

Defined in Z.Data.CBytes

Methods

toException :: NullPointerException -> SomeException

fromException :: SomeException -> Maybe NullPointerException

displayException :: NullPointerException -> String

type CString = Ptr CChar

A C string is a reference to an array of C characters terminated by NUL.