Data.ByteString.Short

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

The ShortByteString type

data ShortByteString

A compact representation of a Word8 vector.

It has a lower memory overhead than a ByteString and 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

Eq ShortByteString

Methods

(==) :: ShortByteString -> ShortByteString -> Bool

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

Data ShortByteString

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ShortByteString -> c ShortByteString

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ShortByteString

toConstr :: ShortByteString -> Constr

dataTypeOf :: ShortByteString -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c ShortByteString)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ShortByteString)

gmapT :: (forall b. Data b => b -> b) -> ShortByteString -> ShortByteString

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ShortByteString -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ShortByteString -> r

gmapQ :: (forall d. Data d => d -> u) -> ShortByteString -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> ShortByteString -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> ShortByteString -> m ShortByteString

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ShortByteString -> m ShortByteString

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ShortByteString -> m ShortByteString

Ord ShortByteString

Methods

compare :: ShortByteString -> ShortByteString -> Ordering

(<) :: ShortByteString -> ShortByteString -> Bool

(<=) :: ShortByteString -> ShortByteString -> Bool

(>) :: ShortByteString -> ShortByteString -> Bool

(>=) :: ShortByteString -> ShortByteString -> Bool

max :: ShortByteString -> ShortByteString -> ShortByteString

min :: ShortByteString -> ShortByteString -> ShortByteString

Read ShortByteString

Methods

readsPrec :: Int -> ReadS ShortByteString

readList :: ReadS [ShortByteString]

readPrec :: ReadPrec ShortByteString

readListPrec :: ReadPrec [ShortByteString]

Show ShortByteString

Methods

showsPrec :: Int -> ShortByteString -> ShowS

show :: ShortByteString -> String

showList :: [ShortByteString] -> ShowS

IsString ShortByteString

Methods

fromString :: String -> ShortByteString

Semigroup ShortByteString

Methods

(<>) :: ShortByteString -> ShortByteString -> ShortByteString

sconcat :: NonEmpty ShortByteString -> ShortByteString

stimes :: Integral b => b -> ShortByteString -> ShortByteString

Monoid ShortByteString

Methods

mempty :: ShortByteString

mappend :: ShortByteString -> ShortByteString -> ShortByteString

mconcat :: [ShortByteString] -> ShortByteString

NFData ShortByteString

Methods

rnf :: ShortByteString -> ()

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

• ByteString unshared: 9 words; 36 or 72 bytes.
• ByteString shared 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 #-} !ShortByteString

This 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

empty :: ShortByteString

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.