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)

initialization 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.

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

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

fromCStringMaybe :: HasCallStack => CString -> IO (Maybe CBytes)

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

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

fromCString :: HasCallStack => CString -> IO CBytes

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

fromCStringN :: HasCallStack => 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.

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