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


-- | Library for manipulating Operating system strings.
--   
--   This package provides functionality for manipulating <tt>OsString</tt>
--   values, and is shipped with <a>GHC</a>.
@package os-string
@version 2.0.2


-- | Internal low-level utilities mostly for <a>Word16</a>, such as
--   byte-array operations and other stuff not meant to be exported from
--   Word16 module.
module System.OsString.Data.ByteString.Short.Internal
_nul :: Word16
isSpace :: Word16 -> Bool

-- | Total conversion to char.
word16ToChar :: Word16 -> Char
create :: Int -> (forall s. () => MBA s -> ST s ()) -> ShortByteString
asBA :: ShortByteString -> BA
data BA
BA# :: ByteArray# -> BA
data MBA s
MBA# :: MutableByteArray# s -> MBA s
newPinnedByteArray :: Int -> ST s (MBA s)
newByteArray :: Int -> ST s (MBA s)
copyByteArray :: BA -> Int -> MBA s -> Int -> Int -> ST s ()
unsafeFreezeByteArray :: MBA s -> ST s BA
copyAddrToByteArray :: Ptr a -> MBA RealWorld -> Int -> Int -> ST RealWorld ()

-- | <i>O(n).</i> Construct a new <tt>ShortByteString</tt> from a
--   <tt>CWString</tt>. The resulting <tt>ShortByteString</tt> is an
--   immutable copy of the original <tt>CWString</tt>, and is managed on
--   the Haskell heap. The original <tt>CWString</tt> must be null
--   terminated.
packCWString :: Ptr Word16 -> IO ShortByteString

-- | <i>O(n).</i> Construct a new <tt>ShortByteString</tt> from a
--   <tt>CWStringLen</tt>. The resulting <tt>ShortByteString</tt> is an
--   immutable copy of the original <tt>CWStringLen</tt>. The
--   <tt>ShortByteString</tt> is a normal Haskell value and will be managed
--   on the Haskell heap.
packCWStringLen :: (Ptr Word16, Int) -> IO ShortByteString

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a null-terminated <tt>CWString</tt>. The
--   <tt>CWString</tt> is a copy and will be freed automatically; it must
--   not be stored or used after the subcomputation finishes.
useAsCWString :: ShortByteString -> (Ptr Word16 -> IO a) -> IO a

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a <tt>CWStringLen</tt>. As for
--   <tt>useAsCWString</tt> this function makes a copy of the original
--   <tt>ShortByteString</tt>. It must not be stored or used after the
--   subcomputation finishes.
useAsCWStringLen :: ShortByteString -> ((Ptr Word16, Int) -> IO a) -> IO a

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a <tt>CWStringLen</tt>. As for
--   <tt>useAsCWString</tt> this function makes a copy of the original
--   <tt>ShortByteString</tt>. It must not be stored or used after the
--   subcomputation finishes.
newCWString :: ShortByteString -> IO (Ptr Word16)
moduleErrorIO :: String -> String -> IO a
moduleErrorMsg :: String -> String -> String
packWord16 :: [Word16] -> ShortByteString
packLenWord16 :: Int -> [Word16] -> ShortByteString
unpackWord16 :: ShortByteString -> [Word16]
packWord16Rev :: [Word16] -> ShortByteString
packLenWord16Rev :: Int -> [Word16] -> ShortByteString

-- | Encode Word16 as little-endian.
writeWord16Array :: MBA s -> Int -> Word16 -> ST s ()
indexWord8Array :: BA -> Int -> Word8

-- | Decode Word16 from little-endian.
indexWord16Array :: BA -> Int -> Word16
word16ToLE# :: Word16# -> Word16#
word16FromLE# :: Word16# -> Word16#
setByteArray :: MBA s -> Int -> Int -> Int -> ST s ()
copyMutableByteArray :: MBA s -> Int -> MBA s -> Int -> Int -> ST s ()

-- | Given the maximum size needed and a function to make the contents of a
--   ShortByteString, createAndTrim makes the <a>ShortByteString</a>. The
--   generating function is required to return the actual final size (&lt;=
--   the maximum size) and the result value. The resulting byte array is
--   realloced to this size.
createAndTrim :: Int -> (forall s. () => MBA s -> ST s (Int, a)) -> (ShortByteString, a)
createAndTrim' :: Int -> (forall s. () => MBA s -> ST s Int) -> ShortByteString
createAndTrim'' :: Int -> (forall s. () => MBA s -> MBA s -> ST s (Int, Int)) -> (ShortByteString, ShortByteString)
findIndexOrLength :: (Word16 -> Bool) -> ShortByteString -> Int

-- | Returns the length of the substring matching, not the index. If no
--   match, returns 0.
findFromEndUntil :: (Word16 -> Bool) -> ShortByteString -> Int
assertEven :: ShortByteString -> ShortByteString
errorEmptySBS :: HasCallStack => String -> a
moduleError :: HasCallStack => String -> String -> a
compareByteArraysOff :: BA -> Int -> BA -> Int -> Int -> Int


-- | A compact representation suitable for storing short byte strings in
--   memory.
--   
--   In typical use cases it can be imported alongside
--   <a>Data.ByteString</a>, e.g.
--   
--   <pre>
--   import qualified Data.ByteString       as B
--   import qualified Data.ByteString.Short as B
--            (ShortByteString, toShort, fromShort)
--   </pre>
--   
--   Other <a>ShortByteString</a> operations clash with
--   <a>Data.ByteString</a> or <a>Prelude</a> functions however, so they
--   should be imported <tt>qualified</tt> with a different alias e.g.
--   
--   <pre>
--   import qualified Data.ByteString.Short as B.Short
--   </pre>
module System.OsString.Data.ByteString.Short

-- | A compact representation of a <a>Word8</a> vector.
--   
--   It has a lower memory overhead than a <a>ByteString</a> and does not
--   contribute to heap fragmentation. It can be converted to or from a
--   <a>ByteString</a> (at the cost of copying the string data). It
--   supports very few other operations.
newtype ShortByteString

ShortByteString :: ByteArray -> ShortByteString

[unShortByteString] :: ShortByteString -> ByteArray

-- | Prior to <tt>bytestring-0.12</tt> <a>SBS</a> was a genuine constructor
--   of <a>ShortByteString</a>, but now it is a bundled pattern synonym,
--   provided as a compatibility shim.
pattern SBS :: ByteArray# -> ShortByteString

-- | <i>O(1)</i>. The empty <a>ShortByteString</a>.
empty :: ShortByteString

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ShortByteString</a>
singleton :: Word8 -> ShortByteString

-- | <i>O(n)</i>. Convert a list into a <a>ShortByteString</a>
pack :: [Word8] -> ShortByteString

-- | <i>O(n)</i>. Convert a <a>ShortByteString</a> into a list.
unpack :: ShortByteString -> [Word8]

-- | <i>O(n)</i>. Convert a <a>ShortByteString</a> into a
--   <a>ByteString</a>.
fromShort :: ShortByteString -> ByteString

-- | <i>O(n)</i>. Convert a <a>ByteString</a> into a
--   <a>ShortByteString</a>.
--   
--   This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString

-- | <i>O(n)</i> Append a byte to the end of a <a>ShortByteString</a>
--   
--   Note: copies the entire byte array
snoc :: ShortByteString -> Word8 -> ShortByteString
infixl 5 `snoc`

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
--   
--   Note: copies the entire byte array
cons :: Word8 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString

-- | <i>O(1)</i> Extract the last element of a ShortByteString, which must
--   be finite and non-empty. An exception will be thrown in the case of an
--   empty ShortByteString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
last :: HasCallStack => ShortByteString -> Word8

-- | <i>O(n)</i> Extract the elements after the head of a ShortByteString,
--   which must be non-empty. An exception will be thrown in the case of an
--   empty ShortByteString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
--   
--   Note: copies the entire byte array
tail :: HasCallStack => ShortByteString -> ShortByteString

-- | <i>O(n)</i> Extract the <a>head</a> and <a>tail</a> of a
--   ShortByteString, returning <a>Nothing</a> if it is empty.
uncons :: ShortByteString -> Maybe (Word8, ShortByteString)
uncons2 :: ShortByteString -> Maybe (Word8, Word8, ShortByteString)

-- | <i>O(1)</i> Extract the first element of a ShortByteString, which must
--   be non-empty. An exception will be thrown in the case of an empty
--   ShortByteString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
head :: HasCallStack => ShortByteString -> Word8

-- | <i>O(n)</i> Return all the elements of a <a>ShortByteString</a> except
--   the last one. An exception will be thrown in the case of an empty
--   ShortByteString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
--   
--   Note: copies the entire byte array
init :: HasCallStack => ShortByteString -> ShortByteString

-- | <i>O(n)</i> Extract the <a>init</a> and <a>last</a> of a
--   ShortByteString, returning <a>Nothing</a> if it is empty.
unsnoc :: ShortByteString -> Maybe (ShortByteString, Word8)

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

-- | <i>O(1)</i> The length of a <a>ShortByteString</a>.
length :: ShortByteString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ShortByteString obtained
--   by applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word8 -> Word8) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: ShortByteString -> ShortByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a
--   <a>ShortByteString</a> and a list of <a>ShortByteString</a>s and
--   concatenates the list after interspersing the first argument between
--   each element of the list.
intercalate :: ShortByteString -> [ShortByteString] -> ShortByteString

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ShortByteString,
--   reduces the ShortByteString using the binary operator, from left to
--   right.
foldl :: (a -> Word8 -> a) -> a -> ShortByteString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ShortByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s. An exception will be thrown in the case of an
--   empty ShortByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a ShortByteString,
--   reduces the ShortByteString using the binary operator, from right to
--   left.
foldr :: (Word8 -> a -> a) -> a -> ShortByteString -> a

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ShortByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s An exception will be thrown in the case of an
--   empty ShortByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8

-- | <i>O(n)</i> Applied to a predicate and a <a>ShortByteString</a>,
--   <a>all</a> determines if all elements of the <a>ShortByteString</a>
--   satisfy the predicate.
all :: (Word8 -> Bool) -> ShortByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>ShortByteString</a>,
--   <a>any</a> determines if any element of the <a>ShortByteString</a>
--   satisfies the predicate.
any :: (Word8 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ShortByteString of
--   length <tt>n</tt> with <tt>x</tt> the value of every element. The
--   following holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> Word8 -> ShortByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ShortByteString from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ShortByteString or returns <a>Just</a> <tt>(a,b)</tt>,
--   in which case, <tt>a</tt> is the next byte in the string, and
--   <tt>b</tt> is the seed value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word8]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <a>ShortByteString</a>.
--   
--   If you know the maximum length, consider using <a>unfoldrN</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ShortByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a
--   ShortByteString from a seed value. However, the length of the result
--   is limited by the first argument to <a>unfoldrN</a>. This function is
--   more efficient than <a>unfoldr</a> when the maximum length of the
--   result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ShortByteString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a ShortByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <a>empty</a> if <tt>n &gt;
--   <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
--   
--   Note: copies the entire byte array
dropWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) sbs
--      ==
--   let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--   </pre>
spanEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n sbs</tt> is equivalent to
--   <tt>(<a>take</a> n sbs, <a>drop</a> n sbs)</tt>.
--   
--   Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> Break a <a>ShortByteString</a> into pieces separated by
--   the byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   Note: copies the substrings
split :: Word8 -> ShortByteString -> [ShortByteString]

-- | <i>O(n)</i> Splits a <a>ShortByteString</a> 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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith undefined ""     == []                  -- and not [""]
--   </pre>
splitWith :: (Word8 -> Bool) -> ShortByteString -> [ShortByteString]

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its suffix, and otherwise <a>Nothing</a>.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its prefix, and otherwise <a>Nothing</a>.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: ShortByteString -> ShortByteString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: ShortByteString -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> <a>elem</a> is the <a>ShortByteString</a> membership
--   predicate.
elem :: Word8 -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ShortByteString, and returns the first element in matching the
--   predicate, or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word8 -> Bool) -> ShortByteString -> Maybe Word8

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a
--   ShortByteString, returns a ShortByteString containing those characters
--   that satisfy the predicate.
filter :: (Word8 -> Bool) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a
--   ShortByteString and returns the pair of ShortByteStrings with elements
--   which do and do not satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p sbs, filter (not . p) sbs)
--   </pre>
partition :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(1)</i> <a>ShortByteString</a> index (subscript) operator,
--   starting from 0.
--   
--   This is a partial function, consider using <a>indexMaybe</a> instead.
index :: HasCallStack => ShortByteString -> Int -> Word8

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ShortByteString -> Int -> Maybe Word8

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ShortByteString -> Int -> Maybe Word8

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ShortByteString</a> which is equal to
--   the query element, or <a>Nothing</a> if there is no such element.
elemIndex :: Word8 -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: Word8 -> ShortByteString -> [Int]

-- | count returns the number of times its argument appears in the
--   ShortByteString
count :: Word8 -> ShortByteString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <a>ShortByteString</a> and returns the index of the first element in
--   the ShortByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (Word8 -> Bool) -> ShortByteString -> [Int]

-- | <i>O(n).</i> Construct a new <tt>ShortByteString</tt> from a
--   <tt>CString</tt>. The resulting <tt>ShortByteString</tt> is an
--   immutable copy of the original <tt>CString</tt>, and is managed on the
--   Haskell heap. The original <tt>CString</tt> must be null terminated.
packCString :: CString -> IO ShortByteString

-- | <i>O(n).</i> Construct a new <tt>ShortByteString</tt> from a
--   <tt>CStringLen</tt>. The resulting <tt>ShortByteString</tt> is an
--   immutable copy of the original <tt>CStringLen</tt>. The
--   <tt>ShortByteString</tt> is a normal Haskell value and will be managed
--   on the Haskell heap.
packCStringLen :: CStringLen -> IO ShortByteString

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a null-terminated <tt>CString</tt>. The
--   <tt>CString</tt> is a copy and will be freed automatically; it must
--   not be stored or used after the subcomputation finishes.
useAsCString :: ShortByteString -> (CString -> IO a) -> IO a

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a <a>CStringLen</a>. As for <a>useAsCString</a>
--   this function makes a copy of the original <tt>ShortByteString</tt>.
--   It must not be stored or used after the subcomputation finishes.
--   
--   Beware that this function does not add a terminating <tt>NUL</tt> byte
--   at the end of <a>CStringLen</a>. If you need to construct a pointer to
--   a null-terminated sequence, use <a>useAsCString</a> (and measure
--   length independently if desired).
useAsCStringLen :: ShortByteString -> (CStringLen -> IO a) -> IO a


-- | ShortByteStrings encoded as UTF16-LE, suitable for windows FFI calls.
--   
--   Word16s are *always* in BE encoding (both input and output), so e.g.
--   <a>pack</a> takes a list of BE encoded <tt>[Word16]</tt> and produces
--   a UTF16-LE encoded ShortByteString.
--   
--   Likewise, <a>unpack</a> takes a UTF16-LE encoded ShortByteString and
--   produces a list of BE encoded <tt>[Word16]</tt>.
--   
--   Indices and lengths are always in respect to Word16, not Word8.
--   
--   All functions will error out if the input string is not a valid UTF16
--   stream (uneven number of bytes). So use this module with caution.
module System.OsString.Data.ByteString.Short.Word16

-- | A compact representation of a <a>Word8</a> vector.
--   
--   It has a lower memory overhead than a <a>ByteString</a> and does not
--   contribute to heap fragmentation. It can be converted to or from a
--   <a>ByteString</a> (at the cost of copying the string data). It
--   supports very few other operations.
newtype ShortByteString

ShortByteString :: ByteArray -> ShortByteString

[unShortByteString] :: ShortByteString -> ByteArray

-- | Prior to <tt>bytestring-0.12</tt> <a>SBS</a> was a genuine constructor
--   of <a>ShortByteString</a>, but now it is a bundled pattern synonym,
--   provided as a compatibility shim.
pattern SBS :: ByteArray# -> ShortByteString

-- | <i>O(1)</i>. The empty <a>ShortByteString</a>.
empty :: ShortByteString

-- | <i>O(1)</i> Convert a <a>Word16</a> into a <a>ShortByteString</a>
singleton :: Word16 -> ShortByteString

-- | <i>O(n)</i>. Convert a list into a <a>ShortByteString</a>
pack :: [Word16] -> ShortByteString

-- | <i>O(n)</i>. Convert a <a>ShortByteString</a> into a list.
unpack :: ShortByteString -> [Word16]

-- | <i>O(n)</i>. Convert a <a>ShortByteString</a> into a
--   <a>ByteString</a>.
fromShort :: ShortByteString -> ByteString

-- | <i>O(n)</i>. Convert a <a>ByteString</a> into a
--   <a>ShortByteString</a>.
--   
--   This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString

-- | <i>O(n)</i> Append a Word16 to the end of a <a>ShortByteString</a>
--   
--   Note: copies the entire byte array
snoc :: ShortByteString -> Word16 -> ShortByteString
infixl 5 `snoc`

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
--   
--   Note: copies the entire byte array
cons :: Word16 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString

-- | <i>O(1)</i> Extract the last element of a ShortByteString, which must
--   be finite and at least one Word16. An exception will be thrown in the
--   case of an empty ShortByteString.
last :: HasCallStack => ShortByteString -> Word16

-- | <i>O(n)</i> Extract the elements after the head of a ShortByteString,
--   which must at least one Word16. An exception will be thrown in the
--   case of an empty ShortByteString.
--   
--   Note: copies the entire byte array
tail :: HasCallStack => ShortByteString -> ShortByteString

-- | <i>O(n)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ShortByteString -> Maybe (Word16, ShortByteString)

-- | <i>O(n)</i> Extract first two elements and the rest of a ByteString,
--   returning Nothing if it is shorter than two elements.
uncons2 :: ShortByteString -> Maybe (Word16, Word16, ShortByteString)

-- | <i>O(1)</i> Extract the first element of a ShortByteString, which must
--   be at least one Word16. An exception will be thrown in the case of an
--   empty ShortByteString.
head :: HasCallStack => ShortByteString -> Word16

-- | <i>O(n)</i> Return all the elements of a <a>ShortByteString</a> except
--   the last one. An exception will be thrown in the case of an empty
--   ShortByteString.
--   
--   Note: copies the entire byte array
init :: HasCallStack => ShortByteString -> ShortByteString

-- | <i>O(n)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
--   returning Nothing if it is empty.
unsnoc :: ShortByteString -> Maybe (ShortByteString, Word16)

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

-- | <i>O(1)</i> The length of a <a>ShortByteString</a>.
length :: ShortByteString -> Int

-- | This is like <a>length</a>, but the number of <a>Word16</a>, not
--   <a>Word8</a>.
numWord16 :: ShortByteString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ShortByteString obtained
--   by applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (Word16 -> Word16) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: ShortByteString -> ShortByteString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a
--   <a>ShortByteString</a> and a list of <a>ShortByteString</a>s and
--   concatenates the list after interspersing the first argument between
--   each element of the list.
intercalate :: ShortByteString -> [ShortByteString] -> ShortByteString

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ShortByteString,
--   reduces the ShortByteString using the binary operator, from left to
--   right.
foldl :: (a -> Word16 -> a) -> a -> ShortByteString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> Word16 -> a) -> a -> ShortByteString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s. An exception will be thrown in the case of an
--   empty ShortByteString.
foldl1 :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a ShortByteString,
--   reduces the ShortByteString using the binary operator, from right to
--   left.
foldr :: (Word16 -> a -> a) -> a -> ShortByteString -> a

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (Word16 -> a -> a) -> a -> ShortByteString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty
--   <a>ShortByteString</a>s An exception will be thrown in the case of an
--   empty ShortByteString.
foldr1 :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16

-- | <i>O(n)</i> Applied to a predicate and a <a>ShortByteString</a>,
--   <a>all</a> determines if all elements of the <a>ShortByteString</a>
--   satisfy the predicate.
all :: (Word16 -> Bool) -> ShortByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <tt>ByteString</tt> satisfies the
--   predicate.
any :: (Word16 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> Word16 -> ShortByteString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ShortByteString from a seed value. The
--   function takes the element and returns <a>Nothing</a> if it is done
--   producing the ShortByteString or returns <a>Just</a> <tt>(a,b)</tt>,
--   in which case, <tt>a</tt> is the next byte in the string, and
--   <tt>b</tt> is the seed value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word16]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <a>ShortByteString</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (Word16, a)) -> a -> ShortByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a
--   ShortByteString from a seed value. However, the length of the result
--   is limited by the first argument to <a>unfoldrN</a>. This function is
--   more efficient than <a>unfoldr</a> when the maximum length of the
--   result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (Word16, a)) -> a -> (ShortByteString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a ShortByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString

-- | <i>O(1)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
--   "e\NULf\NULg\NUL"
--   
--   &gt;&gt;&gt; takeEnd 0 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "a\NULb\NULc\NUL"
--   "a\NULb\NULc\NUL"
--   </pre>
takeEnd :: Int -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (Word16 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (Word16 -> Bool) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <tt>[]</tt> if <tt>n &gt;
--   <a>length</a> xs</tt>.
--   
--   Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString

-- | <i>O(1)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
--   "a\NULb\NULc\NULd\NUL"
--   
--   &gt;&gt;&gt; dropEnd 0 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
--   "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
--   
--   &gt;&gt;&gt; dropEnd 4 "a\NULb\NULc\NUL"
--   ""
--   </pre>
dropEnd :: Int -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
--   
--   Note: copies the entire byte array
dropWhile :: (Word16 -> Bool) -> ShortByteString -> ShortByteString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (Word16 -> Bool) -> ShortByteString -> ShortByteString

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) ps
--      ==
--   let (x, y) = span (not . isSpace) (reverse ps) in (reverse y, reverse x)
--   </pre>
spanEnd :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
--   
--   Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> Break a <a>ShortByteString</a> into pieces separated by
--   the byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   Note: copies the substrings
split :: Word16 -> ShortByteString -> [ShortByteString]

-- | <i>O(n)</i> Splits a <a>ShortByteString</a> 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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith undefined ""     == []                  -- and not [""]
--   </pre>
splitWith :: (Word16 -> Bool) -> ShortByteString -> [ShortByteString]

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its suffix, and otherwise <a>Nothing</a>.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ShortByteStrings
--   and returns <a>Just</a> the remainder of the second iff the first is
--   its prefix, and otherwise <a>Nothing</a>.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString

-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a> iff the first is a prefix of the second.
isPrefixOf :: ShortByteString -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ShortByteStrings
--   and returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: ShortByteString -> ShortByteString -> Bool
breakSubstring :: ShortByteString -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(n)</i> <a>elem</a> is the <a>ShortByteString</a> membership
--   predicate.
elem :: Word16 -> ShortByteString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (Word16 -> Bool) -> ShortByteString -> Maybe Word16

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: (Word16 -> Bool) -> ShortByteString -> ShortByteString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a
--   ByteString and returns the pair of ByteStrings with elements which do
--   and do not satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p xs, filter (not . p) xs)
--   </pre>
partition :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)

-- | <i>O(1)</i> <a>ShortByteString</a> index (subscript) operator,
--   starting from 0.
index :: HasCallStack => ShortByteString -> Int -> Word16

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: ShortByteString -> Int -> Maybe Word16

-- | <i>O(1)</i> <a>ShortByteString</a> index, starting from 0, that
--   returns <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: ShortByteString -> Int -> Maybe Word16

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ShortByteString</a> which is equal to
--   the query element, or <a>Nothing</a> if there is no such element.
elemIndex :: Word16 -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: Word16 -> ShortByteString -> [Int]

-- | count returns the number of times its argument appears in the
--   ShortByteString
count :: Word16 -> ShortByteString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <a>ShortByteString</a> and returns the index of the first element in
--   the ByteString satisfying the predicate.
findIndex :: (Word16 -> Bool) -> ShortByteString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (Word16 -> Bool) -> ShortByteString -> [Int]

-- | <i>O(n).</i> Construct a new <tt>ShortByteString</tt> from a
--   <tt>CWString</tt>. The resulting <tt>ShortByteString</tt> is an
--   immutable copy of the original <tt>CWString</tt>, and is managed on
--   the Haskell heap. The original <tt>CWString</tt> must be null
--   terminated.
packCWString :: Ptr Word16 -> IO ShortByteString

-- | <i>O(n).</i> Construct a new <tt>ShortByteString</tt> from a
--   <tt>CWStringLen</tt>. The resulting <tt>ShortByteString</tt> is an
--   immutable copy of the original <tt>CWStringLen</tt>. The
--   <tt>ShortByteString</tt> is a normal Haskell value and will be managed
--   on the Haskell heap.
packCWStringLen :: (Ptr Word16, Int) -> IO ShortByteString

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a <tt>CWStringLen</tt>. As for
--   <tt>useAsCWString</tt> this function makes a copy of the original
--   <tt>ShortByteString</tt>. It must not be stored or used after the
--   subcomputation finishes.
newCWString :: ShortByteString -> IO (Ptr Word16)

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a null-terminated <tt>CWString</tt>. The
--   <tt>CWString</tt> is a copy and will be freed automatically; it must
--   not be stored or used after the subcomputation finishes.
useAsCWString :: ShortByteString -> (Ptr Word16 -> IO a) -> IO a

-- | <i>O(n) construction.</i> Use a <tt>ShortByteString</tt> with a
--   function requiring a <tt>CWStringLen</tt>. As for
--   <tt>useAsCWString</tt> this function makes a copy of the original
--   <tt>ShortByteString</tt>. It must not be stored or used after the
--   subcomputation finishes.
useAsCWStringLen :: ShortByteString -> ((Ptr Word16, Int) -> IO a) -> IO a

module System.OsString.Encoding.Internal
ucs2le :: TextEncoding
mkUcs2le :: CodingFailureMode -> TextEncoding
ucs2le_DF :: CodingFailureMode -> IO (TextDecoder ())
ucs2le_EF :: CodingFailureMode -> IO (TextEncoder ())
ucs2le_decode :: DecodeBuffer
ucs2le_encode :: EncodeBuffer

-- | Mimics the base encoding for filesystem operations. This should be
--   total on all inputs (word16 byte arrays).
--   
--   Note that this has a subtle difference to
--   <a>encodeWithBaseWindows</a>/<a>decodeWithBaseWindows</a>: it doesn't
--   care for the <tt>0x0000</tt> end marker and will as such produce
--   different results. Use <tt>takeWhile (/= 'NUL')</tt> on the input to
--   recover this behavior.
utf16le_b :: TextEncoding
mkUTF16le_b :: CodingFailureMode -> TextEncoding
utf16le_b_DF :: CodingFailureMode -> IO (TextDecoder ())
utf16le_b_EF :: CodingFailureMode -> IO (TextEncoder ())
utf16le_b_decode :: DecodeBuffer
utf16le_b_encode :: EncodeBuffer
cWcharsToChars_UCS2 :: [Word16] -> [Char]
cWcharsToChars :: [Word16] -> [Char]
charsToCWchars :: [Char] -> [Word16]
withWindowsString :: String -> (Int -> Ptr Word16 -> IO a) -> IO a
peekWindowsString :: (Ptr Word16, Int) -> IO String
withPosixString :: String -> (CStringLen -> IO a) -> IO a
peekPosixString :: CStringLen -> IO String

-- | Decode with the given <a>TextEncoding</a>.
decodeWithTE :: TextEncoding -> ShortByteString -> Either EncodingException String

-- | Encode with the given <a>TextEncoding</a>.
encodeWithTE :: TextEncoding -> String -> Either EncodingException ShortByteString

-- | This mimics the filepath decoder base uses on unix, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
decodeWithBasePosix :: ShortByteString -> IO String

-- | This mimics the filepath dencoder base uses on unix, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
encodeWithBasePosix :: String -> IO ShortByteString

-- | This mimics the filepath decoder base uses on windows, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
decodeWithBaseWindows :: ShortByteString -> IO String

-- | This mimics the filepath dencoder base uses on windows, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
encodeWithBaseWindows :: String -> IO ShortByteString
data EncodingException

-- | Could not decode a byte sequence because it was invalid under the
--   given encoding, or ran out of input in mid-decode.
EncodingError :: String -> Maybe Word8 -> EncodingException
showEncodingException :: EncodingException -> String
wNUL :: Word16
instance GHC.Classes.Eq System.OsString.Encoding.Internal.EncodingException
instance GHC.Internal.Exception.Type.Exception System.OsString.Encoding.Internal.EncodingException
instance Control.DeepSeq.NFData System.OsString.Encoding.Internal.EncodingException
instance GHC.Internal.Show.Show System.OsString.Encoding.Internal.EncodingException

module System.OsString.Encoding
data EncodingException

-- | Could not decode a byte sequence because it was invalid under the
--   given encoding, or ran out of input in mid-decode.
EncodingError :: String -> Maybe Word8 -> EncodingException
showEncodingException :: EncodingException -> String
ucs2le :: TextEncoding
mkUcs2le :: CodingFailureMode -> TextEncoding
ucs2le_DF :: CodingFailureMode -> IO (TextDecoder ())
ucs2le_EF :: CodingFailureMode -> IO (TextEncoder ())
ucs2le_decode :: DecodeBuffer
ucs2le_encode :: EncodeBuffer

-- | Mimics the base encoding for filesystem operations. This should be
--   total on all inputs (word16 byte arrays).
--   
--   Note that this has a subtle difference to
--   <a>encodeWithBaseWindows</a>/<a>decodeWithBaseWindows</a>: it doesn't
--   care for the <tt>0x0000</tt> end marker and will as such produce
--   different results. Use <tt>takeWhile (/= 'NUL')</tt> on the input to
--   recover this behavior.
utf16le_b :: TextEncoding
mkUTF16le_b :: CodingFailureMode -> TextEncoding
utf16le_b_DF :: CodingFailureMode -> IO (TextDecoder ())
utf16le_b_EF :: CodingFailureMode -> IO (TextEncoder ())
utf16le_b_decode :: DecodeBuffer
utf16le_b_encode :: EncodeBuffer

-- | This mimics the filepath dencoder base uses on unix, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
encodeWithBasePosix :: String -> IO ShortByteString

-- | This mimics the filepath decoder base uses on unix, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
decodeWithBasePosix :: ShortByteString -> IO String

-- | This mimics the filepath dencoder base uses on windows, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
encodeWithBaseWindows :: String -> IO ShortByteString

-- | This mimics the filepath decoder base uses on windows, with the small
--   distinction that we're not truncating at NUL bytes (because we're not
--   at the outer FFI layer).
decodeWithBaseWindows :: ShortByteString -> IO String

module System.OsString.Internal.Types

-- | Commonly used windows string as wide character bytes.
newtype WindowsString
WindowsString :: ShortByteString -> WindowsString
[getWindowsString] :: WindowsString -> ShortByteString

-- | Just a short bidirectional synonym for <a>WindowsString</a>
--   constructor.
pattern WS :: ShortByteString -> WindowsString
unWS :: WindowsString -> ShortByteString

-- | Commonly used Posix string as uninterpreted <tt>char[]</tt> array.
newtype PosixString
PosixString :: ShortByteString -> PosixString
[getPosixString] :: PosixString -> ShortByteString
unPS :: PosixString -> ShortByteString

-- | Just a short bidirectional synonym for <a>PosixString</a> constructor.
pattern PS :: ShortByteString -> PosixString
type PlatformString = PosixString
newtype WindowsChar
WindowsChar :: Word16 -> WindowsChar
[getWindowsChar] :: WindowsChar -> Word16
unWW :: WindowsChar -> Word16

-- | Just a short bidirectional synonym for <a>WindowsChar</a> constructor.
pattern WW :: Word16 -> WindowsChar
newtype PosixChar
PosixChar :: Word8 -> PosixChar
[getPosixChar] :: PosixChar -> Word8
unPW :: PosixChar -> Word8

-- | Just a short bidirectional synonym for <a>PosixChar</a> constructor.
pattern PW :: Word8 -> PosixChar
type PlatformChar = PosixChar

-- | Newtype representing short operating system specific strings.
--   
--   Internally this is either <a>WindowsString</a> or <a>PosixString</a>,
--   depending on the platform. Both use unpinned <tt>ShortByteString</tt>
--   for efficiency.
--   
--   The constructor is only exported via
--   <a>System.OsString.Internal.Types</a>, since dealing with the
--   internals isn't generally recommended, but supported in case you need
--   to write platform specific code.
newtype OsString
OsString :: PlatformString -> OsString
[getOsString] :: OsString -> PlatformString

-- | Newtype representing a code unit.
--   
--   On Windows, this is restricted to two-octet codepoints <a>Word16</a>,
--   on POSIX one-octet (<a>Word8</a>).
newtype OsChar
OsChar :: PlatformChar -> OsChar
[getOsChar] :: OsChar -> PlatformChar

-- | This is a type-level evidence that <a>OsChar</a> is a newtype wrapper
--   over <a>WindowsChar</a> or <a>PosixChar</a> and <a>OsString</a> is a
--   newtype wrapper over <a>WindowsString</a> or <a>PosixString</a>. If
--   you pattern match on <a>coercionToPlatformTypes</a>, GHC will know
--   that relevant types are coercible to each other. This helps to avoid
--   CPP in certain scenarios.
coercionToPlatformTypes :: Either (Coercion OsChar WindowsChar, Coercion OsString WindowsString) (Coercion OsChar PosixChar, Coercion OsString PosixString)
instance GHC.Classes.Eq System.OsString.Internal.Types.OsChar
instance GHC.Classes.Eq System.OsString.Internal.Types.OsString
instance GHC.Classes.Eq System.OsString.Internal.Types.PosixChar
instance GHC.Classes.Eq System.OsString.Internal.Types.PosixString
instance GHC.Classes.Eq System.OsString.Internal.Types.WindowsChar
instance GHC.Classes.Eq System.OsString.Internal.Types.WindowsString
instance GHC.Internal.Generics.Generic System.OsString.Internal.Types.OsChar
instance GHC.Internal.Generics.Generic System.OsString.Internal.Types.OsString
instance GHC.Internal.Generics.Generic System.OsString.Internal.Types.PosixChar
instance GHC.Internal.Generics.Generic System.OsString.Internal.Types.PosixString
instance GHC.Internal.Generics.Generic System.OsString.Internal.Types.WindowsChar
instance GHC.Internal.Generics.Generic System.OsString.Internal.Types.WindowsString
instance Language.Haskell.TH.Syntax.Lift System.OsString.Internal.Types.OsString
instance Language.Haskell.TH.Syntax.Lift System.OsString.Internal.Types.PosixString
instance Language.Haskell.TH.Syntax.Lift System.OsString.Internal.Types.WindowsString
instance GHC.Internal.Base.Monoid System.OsString.Internal.Types.OsString
instance GHC.Internal.Base.Monoid System.OsString.Internal.Types.PosixString
instance GHC.Internal.Base.Monoid System.OsString.Internal.Types.WindowsString
instance Control.DeepSeq.NFData System.OsString.Internal.Types.OsChar
instance Control.DeepSeq.NFData System.OsString.Internal.Types.OsString
instance Control.DeepSeq.NFData System.OsString.Internal.Types.PosixChar
instance Control.DeepSeq.NFData System.OsString.Internal.Types.PosixString
instance Control.DeepSeq.NFData System.OsString.Internal.Types.WindowsChar
instance Control.DeepSeq.NFData System.OsString.Internal.Types.WindowsString
instance GHC.Classes.Ord System.OsString.Internal.Types.OsChar
instance GHC.Classes.Ord System.OsString.Internal.Types.OsString
instance GHC.Classes.Ord System.OsString.Internal.Types.PosixChar
instance GHC.Classes.Ord System.OsString.Internal.Types.PosixString
instance GHC.Classes.Ord System.OsString.Internal.Types.WindowsChar
instance GHC.Classes.Ord System.OsString.Internal.Types.WindowsString
instance GHC.Internal.Base.Semigroup System.OsString.Internal.Types.OsString
instance GHC.Internal.Base.Semigroup System.OsString.Internal.Types.PosixString
instance GHC.Internal.Base.Semigroup System.OsString.Internal.Types.WindowsString
instance GHC.Internal.Show.Show System.OsString.Internal.Types.OsChar
instance GHC.Internal.Show.Show System.OsString.Internal.Types.OsString
instance GHC.Internal.Show.Show System.OsString.Internal.Types.PosixChar
instance GHC.Internal.Show.Show System.OsString.Internal.Types.PosixString
instance GHC.Internal.Show.Show System.OsString.Internal.Types.WindowsChar
instance GHC.Internal.Show.Show System.OsString.Internal.Types.WindowsString

module System.OsString.Posix

-- | Commonly used Posix string as uninterpreted <tt>char[]</tt> array.
data PosixString
data PosixChar

-- | Partial unicode friendly encoding.
--   
--   This encodes as UTF8 (strictly), which is a good guess.
--   
--   Throws an <a>EncodingException</a> if encoding fails. If the input
--   does not contain surrogate chars, you can use <a>unsafeEncodeUtf</a>.
encodeUtf :: MonadThrow m => String -> m PosixString

-- | Unsafe unicode friendly encoding.
--   
--   Like <a>encodeUtf</a>, except it crashes when the input contains
--   surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> PosixString

-- | Encode a <a>String</a> with the specified encoding.
encodeWith :: TextEncoding -> String -> Either EncodingException PosixString

-- | This mimics the behavior of the base library when doing filesystem
--   operations, which uses shady PEP 383 style encoding (based on the
--   current locale, but PEP 383 only works properly on UTF-8 encodings, so
--   good luck).
--   
--   Looking up the locale requires IO. If you're not worried about calls
--   to <tt>setFileSystemEncoding</tt>, then <a>unsafePerformIO</a> may be
--   feasible (make sure to deeply evaluate the result to catch
--   exceptions).
encodeFS :: String -> IO PosixString

-- | Constructs a platform string from a ByteString.
--   
--   This is a no-op.
fromBytes :: MonadThrow m => ByteString -> m PosixString

-- | QuasiQuote a <a>PosixString</a>. This accepts Unicode characters and
--   encodes as UTF-8 on unix.
pstr :: QuasiQuoter
singleton :: PosixChar -> PosixString
empty :: PosixString

-- | Pack a list of platform words to a platform string.
--   
--   Note that using this in conjunction with <a>unsafeFromChar</a> to
--   convert from <tt>[Char]</tt> to platform string is probably not what
--   you want, because it will truncate unicode code points.
pack :: [PosixChar] -> PosixString

-- | Partial unicode friendly decoding.
--   
--   This decodes as UTF8 (strictly), which is a good guess. Note that
--   filenames on unix are encoding agnostic char arrays.
--   
--   Throws a <a>EncodingException</a> if decoding fails.
decodeUtf :: MonadThrow m => PosixString -> m String

-- | Decode a <a>PosixString</a> with the specified encoding.
--   
--   The String is forced into memory to catch all exceptions.
decodeWith :: TextEncoding -> PosixString -> Either EncodingException String

-- | This mimics the behavior of the base library when doing filesystem
--   operations, which uses shady PEP 383 style encoding (based on the
--   current locale, but PEP 383 only works properly on UTF-8 encodings, so
--   good luck).
--   
--   Looking up the locale requires IO. If you're not worried about calls
--   to <tt>setFileSystemEncoding</tt>, then <a>unsafePerformIO</a> may be
--   feasible (make sure to deeply evaluate the result to catch
--   exceptions).
decodeFS :: PosixString -> IO String

-- | Unpack a platform string to a list of platform words.
unpack :: PosixString -> [PosixChar]

-- | Truncates to 1 octet.
unsafeFromChar :: Char -> PosixChar

-- | Converts back to a unicode codepoint (total).
toChar :: PosixChar -> Char

-- | <i>O(n)</i> Append a byte to the end of a <tt>OsString</tt>
snoc :: PosixString -> PosixChar -> PosixString

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
cons :: PosixChar -> PosixString -> PosixString

-- | <i>O(1)</i> Extract the last element of a OsString, which must be
--   finite and non-empty. An exception will be thrown in the case of an
--   empty OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
last :: HasCallStack => PosixString -> PosixChar

-- | <i>O(n)</i> Extract the elements after the head of a OsString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
tail :: HasCallStack => PosixString -> PosixString

-- | <i>O(n)</i> Extract the <a>head</a> and <a>tail</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
uncons :: PosixString -> Maybe (PosixChar, PosixString)

-- | <i>O(1)</i> Extract the first element of a OsString, which must be
--   non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
head :: HasCallStack => PosixString -> PosixChar

-- | <i>O(n)</i> Return all the elements of a <tt>OsString</tt> except the
--   last one. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
init :: HasCallStack => PosixString -> PosixString

-- | <i>O(n)</i> Extract the <a>init</a> and <a>last</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
unsnoc :: PosixString -> Maybe (PosixString, PosixChar)

-- | <i>O(1)</i>. The empty <tt>OsString</tt>.
null :: PosixString -> Bool

-- | <i>O(1)</i> The length of a <tt>OsString</tt>.
length :: PosixString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the OsString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (PosixChar -> PosixChar) -> PosixString -> PosixString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: PosixString -> PosixString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <tt>OsString</tt>
--   and a list of <tt>OsString</tt>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: PosixString -> [PosixString] -> PosixString

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a OsString, reduces
--   the OsString using the binary operator, from left to right.
foldl :: (a -> PosixChar -> a) -> a -> PosixString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> PosixChar -> a) -> a -> PosixString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>OsString</tt>s. An
--   exception will be thrown in the case of an empty OsString.
foldl1 :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty OsString.
foldl1' :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a OsString,
--   reduces the OsString using the binary operator, from right to left.
foldr :: (PosixChar -> a -> a) -> a -> PosixString -> a

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (PosixChar -> a -> a) -> a -> PosixString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>OsString</tt>s An
--   exception will be thrown in the case of an empty OsString.
foldr1 :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar

-- | <i>O(n)</i> Applied to a predicate and a <tt>OsString</tt>, <a>all</a>
--   determines if all elements of the <tt>OsString</tt> satisfy the
--   predicate.
all :: (PosixChar -> Bool) -> PosixString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <tt>OsString</tt>, <a>any</a>
--   determines if any element of the <tt>OsString</tt> satisfies the
--   predicate.
any :: (PosixChar -> Bool) -> PosixString -> Bool
concat :: [PosixString] -> PosixString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a OsString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> PosixChar -> PosixString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a OsString from a seed value. The function takes
--   the element and returns <a>Nothing</a> if it is done producing the
--   OsString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
--   value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word8]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <tt>OsString</tt>.
--   
--   If you know the maximum length, consider using <a>unfoldrN</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (PosixChar, a)) -> a -> PosixString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a OsString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (PosixChar, a)) -> a -> (PosixString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a OsString <tt>xs</tt>,
--   returns the prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> PosixString -> PosixString

-- | <i>O(n)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> PosixString -> PosixString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (PosixChar -> Bool) -> PosixString -> PosixString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (PosixChar -> Bool) -> PosixString -> PosixString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <a>empty</a> if <tt>n &gt;
--   <a>length</a> xs</tt>.
drop :: Int -> PosixString -> PosixString

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> PosixString -> PosixString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (PosixChar -> Bool) -> PosixString -> PosixString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
dropWhile :: (PosixChar -> Bool) -> PosixString -> PosixString

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) sbs
--      ==
--   let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--   </pre>
spanEnd :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n sbs</tt> is equivalent to
--   <tt>(<a>take</a> n sbs, <a>drop</a> n sbs)</tt>.
splitAt :: Int -> PosixString -> (PosixString, PosixString)

-- | <i>O(n)</i> Break a <tt>OsString</tt> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
split :: PosixChar -> PosixString -> [PosixString]

-- | <i>O(n)</i> Splits a <tt>OsString</tt> 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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith undefined ""     == []                  -- and not [""]
--   </pre>
splitWith :: (PosixChar -> Bool) -> PosixString -> [PosixString]

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   suffix, and otherwise <a>Nothing</a>.
stripSuffix :: PosixString -> PosixString -> Maybe PosixString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: PosixString -> PosixString -> Maybe PosixString

-- | Check whether one string is a substring of another.
isInfixOf :: PosixString -> PosixString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two OsStrings and
--   returns <a>True</a>
isPrefixOf :: PosixString -> PosixString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two OsStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: PosixString -> PosixString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: PosixString -> PosixString -> (PosixString, PosixString)

-- | <i>O(n)</i> <a>elem</a> is the <tt>OsString</tt> membership predicate.
elem :: PosixChar -> PosixString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a OsString,
--   and returns the first element in matching the predicate, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (PosixChar -> Bool) -> PosixString -> Maybe PosixChar

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a OsString,
--   returns a OsString containing those characters that satisfy the
--   predicate.
filter :: (PosixChar -> Bool) -> PosixString -> PosixString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a OsString
--   and returns the pair of OsStrings with elements which do and do not
--   satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p sbs, filter (not . p) sbs)
--   </pre>
partition :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)

-- | <i>O(1)</i> <tt>OsString</tt> index (subscript) operator, starting
--   from 0.
index :: HasCallStack => PosixString -> Int -> PosixChar

-- | <i>O(1)</i> <tt>OsString</tt> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: PosixString -> Int -> Maybe PosixChar

-- | <i>O(1)</i> <tt>OsString</tt> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: PosixString -> Int -> Maybe PosixChar

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <tt>OsString</tt> which is equal to the
--   query element, or <a>Nothing</a> if there is no such element.
elemIndex :: PosixChar -> PosixString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: PosixChar -> PosixString -> [Int]

-- | count returns the number of times its argument appears in the OsString
count :: PosixChar -> PosixString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <tt>OsString</tt> and returns the index of the first element in the
--   OsString satisfying the predicate.
findIndex :: (PosixChar -> Bool) -> PosixString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (PosixChar -> Bool) -> PosixString -> [Int]

module System.OsString.Internal

-- | Partial unicode friendly encoding.
--   
--   On windows this encodes as UTF16-LE (strictly), which is a pretty good
--   guess. On unix this encodes as UTF8 (strictly), which is a good guess.
--   
--   Throws an <a>EncodingException</a> if encoding fails. If the input
--   does not contain surrogate chars, you can use <a>unsafeEncodeUtf</a>.
encodeUtf :: MonadThrow m => String -> m OsString

-- | Unsafe unicode friendly encoding.
--   
--   Like <a>encodeUtf</a>, except it crashes when the input contains
--   surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> OsString

-- | Encode an <a>OsString</a> given the platform specific encodings.
encodeWith :: TextEncoding -> TextEncoding -> String -> Either EncodingException OsString

-- | Like <a>encodeUtf</a>, except this mimics the behavior of the base
--   library when doing filesystem operations, which is:
--   
--   <ol>
--   <li>on unix, uses shady PEP 383 style encoding (based on the current
--   locale, but PEP 383 only works properly on UTF-8 encodings, so good
--   luck)</li>
--   <li>on windows does permissive UTF-16 encoding, where coding errors
--   generate Chars in the surrogate range</li>
--   </ol>
--   
--   Looking up the locale requires IO. If you're not worried about calls
--   to <tt>setFileSystemEncoding</tt>, then <tt>unsafePerformIO</tt> may
--   be feasible (make sure to deeply evaluate the result to catch
--   exceptions).
encodeFS :: String -> IO OsString

-- | Partial unicode friendly decoding.
--   
--   On windows this decodes as UTF16-LE (strictly), which is a pretty good
--   guess. On unix this decodes as UTF8 (strictly), which is a good guess.
--   Note that filenames on unix are encoding agnostic char arrays.
--   
--   Throws a <a>EncodingException</a> if decoding fails.
decodeUtf :: MonadThrow m => OsString -> m String

-- | Decode an <a>OsString</a> with the specified encoding.
--   
--   The String is forced into memory to catch all exceptions.
decodeWith :: TextEncoding -> TextEncoding -> OsString -> Either EncodingException String

-- | Like <a>decodeUtf</a>, except this mimics the behavior of the base
--   library when doing filesystem operations, which is:
--   
--   <ol>
--   <li>on unix, uses shady PEP 383 style encoding (based on the current
--   locale, but PEP 383 only works properly on UTF-8 encodings, so good
--   luck)</li>
--   <li>on windows does permissive UTF-16 encoding, where coding errors
--   generate Chars in the surrogate range</li>
--   </ol>
--   
--   Looking up the locale requires IO. If you're not worried about calls
--   to <tt>setFileSystemEncoding</tt>, then <tt>unsafePerformIO</tt> may
--   be feasible (make sure to deeply evaluate the result to catch
--   exceptions).
decodeFS :: OsString -> IO String

-- | Constructs an <tt>OsString</tt> from a ByteString.
--   
--   On windows, this ensures valid UCS-2LE, on unix it is passed
--   unchanged/unchecked.
--   
--   Throws <a>EncodingException</a> on invalid UCS-2LE on windows
--   (although unlikely).
fromBytes :: MonadThrow m => ByteString -> m OsString

-- | QuasiQuote an <a>OsString</a>. This accepts Unicode characters and
--   encodes as UTF-8 on unix and UTF-16 on windows. If used as pattern,
--   requires turning on the <tt>ViewPatterns</tt> extension.
osstr :: QuasiQuoter

-- | Unpack an <a>OsString</a> to a list of <a>OsChar</a>.
unpack :: OsString -> [OsChar]

-- | Pack a list of <a>OsChar</a> to an <a>OsString</a>
--   
--   Note that using this in conjunction with <a>unsafeFromChar</a> to
--   convert from <tt>[Char]</tt> to <a>OsString</a> is probably not what
--   you want, because it will truncate unicode code points.
pack :: [OsChar] -> OsString
empty :: OsString
singleton :: OsChar -> OsString

-- | Truncates on unix to 1 and on Windows to 2 octets.
unsafeFromChar :: Char -> OsChar

-- | Converts back to a unicode codepoint (total).
toChar :: OsChar -> Char

-- | <i>O(n)</i> Append a byte to the end of a <a>OsString</a>
snoc :: OsString -> OsChar -> OsString

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
cons :: OsChar -> OsString -> OsString

-- | <i>O(1)</i> Extract the last element of a OsString, which must be
--   finite and non-empty. An exception will be thrown in the case of an
--   empty OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
last :: HasCallStack => OsString -> OsChar

-- | <i>O(n)</i> Extract the elements after the head of a OsString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
tail :: HasCallStack => OsString -> OsString

-- | <i>O(n)</i> Extract the <a>head</a> and <a>tail</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
uncons :: OsString -> Maybe (OsChar, OsString)

-- | <i>O(1)</i> Extract the first element of a OsString, which must be
--   non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
head :: HasCallStack => OsString -> OsChar

-- | <i>O(n)</i> Return all the elements of a <a>OsString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
init :: HasCallStack => OsString -> OsString

-- | <i>O(n)</i> Extract the <a>init</a> and <a>last</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
unsnoc :: OsString -> Maybe (OsString, OsChar)

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

-- | <i>O(1)</i> The length of a <a>OsString</a>.
length :: OsString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the OsString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (OsChar -> OsChar) -> OsString -> OsString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: OsString -> OsString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>OsString</a>
--   and a list of <a>OsString</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: OsString -> [OsString] -> OsString

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a OsString, reduces
--   the OsString using the binary operator, from left to right.
foldl :: (a -> OsChar -> a) -> a -> OsString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> OsChar -> a) -> a -> OsString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>OsString</a>s. An
--   exception will be thrown in the case of an empty OsString.
foldl1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty OsString.
foldl1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a OsString,
--   reduces the OsString using the binary operator, from right to left.
foldr :: (OsChar -> a -> a) -> a -> OsString -> a

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (OsChar -> a -> a) -> a -> OsString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>OsString</a>s An
--   exception will be thrown in the case of an empty OsString.
foldr1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <i>O(n)</i> Applied to a predicate and a <a>OsString</a>, <a>all</a>
--   determines if all elements of the <a>OsString</a> satisfy the
--   predicate.
all :: (OsChar -> Bool) -> OsString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>OsString</a>, <a>any</a>
--   determines if any element of the <a>OsString</a> satisfies the
--   predicate.
any :: (OsChar -> Bool) -> OsString -> Bool
concat :: [OsString] -> OsString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a OsString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> OsChar -> OsString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a OsString from a seed value. The function takes
--   the element and returns <a>Nothing</a> if it is done producing the
--   OsString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
--   value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word8]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <a>OsString</a>.
--   
--   If you know the maximum length, consider using <a>unfoldrN</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (OsChar, a)) -> a -> OsString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a OsString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (OsChar, a)) -> a -> (OsString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a OsString <tt>xs</tt>,
--   returns the prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> OsString -> OsString

-- | <i>O(n)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> OsString -> OsString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (OsChar -> Bool) -> OsString -> OsString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (OsChar -> Bool) -> OsString -> OsString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <a>empty</a> if <tt>n &gt;
--   <a>length</a> xs</tt>.
drop :: Int -> OsString -> OsString

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> OsString -> OsString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
dropWhile :: (OsChar -> Bool) -> OsString -> OsString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (OsChar -> Bool) -> OsString -> OsString

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) sbs
--      ==
--   let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--   </pre>
spanEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n sbs</tt> is equivalent to
--   <tt>(<a>take</a> n sbs, <a>drop</a> n sbs)</tt>.
splitAt :: Int -> OsString -> (OsString, OsString)

-- | <i>O(n)</i> Break a <a>OsString</a> into pieces separated by the byte
--   argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
split :: OsChar -> OsString -> [OsString]

-- | <i>O(n)</i> Splits a <a>OsString</a> 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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith undefined ""     == []                  -- and not [""]
--   </pre>
splitWith :: (OsChar -> Bool) -> OsString -> [OsString]

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   suffix, and otherwise <a>Nothing</a>.
stripSuffix :: OsString -> OsString -> Maybe OsString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: OsString -> OsString -> Maybe OsString

-- | Check whether one string is a substring of another.
isInfixOf :: OsString -> OsString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two OsStrings and
--   returns <a>True</a>
isPrefixOf :: OsString -> OsString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two OsStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: OsString -> OsString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: OsString -> OsString -> (OsString, OsString)

-- | <i>O(n)</i> <a>elem</a> is the <a>OsString</a> membership predicate.
elem :: OsChar -> OsString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a OsString,
--   and returns the first element in matching the predicate, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (OsChar -> Bool) -> OsString -> Maybe OsChar

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a OsString,
--   returns a OsString containing those characters that satisfy the
--   predicate.
filter :: (OsChar -> Bool) -> OsString -> OsString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a OsString
--   and returns the pair of OsStrings with elements which do and do not
--   satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p sbs, filter (not . p) sbs)
--   </pre>
partition :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | <i>O(1)</i> <a>OsString</a> index (subscript) operator, starting from
--   0.
index :: HasCallStack => OsString -> Int -> OsChar

-- | <i>O(1)</i> <a>OsString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: OsString -> Int -> Maybe OsChar

-- | <i>O(1)</i> <a>OsString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: OsString -> Int -> Maybe OsChar

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>OsString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element.
elemIndex :: OsChar -> OsString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: OsChar -> OsString -> [Int]

-- | count returns the number of times its argument appears in the OsString
count :: OsChar -> OsString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <a>OsString</a> and returns the index of the first element in the
--   OsString satisfying the predicate.
findIndex :: (OsChar -> Bool) -> OsString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (OsChar -> Bool) -> OsString -> [Int]


-- | An implementation of platform specific short <a>OsString</a>, which
--   is:
--   
--   <ol>
--   <li>on windows wide char bytes (<tt>[Word16]</tt>)</li>
--   <li>on unix char bytes (<tt>[Word8]</tt>)</li>
--   </ol>
--   
--   It captures the notion of syscall specific encoding (or the lack
--   thereof) to avoid roundtrip issues and memory fragmentation by using
--   unpinned byte arrays. Bytes are not touched or interpreted.
module System.OsString

-- | Newtype representing short operating system specific strings.
--   
--   Internally this is either <a>WindowsString</a> or <a>PosixString</a>,
--   depending on the platform. Both use unpinned <tt>ShortByteString</tt>
--   for efficiency.
--   
--   The constructor is only exported via
--   <a>System.OsString.Internal.Types</a>, since dealing with the
--   internals isn't generally recommended, but supported in case you need
--   to write platform specific code.
data OsString

-- | Partial unicode friendly encoding.
--   
--   On windows this encodes as UTF16-LE (strictly), which is a pretty good
--   guess. On unix this encodes as UTF8 (strictly), which is a good guess.
--   
--   Throws an <a>EncodingException</a> if encoding fails. If the input
--   does not contain surrogate chars, you can use <a>unsafeEncodeUtf</a>.
encodeUtf :: MonadThrow m => String -> m OsString

-- | Unsafe unicode friendly encoding.
--   
--   Like <a>encodeUtf</a>, except it crashes when the input contains
--   surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> OsString

-- | Encode an <a>OsString</a> given the platform specific encodings.
encodeWith :: TextEncoding -> TextEncoding -> String -> Either EncodingException OsString

-- | Like <a>encodeUtf</a>, except this mimics the behavior of the base
--   library when doing filesystem operations, which is:
--   
--   <ol>
--   <li>on unix, uses shady PEP 383 style encoding (based on the current
--   locale, but PEP 383 only works properly on UTF-8 encodings, so good
--   luck)</li>
--   <li>on windows does permissive UTF-16 encoding, where coding errors
--   generate Chars in the surrogate range</li>
--   </ol>
--   
--   Looking up the locale requires IO. If you're not worried about calls
--   to <tt>setFileSystemEncoding</tt>, then <tt>unsafePerformIO</tt> may
--   be feasible (make sure to deeply evaluate the result to catch
--   exceptions).
encodeFS :: String -> IO OsString

-- | QuasiQuote an <a>OsString</a>. This accepts Unicode characters and
--   encodes as UTF-8 on unix and UTF-16 on windows. If used as pattern,
--   requires turning on the <tt>ViewPatterns</tt> extension.
osstr :: QuasiQuoter
empty :: OsString
singleton :: OsChar -> OsString

-- | Pack a list of <a>OsChar</a> to an <a>OsString</a>
--   
--   Note that using this in conjunction with <a>unsafeFromChar</a> to
--   convert from <tt>[Char]</tt> to <a>OsString</a> is probably not what
--   you want, because it will truncate unicode code points.
pack :: [OsChar] -> OsString

-- | Partial unicode friendly decoding.
--   
--   On windows this decodes as UTF16-LE (strictly), which is a pretty good
--   guess. On unix this decodes as UTF8 (strictly), which is a good guess.
--   Note that filenames on unix are encoding agnostic char arrays.
--   
--   Throws a <a>EncodingException</a> if decoding fails.
decodeUtf :: MonadThrow m => OsString -> m String

-- | Decode an <a>OsString</a> with the specified encoding.
--   
--   The String is forced into memory to catch all exceptions.
decodeWith :: TextEncoding -> TextEncoding -> OsString -> Either EncodingException String

-- | Like <a>decodeUtf</a>, except this mimics the behavior of the base
--   library when doing filesystem operations, which is:
--   
--   <ol>
--   <li>on unix, uses shady PEP 383 style encoding (based on the current
--   locale, but PEP 383 only works properly on UTF-8 encodings, so good
--   luck)</li>
--   <li>on windows does permissive UTF-16 encoding, where coding errors
--   generate Chars in the surrogate range</li>
--   </ol>
--   
--   Looking up the locale requires IO. If you're not worried about calls
--   to <tt>setFileSystemEncoding</tt>, then <tt>unsafePerformIO</tt> may
--   be feasible (make sure to deeply evaluate the result to catch
--   exceptions).
decodeFS :: OsString -> IO String

-- | Unpack an <a>OsString</a> to a list of <a>OsChar</a>.
unpack :: OsString -> [OsChar]

-- | Newtype representing a code unit.
--   
--   On Windows, this is restricted to two-octet codepoints <a>Word16</a>,
--   on POSIX one-octet (<a>Word8</a>).
data OsChar

-- | Truncates on unix to 1 and on Windows to 2 octets.
unsafeFromChar :: Char -> OsChar

-- | Converts back to a unicode codepoint (total).
toChar :: OsChar -> Char

-- | <i>O(n)</i> Append a byte to the end of a <a>OsString</a>
snoc :: OsString -> OsChar -> OsString

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
cons :: OsChar -> OsString -> OsString

-- | <i>O(1)</i> Extract the last element of a OsString, which must be
--   finite and non-empty. An exception will be thrown in the case of an
--   empty OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
last :: HasCallStack => OsString -> OsChar

-- | <i>O(n)</i> Extract the elements after the head of a OsString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
tail :: HasCallStack => OsString -> OsString

-- | <i>O(n)</i> Extract the <a>head</a> and <a>tail</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
uncons :: OsString -> Maybe (OsChar, OsString)

-- | <i>O(1)</i> Extract the first element of a OsString, which must be
--   non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
head :: HasCallStack => OsString -> OsChar

-- | <i>O(n)</i> Return all the elements of a <a>OsString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
init :: HasCallStack => OsString -> OsString

-- | <i>O(n)</i> Extract the <a>init</a> and <a>last</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
unsnoc :: OsString -> Maybe (OsString, OsChar)

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

-- | <i>O(1)</i> The length of a <a>OsString</a>.
length :: OsString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the OsString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (OsChar -> OsChar) -> OsString -> OsString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: OsString -> OsString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>OsString</a>
--   and a list of <a>OsString</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: OsString -> [OsString] -> OsString

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a OsString, reduces
--   the OsString using the binary operator, from left to right.
foldl :: (a -> OsChar -> a) -> a -> OsString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> OsChar -> a) -> a -> OsString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>OsString</a>s. An
--   exception will be thrown in the case of an empty OsString.
foldl1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty OsString.
foldl1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a OsString,
--   reduces the OsString using the binary operator, from right to left.
foldr :: (OsChar -> a -> a) -> a -> OsString -> a

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (OsChar -> a -> a) -> a -> OsString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>OsString</a>s An
--   exception will be thrown in the case of an empty OsString.
foldr1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar

-- | <i>O(n)</i> Applied to a predicate and a <a>OsString</a>, <a>all</a>
--   determines if all elements of the <a>OsString</a> satisfy the
--   predicate.
all :: (OsChar -> Bool) -> OsString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <a>OsString</a>, <a>any</a>
--   determines if any element of the <a>OsString</a> satisfies the
--   predicate.
any :: (OsChar -> Bool) -> OsString -> Bool
concat :: [OsString] -> OsString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a OsString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> OsChar -> OsString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a OsString from a seed value. The function takes
--   the element and returns <a>Nothing</a> if it is done producing the
--   OsString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
--   value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word8]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <a>OsString</a>.
--   
--   If you know the maximum length, consider using <a>unfoldrN</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (OsChar, a)) -> a -> OsString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a OsString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (OsChar, a)) -> a -> (OsString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a OsString <tt>xs</tt>,
--   returns the prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> OsString -> OsString

-- | <i>O(n)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> OsString -> OsString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (OsChar -> Bool) -> OsString -> OsString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (OsChar -> Bool) -> OsString -> OsString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <a>empty</a> if <tt>n &gt;
--   <a>length</a> xs</tt>.
drop :: Int -> OsString -> OsString

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> OsString -> OsString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (OsChar -> Bool) -> OsString -> OsString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
dropWhile :: (OsChar -> Bool) -> OsString -> OsString

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) sbs
--      ==
--   let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--   </pre>
spanEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n sbs</tt> is equivalent to
--   <tt>(<a>take</a> n sbs, <a>drop</a> n sbs)</tt>.
splitAt :: Int -> OsString -> (OsString, OsString)

-- | <i>O(n)</i> Break a <a>OsString</a> into pieces separated by the byte
--   argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
split :: OsChar -> OsString -> [OsString]

-- | <i>O(n)</i> Splits a <a>OsString</a> 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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith undefined ""     == []                  -- and not [""]
--   </pre>
splitWith :: (OsChar -> Bool) -> OsString -> [OsString]

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   suffix, and otherwise <a>Nothing</a>.
stripSuffix :: OsString -> OsString -> Maybe OsString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: OsString -> OsString -> Maybe OsString

-- | Check whether one string is a substring of another.
isInfixOf :: OsString -> OsString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two OsStrings and
--   returns <a>True</a>
isPrefixOf :: OsString -> OsString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two OsStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: OsString -> OsString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: OsString -> OsString -> (OsString, OsString)

-- | <i>O(n)</i> <a>elem</a> is the <a>OsString</a> membership predicate.
elem :: OsChar -> OsString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a OsString,
--   and returns the first element in matching the predicate, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (OsChar -> Bool) -> OsString -> Maybe OsChar

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a OsString,
--   returns a OsString containing those characters that satisfy the
--   predicate.
filter :: (OsChar -> Bool) -> OsString -> OsString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a OsString
--   and returns the pair of OsStrings with elements which do and do not
--   satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p sbs, filter (not . p) sbs)
--   </pre>
partition :: (OsChar -> Bool) -> OsString -> (OsString, OsString)

-- | <i>O(1)</i> <a>OsString</a> index (subscript) operator, starting from
--   0.
index :: HasCallStack => OsString -> Int -> OsChar

-- | <i>O(1)</i> <a>OsString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: OsString -> Int -> Maybe OsChar

-- | <i>O(1)</i> <a>OsString</a> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: OsString -> Int -> Maybe OsChar

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>OsString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element.
elemIndex :: OsChar -> OsString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: OsChar -> OsString -> [Int]

-- | count returns the number of times its argument appears in the OsString
count :: OsChar -> OsString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <a>OsString</a> and returns the index of the first element in the
--   OsString satisfying the predicate.
findIndex :: (OsChar -> Bool) -> OsString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (OsChar -> Bool) -> OsString -> [Int]

-- | This is a type-level evidence that <a>OsChar</a> is a newtype wrapper
--   over <a>WindowsChar</a> or <a>PosixChar</a> and <a>OsString</a> is a
--   newtype wrapper over <a>WindowsString</a> or <a>PosixString</a>. If
--   you pattern match on <a>coercionToPlatformTypes</a>, GHC will know
--   that relevant types are coercible to each other. This helps to avoid
--   CPP in certain scenarios.
coercionToPlatformTypes :: Either (Coercion OsChar WindowsChar, Coercion OsString WindowsString) (Coercion OsChar PosixChar, Coercion OsString PosixString)

module System.OsString.Windows

-- | Commonly used windows string as wide character bytes.
data WindowsString
data WindowsChar

-- | Partial unicode friendly encoding.
--   
--   This encodes as UTF16-LE (strictly), which is a pretty good guess.
--   
--   Throws an <a>EncodingException</a> if encoding fails. If the input
--   does not contain surrogate chars, you can use
--   <tt>unsafeEncodeUtf</tt>.
encodeUtf :: MonadThrow m => String -> m WindowsString

-- | Unsafe unicode friendly encoding.
--   
--   Like <a>encodeUtf</a>, except it crashes when the input contains
--   surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> WindowsString

-- | Encode a <a>String</a> with the specified encoding.
encodeWith :: TextEncoding -> String -> Either EncodingException WindowsString

-- | This mimics the behavior of the base library when doing filesystem
--   operations, which does permissive UTF-16 encoding, where coding errors
--   generate Chars in the surrogate range.
--   
--   The reason this is in IO is because it unifies with the Posix
--   counterpart, which does require IO. This is safe to
--   <a>unsafePerformIO</a>/<tt>unsafeDupablePerformIO</tt>.
encodeFS :: String -> IO WindowsString

-- | Constructs a platform string from a ByteString.
--   
--   This ensures valid UCS-2LE. Note that this doesn't expand Word8 to
--   Word16 on windows, so you may get invalid UTF-16.
--   
--   Throws <a>EncodingException</a> on invalid UCS-2LE (although
--   unlikely).
fromBytes :: MonadThrow m => ByteString -> m WindowsString

-- | QuasiQuote a <a>WindowsString</a>. This accepts Unicode characters and
--   encodes as UTF-16LE on windows.
pstr :: QuasiQuoter
singleton :: WindowsChar -> WindowsString
empty :: WindowsString

-- | Pack a list of platform words to a platform string.
--   
--   Note that using this in conjunction with <a>unsafeFromChar</a> to
--   convert from <tt>[Char]</tt> to platform string is probably not what
--   you want, because it will truncate unicode code points.
pack :: [WindowsChar] -> WindowsString

-- | Partial unicode friendly decoding.
--   
--   This decodes as UTF16-LE (strictly), which is a pretty good.
--   
--   Throws a <a>EncodingException</a> if decoding fails.
decodeUtf :: MonadThrow m => WindowsString -> m String

-- | Decode a <a>WindowsString</a> with the specified encoding.
--   
--   The String is forced into memory to catch all exceptions.
decodeWith :: TextEncoding -> WindowsString -> Either EncodingException String

-- | Like <a>decodeUtf</a>, except this mimics the behavior of the base
--   library when doing filesystem operations, which does permissive UTF-16
--   encoding, where coding errors generate Chars in the surrogate range.
--   
--   The reason this is in IO is because it unifies with the Posix
--   counterpart, which does require IO.
--   <a>unsafePerformIO</a>/<tt>unsafeDupablePerformIO</tt> are safe,
--   however.
decodeFS :: WindowsString -> IO String

-- | Unpack a platform string to a list of platform words.
unpack :: WindowsString -> [WindowsChar]

-- | Truncates to 2 octets.
unsafeFromChar :: Char -> WindowsChar

-- | Converts back to a unicode codepoint (total).
toChar :: WindowsChar -> Char

-- | <i>O(n)</i> Append a byte to the end of a <tt>OsString</tt>
snoc :: WindowsString -> WindowsChar -> WindowsString

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists.
cons :: WindowsChar -> WindowsString -> WindowsString

-- | <i>O(1)</i> Extract the last element of a OsString, which must be
--   finite and non-empty. An exception will be thrown in the case of an
--   empty OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
last :: HasCallStack => WindowsString -> WindowsChar

-- | <i>O(n)</i> Extract the elements after the head of a OsString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
tail :: HasCallStack => WindowsString -> WindowsString

-- | <i>O(n)</i> Extract the <a>head</a> and <a>tail</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
uncons :: WindowsString -> Maybe (WindowsChar, WindowsString)

-- | <i>O(1)</i> Extract the first element of a OsString, which must be
--   non-empty. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>uncons</a> instead.
head :: HasCallStack => WindowsString -> WindowsChar

-- | <i>O(n)</i> Return all the elements of a <tt>OsString</tt> except the
--   last one. An exception will be thrown in the case of an empty
--   OsString.
--   
--   This is a partial function, consider using <a>unsnoc</a> instead.
init :: HasCallStack => WindowsString -> WindowsString

-- | <i>O(n)</i> Extract the <a>init</a> and <a>last</a> of a OsString,
--   returning <a>Nothing</a> if it is empty.
unsnoc :: WindowsString -> Maybe (WindowsString, WindowsChar)

-- | <i>O(1)</i>. The empty <tt>OsString</tt>.
null :: WindowsString -> Bool

-- | <i>O(1)</i> The length of a <tt>OsString</tt>.
length :: WindowsString -> Int

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the OsString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: (WindowsChar -> WindowsChar) -> WindowsString -> WindowsString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: WindowsString -> WindowsString

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <tt>OsString</tt>
--   and a list of <tt>OsString</tt>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: WindowsString -> [WindowsString] -> WindowsString

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a OsString, reduces
--   the OsString using the binary operator, from left to right.
foldl :: (a -> WindowsChar -> a) -> a -> WindowsString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: (a -> WindowsChar -> a) -> a -> WindowsString -> a

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>OsString</tt>s. An
--   exception will be thrown in the case of an empty OsString.
foldl1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar

-- | <a>foldl1'</a> is like <a>foldl1</a>, but strict in the accumulator.
--   An exception will be thrown in the case of an empty OsString.
foldl1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a OsString,
--   reduces the OsString using the binary operator, from right to left.
foldr :: (WindowsChar -> a -> a) -> a -> WindowsString -> a

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: (WindowsChar -> a -> a) -> a -> WindowsString -> a

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>OsString</tt>s An
--   exception will be thrown in the case of an empty OsString.
foldr1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar

-- | <a>foldr1'</a> is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar

-- | <i>O(n)</i> Applied to a predicate and a <tt>OsString</tt>, <a>all</a>
--   determines if all elements of the <tt>OsString</tt> satisfy the
--   predicate.
all :: (WindowsChar -> Bool) -> WindowsString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a <tt>OsString</tt>, <a>any</a>
--   determines if any element of the <tt>OsString</tt> satisfies the
--   predicate.
any :: (WindowsChar -> Bool) -> WindowsString -> Bool
concat :: [WindowsString] -> WindowsString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a OsString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
replicate :: Int -> WindowsChar -> WindowsString

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a OsString from a seed value. The function takes
--   the element and returns <a>Nothing</a> if it is done producing the
--   OsString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
--   value for further production.
--   
--   This function is not efficient/safe. It will build a list of
--   <tt>[Word8]</tt> and run the generator until it returns
--   <a>Nothing</a>, otherwise recurse infinitely, then finally create a
--   <tt>OsString</tt>.
--   
--   If you know the maximum length, consider using <a>unfoldrN</a>.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: (a -> Maybe (WindowsChar, a)) -> a -> WindowsString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a OsString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: Int -> (a -> Maybe (WindowsChar, a)) -> a -> (WindowsString, Maybe a)

-- | <i>O(n)</i> <a>take</a> <tt>n</tt>, applied to a OsString <tt>xs</tt>,
--   returns the prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt>
--   itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> WindowsString -> WindowsString

-- | <i>O(n)</i> <tt><a>takeEnd</a> n xs</tt> is equivalent to
--   <tt><a>drop</a> (<a>length</a> xs - n) xs</tt>. Takes <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; takeEnd 3 "abcdefg"
--   "efg"
--   
--   &gt;&gt;&gt; takeEnd 0 "abcdefg"
--   ""
--   
--   &gt;&gt;&gt; takeEnd 4 "abc"
--   "abc"
--   </pre>
takeEnd :: Int -> WindowsString -> WindowsString

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate.
--   
--   <tt><a>takeWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>takeWhile</a> p . <a>reverse</a></tt>.
takeWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString

-- | Similar to <a>takeWhile</a>, returns the longest (possibly empty)
--   prefix of elements satisfying the predicate.
takeWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString

-- | <i>O(n)</i> <a>drop</a> <tt>n</tt> <tt>xs</tt> returns the suffix of
--   <tt>xs</tt> after the first n elements, or <a>empty</a> if <tt>n &gt;
--   <a>length</a> xs</tt>.
drop :: Int -> WindowsString -> WindowsString

-- | <i>O(n)</i> <tt><a>dropEnd</a> n xs</tt> is equivalent to
--   <tt><a>take</a> (<a>length</a> xs - n) xs</tt>. Drops <tt>n</tt>
--   elements from end of bytestring.
--   
--   <pre>
--   &gt;&gt;&gt; dropEnd 3 "abcdefg"
--   "abcd"
--   
--   &gt;&gt;&gt; dropEnd 0 "abcdefg"
--   "abcdefg"
--   
--   &gt;&gt;&gt; dropEnd 4 "abc"
--   ""
--   </pre>
dropEnd :: Int -> WindowsString -> WindowsString

-- | Similar to <a>dropWhileEnd</a>, drops the longest (possibly empty)
--   suffix of elements satisfying the predicate and returns the remainder.
--   
--   <tt><a>dropWhileEnd</a> p</tt> is equivalent to <tt><a>reverse</a> .
--   <a>dropWhile</a> p . <a>reverse</a></tt>.
dropWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString

-- | Similar to <a>dropWhile</a>, drops the longest (possibly empty) prefix
--   of elements satisfying the predicate and returns the remainder.
dropWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString

-- | Similar to <a>break</a>, returns the longest (possibly empty) prefix
--   of elements which <b>do not</b> satisfy the predicate and the
--   remainder of the string.
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhile</a> (not . p))</tt>.
break :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)

-- | Returns the longest (possibly empty) suffix of elements which <b>do
--   not</b> satisfy the predicate and the remainder of the string.
--   
--   <a>breakEnd</a> <tt>p</tt> is equivalent to <tt><a>spanEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> (not . p) &amp;&amp;&amp;
--   <a>dropWhileEnd</a> (not . p))</tt>.
breakEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)

-- | Similar to <a>span</a>, returns the longest (possibly empty) prefix of
--   elements satisfying the predicate and the remainder of the string.
--   
--   <a>span</a> <tt>p</tt> is equivalent to <tt><a>break</a> (not .
--   p)</tt> and to <tt>(<a>takeWhile</a> p &amp;&amp;&amp;
--   <a>dropWhile</a> p)</tt>.
span :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)

-- | Returns the longest (possibly empty) suffix of elements satisfying the
--   predicate and the remainder of the string.
--   
--   <a>spanEnd</a> <tt>p</tt> is equivalent to <tt><a>breakEnd</a> (not .
--   p)</tt> and to <tt>(<a>takeWhileEnd</a> p &amp;&amp;&amp;
--   <a>dropWhileEnd</a> p)</tt>.
--   
--   We have
--   
--   <pre>
--   spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) sbs
--      ==
--   let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--   </pre>
spanEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)

-- | <i>O(n)</i> <a>splitAt</a> <tt>n sbs</tt> is equivalent to
--   <tt>(<a>take</a> n sbs, <a>drop</a> n sbs)</tt>.
splitAt :: Int -> WindowsString -> (WindowsString, WindowsString)

-- | <i>O(n)</i> Break a <tt>OsString</tt> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split 10  "a\nb\nd\ne" == ["a","b","d","e"]   -- fromEnum '\n' == 10
--   split 97  "aXaXaXa"    == ["","X","X","X",""] -- fromEnum 'a' == 97
--   split 120 "x"          == ["",""]             -- fromEnum 'x' == 120
--   split undefined ""     == []                  -- and not [""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
split :: WindowsChar -> WindowsString -> [WindowsString]

-- | <i>O(n)</i> Splits a <tt>OsString</tt> 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>
--   splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
--   splitWith undefined ""     == []                  -- and not [""]
--   </pre>
splitWith :: (WindowsChar -> Bool) -> WindowsString -> [WindowsString]

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   suffix, and otherwise <a>Nothing</a>.
stripSuffix :: WindowsString -> WindowsString -> Maybe WindowsString

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two OsStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: WindowsString -> WindowsString -> Maybe WindowsString

-- | Check whether one string is a substring of another.
isInfixOf :: WindowsString -> WindowsString -> Bool

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two OsStrings and
--   returns <a>True</a>
isPrefixOf :: WindowsString -> WindowsString -> Bool

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two OsStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
isSuffixOf :: WindowsString -> WindowsString -> Bool

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurrence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: WindowsString -> WindowsString -> (WindowsString, WindowsString)

-- | <i>O(n)</i> <a>elem</a> is the <tt>OsString</tt> membership predicate.
elem :: WindowsChar -> WindowsString -> Bool

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a OsString,
--   and returns the first element in matching the predicate, or
--   <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: (WindowsChar -> Bool) -> WindowsString -> Maybe WindowsChar

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a OsString,
--   returns a OsString containing those characters that satisfy the
--   predicate.
filter :: (WindowsChar -> Bool) -> WindowsString -> WindowsString

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a OsString
--   and returns the pair of OsStrings with elements which do and do not
--   satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p sbs, filter (not . p) sbs)
--   </pre>
partition :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)

-- | <i>O(1)</i> <tt>OsString</tt> index (subscript) operator, starting
--   from 0.
index :: HasCallStack => WindowsString -> Int -> WindowsChar

-- | <i>O(1)</i> <tt>OsString</tt> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
indexMaybe :: WindowsString -> Int -> Maybe WindowsChar

-- | <i>O(1)</i> <tt>OsString</tt> index, starting from 0, that returns
--   <a>Just</a> if:
--   
--   <pre>
--   0 &lt;= n &lt; length bs
--   </pre>
(!?) :: WindowsString -> Int -> Maybe WindowsChar

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <tt>OsString</tt> which is equal to the
--   query element, or <a>Nothing</a> if there is no such element.
elemIndex :: WindowsChar -> WindowsString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order.
elemIndices :: WindowsChar -> WindowsString -> [Int]

-- | count returns the number of times its argument appears in the OsString
count :: WindowsChar -> WindowsString -> Int

-- | <i>O(n)</i> The <a>findIndex</a> function takes a predicate and a
--   <tt>OsString</tt> and returns the index of the first element in the
--   OsString satisfying the predicate.
findIndex :: (WindowsChar -> Bool) -> WindowsString -> Maybe Int

-- | <i>O(n)</i> The <a>findIndices</a> function extends <a>findIndex</a>,
--   by returning the indices of all elements satisfying the predicate, in
--   ascending order.
findIndices :: (WindowsChar -> Bool) -> WindowsString -> [Int]
