-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Memory-efficient representation of Unicode text strings
--   
--   This package provides the <a>ShortText</a> type which is suitable for
--   keeping many short strings in memory. This is similiar to how
--   <a>ShortByteString</a> relates to <a>ByteString</a>.
--   
--   The main difference between <a>Text</a> and <a>ShortText</a> is that
--   <a>ShortText</a> uses UTF-8 instead of UTF-16 internally and also
--   doesn't support slicing (thereby saving 2 words). Consequently, the
--   memory footprint of a (boxed) <a>ShortText</a> value is 4 words (2
--   words when unboxed) plus the length of the UTF-8 encoded payload.
@package text-short
@version 0.1


-- | Memory-efficient representation of Unicode text strings.
module Data.Text.Short

-- | A compact representation of Unicode strings.
--   
--   This type relates to <a>Text</a> as <a>ShortByteString</a> relates to
--   <a>ByteString</a> by providing a more compact type. Please consult the
--   documentation of <a>Data.ByteString.Short</a> for more information.
--   
--   Currently, a boxed unshared <a>Text</a> has a memory footprint of 6
--   words (i.e. 48 bytes on 64-bit systems) plus 2 or 4 bytes per
--   code-point (due to the internal UTF-16 representation). Each
--   <a>Text</a> value which can share its payload with another <a>Text</a>
--   requires only 4 words additionally. Unlike <a>ByteString</a>,
--   <a>Text</a> use unpinned memory.
--   
--   In comparison, the footprint of a boxed <a>ShortText</a> is only 4
--   words (i.e. 32 bytes on 64-bit systems) plus 1<i>2</i>3/4 bytes per
--   code-point (due to the internal UTF-8 representation). It can be shown
--   that for realistic data <a>UTF-16 has a space overhead of 50% over
--   UTF-8</a>.
data ShortText

-- | <i>O(1)</i> Test whether a <a>ShortText</a> is empty.
null :: ShortText -> Bool

-- | <i>O(n)</i> Count the number of Unicode code-points in a
--   <a>ShortText</a>.
length :: ShortText -> Int

-- | <i>O(n)</i> Test whether <a>ShortText</a> contains only ASCII
--   code-points (i.e. only U+0000 through U+007F).
isAscii :: ShortText -> Bool

-- | <i>O(n)</i> Construct/pack from <a>String</a>
--   
--   Note: This function is total because it replaces the (invalid)
--   code-points U+D800 through U+DFFF with the replacement character
--   U+FFFD.
fromString :: String -> ShortText

-- | <i>O(n)</i> Convert to <a>String</a>
toString :: ShortText -> String

-- | <i>O(n)</i> Construct <a>ShortText</a> from <a>Text</a>
--   
--   This is currently not <i>O(1)</i> because currently <a>Text</a> uses
--   UTF-16 as its internal representation. In the event that <a>Text</a>
--   will change its internal representation to UTF-8 this operation will
--   become <i>O(1)</i>.
fromText :: Text -> ShortText

-- | <i>O(n)</i> Convert to <a>Text</a>
--   
--   This is currently not <i>O(1)</i> because currently <a>Text</a> uses
--   UTF-16 as its internal representation. In the event that <a>Text</a>
--   will change its internal representation to UTF-8 this operation will
--   become <i>O(1)</i>.
toText :: ShortText -> Text

-- | <i>O(n)</i> Construct <a>ShortText</a> from UTF-8 encoded
--   <a>ShortByteString</a>
--   
--   This operation doesn't copy the input <a>ShortByteString</a> but it
--   cannot be <i>O(1)</i> because we need to validate the UTF-8 encoding.
--   
--   Returns <a>Nothing</a> in case of invalid UTF-8 encoding.
fromShortByteString :: ShortByteString -> Maybe ShortText

-- | <i>O(0)</i> Converts to UTF-8 encoded <a>ShortByteString</a>
--   
--   This operation has effectively no overhead, as it's currently merely a
--   <tt>newtype</tt>-cast.
toShortByteString :: ShortText -> ShortByteString

-- | <i>O(n)</i> Construct <a>ShortText</a> from UTF-8 encoded
--   <a>ByteString</a>
--   
--   Returns <a>Nothing</a> in case of invalid UTF-8 encoding.
fromByteString :: ByteString -> Maybe ShortText

-- | <i>O(n)</i> Converts to UTF-8 encoded <a>ByteString</a>
toByteString :: ShortText -> ByteString

-- | Construct a <a>Builder</a> that encodes <a>ShortText</a> as UTF-8.
toBuilder :: ShortText -> Builder
instance Control.DeepSeq.NFData Data.Text.Short.ShortText
instance Data.Hashable.Class.Hashable Data.Text.Short.ShortText
instance Data.Semigroup.Semigroup Data.Text.Short.ShortText
instance GHC.Base.Monoid Data.Text.Short.ShortText
instance GHC.Classes.Ord Data.Text.Short.ShortText
instance GHC.Classes.Eq Data.Text.Short.ShortText
instance GHC.Show.Show Data.Text.Short.ShortText
instance GHC.Read.Read Data.Text.Short.ShortText
instance Data.String.IsString Data.Text.Short.ShortText
instance Data.Binary.Class.Binary Data.Text.Short.ShortText
