stdio-0.1.0.0: A simple and high performance IO toolkit for Haskell

Copyright(c) Dong Han 2017-2018
LicenseBSD
Maintainerwinterland1989@gmail.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Std.Data.CBytes

Description

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.

Synopsis

Documentation

data CBytes Source #

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

Instances
Eq CBytes Source # 
Instance details

Defined in Std.Data.CBytes

Methods

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

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

Ord CBytes Source # 
Instance details

Defined in Std.Data.CBytes

Read CBytes Source # 
Instance details

Defined in Std.Data.CBytes

Show CBytes Source # 
Instance details

Defined in Std.Data.CBytes

IsString CBytes Source # 
Instance details

Defined in Std.Data.CBytes

Methods

fromString :: String -> CBytes #

Semigroup CBytes Source # 
Instance details

Defined in Std.Data.CBytes

Monoid CBytes Source # 
Instance details

Defined in Std.Data.CBytes

Hashable CBytes Source # 
Instance details

Defined in Std.Data.CBytes

Methods

hashWithSalt :: Int -> CBytes -> Int

hash :: CBytes -> Int

create Source #

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 Source #

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.

toBytes :: CBytes -> Bytes Source #

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 Source #

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

fromText :: Text -> CBytes Source #

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

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

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 Source #

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

fromCStringN :: HasCallStack => CString -> Int -> IO CBytes Source #

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

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

Pass CBytes to foreign function as a const char*.

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