1 {-# LANGUAGE CPP #-}
    2 #if __GLASGOW_HASKELL__ >= 701
    3 {-# LANGUAGE Trustworthy #-}
    4 #endif
    5 
    6 -- |
    7 -- Module      : Data.ByteString.Short
    8 -- Copyright   : (c) Duncan Coutts 2012-2013
    9 -- License     : BSD-style
   10 --
   11 -- Maintainer  : duncan@community.haskell.org
   12 -- Stability   : stable
   13 -- Portability : ghc only
   14 -- 
   15 -- A compact representation suitable for storing short byte strings in memory.
   16 --
   17 -- In typical use cases it can be imported alongside "Data.ByteString", e.g.
   18 --
   19 -- > import qualified Data.ByteString       as B
   20 -- > import qualified Data.ByteString.Short as B
   21 -- >          (ShortByteString, toShort, fromShort)
   22 --
   23 -- Other 'ShortByteString' operations clash with "Data.ByteString" or "Prelude"
   24 -- functions however, so they should be imported @qualified@ with a different
   25 -- alias e.g.
   26 --
   27 -- > import qualified Data.ByteString.Short as B.Short
   28 --
   29 module Data.ByteString.Short (
   30 
   31     -- * The @ShortByteString@ type
   32 
   33     ShortByteString,
   34 
   35     -- ** Memory overhead
   36     -- | With GHC, the memory overheads are as follows, expressed in words and
   37     -- in bytes (words are 4 and 8 bytes on 32 or 64bit machines respectively).
   38     --
   39     -- * 'ByteString' unshared: 9 words; 36 or 72 bytes.
   40     --
   41     -- * 'ByteString' shared substring: 5 words; 20 or 40 bytes.
   42     --
   43     -- * 'ShortByteString': 4 words; 16 or 32 bytes.
   44     --
   45     -- For the string data itself, both 'ShortByteString' and 'ByteString' use
   46     -- one byte per element, rounded up to the nearest word. For example,
   47     -- including the overheads, a length 10 'ShortByteString' would take
   48     -- @16 + 12 = 28@ bytes on a 32bit platform and @32 + 16 = 48@ bytes on a
   49     -- 64bit platform.
   50     --
   51     -- These overheads can all be reduced by 1 word (4 or 8 bytes) when the
   52     -- 'ShortByteString' or 'ByteString' is unpacked into another constructor.
   53     --
   54     -- For example:
   55     --
   56     -- > data ThingId = ThingId {-# UNPACK #-} !Int
   57     -- >                        {-# UNPACK #-} !ShortByteString
   58     --
   59     -- This will take @1 + 1 + 3@ words (the @ThingId@ constructor +
   60     -- unpacked @Int@ + unpacked @ShortByteString@), plus the words for the
   61     -- string data.
   62     
   63     -- ** Heap fragmentation
   64     -- | With GHC, the 'ByteString' representation uses /pinned/ memory,
   65     -- meaning it cannot be moved by the GC. This is usually the right thing to
   66     -- do for larger strings, but for small strings using pinned memory can
   67     -- lead to heap fragmentation which wastes space. The 'ShortByteString'
   68     -- type (and the @Text@ type from the @text@ package) use /unpinned/ memory
   69     -- so they do not contribute to heap fragmentation. In addition, with GHC,
   70     -- small unpinned strings are allocated in the same way as normal heap
   71     -- allocations, rather than in a separate pinned area.
   72 
   73     -- * Conversions
   74     toShort,
   75     fromShort,
   76     pack,
   77     unpack,
   78 
   79     -- * Other operations
   80     empty, null, length, index,
   81   ) where
   82 
   83 import Data.ByteString.Short.Internal
   84 import Prelude ()
   85