Data.ByteString.Short.Internal

bytestring-0.10.12.1: Fast, compact, strict and lazy byte strings with a list interface

Copyright | (c) Duncan Coutts 2012-2013
License | BSD-style
Maintainer | duncan@community.haskell.org
Stability | stable
Portability | ghc only
Safe Haskell | Unsafe
Language | Haskell98

Data.ByteString.Short.Internal

Contents

- The `ShortByteString` type and representation
- Conversions
- Other operations
- Low level operations
- Low level conversions
  - Packing `CString`s and pointers
  - Using ByteStrings as `CString`s

Description

Internal representation of ShortByteString

Synopsis

- data ShortByteString = SBS ByteArray#
- toShort :: ByteString -> ShortByteString
- fromShort :: ShortByteString -> ByteString
- pack :: [Word8] -> ShortByteString
- unpack :: ShortByteString -> [Word8]
- empty :: ShortByteString
- null :: ShortByteString -> Bool
- length :: ShortByteString -> Int
- index :: ShortByteString -> Int -> Word8
- unsafeIndex :: ShortByteString -> Int -> Word8
- createFromPtr :: Ptr a -> Int -> IO ShortByteString
- copyToPtr :: ShortByteString -> Int -> Ptr a -> Int -> IO ()
- packCString :: CString -> IO ShortByteString
- packCStringLen :: CStringLen -> IO ShortByteString
- useAsCString :: ShortByteString -> (CString -> IO a) -> IO a
- useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a

# The `ShortByteString` type and representation

data ShortByteString Source #

A compact representation of a `Word8` vector.

It has a lower memory overhead than a `ByteString` and does not contribute to heap fragmentation. It can be converted to or from a `ByteString` (at the cost of copying the string data). It supports very few other operations.

It is suitable for use as an internal representation for code that needs to keep many short strings in memory, but it should not be used as an interchange type. That is, it should not generally be used in public APIs. The `ByteString` type is usually more suitable for use in interfaces; it is more flexible and it supports a wide range of operations.

Constructors

SBS ByteArray# |

#### Instances

Instances details

IsList ShortByteString # | Since: bytestring-0.10.12.0
Instance details Defined in Data.ByteString.Short.Internal Associated Types type Item ShortByteString Source # Methods fromList :: [Item ShortByteString] -> ShortByteString Source # fromListN :: Int -> [Item ShortByteString] -> ShortByteString Source # toList :: ShortByteString -> [Item ShortByteString] Source #
Eq ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods (==) :: ShortByteString -> ShortByteString -> Bool Source # (/=) :: ShortByteString -> ShortByteString -> Bool Source #
Data ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ShortByteString -> c ShortByteString Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ShortByteString Source # toConstr :: ShortByteString -> Constr Source # dataTypeOf :: ShortByteString -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ShortByteString) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ShortByteString) Source # gmapT :: (forall b. Data b => b -> b) -> ShortByteString -> ShortByteString Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ShortByteString -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ShortByteString -> r Source # gmapQ :: (forall d. Data d => d -> u) -> ShortByteString -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> ShortByteString -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> ShortByteString -> m ShortByteString Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ShortByteString -> m ShortByteString Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ShortByteString -> m ShortByteString Source #
Ord ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods compare :: ShortByteString -> ShortByteString -> Ordering Source # (<) :: ShortByteString -> ShortByteString -> Bool Source # (<=) :: ShortByteString -> ShortByteString -> Bool Source # (>) :: ShortByteString -> ShortByteString -> Bool Source # (>=) :: ShortByteString -> ShortByteString -> Bool Source # max :: ShortByteString -> ShortByteString -> ShortByteString Source # min :: ShortByteString -> ShortByteString -> ShortByteString Source #
Read ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods readsPrec :: Int -> ReadS ShortByteString Source # readList :: ReadS [ShortByteString] Source # readPrec :: ReadPrec ShortByteString Source # readListPrec :: ReadPrec [ShortByteString] Source #
Show ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods showsPrec :: Int -> ShortByteString -> ShowS Source # show :: ShortByteString -> String Source # showList :: [ShortByteString] -> ShowS Source #
IsString ShortByteString # | Beware: `fromString` truncates multi-byte characters to octets. e.g. "枯朶に烏のとまりけり秋の暮" becomes �6k�nh~�Q��n�
Instance details Defined in Data.ByteString.Short.Internal Methods fromString :: String -> ShortByteString Source #
Semigroup ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods (<>) :: ShortByteString -> ShortByteString -> ShortByteString Source # sconcat :: NonEmpty ShortByteString -> ShortByteString Source # stimes :: Integral b => b -> ShortByteString -> ShortByteString Source #
Monoid ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods mempty :: ShortByteString Source # mappend :: ShortByteString -> ShortByteString -> ShortByteString Source # mconcat :: [ShortByteString] -> ShortByteString Source #
NFData ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal Methods rnf :: ShortByteString -> () Source #
type Item ShortByteString # |
Instance details Defined in Data.ByteString.Short.Internal type Item ShortByteString = Word8

# Conversions

toShort :: ByteString -> ShortByteString Source #

O(n). Convert a `ByteString` into a `ShortByteString`.

This makes a copy, so does not retain the input string.

fromShort :: ShortByteString -> ByteString Source #

O(n). Convert a `ShortByteString` into a `ByteString`.

pack :: [Word8] -> ShortByteString Source #

O(n). Convert a list into a `ShortByteString`

unpack :: ShortByteString -> [Word8] Source #

O(n). Convert a `ShortByteString` into a list.

# Other operations

empty :: ShortByteString Source #

O(1). The empty `ShortByteString`.

null :: ShortByteString -> Bool Source #

O(1) Test whether a `ShortByteString` is empty.

length :: ShortByteString -> Int Source #

O(1) The length of a `ShortByteString`.

index :: ShortByteString -> Int -> Word8 Source #

O(1) `ShortByteString` index (subscript) operator, starting from 0.

unsafeIndex :: ShortByteString -> Int -> Word8 Source #

# Low level operations

createFromPtr Source #

Arguments

:: Ptr a | source data
-> Int | number of bytes to copy
-> IO ShortByteString |

copyToPtr Source #

Arguments

:: ShortByteString | source data
-> Int | offset into source
-> Ptr a | destination
-> Int | number of bytes to copy
-> IO () |

# Low level conversions

## Packing `CString`s and pointers

packCString :: CString -> IO ShortByteString Source #

O(n). Construct a new `ShortByteString` from a `CString`. The resulting `ShortByteString` is an immutable copy of the original `CString`, and is managed on the Haskell heap. The original `CString` must be null terminated.

Since: bytestring-0.10.10.0

packCStringLen :: CStringLen -> IO ShortByteString Source #

O(n). Construct a new `ShortByteString` from a `CStringLen`. The resulting `ShortByteString` is an immutable copy of the original `CStringLen`. The `ShortByteString` is a normal Haskell value and will be managed on the Haskell heap.

Since: bytestring-0.10.10.0

## Using ByteStrings as `CString`s

useAsCString :: ShortByteString -> (CString -> IO a) -> IO a Source #

O(n) construction. Use a `ShortByteString` with a function requiring a null-terminated `CString`. The `CString` is a copy and will be freed automatically; it must not be stored or used after the subcomputation finishes.

Since: bytestring-0.10.10.0

useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a Source #

O(n) construction. Use a `ShortByteString` with a function requiring a `CStringLen`. As for `useAsCString` this function makes a copy of the original `ShortByteString`. It must not be stored or used after the subcomputation finishes.

Since: bytestring-0.10.10.0