Std.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 Std.Data.CBytes

Methods

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

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

Ord CBytes

Defined in Std.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 Std.Data.CBytes

Methods

readsPrec :: Int -> ReadS CBytes

readList :: ReadS [CBytes]

readPrec :: ReadPrec CBytes

readListPrec :: ReadPrec [CBytes]

Show CBytes

Defined in Std.Data.CBytes

Methods

showsPrec :: Int -> CBytes -> ShowS

show :: CBytes -> String

showList :: [CBytes] -> ShowS

IsString CBytes

Defined in Std.Data.CBytes

Methods

fromString :: String -> CBytes

Semigroup CBytes

Defined in Std.Data.CBytes

Methods

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

sconcat :: NonEmpty CBytes -> CBytes

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

Monoid CBytes

Defined in Std.Data.CBytes

Methods

mempty :: CBytes

mappend :: CBytes -> CBytes -> CBytes

mconcat :: [CBytes] -> CBytes

NFData CBytes

Defined in Std.Data.CBytes

Methods

rnf :: CBytes -> ()

Hashable CBytes

Defined in Std.Data.CBytes

Methods

hashWithSalt :: Int -> CBytes -> Int

hash :: CBytes -> Int

LEON CBytes

Defined in Std.Data.LEON

Methods

encode :: CBytes -> Builder ()

decode :: Parser CBytes

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

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

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