Z.Data.CBytes

• - This module provide CBytes with some useful instances / tools for retrieving, storing or processing
• - short byte sequences, such as file path, environment variables, etc.

Documentation

data CBytes where

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

The main use case 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.

CBytes don't support O(1) slicing, it's not suitable to use it to store large byte chunk, If you need advance editing, convert CBytes to / from PrimArray with CB, or Bytes with 'toBytes\/fromBytes' if you need O(1) slicing, then use vector combinators.

When textual represatation is needed(conver to String, Text, Show instance, etc.), we assume CBytes using UTF-8 encodings, CBytes can be used with OverloadedString, literal encoding is UTF-8 with some modifications: NUL is encoded to 'C0 80', and '\xD800' ~ '\xDFFF' is encoded as a three bytes normal utf-8 codepoint.

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 when text represatation is needed. --

Bundled Patterns

pattern CB :: PrimArray Word8 -> CBytes

Use this pattern to match or construct CBytes, result will be trimmed down to first byte before NUL byte if there's any.

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

Arbitrary CBytes

Defined in Z.Data.CBytes

Methods

arbitrary :: Gen CBytes

shrink :: CBytes -> [CBytes]

CoArbitrary CBytes

Defined in Z.Data.CBytes

Methods

coarbitrary :: CBytes -> Gen b -> Gen b

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

Unaligned CBytes

This instance peek bytes until NUL(or input chunk ends), poke bytes with an extra NUL terminator.

Defined in Z.Data.CBytes

Methods

unalignedSize :: CBytes -> Int

indexWord8ArrayAs# :: ByteArray# -> Int# -> CBytes

readWord8ArrayAs# :: MutableByteArray# s -> Int# -> State# s -> (#State# s, CBytes#)

writeWord8ArrayAs# :: MutableByteArray# s -> Int# -> CBytes -> State# s -> State# s

peekMBA :: MutableByteArray# RealWorld -> Int -> IO CBytes

pokeMBA :: MutableByteArray# RealWorld -> Int -> CBytes -> IO ()

indexBA :: ByteArray# -> Int -> CBytes

ShowT CBytes

This instance provide UTF8 guarantee, illegal codepoints will be written as replacementChars.

Defined in Z.Data.CBytes

Methods

toTextBuilder :: Int -> CBytes -> TextBuilder ()

toPrimArray :: CBytes -> PrimArray Word8

Convert to PrimArray,

there's an invariance that this array never contains NUL

pack :: String -> CBytes

Pack a String into CBytes.

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

unpack :: CBytes -> String

O(n) Convert cbytes to a char list using UTF8 encoding assumption.

This function is much tolerant than toText, it simply decoding codepoints using UTF8 decodeChar without checking errors such as overlong or invalid range.

Unpacking is done lazily. i.e. we will retain reference to the array until all element are consumed.

This function is a good producer in the sense of build/foldr fusion.

null :: CBytes -> Bool

Return True if CBytes is empty.

length :: CBytes -> Int

Return the BTYE length of CBytes.

empty :: CBytes

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

Intercalate bytes list with NUL will effectively leave the first bytes in the list.

toBytes :: CBytes -> Bytes

O(1), convert to Bytes, which can be processed by vector combinators.

fromBytes :: Bytes -> CBytes

O(n), convert from Bytes

Result will be trimmed down to first byte before NUL byte if there's any.

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,

Result will be trimmed down to first byte before NUL byte if there's any.

toBuilder :: CBytes -> Builder ()

Write CBytes 's byte sequence to buffer.

This function is different from ShowT instance in that it directly write byte sequence without checking if it's UTF8 encoded.

buildCBytes :: Builder a -> CBytes

Build a CBytes with builder, result will be trimmed down to first byte before NUL byte if there's any.

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.

fromCStringN :: CString -> Int -> IO CBytes

Same with fromCString, but only take at most N bytes.

Result will be trimmed down to first byte before NUL byte if there's any.

withCBytesUnsafe :: CBytes -> (BA# Word8 -> IO a) -> IO a

Pass CBytes to foreign function as a const char*.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

withCBytes :: CBytes -> (Ptr Word8 -> IO a) -> IO a

Pass CBytes to foreign function as a const char*.

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

allocCBytesUnsafe

Arguments

:: HasCallStack

=> Int

capacity n(include the NUL terminator)

-> (MBA# Word8 -> IO a)

initialization function,

-> IO (CBytes, a)

Create a CBytes with IO action.

If (<=0) capacity is provided, a pointer pointing to NUL is passed to initialize function and empty will be returned. This behavior is different from allocCBytes, which may cause trouble for some FFI functions.

USE THIS FUNCTION WITH UNSAFE FFI CALL ONLY.

allocCBytes

Arguments

:: HasCallStack

=> Int

capacity n(include 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.

type CString = Ptr CChar

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

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.

w2c :: Word8 -> Char

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