| Copyright | (c) Duncan Coutts 2012-2013 | 
|---|---|
| License | BSD-style | 
| Maintainer | duncan@community.haskell.org | 
| Stability | stable | 
| Portability | ghc only | 
| Safe Haskell | Trustworthy | 
| Language | Haskell98 | 
Data.ByteString.Short
Description
A compact representation suitable for storing short byte strings in memory.
In typical use cases it can be imported alongside Data.ByteString, e.g.
import qualified Data.ByteString       as B
import qualified Data.ByteString.Short as B
         (ShortByteString, toShort, fromShort)Other ShortByteString operations clash with Data.ByteString or Prelude
 functions however, so they should be imported qualified with a different
 alias e.g.
import qualified Data.ByteString.Short as B.Short
Synopsis
- data ShortByteString
- toShort :: ByteString -> ShortByteString
- fromShort :: ShortByteString -> ByteString
- pack :: [Word8] -> ShortByteString
- unpack :: ShortByteString -> [Word8]
- empty :: ShortByteString
- null :: ShortByteString -> Bool
- length :: ShortByteString -> Int
- index :: ShortByteString -> Int -> Word8
- 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
data ShortByteString #
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.
Instances
Memory overhead
With GHC, the memory overheads are as follows, expressed in words and in bytes (words are 4 and 8 bytes on 32 or 64bit machines respectively).
- ByteStringunshared: 9 words; 36 or 72 bytes.
- ByteStringshared substring: 5 words; 20 or 40 bytes.
- ShortByteString: 4 words; 16 or 32 bytes.
For the string data itself, both ShortByteString and ByteString use
 one byte per element, rounded up to the nearest word. For example,
 including the overheads, a length 10 ShortByteString would take
 16 + 12 = 28 bytes on a 32bit platform and 32 + 16 = 48 bytes on a
 64bit platform.
These overheads can all be reduced by 1 word (4 or 8 bytes) when the
 ShortByteString or ByteString is unpacked into another constructor.
For example:
data ThingId = ThingId {-# UNPACK #-} !Int
                       {-# UNPACK #-} !ShortByteStringThis will take 1 + 1 + 3 words (the ThingId constructor +
 unpacked Int + unpacked ShortByteString), plus the words for the
 string data.
Heap fragmentation
With GHC, the ByteString representation uses pinned memory,
 meaning it cannot be moved by the GC. This is usually the right thing to
 do for larger strings, but for small strings using pinned memory can
 lead to heap fragmentation which wastes space. The ShortByteString
 type (and the Text type from the text package) use unpinned memory
 so they do not contribute to heap fragmentation. In addition, with GHC,
 small unpinned strings are allocated in the same way as normal heap
 allocations, rather than in a separate pinned area.
Conversions
toShort :: ByteString -> ShortByteString #
O(n). Convert a ByteString into a ShortByteString.
This makes a copy, so does not retain the input string.
fromShort :: ShortByteString -> ByteString #
O(n). Convert a ShortByteString into a ByteString.
pack :: [Word8] -> ShortByteString #
O(n). Convert a list into a ShortByteString
unpack :: ShortByteString -> [Word8] #
O(n). Convert a ShortByteString into a list.
Other operations
O(1). The empty ShortByteString.
null :: ShortByteString -> Bool #
O(1) Test whether a ShortByteString is empty.
length :: ShortByteString -> Int #
O(1) The length of a ShortByteString.
index :: ShortByteString -> Int -> Word8 #
O(1) ShortByteString index (subscript) operator, starting from 0.
Low level conversions
Packing CStrings and pointers
packCString :: CString -> IO ShortByteString #
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 #
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 CStrings
useAsCString :: ShortByteString -> (CString -> IO a) -> IO a #
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 #
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