-- 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> doesn't support zero-copy slicing (thereby saving 2
--   words), and, compared to text-1.*, that it uses UTF-8 instead of
--   UTF-16 internally. 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.6.1


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


-- | Memory-efficient representation of Unicode text strings.
--   
--   This module is intended to be imported <tt>qualified</tt>, to avoid
--   name clashes with <a>Prelude</a> functions, e.g.
--   
--   <pre>
--   import qualified Data.Text.Short as TS
--   import qualified Data.Text.Short (ShortText)
--   </pre>
--   
--   This modules deliberately omits (common) partial functions, which can
--   be found in <a>Data.Text.Short.Partial</a> instead.
module Data.Text.Short

-- | A compact representation of Unicode strings.
--   
--   A <a>ShortText</a> value is a sequence of Unicode scalar values, as
--   defined in <a>§3.9, definition D76 of the Unicode 5.2 standard</a>;
--   This means that a <a>ShortText</a> is a list of (scalar) Unicode
--   code-points (i.e. code-points in the range <tt>[U+00 .. U+D7FF] ∪
--   [U+E000 .. U+10FFFF]</tt>).
--   
--   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 1, 2, 3 or 4 bytes per
--   code-point for text-2 (due to the internal UTF-8 representation) or 2
--   or 4 bytes per code-point for text-1 (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, 2, 3, or 4 bytes per
--   code-point (due to the internal UTF-8 representation).
--   
--   It can be shown that for realistic data <a>UTF-16, which is used by
--   text-1, has a space overhead of 50% over UTF-8</a>.
--   
--   <b>NOTE</b>: The <a>Typeable</a> instance isn't defined for GHC 7.8
--   (and older) prior to <tt>text-short-0.1.3</tt>
data ShortText

-- | &lt;math&gt; The <i>empty</i> <a>ShortText</a>.
--   
--   This is a type-specialised alias of <a>mempty</a>.
--   
--   <pre>
--   &gt;&gt;&gt; empty
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; null empty
--   True
--   </pre>
empty :: ShortText

-- | &lt;math&gt; Construct <a>ShortText</a> from single codepoint.
--   
--   <pre>
--   singleton c == pack [c]
--   </pre>
--   
--   <pre>
--   length (singleton c) == 1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; singleton 'A'
--   "A"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map singleton ['\55295','\55296','\57343','\57344'] -- U+D7FF U+D800 U+DFFF U+E000
--   ["\55295","\65533","\65533","\57344"]
--   </pre>
--   
--   <b>Note</b>: This function is total because it replaces the (invalid)
--   code-points U+D800 through U+DFFF with the replacement character
--   U+FFFD.
singleton :: Char -> ShortText

-- | &lt;math&gt; Construct a <a>ShortText</a> from a list of <a>Char</a>s.
--   
--   This is an alias for <a>fromString</a>.
pack :: [Char] -> ShortText

-- | &lt;math&gt; Concatenate two <a>ShortText</a>s
--   
--   This is a type-specialised alias of <a>&lt;&gt;</a>.
--   
--   <pre>
--   &gt;&gt;&gt; append "foo" "bar"
--   "foobar"
--   </pre>
--   
--   <pre>
--   length (append t1 t2) == length t1 + length t2
--   </pre>
append :: ShortText -> ShortText -> ShortText

-- | &lt;math&gt; Concatenate list of <a>ShortText</a>s
--   
--   This is a type-specialised alias of <a>mconcat</a>.
--   
--   <pre>
--   &gt;&gt;&gt; concat []
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; concat ["foo","bar","doo"]
--   "foobardoo"
--   </pre>
concat :: [ShortText] -> ShortText

-- | &lt;math&gt; Prepend a character to a <a>ShortText</a>.
--   
--   <pre>
--   cons c t == singleton c &lt;&gt; t
--   </pre>
cons :: Char -> ShortText -> ShortText

-- | &lt;math&gt; Append a character to the ond of a <a>ShortText</a>.
--   
--   <pre>
--   snoc t c == t &lt;&gt; singleton c
--   </pre>
snoc :: ShortText -> Char -> ShortText

-- | &lt;math&gt; Replicate a <a>ShortText</a>.
--   
--   A repetition count smaller than 1 results in an empty string result.
--   
--   <pre>
--   &gt;&gt;&gt; replicate 3 "jobs!"
--   "jobs!jobs!jobs!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; replicate 10000 ""
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; replicate 0 "nothing"
--   ""
--   </pre>
--   
--   <pre>
--   length (replicate n t) == max 0 n * length t
--   </pre>
replicate :: Int -> ShortText -> ShortText

-- | &lt;math&gt; Convert <a>ShortText</a> into a list of <a>Char</a>s.
--   
--   This is an alias for <a>toString</a>.
--   
--   <pre>
--   (pack . unpack) t == t
--   </pre>
unpack :: ShortText -> [Char]

-- | &lt;math&gt; Inverse operation to <a>cons</a>
--   
--   Returns <a>Nothing</a> for empty input <a>ShortText</a>.
--   
--   <pre>
--   uncons (cons c t) == Just (c,t)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncons ""
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncons "fmap"
--   Just ('f',"map")
--   </pre>
uncons :: ShortText -> Maybe (Char, ShortText)

-- | &lt;math&gt; Inverse operation to <a>snoc</a>
--   
--   Returns <a>Nothing</a> for empty input <a>ShortText</a>.
--   
--   <pre>
--   unsnoc (snoc t c) == Just (t,c)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; unsnoc ""
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; unsnoc "fmap"
--   Just ("fma",'p')
--   </pre>
unsnoc :: ShortText -> Maybe (ShortText, Char)

-- | &lt;math&gt; Test whether a <a>ShortText</a> is empty.
--   
--   <pre>
--   &gt;&gt;&gt; null ""
--   True
--   </pre>
--   
--   <pre>
--   null (singleton c) == False
--   </pre>
--   
--   <pre>
--   null t == (length t == 0)
--   </pre>
null :: ShortText -> Bool

-- | &lt;math&gt; Count the number of Unicode code-points in a
--   <a>ShortText</a>.
--   
--   <pre>
--   &gt;&gt;&gt; length "abcd€"
--   5
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; length ""
--   0
--   </pre>
--   
--   <pre>
--   length t &gt;= 0
--   </pre>
length :: ShortText -> Int

-- | &lt;math&gt; Test whether <a>ShortText</a> contains only ASCII
--   code-points (i.e. only U+0000 through U+007F).
--   
--   This is a more efficient version of <tt><a>all</a>
--   <a>isAscii</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; isAscii ""
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isAscii "abc\NUL"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isAscii "abcd€"
--   False
--   </pre>
--   
--   <pre>
--   isAscii t == all (&lt; '\x80') t
--   </pre>
isAscii :: ShortText -> Bool

-- | &lt;math&gt; Test whether <i>all</i> code points in <a>ShortText</a>
--   satisfy a predicate.
--   
--   <pre>
--   &gt;&gt;&gt; all (const False) ""
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; all (&gt; 'c') "abcdabcd"
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; all (/= 'c') "abdabd"
--   True
--   </pre>
all :: (Char -> Bool) -> ShortText -> Bool

-- | &lt;math&gt; Test whether <i>any</i> code points in <a>ShortText</a>
--   satisfy a predicate.
--   
--   <pre>
--   &gt;&gt;&gt; any (&gt; 'c') "abcdabcd"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; any (const True) ""
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; any (== 'c') "abdabd"
--   False
--   </pre>
--   
--   <pre>
--   any p t == not (all (not . p) t)
--   </pre>
any :: (Char -> Bool) -> ShortText -> Bool

-- | &lt;math&gt; Return the left-most codepoint in <a>ShortText</a> that
--   satisfies the given predicate.
--   
--   <pre>
--   &gt;&gt;&gt; find (&gt; 'b') "abcdabcd"
--   Just 'c'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; find (&gt; 'b') "ababab"
--   Nothing
--   </pre>
find :: (Char -> Bool) -> ShortText -> Maybe Char

-- | &lt;math&gt; Tests whether the first <a>ShortText</a> is a prefix of
--   the second <a>ShortText</a>
--   
--   <pre>
--   &gt;&gt;&gt; isPrefixOf "ab" "abcdef"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isPrefixOf "ac" "abcdef"
--   False
--   </pre>
--   
--   <pre>
--   isPrefixOf "" t == True
--   </pre>
--   
--   <pre>
--   isPrefixOf t t == True
--   </pre>
isPrefixOf :: ShortText -> ShortText -> Bool

-- | &lt;math&gt; Tests whether the first <a>ShortText</a> is a suffix of
--   the second <a>ShortText</a>
--   
--   <pre>
--   &gt;&gt;&gt; isSuffixOf "ef" "abcdef"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isPrefixOf "df" "abcdef"
--   False
--   </pre>
--   
--   <pre>
--   isSuffixOf "" t == True
--   </pre>
--   
--   <pre>
--   isSuffixOf t t == True
--   </pre>
isSuffixOf :: ShortText -> ShortText -> Bool

-- | &lt;math&gt; Index <i>i</i>-th code-point in <a>ShortText</a>.
--   
--   Infix operator alias of <a>indexMaybe</a>
--   
--   <pre>
--   &gt;&gt;&gt; "abcdefg" !? 2
--   Just 'c'
--   </pre>
(!?) :: ShortText -> Int -> Maybe Char

-- | &lt;math&gt; Lookup <i>i</i>-th code-point in <a>ShortText</a>.
--   
--   Returns <a>Nothing</a> if out of bounds.
--   
--   <pre>
--   indexMaybe (singleton c) 0 == Just c
--   </pre>
--   
--   <pre>
--   indexMaybe t 0 == fmap fst (uncons t)
--   </pre>
--   
--   <pre>
--   indexMaybe mempty i == Nothing
--   </pre>
indexMaybe :: ShortText -> Int -> Maybe Char

-- | &lt;math&gt; Lookup <i>i</i>-th code-point from the end of
--   <a>ShortText</a>.
--   
--   Returns <a>Nothing</a> if out of bounds.
--   
--   <pre>
--   indexEndMaybe (singleton c) 0 == Just c
--   </pre>
--   
--   <pre>
--   indexEndMaybe t 0 == fmap snd (unsnoc t)
--   </pre>
--   
--   <pre>
--   indexEndMaybe mempty i == Nothing
--   </pre>
indexEndMaybe :: ShortText -> Int -> Maybe Char

-- | &lt;math&gt; Return the index of the left-most codepoint in
--   <a>ShortText</a> that satisfies the given predicate.
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 'b') "abcdabcdef"
--   Just 2
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; findIndex (&gt; 'b') "ababab"
--   Nothing
--   </pre>
--   
--   <pre>
--   (indexMaybe t =&lt;&lt; findIndex p t) == find p t
--   </pre>
findIndex :: (Char -> Bool) -> ShortText -> Maybe Int

-- | &lt;math&gt; Take prefix of given length or return whole
--   <a>ShortText</a> if too short.
--   
--   <pre>
--   &gt;&gt;&gt; take 3 "abcdef"
--   "abc"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take 3 "ab"
--   "ab"
--   </pre>
take :: Int -> ShortText -> ShortText

-- | &lt;math&gt; Take suffix of given length or return whole
--   <a>ShortText</a> if too short.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "ab"
--   "ab"
--   </pre>
takeEnd :: Int -> ShortText -> ShortText

-- | &lt;math&gt; Take remove prefix of given length from <a>ShortText</a>
--   or return <a>empty</a> <a>ShortText</a> if too short.
--   
--   <pre>
--   &gt;&gt;&gt; drop 4 "abcdef"
--   "ef"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; drop 4 "ab"
--   ""
--   </pre>
drop :: Int -> ShortText -> ShortText

-- | &lt;math&gt; Take remove suffix of given length from <a>ShortText</a>
--   or return <a>empty</a> <a>ShortText</a> if too short.
--   
--   <pre>
--   &gt;&gt;&gt; drop 4 "abcdefghi"
--   "efghi"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; drop 4 "ab"
--   ""
--   </pre>
dropEnd :: Int -> ShortText -> ShortText

-- | &lt;math&gt; Take longest prefix satisfying given predicate.
--   
--   <pre>
--   takeWhile p t == fst (span p t)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; takeWhile (&lt; 'c') "abcdabcd"
--   "ab"
--   </pre>
takeWhile :: (Char -> Bool) -> ShortText -> ShortText

-- | &lt;math&gt; Take longest suffix satisfying given predicate.
--   
--   <pre>
--   takeWhileEnd p t == snd (spanEnd p t)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; takeWhileEnd (&gt;= 'c') "abcdabcd"
--   "cd"
--   </pre>
takeWhileEnd :: (Char -> Bool) -> ShortText -> ShortText

-- | &lt;math&gt; Remove longest prefix satisfying given predicate.
--   
--   <pre>
--   dropWhile p t == snd (span p t)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; dropWhile (&lt; 'c') "abcdabcd"
--   "cdabcd"
--   </pre>
dropWhile :: (Char -> Bool) -> ShortText -> ShortText

-- | &lt;math&gt; Remove longest suffix satisfying given predicate.
--   
--   <pre>
--   dropWhileEnd p t == fst (spanEnd p t)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; dropWhileEnd (&gt;= 'c') "abcdabcd"
--   "abcdab"
--   </pre>
dropWhileEnd :: (Char -> Bool) -> ShortText -> ShortText

-- | &lt;math&gt; Strip characters from the beginning end and of
--   <a>ShortText</a> which satisfy given predicate.
--   
--   <pre>
--   &gt;&gt;&gt; dropAround (== ' ') "   white   space   "
--   "white   space"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; dropAround (&gt; 'a') "bcdefghi"
--   ""
--   </pre>
dropAround :: (Char -> Bool) -> ShortText -> ShortText

-- | &lt;math&gt; Split <a>ShortText</a> into two halves.
--   
--   <tt><a>splitAt</a> n t</tt> returns a pair of <a>ShortText</a> with
--   the following properties:
--   
--   <pre>
--   length (fst (splitAt n t)) == min (length t) (max 0 n)
--   </pre>
--   
--   <pre>
--   fst (splitAt n t) &lt;&gt; snd (splitAt n t) == t
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; splitAt 2 "abcdef"
--   ("ab","cdef")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; splitAt 10 "abcdef"
--   ("abcdef","")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; splitAt (-1) "abcdef"
--   ("","abcdef")
--   </pre>
splitAt :: Int -> ShortText -> (ShortText, ShortText)

-- | &lt;math&gt; Split <a>ShortText</a> into two halves.
--   
--   <tt><a>splitAtEnd</a> n t</tt> returns a pair of <a>ShortText</a> with
--   the following properties:
--   
--   <pre>
--   length (snd (splitAtEnd n t)) == min (length t) (max 0 n)
--   </pre>
--   
--   <pre>
--   fst (splitAtEnd n t) &lt;&gt; snd (splitAtEnd n t) == t
--   </pre>
--   
--   <pre>
--   splitAtEnd n t == splitAt (length t - n) t
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; splitAtEnd 2 "abcdef"
--   ("abcd","ef")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; splitAtEnd 10 "abcdef"
--   ("","abcdef")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; splitAtEnd (-1) "abcdef"
--   ("abcdef","")
--   </pre>
splitAtEnd :: Int -> ShortText -> (ShortText, ShortText)

-- | &lt;math&gt; Split <a>ShortText</a> into longest prefix satisfying the
--   given predicate and the remaining suffix.
--   
--   <pre>
--   &gt;&gt;&gt; span (&lt; 'c') "abcdabcd"
--   ("ab","cdabcd")
--   </pre>
--   
--   <pre>
--   fst (span p t) &lt;&gt; snd (span p t) == t
--   </pre>
span :: (Char -> Bool) -> ShortText -> (ShortText, ShortText)

-- | &lt;math&gt; Variant of <a>span</a> with negated predicate.
--   
--   <pre>
--   &gt;&gt;&gt; break (&gt; 'c') "abcdabcd"
--   ("abc","dabcd")
--   </pre>
--   
--   <pre>
--   break p t == span (not . p) t
--   </pre>
--   
--   <pre>
--   fst (break p t) &lt;&gt; snd (break p t) == t
--   </pre>
break :: (Char -> Bool) -> ShortText -> (ShortText, ShortText)

-- | &lt;math&gt; Split <a>ShortText</a> into longest suffix satisfying the
--   given predicate and the preceding prefix.
--   
--   <pre>
--   &gt;&gt;&gt; spanEnd (&gt; 'c') "abcdabcd"
--   ("abcdabc","d")
--   </pre>
--   
--   <pre>
--   fst (spanEnd p t) &lt;&gt; snd (spanEnd p t) == t
--   </pre>
spanEnd :: (Char -> Bool) -> ShortText -> (ShortText, ShortText)

-- | &lt;math&gt; Variant of <a>spanEnd</a> with negated predicate.
--   
--   <pre>
--   &gt;&gt;&gt; breakEnd (&lt; 'c') "abcdabcd"
--   ("abcdab","cd")
--   </pre>
--   
--   <pre>
--   breakEnd p t == spanEnd (not . p) t
--   </pre>
--   
--   <pre>
--   fst (breakEnd p t) &lt;&gt; snd (breakEnd p t) == t
--   </pre>
breakEnd :: (Char -> Bool) -> ShortText -> (ShortText, ShortText)

-- | &lt;math&gt; Splits a string into components delimited by separators,
--   where the predicate returns True for a separator element. The
--   resulting components do not contain the separators. Two adjacent
--   separators result in an empty component in the output. eg.
--   
--   <pre>
--   &gt;&gt;&gt; split (=='a') "aabbaca"
--   ["","","bb","c",""]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; split (=='a') ""
--   [""]
--   </pre>
--   
--   <pre>
--   intercalate (singleton c) (split (== c) t) = t
--   </pre>
--   
--   <b>NOTE</b>: <a>split</a> never returns an empty list to match the
--   semantics of its counterpart from <a>Data.Text</a>.
split :: (Char -> Bool) -> ShortText -> [ShortText]

-- | &lt;math&gt; Strip prefix from second <a>ShortText</a> argument.
--   
--   Returns <a>Nothing</a> if first argument is not a prefix of the second
--   argument.
--   
--   <pre>
--   &gt;&gt;&gt; stripPrefix "text-" "text-short"
--   Just "short"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stripPrefix "test-" "text-short"
--   Nothing
--   </pre>
stripPrefix :: ShortText -> ShortText -> Maybe ShortText

-- | &lt;math&gt; Strip suffix from second <a>ShortText</a> argument.
--   
--   Returns <a>Nothing</a> if first argument is not a suffix of the second
--   argument.
--   
--   <pre>
--   &gt;&gt;&gt; stripSuffix "-short" "text-short"
--   Just "text"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; stripSuffix "-utf8" "text-short"
--   Nothing
--   </pre>
stripSuffix :: ShortText -> ShortText -> Maybe ShortText

-- | &lt;math&gt; Insert character between characters of <a>ShortText</a>.
--   
--   <pre>
--   &gt;&gt;&gt; intersperse '*' "_"
--   "_"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; intersperse '*' "MASH"
--   "M*A*S*H"
--   </pre>
intersperse :: Char -> ShortText -> ShortText

-- | &lt;math&gt; Insert <a>ShortText</a> inbetween list of
--   <a>ShortText</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " []
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " ["foo"]
--   "foo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " ["foo","bar","doo"]
--   "foo, bar, doo"
--   </pre>
--   
--   <pre>
--   intercalate "" ts == concat ts
--   </pre>
intercalate :: ShortText -> [ShortText] -> ShortText

-- | &lt;math&gt; Reverse characters in <a>ShortText</a>.
--   
--   <pre>
--   &gt;&gt;&gt; reverse "star live desserts"
--   "stressed evil rats"
--   </pre>
--   
--   <pre>
--   reverse (singleton c) == singleton c
--   </pre>
--   
--   <pre>
--   reverse (reverse t) == t
--   </pre>
reverse :: ShortText -> ShortText

-- | &lt;math&gt; Remove characters from <a>ShortText</a> which don't
--   satisfy given predicate.
--   
--   <pre>
--   &gt;&gt;&gt; filter (`notElem` ['a','e','i','o','u']) "You don't need vowels to convey information!"
--   "Y dn't nd vwls t cnvy nfrmtn!"
--   </pre>
--   
--   <pre>
--   filter (const False) t == ""
--   </pre>
--   
--   <pre>
--   filter (const True) t == t
--   </pre>
--   
--   <pre>
--   length (filter p t) &lt;= length t
--   </pre>
--   
--   <pre>
--   filter p t == pack [ c | c &lt;- unpack t, p c ]
--   </pre>
filter :: (Char -> Bool) -> ShortText -> ShortText

-- | &lt;math&gt; Reduces the characters of the <a>ShortText</a> with the
--   binary operator and an initial in forward direction (i.e. from left to
--   right).
--   
--   <pre>
--   &gt;&gt;&gt; foldl (\_ _ -&gt; True) False ""
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl (\s c -&gt; c : s) ['.'] "abcd"
--   "dcba."
--   </pre>
foldl :: (a -> Char -> a) -> a -> ShortText -> a

-- | &lt;math&gt; Strict version of <a>foldl</a>.
foldl' :: (a -> Char -> a) -> a -> ShortText -> a

-- | &lt;math&gt; Reduces the characters of the <a>ShortText</a> with the
--   binary operator and an initial in reverse direction (i.e. from right
--   to left).
--   
--   <pre>
--   &gt;&gt;&gt; foldr (\_ _ -&gt; True) False ""
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr (:) ['.'] "abcd"
--   "abcd."
--   </pre>
foldr :: (Char -> a -> a) -> a -> ShortText -> a

-- | &lt;math&gt; Construct/pack from <a>String</a>
--   
--   <pre>
--   &gt;&gt;&gt; fromString []
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromString ['a','b','c']
--   "abc"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromString ['\55295','\55296','\57343','\57344'] -- U+D7FF U+D800 U+DFFF U+E000
--   "\55295\65533\65533\57344"
--   </pre>
--   
--   <b>Note</b>: 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>
--   
--   <pre>
--   (fromString . toString) t == t
--   </pre>
--   
--   <b>Note</b>: See documentation of <a>fromString</a> for why
--   <tt>(<a>toString</a> . <a>fromString</a>)</tt> is not an identity
--   function.
toString :: ShortText -> String

-- | &lt;math&gt; Construct <a>ShortText</a> from <a>Text</a>
--   
--   This is &lt;math&gt; with <tt>text-2</tt> when the <a>Text</a> is not
--   sliced. Previously it wasn't because <a>Text</a> used UTF-16 as its
--   internal representation.
fromText :: Text -> ShortText

-- | &lt;math&gt; Convert to <a>Text</a>
--   
--   <pre>
--   (fromText . toText) t == t
--   </pre>
--   
--   <pre>
--   (toText . fromText) t == t
--   </pre>
--   
--   This is &lt;math&gt; with <tt>text-2</tt>. Previously it wasn't
--   because <a>Text</a> used UTF-16 as its internal representation.
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.
--   
--   <pre>
--   &gt;&gt;&gt; fromShortByteString "\x00\x38\xF0\x90\x8C\x9A" -- U+00 U+38 U+1031A
--   Just "\NUL8\66330"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromShortByteString "\xC0\x80" -- invalid denormalised U+00
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromShortByteString "\xED\xA0\x80" -- U+D800 (non-scalar code-point)
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromShortByteString "\xF4\x8f\xbf\xbf" -- U+10FFFF
--   Just "\1114111"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromShortByteString "\xF4\x90\x80\x80" -- U+110000 (invalid)
--   Nothing
--   </pre>
--   
--   <pre>
--   fromShortByteString (toShortByteString t) == Just t
--   </pre>
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>
--   
--   <a>fromByteString</a> accepts (or rejects) the same input data as
--   <a>fromShortByteString</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


-- | Partial functions vocabulary
--   
--   This module provides common partial functions for operating on
--   <a>ShortText</a>.
--   
--   The use of these functions is discouraged as they tend to be
--   error-prone.
module Data.Text.Short.Partial

-- | &lt;math&gt; Returns first character of a non-empty <a>ShortText</a>
--   
--   <pre>
--   &gt;&gt;&gt; head "abcd"
--   'a'
--   </pre>
--   
--   <b>Note</b>: Will throw an <a>error</a> exception for empty
--   <a>ShortText</a>s. Consider using the total functions <a>uncons</a> or
--   <a>indexMaybe</a> instead.
head :: ShortText -> Char

-- | &lt;math&gt; Drop first character from non-empty <a>ShortText</a>.
--   
--   <pre>
--   &gt;&gt;&gt; tail "abcd"
--   "bcd"
--   </pre>
--   
--   <b>Note</b>: Will throw an <a>error</a> exception for empty
--   <a>ShortText</a>s. Consider using the total functions <a>uncons</a> or
--   <a>drop</a> instead.
tail :: ShortText -> ShortText

-- | &lt;math&gt; Drop last character from non-empty <a>ShortText</a>.
--   
--   <pre>
--   &gt;&gt;&gt; tail "abcd"
--   "bcd"
--   </pre>
--   
--   <b>Note</b>: Will throw an <a>error</a> exception for empty
--   <a>ShortText</a>s. Consider using the total functions <a>unsnoc</a> or
--   <a>dropEnd</a> instead.
init :: ShortText -> ShortText

-- | &lt;math&gt; Return last character from non-empty <a>ShortText</a>.
--   
--   <pre>
--   &gt;&gt;&gt; last "abcd"
--   'd'
--   </pre>
--   
--   <b>Note</b>: Will throw an <a>error</a> exception for empty
--   <a>ShortText</a>s. Consider using the total functions <a>unsnoc</a> or
--   <a>indexEndMaybe</a> instead.
last :: ShortText -> Char

-- | &lt;math&gt; Retrieve &lt;math&gt;-th character (code-point)
--   
--   <pre>
--   &gt;&gt;&gt; index "abcd" 1
--   'b'
--   </pre>
--   
--   <b>Note</b>: Will throw an <a>error</a> exception if index is out of
--   bounds. Consider using the total functions <a>indexMaybe</a> or
--   <a>indexEndMaybe</a> instead.
index :: ShortText -> Int -> Char

-- | &lt;math&gt; Reduces the characters of the <a>ShortText</a> with the
--   binary operator.
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 max "abcdcba"
--   'd'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 const "abcd"
--   'a'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (flip const) "abcd"
--   'd'
--   </pre>
--   
--   <b>Note</b>: Will throw an <a>error</a> exception if index is out of
--   bounds.
foldl1 :: (Char -> Char -> Char) -> ShortText -> Char

-- | &lt;math&gt; Strict version of <a>foldl1</a>.
foldl1' :: (Char -> Char -> Char) -> ShortText -> Char

-- | &lt;math&gt; Reduces the characters of the <a>ShortText</a> with the
--   binary operator.
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 max "abcdcba"
--   'd'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 const "abcd"
--   'a'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (flip const) "abcd"
--   'd'
--   </pre>
--   
--   <b>Note</b>: Will throw an <a>error</a> exception if index is out of
--   bounds.
foldr1 :: (Char -> Char -> Char) -> ShortText -> Char
