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

-- | &lt;math&gt; Test whether a <a>ShortText</a> is empty.
null :: ShortText -> Bool

-- | &lt;math&gt; Count the number of Unicode code-points in a
--   <a>ShortText</a>.
length :: ShortText -> Int

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

-- | &lt;math&gt; 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

-- | &lt;math&gt; Convert to <a>String</a>
toString :: ShortText -> String

-- | &lt;math&gt; Construct <a>ShortText</a> from <a>Text</a>
--   
--   This is currently not &lt;math&gt; 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 &lt;math&gt;.
fromText :: Text -> ShortText

-- | &lt;math&gt; Convert to <a>Text</a>
--   
--   This is currently not &lt;math&gt; 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 &lt;math&gt;.
toText :: ShortText -> Text

-- | &lt;math&gt; 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 &lt;math&gt; because we need to validate the UTF-8 encoding.
--   
--   Returns <a>Nothing</a> in case of invalid UTF-8 encoding.
fromShortByteString :: ShortByteString -> Maybe ShortText

-- | &lt;math&gt; 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

-- | &lt;math&gt; 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

-- | &lt;math&gt; 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


-- | Unsafe API
--   
--   This module provides unsafe conversion functions
module Data.Text.Short.Unsafe

-- | &lt;math&gt; Construct <a>ShortText</a> from UTF-8 encoded
--   <a>ShortByteString</a>
--   
--   This operation has effectively no overhead, as it's currently merely a
--   <tt>newtype</tt>-cast.
--   
--   <b>WARNING</b>: Unlike the safe <a>fromShortByteString</a> conversion,
--   this conversion is <i>unsafe</i> as it doesn't validate the
--   well-formedness of the UTF-8 encoding.
fromShortByteStringUnsafe :: ShortByteString -> ShortText

-- | &lt;math&gt; Construct <a>ShortText</a> from UTF-8 encoded
--   <a>ByteString</a>
--   
--   This operation is &lt;math&gt; because the <a>ByteString</a> needs to
--   be copied into an unpinned <a>ByteArray#</a>.
--   
--   <b>WARNING</b>: Unlike the safe <a>fromByteString</a> conversion, this
--   conversion is <i>unsafe</i> as it doesn't validate the well-formedness
--   of the UTF-8 encoding.
fromByteStringUnsafe :: ByteString -> ShortText
