-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Library for manipulating Operating system strings.
--
-- This package provides functionality for manipulating OsString
-- values, and is shipped with GHC.
@package os-string
@version 2.0.7
-- | Internal low-level utilities mostly for Word16, 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 ()
-- | O(n). Construct a new ShortByteString from a
-- CWString. The resulting ShortByteString is an
-- immutable copy of the original CWString, and is managed on
-- the Haskell heap. The original CWString must be null
-- terminated.
packCWString :: Ptr Word16 -> IO ShortByteString
-- | O(n). Construct a new ShortByteString from a
-- CWStringLen. The resulting ShortByteString is an
-- immutable copy of the original CWStringLen. The
-- ShortByteString is a normal Haskell value and will be managed
-- on the Haskell heap.
packCWStringLen :: (Ptr Word16, Int) -> IO ShortByteString
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a null-terminated CWString. The
-- CWString 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
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a CWStringLen. As for
-- useAsCWString this function makes a copy of the original
-- ShortByteString. It must not be stored or used after the
-- subcomputation finishes.
useAsCWStringLen :: ShortByteString -> ((Ptr Word16, Int) -> IO a) -> IO a
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a CWStringLen. As for
-- useAsCWString this function makes a copy of the original
-- ShortByteString. 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 ShortByteString. The
-- generating function is required to return the actual final size (<=
-- 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
-- Data.ByteString, e.g.
--
--
-- import qualified Data.ByteString as B
-- import qualified Data.ByteString.Short as B
-- (ShortByteString, toShort, fromShort)
--
--
-- Other ShortByteString operations clash with
-- Data.ByteString or Prelude functions however, so they
-- should be imported qualified with a different alias e.g.
--
--
-- import qualified Data.ByteString.Short as B.Short
--
module System.OsString.Data.ByteString.Short
-- | A compact representation of a Word8 vector.
--
-- It has a lower memory overhead than a ByteString and does not
-- contribute to heap fragmentation. It can be converted to or from a
-- ByteString (at the cost of copying the string data). It
-- supports very few other operations.
newtype ShortByteString
ShortByteString :: ByteArray -> ShortByteString
[unShortByteString] :: ShortByteString -> ByteArray
-- | Prior to bytestring-0.12 SBS was a genuine constructor
-- of ShortByteString, but now it is a bundled pattern synonym,
-- provided as a compatibility shim.
pattern SBS :: ByteArray# -> ShortByteString
-- | O(1). The empty ShortByteString.
empty :: ShortByteString
-- | O(1) Convert a Word8 into a ShortByteString
singleton :: Word8 -> ShortByteString
-- | O(n). Convert a list into a ShortByteString
pack :: [Word8] -> ShortByteString
-- | O(n). Convert a ShortByteString into a list.
unpack :: ShortByteString -> [Word8]
-- | O(n). Convert a ShortByteString into a
-- ByteString.
fromShort :: ShortByteString -> ByteString
-- | O(n). Convert a ByteString into a
-- ShortByteString.
--
-- This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString
-- | O(n) Append a byte to the end of a ShortByteString
--
-- Note: copies the entire byte array
snoc :: ShortByteString -> Word8 -> ShortByteString
infixl 5 `snoc`
-- | O(n) cons is analogous to (:) for lists.
--
-- Note: copies the entire byte array
cons :: Word8 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString
-- | O(1) 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 unsnoc instead.
last :: HasCallStack => ShortByteString -> Word8
-- | O(n) 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 uncons instead.
--
-- Note: copies the entire byte array
tail :: HasCallStack => ShortByteString -> ShortByteString
-- | O(n) Extract the head and tail of a
-- ShortByteString, returning Nothing if it is empty.
uncons :: ShortByteString -> Maybe (Word8, ShortByteString)
uncons2 :: ShortByteString -> Maybe (Word8, Word8, ShortByteString)
-- | O(1) 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 uncons instead.
head :: HasCallStack => ShortByteString -> Word8
-- | O(n) Return all the elements of a ShortByteString except
-- the last one. An exception will be thrown in the case of an empty
-- ShortByteString.
--
-- This is a partial function, consider using unsnoc instead.
--
-- Note: copies the entire byte array
init :: HasCallStack => ShortByteString -> ShortByteString
-- | O(n) Extract the init and last of a
-- ShortByteString, returning Nothing if it is empty.
unsnoc :: ShortByteString -> Maybe (ShortByteString, Word8)
-- | O(1) Test whether a ShortByteString is empty.
null :: ShortByteString -> Bool
-- | O(1) The length of a ShortByteString.
length :: ShortByteString -> Int
-- | O(n) map f xs is the ShortByteString obtained
-- by applying f to each element of xs.
map :: (Word8 -> Word8) -> ShortByteString -> ShortByteString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: ShortByteString -> ShortByteString
-- | O(n) The intercalate function takes a
-- ShortByteString and a list of ShortByteStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: ShortByteString -> [ShortByteString] -> ShortByteString
-- | foldl, 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Word8 -> a) -> a -> ShortByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings. An exception will be thrown in the case of an
-- empty ShortByteString.
foldl1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldr, 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
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (Word8 -> a -> a) -> a -> ShortByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings An exception will be thrown in the case of an
-- empty ShortByteString.
foldr1 :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: HasCallStack => (Word8 -> Word8 -> Word8) -> ShortByteString -> Word8
-- | O(n) Applied to a predicate and a ShortByteString,
-- all determines if all elements of the ShortByteString
-- satisfy the predicate.
all :: (Word8 -> Bool) -> ShortByteString -> Bool
-- | O(n) Applied to a predicate and a ShortByteString,
-- any determines if any element of the ShortByteString
-- satisfies the predicate.
any :: (Word8 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString
-- | O(n) replicate n x is a ShortByteString of
-- length n with x the value of every element. The
-- following holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> Word8 -> ShortByteString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ShortByteString from a seed value. The
-- function takes the element and returns Nothing if it is done
-- producing the ShortByteString or returns Just (a,b),
-- in which case, a is the next byte in the string, and
-- b is the seed value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word8] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- ShortByteString.
--
-- If you know the maximum length, consider using unfoldrN.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ShortByteString
-- | O(n) Like unfoldr, unfoldrN builds a
-- ShortByteString from a seed value. However, the length of the result
-- is limited by the first argument to unfoldrN. This function is
-- more efficient than unfoldr when the maximum length of the
-- result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ShortByteString, Maybe a)
-- | O(n) take n, applied to a ShortByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
--
-- Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString
-- | O(n) takeEnd n xs is equivalent to
-- drop (length xs - n) xs. Takes n
-- elements from end of bytestring.
--
--
-- >>> takeEnd 3 "abcdefg"
-- "efg"
--
-- >>> takeEnd 0 "abcdefg"
-- ""
--
-- >>> takeEnd 4 "abc"
-- "abc"
--
takeEnd :: Int -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if n >
-- length xs.
--
-- Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString
-- | O(n) dropEnd n xs is equivalent to
-- take (length xs - n) xs. Drops n
-- elements from end of bytestring.
--
--
-- >>> dropEnd 3 "abcdefg"
-- "abcd"
--
-- >>> dropEnd 0 "abcdefg"
-- "abcdefg"
--
-- >>> dropEnd 4 "abc"
-- ""
--
dropEnd :: Int -> ShortByteString -> ShortByteString
-- | Similar to dropWhile, 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 dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) sbs
-- ==
-- let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--
spanEnd :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) splitAt n sbs is equivalent to
-- (take n sbs, drop n sbs).
--
-- Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) Break a ShortByteString into pieces separated by
-- the byte argument, consuming the delimiter. I.e.
--
--
-- 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 [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- Note: copies the substrings
split :: Word8 -> ShortByteString -> [ShortByteString]
-- | O(n) Splits a ShortByteString 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.
--
--
-- splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (Word8 -> Bool) -> ShortByteString -> [ShortByteString]
-- | O(n) The stripSuffix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its suffix, and otherwise Nothing.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | O(n) The stripPrefix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its prefix, and otherwise Nothing.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isPrefixOf function takes two ShortByteStrings
-- and returns True iff the first is a prefix of the second.
isPrefixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isSuffixOf function takes two ShortByteStrings
-- and returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
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:
--
--
-- break (== c) l == breakSubstring (singleton c) l
--
--
-- For example, to tokenise a string, dropping delimiters:
--
--
-- tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
-- where (h,t) = breakSubstring x y
--
--
-- To skip to the first occurrence of a string:
--
--
-- snd (breakSubstring x y)
--
--
-- To take the parts of a string before a delimiter:
--
--
-- fst (breakSubstring x y)
--
--
-- 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)
-- | O(n) elem is the ShortByteString membership
-- predicate.
elem :: Word8 -> ShortByteString -> Bool
-- | O(n) The find function takes a predicate and a
-- ShortByteString, and returns the first element in matching the
-- predicate, or Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (Word8 -> Bool) -> ShortByteString -> Maybe Word8
-- | O(n) filter, applied to a predicate and a
-- ShortByteString, returns a ShortByteString containing those characters
-- that satisfy the predicate.
filter :: (Word8 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p sbs, filter (not . p) sbs)
--
partition :: (Word8 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(1) ShortByteString index (subscript) operator,
-- starting from 0.
--
-- This is a partial function, consider using indexMaybe instead.
index :: HasCallStack => ShortByteString -> Int -> Word8
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ShortByteString -> Int -> Maybe Word8
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ShortByteString -> Int -> Maybe Word8
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ShortByteString which is equal to
-- the query element, or Nothing if there is no such element.
elemIndex :: Word8 -> ShortByteString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- 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
-- | O(n) The findIndex function takes a predicate and a
-- ShortByteString and returns the index of the first element in
-- the ShortByteString satisfying the predicate.
findIndex :: (Word8 -> Bool) -> ShortByteString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- by returning the indices of all elements satisfying the predicate, in
-- ascending order.
findIndices :: (Word8 -> Bool) -> ShortByteString -> [Int]
-- | O(n). Construct a new ShortByteString from a
-- CString. The resulting ShortByteString is an
-- immutable copy of the original CString, and is managed on the
-- Haskell heap. The original CString must be null terminated.
packCString :: CString -> IO ShortByteString
-- | O(n). Construct a new ShortByteString from a
-- CStringLen. The resulting ShortByteString is an
-- immutable copy of the original CStringLen. The
-- ShortByteString is a normal Haskell value and will be managed
-- on the Haskell heap.
packCStringLen :: CStringLen -> IO ShortByteString
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a null-terminated CString. The
-- CString 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
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a CStringLen. As for useAsCString
-- this function makes a copy of the original ShortByteString.
-- It must not be stored or used after the subcomputation finishes.
--
-- Beware that this function does not add a terminating NUL byte
-- at the end of CStringLen. If you need to construct a pointer to
-- a null-terminated sequence, use useAsCString (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.
-- pack takes a list of BE encoded [Word16] and produces
-- a UTF16-LE encoded ShortByteString.
--
-- Likewise, unpack takes a UTF16-LE encoded ShortByteString and
-- produces a list of BE encoded [Word16].
--
-- 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 Word8 vector.
--
-- It has a lower memory overhead than a ByteString and does not
-- contribute to heap fragmentation. It can be converted to or from a
-- ByteString (at the cost of copying the string data). It
-- supports very few other operations.
newtype ShortByteString
ShortByteString :: ByteArray -> ShortByteString
[unShortByteString] :: ShortByteString -> ByteArray
-- | Prior to bytestring-0.12 SBS was a genuine constructor
-- of ShortByteString, but now it is a bundled pattern synonym,
-- provided as a compatibility shim.
pattern SBS :: ByteArray# -> ShortByteString
-- | O(1). The empty ShortByteString.
empty :: ShortByteString
-- | O(1) Convert a Word16 into a ShortByteString
singleton :: Word16 -> ShortByteString
-- | O(n). Convert a list into a ShortByteString
pack :: [Word16] -> ShortByteString
-- | O(n). Convert a ShortByteString into a list.
unpack :: ShortByteString -> [Word16]
-- | O(n). Convert a ShortByteString into a
-- ByteString.
fromShort :: ShortByteString -> ByteString
-- | O(n). Convert a ByteString into a
-- ShortByteString.
--
-- This makes a copy, so does not retain the input string.
toShort :: ByteString -> ShortByteString
-- | O(n) Append a Word16 to the end of a ShortByteString
--
-- Note: copies the entire byte array
snoc :: ShortByteString -> Word16 -> ShortByteString
infixl 5 `snoc`
-- | O(n) cons is analogous to (:) for lists.
--
-- Note: copies the entire byte array
cons :: Word16 -> ShortByteString -> ShortByteString
infixr 5 `cons`
append :: ShortByteString -> ShortByteString -> ShortByteString
-- | O(1) 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
-- | O(n) 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
-- | O(n) Extract the head and tail of a ByteString, returning
-- Nothing if it is empty.
uncons :: ShortByteString -> Maybe (Word16, ShortByteString)
-- | O(n) 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)
-- | O(1) 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
-- | O(n) Return all the elements of a ShortByteString 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
-- | O(n) Extract the init and last of a ByteString,
-- returning Nothing if it is empty.
unsnoc :: ShortByteString -> Maybe (ShortByteString, Word16)
-- | O(1) Test whether a ShortByteString is empty.
null :: ShortByteString -> Bool
-- | O(1) The length of a ShortByteString.
length :: ShortByteString -> Int
-- | This is like length, but the number of Word16, not
-- Word8.
numWord16 :: ShortByteString -> Int
-- | O(n) map f xs is the ShortByteString obtained
-- by applying f to each element of xs.
map :: (Word16 -> Word16) -> ShortByteString -> ShortByteString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: ShortByteString -> ShortByteString
-- | O(n) The intercalate function takes a
-- ShortByteString and a list of ShortByteStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: ShortByteString -> [ShortByteString] -> ShortByteString
-- | foldl, 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> Word16 -> a) -> a -> ShortByteString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings. An exception will be thrown in the case of an
-- empty ShortByteString.
foldl1 :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty ShortByteString.
foldl1' :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16
-- | foldr, 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
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (Word16 -> a -> a) -> a -> ShortByteString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty
-- ShortByteStrings An exception will be thrown in the case of an
-- empty ShortByteString.
foldr1 :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: HasCallStack => (Word16 -> Word16 -> Word16) -> ShortByteString -> Word16
-- | O(n) Applied to a predicate and a ShortByteString,
-- all determines if all elements of the ShortByteString
-- satisfy the predicate.
all :: (Word16 -> Bool) -> ShortByteString -> Bool
-- | O(n) Applied to a predicate and a ByteString, any
-- determines if any element of the ByteString satisfies the
-- predicate.
any :: (Word16 -> Bool) -> ShortByteString -> Bool
concat :: [ShortByteString] -> ShortByteString
-- | O(n) replicate n x is a ByteString of length
-- n with x the value of every element. The following
-- holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> Word16 -> ShortByteString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ShortByteString from a seed value. The
-- function takes the element and returns Nothing if it is done
-- producing the ShortByteString or returns Just (a,b),
-- in which case, a is the next byte in the string, and
-- b is the seed value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word16] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- ShortByteString.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (Word16, a)) -> a -> ShortByteString
-- | O(n) Like unfoldr, unfoldrN builds a
-- ShortByteString from a seed value. However, the length of the result
-- is limited by the first argument to unfoldrN. This function is
-- more efficient than unfoldr when the maximum length of the
-- result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (Word16, a)) -> a -> (ShortByteString, Maybe a)
-- | O(n) take n, applied to a ShortByteString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
--
-- Note: copies the entire byte array
take :: Int -> ShortByteString -> ShortByteString
-- | O(1) takeEnd n xs is equivalent to
-- drop (length xs - n) xs. Takes n
-- elements from end of bytestring.
--
--
-- >>> takeEnd 3 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
-- "e\NULf\NULg\NUL"
--
-- >>> takeEnd 0 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
-- ""
--
-- >>> takeEnd 4 "a\NULb\NULc\NUL"
-- "a\NULb\NULc\NUL"
--
takeEnd :: Int -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (Word16 -> Bool) -> ShortByteString -> ShortByteString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (Word16 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or [] if n >
-- length xs.
--
-- Note: copies the entire byte array
drop :: Int -> ShortByteString -> ShortByteString
-- | O(1) dropEnd n xs is equivalent to
-- take (length xs - n) xs. Drops n
-- elements from end of bytestring.
--
--
-- >>> dropEnd 3 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
-- "a\NULb\NULc\NULd\NUL"
--
-- >>> dropEnd 0 "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
-- "a\NULb\NULc\NULd\NULe\NULf\NULg\NUL"
--
-- >>> dropEnd 4 "a\NULb\NULc\NUL"
-- ""
--
dropEnd :: Int -> ShortByteString -> ShortByteString
-- | Similar to dropWhile, 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 dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (Word16 -> Bool) -> ShortByteString -> ShortByteString
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) ps
-- ==
-- let (x, y) = span (not . isSpace) (reverse ps) in (reverse y, reverse x)
--
spanEnd :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
--
-- Note: copies the substrings
splitAt :: Int -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) Break a ShortByteString into pieces separated by
-- the byte argument, consuming the delimiter. I.e.
--
--
-- 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 [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- Note: copies the substrings
split :: Word16 -> ShortByteString -> [ShortByteString]
-- | O(n) Splits a ShortByteString 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.
--
--
-- splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (Word16 -> Bool) -> ShortByteString -> [ShortByteString]
-- | O(n) The stripSuffix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its suffix, and otherwise Nothing.
stripSuffix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | O(n) The stripPrefix function takes two ShortByteStrings
-- and returns Just the remainder of the second iff the first is
-- its prefix, and otherwise Nothing.
stripPrefix :: ShortByteString -> ShortByteString -> Maybe ShortByteString
-- | Check whether one string is a substring of another.
isInfixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isPrefixOf function takes two ShortByteStrings
-- and returns True iff the first is a prefix of the second.
isPrefixOf :: ShortByteString -> ShortByteString -> Bool
-- | O(n) The isSuffixOf function takes two ShortByteStrings
-- and returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
isSuffixOf :: ShortByteString -> ShortByteString -> Bool
breakSubstring :: ShortByteString -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(n) elem is the ShortByteString membership
-- predicate.
elem :: Word16 -> ShortByteString -> Bool
-- | O(n) The find function takes a predicate and a
-- ByteString, and returns the first element in matching the predicate,
-- or Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (Word16 -> Bool) -> ShortByteString -> Maybe Word16
-- | O(n) filter, applied to a predicate and a ByteString,
-- returns a ByteString containing those characters that satisfy the
-- predicate.
filter :: (Word16 -> Bool) -> ShortByteString -> ShortByteString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p xs, filter (not . p) xs)
--
partition :: (Word16 -> Bool) -> ShortByteString -> (ShortByteString, ShortByteString)
-- | O(1) ShortByteString index (subscript) operator,
-- starting from 0.
index :: HasCallStack => ShortByteString -> Int -> Word16
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: ShortByteString -> Int -> Maybe Word16
-- | O(1) ShortByteString index, starting from 0, that
-- returns Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: ShortByteString -> Int -> Maybe Word16
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ShortByteString which is equal to
-- the query element, or Nothing if there is no such element.
elemIndex :: Word16 -> ShortByteString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- 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
-- | O(n) The findIndex function takes a predicate and a
-- ShortByteString and returns the index of the first element in
-- the ByteString satisfying the predicate.
findIndex :: (Word16 -> Bool) -> ShortByteString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- by returning the indices of all elements satisfying the predicate, in
-- ascending order.
findIndices :: (Word16 -> Bool) -> ShortByteString -> [Int]
-- | O(n). Construct a new ShortByteString from a
-- CWString. The resulting ShortByteString is an
-- immutable copy of the original CWString, and is managed on
-- the Haskell heap. The original CWString must be null
-- terminated.
packCWString :: Ptr Word16 -> IO ShortByteString
-- | O(n). Construct a new ShortByteString from a
-- CWStringLen. The resulting ShortByteString is an
-- immutable copy of the original CWStringLen. The
-- ShortByteString is a normal Haskell value and will be managed
-- on the Haskell heap.
packCWStringLen :: (Ptr Word16, Int) -> IO ShortByteString
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a CWStringLen. As for
-- useAsCWString this function makes a copy of the original
-- ShortByteString. It must not be stored or used after the
-- subcomputation finishes.
newCWString :: ShortByteString -> IO (Ptr Word16)
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a null-terminated CWString. The
-- CWString 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
-- | O(n) construction. Use a ShortByteString with a
-- function requiring a CWStringLen. As for
-- useAsCWString this function makes a copy of the original
-- ShortByteString. It must not be stored or used after the
-- subcomputation finishes.
useAsCWStringLen :: ShortByteString -> ((Ptr Word16, Int) -> IO a) -> IO a
module System.OsString.Internal.Exception
-- | Like try, but rethrows async exceptions.
trySafe :: Exception e => IO a -> IO (Either e a)
isAsyncException :: Exception e => e -> Bool
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
-- encodeWithBaseWindows/decodeWithBaseWindows: it doesn't
-- care for the 0x0000 end marker and will as such produce
-- different results. Use takeWhile (/= 'NUL') 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
withPosixString' :: String -> (CStringLen -> IO a) -> IO a
peekPosixString :: CStringLen -> IO String
peekPosixString' :: CStringLen -> IO String
-- | Decode with the given TextEncoding.
decodeWithTE :: TextEncoding -> ShortByteString -> Either EncodingException String
-- | Encode with the given TextEncoding.
encodeWithTE :: TextEncoding -> String -> Either EncodingException ShortByteString
-- | This mimics the filepath decoder base uses on unix (using PEP-383),
-- 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 string 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 encoder base uses on unix (using PEP-383),
-- 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 string encoder 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
-- encodeWithBaseWindows/decodeWithBaseWindows: it doesn't
-- care for the 0x0000 end marker and will as such produce
-- different results. Use takeWhile (/= 'NUL') 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 encoder base uses on unix (using PEP-383),
-- 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 (using PEP-383),
-- 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 string encoder 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 string 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 WindowsString
-- constructor.
pattern WS :: ShortByteString -> WindowsString
unWS :: WindowsString -> ShortByteString
-- | Commonly used Posix string as uninterpreted char[] array.
newtype PosixString
PosixString :: ShortByteString -> PosixString
[getPosixString] :: PosixString -> ShortByteString
unPS :: PosixString -> ShortByteString
-- | Just a short bidirectional synonym for PosixString 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 WindowsChar constructor.
pattern WW :: Word16 -> WindowsChar
newtype PosixChar
PosixChar :: Word8 -> PosixChar
[getPosixChar] :: PosixChar -> Word8
unPW :: PosixChar -> Word8
-- | Just a short bidirectional synonym for PosixChar constructor.
pattern PW :: Word8 -> PosixChar
type PlatformChar = PosixChar
-- | Newtype representing short operating system specific strings.
--
-- Internally this is either WindowsString or PosixString,
-- depending on the platform. Both use unpinned ShortByteString
-- for efficiency.
--
-- The constructor is only exported via
-- System.OsString.Internal.Types, 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 Word16,
-- on POSIX one-octet (Word8).
newtype OsChar
OsChar :: PlatformChar -> OsChar
[getOsChar] :: OsChar -> PlatformChar
-- | This is a type-level evidence that OsChar is a newtype wrapper
-- over WindowsChar or PosixChar and OsString is a
-- newtype wrapper over WindowsString or PosixString. If
-- you pattern match on coercionToPlatformTypes, 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 char[] array.
data PosixString
data PosixChar
-- | Partial unicode friendly encoding.
--
-- This encodes as UTF8 (strictly), which is a good guess.
--
-- Throws an EncodingException if encoding fails. If the input
-- does not contain surrogate chars, you can use unsafeEncodeUtf.
encodeUtf :: MonadThrow m => String -> m PosixString
-- | Unsafe unicode friendly encoding.
--
-- Like encodeUtf, except it crashes when the input contains
-- surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> PosixString
-- | Encode a String with the specified encoding.
encodeWith :: TextEncoding -> String -> Either EncodingException PosixString
-- | This mimics the behavior of the base library when doing filesystem
-- operations (usually filepaths), 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 setFileSystemEncoding, then unsafePerformIO may be
-- feasible (make sure to deeply evaluate the result to catch
-- exceptions).
-- | Deprecated: Use System.OsPath.Posix.encodeFS from filepath
encodeFS :: String -> IO PosixString
-- | This mimics the behavior of the base library when doing string
-- operations, which uses getLocaleEncoding.
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may be
-- feasible (make sure to deeply evaluate the result to catch
-- exceptions).
encodeLE :: String -> IO PosixString
-- | Constructs a platform string from a ByteString.
--
-- This is a no-op.
fromBytes :: MonadThrow m => ByteString -> m PosixString
-- | Like fromBytes, but not in IO.
--
-- fromBytes was designed to have a symmetric type signature on
-- unix and windows, but morally the function has no IO effects on unix,
-- so we provide this variant without breaking existing API.
--
-- This function does not exist on windows.
fromBytestring :: ByteString -> PosixString
-- | QuasiQuote a PosixString. 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 unsafeFromChar to
-- convert from [Char] 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 EncodingException if decoding fails.
decodeUtf :: MonadThrow m => PosixString -> m String
-- | Decode a PosixString 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 (usually filepaths), 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 setFileSystemEncoding, then unsafePerformIO may be
-- feasible (make sure to deeply evaluate the result to catch
-- exceptions).
-- | Deprecated: Use System.OsPath.Posix.decodeFS from filepath
decodeFS :: PosixString -> IO String
-- | This mimics the behavior of the base library when doing filesystem
-- operations, which uses getLocaleEncoding.
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may be
-- feasible (make sure to deeply evaluate the result to catch
-- exceptions).
decodeLE :: 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
-- | O(n) Append a byte to the end of a OsString
snoc :: PosixString -> PosixChar -> PosixString
-- | O(n) cons is analogous to (:) for lists.
cons :: PosixChar -> PosixString -> PosixString
-- | O(1) 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 unsnoc instead.
last :: HasCallStack => PosixString -> PosixChar
-- | O(n) 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 uncons instead.
tail :: HasCallStack => PosixString -> PosixString
-- | O(n) Extract the head and tail of a OsString,
-- returning Nothing if it is empty.
uncons :: PosixString -> Maybe (PosixChar, PosixString)
-- | O(1) 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 uncons instead.
head :: HasCallStack => PosixString -> PosixChar
-- | O(n) Return all the elements of a OsString except the
-- last one. An exception will be thrown in the case of an empty
-- OsString.
--
-- This is a partial function, consider using unsnoc instead.
init :: HasCallStack => PosixString -> PosixString
-- | O(n) Extract the init and last of a OsString,
-- returning Nothing if it is empty.
unsnoc :: PosixString -> Maybe (PosixString, PosixChar)
-- | O(1). The empty OsString.
null :: PosixString -> Bool
-- | O(1) The length of a OsString.
--
-- This returns the number of code units (Word8 on unix and
-- Word16 on windows), not bytes.
--
--
-- >>> length "abc"
-- 3
--
length :: PosixString -> Int
-- | O(n) map f xs is the OsString obtained by
-- applying f to each element of xs.
map :: (PosixChar -> PosixChar) -> PosixString -> PosixString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: PosixString -> PosixString
-- | O(n) The intercalate function takes a OsString
-- and a list of OsStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: PosixString -> [PosixString] -> PosixString
-- | foldl, 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> PosixChar -> a) -> a -> PosixString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty OsStrings. An
-- exception will be thrown in the case of an empty OsString.
foldl1 :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty OsString.
foldl1' :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar
-- | foldr, 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
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (PosixChar -> a -> a) -> a -> PosixString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty OsStrings An
-- exception will be thrown in the case of an empty OsString.
foldr1 :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: (PosixChar -> PosixChar -> PosixChar) -> PosixString -> PosixChar
-- | O(n) Applied to a predicate and a OsString, all
-- determines if all elements of the OsString satisfy the
-- predicate.
all :: (PosixChar -> Bool) -> PosixString -> Bool
-- | O(n) Applied to a predicate and a OsString, any
-- determines if any element of the OsString satisfies the
-- predicate.
any :: (PosixChar -> Bool) -> PosixString -> Bool
concat :: [PosixString] -> PosixString
-- | O(n) replicate n x is a OsString of length
-- n with x the value of every element. The following
-- holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> PosixChar -> PosixString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a OsString from a seed value. The function takes
-- the element and returns Nothing if it is done producing the
-- OsString or returns Just (a,b), in which case,
-- a is the next byte in the string, and b is the seed
-- value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word8] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- OsString.
--
-- If you know the maximum length, consider using unfoldrN.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (PosixChar, a)) -> a -> PosixString
-- | O(n) Like unfoldr, unfoldrN builds a OsString
-- from a seed value. However, the length of the result is limited by the
-- first argument to unfoldrN. This function is more efficient
-- than unfoldr when the maximum length of the result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (PosixChar, a)) -> a -> (PosixString, Maybe a)
-- | O(n) take n, applied to a OsString xs,
-- returns the prefix of xs of length n, or xs
-- itself if n > length xs.
take :: Int -> PosixString -> PosixString
-- | O(n) takeEnd n xs is equivalent to
-- drop (length xs - n) xs. Takes n
-- elements from end of bytestring.
--
--
-- >>> takeEnd 3 "abcdefg"
-- "efg"
--
-- >>> takeEnd 0 "abcdefg"
-- ""
--
-- >>> takeEnd 4 "abc"
-- "abc"
--
takeEnd :: Int -> PosixString -> PosixString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (PosixChar -> Bool) -> PosixString -> PosixString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (PosixChar -> Bool) -> PosixString -> PosixString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if n >
-- length xs.
drop :: Int -> PosixString -> PosixString
-- | O(n) dropEnd n xs is equivalent to
-- take (length xs - n) xs. Drops n
-- elements from end of bytestring.
--
--
-- >>> dropEnd 3 "abcdefg"
-- "abcd"
--
-- >>> dropEnd 0 "abcdefg"
-- "abcdefg"
--
-- >>> dropEnd 4 "abc"
-- ""
--
dropEnd :: Int -> PosixString -> PosixString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (PosixChar -> Bool) -> PosixString -> PosixString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
dropWhile :: (PosixChar -> Bool) -> PosixString -> PosixString
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) sbs
-- ==
-- let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--
spanEnd :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)
-- | O(n) splitAt n sbs is equivalent to
-- (take n sbs, drop n sbs).
splitAt :: Int -> PosixString -> (PosixString, PosixString)
-- | O(n) Break a OsString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- 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 [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
split :: PosixChar -> PosixString -> [PosixString]
-- | O(n) Splits a OsString 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.
--
--
-- splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (PosixChar -> Bool) -> PosixString -> [PosixString]
-- | O(n) The stripSuffix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- suffix, and otherwise Nothing.
stripSuffix :: PosixString -> PosixString -> Maybe PosixString
-- | O(n) The stripPrefix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- prefix, and otherwise Nothing.
stripPrefix :: PosixString -> PosixString -> Maybe PosixString
-- | Check whether one string is a substring of another.
isInfixOf :: PosixString -> PosixString -> Bool
-- | O(n) The isPrefixOf function takes two OsStrings and
-- returns True
isPrefixOf :: PosixString -> PosixString -> Bool
-- | O(n) The isSuffixOf function takes two OsStrings and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
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:
--
--
-- break (== c) l == breakSubstring (singleton c) l
--
--
-- For example, to tokenise a string, dropping delimiters:
--
--
-- tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
-- where (h,t) = breakSubstring x y
--
--
-- To skip to the first occurrence of a string:
--
--
-- snd (breakSubstring x y)
--
--
-- To take the parts of a string before a delimiter:
--
--
-- fst (breakSubstring x y)
--
--
-- 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)
-- | O(n) elem is the OsString membership predicate.
elem :: PosixChar -> PosixString -> Bool
-- | O(n) The find function takes a predicate and a OsString,
-- and returns the first element in matching the predicate, or
-- Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (PosixChar -> Bool) -> PosixString -> Maybe PosixChar
-- | O(n) filter, applied to a predicate and a OsString,
-- returns a OsString containing those characters that satisfy the
-- predicate.
filter :: (PosixChar -> Bool) -> PosixString -> PosixString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p sbs, filter (not . p) sbs)
--
partition :: (PosixChar -> Bool) -> PosixString -> (PosixString, PosixString)
-- | O(1) OsString index (subscript) operator, starting
-- from 0.
index :: HasCallStack => PosixString -> Int -> PosixChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: PosixString -> Int -> Maybe PosixChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: PosixString -> Int -> Maybe PosixChar
-- | O(n) The elemIndex function returns the index of the
-- first element in the given OsString which is equal to the
-- query element, or Nothing if there is no such element.
elemIndex :: PosixChar -> PosixString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- 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
-- | O(n) The findIndex function takes a predicate and a
-- OsString and returns the index of the first element in the
-- OsString satisfying the predicate.
findIndex :: (PosixChar -> Bool) -> PosixString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- 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 EncodingException if encoding fails. If the input
-- does not contain surrogate chars, you can use unsafeEncodeUtf.
encodeUtf :: MonadThrow m => String -> m OsString
-- | Unsafe unicode friendly encoding.
--
-- Like encodeUtf, except it crashes when the input contains
-- surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> OsString
-- | Encode a FilePath with the specified encoding.
--
-- Note: on windows, we expect a "wide char" encoding (e.g. UCS-2 or
-- UTF-16). Anything that works with Word16 boundaries. Picking
-- an incompatible encoding may crash filepath operations.
encodeWith :: TextEncoding -> TextEncoding -> String -> Either EncodingException OsString
-- | Like encodeUtf, except this mimics the behavior of the base
-- library when doing filesystem operations (usually filepaths), which
-- is:
--
--
-- - 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)
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
encodeFS :: String -> IO OsString
-- | Like encodeUtf, except this mimics the behavior of the base
-- library when doing string operations, which is:
--
--
-- - on unix this uses getLocaleEncoding
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
encodeLE :: 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 EncodingException if decoding fails.
decodeUtf :: MonadThrow m => OsString -> m String
-- | Decode an OsString with the specified encoding.
--
-- The String is forced into memory to catch all exceptions.
decodeWith :: TextEncoding -> TextEncoding -> OsString -> Either EncodingException String
-- | Like decodeUtf, except this mimics the behavior of the base
-- library when doing filesystem operations (usually filepaths), which
-- is:
--
--
-- - 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)
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
decodeFS :: OsString -> IO String
-- | Like decodeUtf, except this mimics the behavior of the base
-- library when doing string operations, which is:
--
--
-- - on unix this uses getLocaleEncoding
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
decodeLE :: OsString -> IO String
-- | Constructs an OsString from a ByteString.
--
-- On windows, this ensures valid UCS-2LE, on unix it is passed
-- unchanged/unchecked.
--
-- Throws EncodingException on invalid UCS-2LE on windows
-- (although unlikely).
fromBytes :: MonadThrow m => ByteString -> m OsString
-- | QuasiQuote an OsString. This accepts Unicode characters and
-- encodes as UTF-8 on unix and UTF-16 on windows. If used as pattern,
-- requires turning on the ViewPatterns extension.
osstr :: QuasiQuoter
-- | Unpack an OsString to a list of OsChar.
unpack :: OsString -> [OsChar]
-- | Pack a list of OsChar to an OsString
--
-- Note that using this in conjunction with unsafeFromChar to
-- convert from [Char] to OsString 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
-- | O(n) Append a byte to the end of a OsString
snoc :: OsString -> OsChar -> OsString
-- | O(n) cons is analogous to (:) for lists.
cons :: OsChar -> OsString -> OsString
-- | O(1) 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 unsnoc instead.
last :: HasCallStack => OsString -> OsChar
-- | O(n) 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 uncons instead.
tail :: HasCallStack => OsString -> OsString
-- | O(n) Extract the head and tail of a OsString,
-- returning Nothing if it is empty.
uncons :: OsString -> Maybe (OsChar, OsString)
-- | O(1) 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 uncons instead.
head :: HasCallStack => OsString -> OsChar
-- | O(n) Return all the elements of a OsString except the
-- last one. An exception will be thrown in the case of an empty
-- OsString.
--
-- This is a partial function, consider using unsnoc instead.
init :: HasCallStack => OsString -> OsString
-- | O(n) Extract the init and last of a OsString,
-- returning Nothing if it is empty.
unsnoc :: OsString -> Maybe (OsString, OsChar)
-- | O(1) Test whether a OsString is empty.
null :: OsString -> Bool
-- | O(1) The length of a OsString.
length :: OsString -> Int
-- | O(n) map f xs is the OsString obtained by
-- applying f to each element of xs.
map :: (OsChar -> OsChar) -> OsString -> OsString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: OsString -> OsString
-- | O(n) The intercalate function takes a OsString
-- and a list of OsStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: OsString -> [OsString] -> OsString
-- | foldl, 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> OsChar -> a) -> a -> OsString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty OsStrings. An
-- exception will be thrown in the case of an empty OsString.
foldl1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty OsString.
foldl1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | foldr, 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
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (OsChar -> a -> a) -> a -> OsString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty OsStrings An
-- exception will be thrown in the case of an empty OsString.
foldr1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | O(n) Applied to a predicate and a OsString, all
-- determines if all elements of the OsString satisfy the
-- predicate.
all :: (OsChar -> Bool) -> OsString -> Bool
-- | O(n) Applied to a predicate and a OsString, any
-- determines if any element of the OsString satisfies the
-- predicate.
any :: (OsChar -> Bool) -> OsString -> Bool
concat :: [OsString] -> OsString
-- | O(n) replicate n x is a OsString of length
-- n with x the value of every element. The following
-- holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> OsChar -> OsString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a OsString from a seed value. The function takes
-- the element and returns Nothing if it is done producing the
-- OsString or returns Just (a,b), in which case,
-- a is the next byte in the string, and b is the seed
-- value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word8] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- OsString.
--
-- If you know the maximum length, consider using unfoldrN.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (OsChar, a)) -> a -> OsString
-- | O(n) Like unfoldr, unfoldrN builds a OsString
-- from a seed value. However, the length of the result is limited by the
-- first argument to unfoldrN. This function is more efficient
-- than unfoldr when the maximum length of the result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (OsChar, a)) -> a -> (OsString, Maybe a)
-- | O(n) take n, applied to a OsString xs,
-- returns the prefix of xs of length n, or xs
-- itself if n > length xs.
take :: Int -> OsString -> OsString
-- | O(n) takeEnd n xs is equivalent to
-- drop (length xs - n) xs. Takes n
-- elements from end of bytestring.
--
--
-- >>> takeEnd 3 "abcdefg"
-- "efg"
--
-- >>> takeEnd 0 "abcdefg"
-- ""
--
-- >>> takeEnd 4 "abc"
-- "abc"
--
takeEnd :: Int -> OsString -> OsString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (OsChar -> Bool) -> OsString -> OsString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (OsChar -> Bool) -> OsString -> OsString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if n >
-- length xs.
drop :: Int -> OsString -> OsString
-- | O(n) dropEnd n xs is equivalent to
-- take (length xs - n) xs. Drops n
-- elements from end of bytestring.
--
--
-- >>> dropEnd 3 "abcdefg"
-- "abcd"
--
-- >>> dropEnd 0 "abcdefg"
-- "abcdefg"
--
-- >>> dropEnd 4 "abc"
-- ""
--
dropEnd :: Int -> OsString -> OsString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
dropWhile :: (OsChar -> Bool) -> OsString -> OsString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (OsChar -> Bool) -> OsString -> OsString
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) sbs
-- ==
-- let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--
spanEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | O(n) splitAt n sbs is equivalent to
-- (take n sbs, drop n sbs).
splitAt :: Int -> OsString -> (OsString, OsString)
-- | O(n) Break a OsString into pieces separated by the byte
-- argument, consuming the delimiter. I.e.
--
--
-- 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 [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
split :: OsChar -> OsString -> [OsString]
-- | O(n) Splits a OsString 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.
--
--
-- splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (OsChar -> Bool) -> OsString -> [OsString]
-- | O(n) The stripSuffix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- suffix, and otherwise Nothing.
stripSuffix :: OsString -> OsString -> Maybe OsString
-- | O(n) The stripPrefix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- prefix, and otherwise Nothing.
stripPrefix :: OsString -> OsString -> Maybe OsString
-- | Check whether one string is a substring of another.
isInfixOf :: OsString -> OsString -> Bool
-- | O(n) The isPrefixOf function takes two OsStrings and
-- returns True
isPrefixOf :: OsString -> OsString -> Bool
-- | O(n) The isSuffixOf function takes two OsStrings and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
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:
--
--
-- break (== c) l == breakSubstring (singleton c) l
--
--
-- For example, to tokenise a string, dropping delimiters:
--
--
-- tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
-- where (h,t) = breakSubstring x y
--
--
-- To skip to the first occurrence of a string:
--
--
-- snd (breakSubstring x y)
--
--
-- To take the parts of a string before a delimiter:
--
--
-- fst (breakSubstring x y)
--
--
-- 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)
-- | O(n) elem is the OsString membership predicate.
elem :: OsChar -> OsString -> Bool
-- | O(n) The find function takes a predicate and a OsString,
-- and returns the first element in matching the predicate, or
-- Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (OsChar -> Bool) -> OsString -> Maybe OsChar
-- | O(n) filter, applied to a predicate and a OsString,
-- returns a OsString containing those characters that satisfy the
-- predicate.
filter :: (OsChar -> Bool) -> OsString -> OsString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p sbs, filter (not . p) sbs)
--
partition :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | O(1) OsString index (subscript) operator, starting from
-- 0.
index :: HasCallStack => OsString -> Int -> OsChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: OsString -> Int -> Maybe OsChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: OsString -> Int -> Maybe OsChar
-- | O(n) The elemIndex function returns the index of the
-- first element in the given OsString which is equal to the query
-- element, or Nothing if there is no such element.
elemIndex :: OsChar -> OsString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- 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
-- | O(n) The findIndex function takes a predicate and a
-- OsString and returns the index of the first element in the
-- OsString satisfying the predicate.
findIndex :: (OsChar -> Bool) -> OsString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- by returning the indices of all elements satisfying the predicate, in
-- ascending order.
findIndices :: (OsChar -> Bool) -> OsString -> [Int]
-- | An implementation of platform specific short OsString, which
-- is:
--
--
-- - on windows wide char bytes ([Word16])
-- - on unix char bytes ([Word8])
--
--
-- 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 WindowsString or PosixString,
-- depending on the platform. Both use unpinned ShortByteString
-- for efficiency.
--
-- The constructor is only exported via
-- System.OsString.Internal.Types, 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 EncodingException if encoding fails. If the input
-- does not contain surrogate chars, you can use unsafeEncodeUtf.
encodeUtf :: MonadThrow m => String -> m OsString
-- | Unsafe unicode friendly encoding.
--
-- Like encodeUtf, except it crashes when the input contains
-- surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> OsString
-- | Encode a FilePath with the specified encoding.
--
-- Note: on windows, we expect a "wide char" encoding (e.g. UCS-2 or
-- UTF-16). Anything that works with Word16 boundaries. Picking
-- an incompatible encoding may crash filepath operations.
encodeWith :: TextEncoding -> TextEncoding -> String -> Either EncodingException OsString
-- | Like encodeUtf, except this mimics the behavior of the base
-- library when doing filesystem operations (usually filepaths), which
-- is:
--
--
-- - 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)
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
-- | Deprecated: Use System.OsPath.encodeFS from filepath
encodeFS :: String -> IO OsString
-- | Like encodeUtf, except this mimics the behavior of the base
-- library when doing string operations, which is:
--
--
-- - on unix this uses getLocaleEncoding
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
encodeLE :: String -> IO OsString
-- | QuasiQuote an OsString. This accepts Unicode characters and
-- encodes as UTF-8 on unix and UTF-16 on windows. If used as pattern,
-- requires turning on the ViewPatterns extension.
osstr :: QuasiQuoter
empty :: OsString
singleton :: OsChar -> OsString
-- | Pack a list of OsChar to an OsString
--
-- Note that using this in conjunction with unsafeFromChar to
-- convert from [Char] to OsString 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 EncodingException if decoding fails.
decodeUtf :: MonadThrow m => OsString -> m String
-- | Decode an OsString with the specified encoding.
--
-- The String is forced into memory to catch all exceptions.
decodeWith :: TextEncoding -> TextEncoding -> OsString -> Either EncodingException String
-- | Like decodeUtf, except this mimics the behavior of the base
-- library when doing filesystem operations (usually filepaths), which
-- is:
--
--
-- - 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)
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
-- | Deprecated: Use System.OsPath.encodeFS from filepath
decodeFS :: OsString -> IO String
-- | Like decodeUtf, except this mimics the behavior of the base
-- library when doing string operations, which is:
--
--
-- - on unix this uses getLocaleEncoding
-- - on windows does permissive UTF-16 encoding, where coding errors
-- generate Chars in the surrogate range
--
--
-- Looking up the locale requires IO. If you're not worried about calls
-- to setFileSystemEncoding, then unsafePerformIO may
-- be feasible (make sure to deeply evaluate the result to catch
-- exceptions).
decodeLE :: OsString -> IO String
-- | Unpack an OsString to a list of OsChar.
unpack :: OsString -> [OsChar]
-- | Newtype representing a code unit.
--
-- On Windows, this is restricted to two-octet codepoints Word16,
-- on POSIX one-octet (Word8).
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
-- | O(n) Append a byte to the end of a OsString
snoc :: OsString -> OsChar -> OsString
-- | O(n) cons is analogous to (:) for lists.
cons :: OsChar -> OsString -> OsString
-- | O(1) 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 unsnoc instead.
last :: HasCallStack => OsString -> OsChar
-- | O(n) 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 uncons instead.
tail :: HasCallStack => OsString -> OsString
-- | O(n) Extract the head and tail of a OsString,
-- returning Nothing if it is empty.
uncons :: OsString -> Maybe (OsChar, OsString)
-- | O(1) 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 uncons instead.
head :: HasCallStack => OsString -> OsChar
-- | O(n) Return all the elements of a OsString except the
-- last one. An exception will be thrown in the case of an empty
-- OsString.
--
-- This is a partial function, consider using unsnoc instead.
init :: HasCallStack => OsString -> OsString
-- | O(n) Extract the init and last of a OsString,
-- returning Nothing if it is empty.
unsnoc :: OsString -> Maybe (OsString, OsChar)
-- | O(1) Test whether a OsString is empty.
null :: OsString -> Bool
-- | O(1) The length of a OsString.
length :: OsString -> Int
-- | O(n) map f xs is the OsString obtained by
-- applying f to each element of xs.
map :: (OsChar -> OsChar) -> OsString -> OsString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: OsString -> OsString
-- | O(n) The intercalate function takes a OsString
-- and a list of OsStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: OsString -> [OsString] -> OsString
-- | foldl, 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> OsChar -> a) -> a -> OsString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty OsStrings. An
-- exception will be thrown in the case of an empty OsString.
foldl1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty OsString.
foldl1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | foldr, 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
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (OsChar -> a -> a) -> a -> OsString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty OsStrings An
-- exception will be thrown in the case of an empty OsString.
foldr1 :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: (OsChar -> OsChar -> OsChar) -> OsString -> OsChar
-- | O(n) Applied to a predicate and a OsString, all
-- determines if all elements of the OsString satisfy the
-- predicate.
all :: (OsChar -> Bool) -> OsString -> Bool
-- | O(n) Applied to a predicate and a OsString, any
-- determines if any element of the OsString satisfies the
-- predicate.
any :: (OsChar -> Bool) -> OsString -> Bool
concat :: [OsString] -> OsString
-- | O(n) replicate n x is a OsString of length
-- n with x the value of every element. The following
-- holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> OsChar -> OsString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a OsString from a seed value. The function takes
-- the element and returns Nothing if it is done producing the
-- OsString or returns Just (a,b), in which case,
-- a is the next byte in the string, and b is the seed
-- value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word8] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- OsString.
--
-- If you know the maximum length, consider using unfoldrN.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (OsChar, a)) -> a -> OsString
-- | O(n) Like unfoldr, unfoldrN builds a OsString
-- from a seed value. However, the length of the result is limited by the
-- first argument to unfoldrN. This function is more efficient
-- than unfoldr when the maximum length of the result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (OsChar, a)) -> a -> (OsString, Maybe a)
-- | O(n) take n, applied to a OsString xs,
-- returns the prefix of xs of length n, or xs
-- itself if n > length xs.
take :: Int -> OsString -> OsString
-- | O(n) takeEnd n xs is equivalent to
-- drop (length xs - n) xs. Takes n
-- elements from end of bytestring.
--
--
-- >>> takeEnd 3 "abcdefg"
-- "efg"
--
-- >>> takeEnd 0 "abcdefg"
-- ""
--
-- >>> takeEnd 4 "abc"
-- "abc"
--
takeEnd :: Int -> OsString -> OsString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (OsChar -> Bool) -> OsString -> OsString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (OsChar -> Bool) -> OsString -> OsString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if n >
-- length xs.
drop :: Int -> OsString -> OsString
-- | O(n) dropEnd n xs is equivalent to
-- take (length xs - n) xs. Drops n
-- elements from end of bytestring.
--
--
-- >>> dropEnd 3 "abcdefg"
-- "abcd"
--
-- >>> dropEnd 0 "abcdefg"
-- "abcdefg"
--
-- >>> dropEnd 4 "abc"
-- ""
--
dropEnd :: Int -> OsString -> OsString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (OsChar -> Bool) -> OsString -> OsString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
dropWhile :: (OsChar -> Bool) -> OsString -> OsString
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) sbs
-- ==
-- let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--
spanEnd :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | O(n) splitAt n sbs is equivalent to
-- (take n sbs, drop n sbs).
splitAt :: Int -> OsString -> (OsString, OsString)
-- | O(n) Break a OsString into pieces separated by the byte
-- argument, consuming the delimiter. I.e.
--
--
-- 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 [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
split :: OsChar -> OsString -> [OsString]
-- | O(n) Splits a OsString 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.
--
--
-- splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (OsChar -> Bool) -> OsString -> [OsString]
-- | O(n) The stripSuffix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- suffix, and otherwise Nothing.
stripSuffix :: OsString -> OsString -> Maybe OsString
-- | O(n) The stripPrefix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- prefix, and otherwise Nothing.
stripPrefix :: OsString -> OsString -> Maybe OsString
-- | Check whether one string is a substring of another.
isInfixOf :: OsString -> OsString -> Bool
-- | O(n) The isPrefixOf function takes two OsStrings and
-- returns True
isPrefixOf :: OsString -> OsString -> Bool
-- | O(n) The isSuffixOf function takes two OsStrings and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
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:
--
--
-- break (== c) l == breakSubstring (singleton c) l
--
--
-- For example, to tokenise a string, dropping delimiters:
--
--
-- tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
-- where (h,t) = breakSubstring x y
--
--
-- To skip to the first occurrence of a string:
--
--
-- snd (breakSubstring x y)
--
--
-- To take the parts of a string before a delimiter:
--
--
-- fst (breakSubstring x y)
--
--
-- 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)
-- | O(n) elem is the OsString membership predicate.
elem :: OsChar -> OsString -> Bool
-- | O(n) The find function takes a predicate and a OsString,
-- and returns the first element in matching the predicate, or
-- Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (OsChar -> Bool) -> OsString -> Maybe OsChar
-- | O(n) filter, applied to a predicate and a OsString,
-- returns a OsString containing those characters that satisfy the
-- predicate.
filter :: (OsChar -> Bool) -> OsString -> OsString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p sbs, filter (not . p) sbs)
--
partition :: (OsChar -> Bool) -> OsString -> (OsString, OsString)
-- | O(1) OsString index (subscript) operator, starting from
-- 0.
index :: HasCallStack => OsString -> Int -> OsChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: OsString -> Int -> Maybe OsChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: OsString -> Int -> Maybe OsChar
-- | O(n) The elemIndex function returns the index of the
-- first element in the given OsString which is equal to the query
-- element, or Nothing if there is no such element.
elemIndex :: OsChar -> OsString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- 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
-- | O(n) The findIndex function takes a predicate and a
-- OsString and returns the index of the first element in the
-- OsString satisfying the predicate.
findIndex :: (OsChar -> Bool) -> OsString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- 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 OsChar is a newtype wrapper
-- over WindowsChar or PosixChar and OsString is a
-- newtype wrapper over WindowsString or PosixString. If
-- you pattern match on coercionToPlatformTypes, 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 EncodingException if encoding fails. If the input
-- does not contain surrogate chars, you can use
-- unsafeEncodeUtf.
encodeUtf :: MonadThrow m => String -> m WindowsString
-- | Unsafe unicode friendly encoding.
--
-- Like encodeUtf, except it crashes when the input contains
-- surrogate chars. For sanitized input, this can be useful.
unsafeEncodeUtf :: HasCallStack => String -> WindowsString
-- | Encode a String with the specified encoding.
--
-- Note: We expect a "wide char" encoding (e.g. UCS-2 or UTF-16).
-- Anything that works with Word16 boundaries. Picking an
-- incompatible encoding may crash filepath operations.
encodeWith :: TextEncoding -> String -> Either EncodingException WindowsString
-- | This mimics the behavior of the base library when doing filesystem
-- operations (usually filepaths), 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
-- unsafePerformIO/unsafeDupablePerformIO.
-- | Deprecated: Use System.OsPath.Windows.encodeFS from filepath
encodeFS :: String -> IO WindowsString
-- | This mimics the behavior of the base library when doing string
-- 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
-- unsafePerformIO/unsafeDupablePerformIO.
encodeLE :: String -> IO WindowsString
-- | Like 'encodeLE but not in IO.
--
-- encodeLE was designed to have a symmetric type signature on
-- unix and windows, but morally the function has no IO effects on
-- windows, so we provide this variant without breaking existing API.
--
-- On windows, encodeLE is equivalent to encodeFS.
--
-- This function does not exist on unix.
fromString :: String -> 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 EncodingException on invalid UCS-2LE (although
-- unlikely).
fromBytes :: MonadThrow m => ByteString -> m WindowsString
-- | QuasiQuote a WindowsString. 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 unsafeFromChar to
-- convert from [Char] 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 EncodingException if decoding fails.
decodeUtf :: MonadThrow m => WindowsString -> m String
-- | Decode a WindowsString with the specified encoding.
--
-- The String is forced into memory to catch all exceptions.
decodeWith :: TextEncoding -> WindowsString -> Either EncodingException String
-- | Like decodeUtf, except this mimics the behavior of the base
-- library when doing filesystem operations (usually filepaths), 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.
-- unsafePerformIO/unsafeDupablePerformIO are safe,
-- however.
-- | Deprecated: Use System.OsPath.Windows.decodeFS from filepath
decodeFS :: WindowsString -> IO String
-- | Like decodeUtf, 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.
-- unsafePerformIO/unsafeDupablePerformIO are safe,
-- however.
decodeLE :: 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
-- | O(n) Append a byte to the end of a OsString
snoc :: WindowsString -> WindowsChar -> WindowsString
-- | O(n) cons is analogous to (:) for lists.
cons :: WindowsChar -> WindowsString -> WindowsString
-- | O(1) 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 unsnoc instead.
last :: HasCallStack => WindowsString -> WindowsChar
-- | O(n) 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 uncons instead.
tail :: HasCallStack => WindowsString -> WindowsString
-- | O(n) Extract the head and tail of a OsString,
-- returning Nothing if it is empty.
uncons :: WindowsString -> Maybe (WindowsChar, WindowsString)
-- | O(1) 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 uncons instead.
head :: HasCallStack => WindowsString -> WindowsChar
-- | O(n) Return all the elements of a OsString except the
-- last one. An exception will be thrown in the case of an empty
-- OsString.
--
-- This is a partial function, consider using unsnoc instead.
init :: HasCallStack => WindowsString -> WindowsString
-- | O(n) Extract the init and last of a OsString,
-- returning Nothing if it is empty.
unsnoc :: WindowsString -> Maybe (WindowsString, WindowsChar)
-- | O(1). The empty OsString.
null :: WindowsString -> Bool
-- | O(1) The length of a OsString.
--
-- This returns the number of code units (Word8 on unix and
-- Word16 on windows), not bytes.
--
--
-- >>> length "abc"
-- 3
--
length :: WindowsString -> Int
-- | O(n) map f xs is the OsString obtained by
-- applying f to each element of xs.
map :: (WindowsChar -> WindowsChar) -> WindowsString -> WindowsString
-- | O(n) reverse xs efficiently returns the
-- elements of xs in reverse order.
reverse :: WindowsString -> WindowsString
-- | O(n) The intercalate function takes a OsString
-- and a list of OsStrings and concatenates the list after
-- interspersing the first argument between each element of the list.
intercalate :: WindowsString -> [WindowsString] -> WindowsString
-- | foldl, 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
-- | foldl' is like foldl, but strict in the accumulator.
foldl' :: (a -> WindowsChar -> a) -> a -> WindowsString -> a
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty OsStrings. An
-- exception will be thrown in the case of an empty OsString.
foldl1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
-- | foldl1' is like foldl1, but strict in the accumulator.
-- An exception will be thrown in the case of an empty OsString.
foldl1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
-- | foldr, 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
-- | foldr' is like foldr, but strict in the accumulator.
foldr' :: (WindowsChar -> a -> a) -> a -> WindowsString -> a
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty OsStrings An
-- exception will be thrown in the case of an empty OsString.
foldr1 :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
-- | foldr1' is a variant of foldr1, but is strict in the
-- accumulator.
foldr1' :: (WindowsChar -> WindowsChar -> WindowsChar) -> WindowsString -> WindowsChar
-- | O(n) Applied to a predicate and a OsString, all
-- determines if all elements of the OsString satisfy the
-- predicate.
all :: (WindowsChar -> Bool) -> WindowsString -> Bool
-- | O(n) Applied to a predicate and a OsString, any
-- determines if any element of the OsString satisfies the
-- predicate.
any :: (WindowsChar -> Bool) -> WindowsString -> Bool
concat :: [WindowsString] -> WindowsString
-- | O(n) replicate n x is a OsString of length
-- n with x the value of every element. The following
-- holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Int -> WindowsChar -> WindowsString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a OsString from a seed value. The function takes
-- the element and returns Nothing if it is done producing the
-- OsString or returns Just (a,b), in which case,
-- a is the next byte in the string, and b is the seed
-- value for further production.
--
-- This function is not efficient/safe. It will build a list of
-- [Word8] and run the generator until it returns
-- Nothing, otherwise recurse infinitely, then finally create a
-- OsString.
--
-- If you know the maximum length, consider using unfoldrN.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (WindowsChar, a)) -> a -> WindowsString
-- | O(n) Like unfoldr, unfoldrN builds a OsString
-- from a seed value. However, the length of the result is limited by the
-- first argument to unfoldrN. This function is more efficient
-- than unfoldr when the maximum length of the result is known.
--
-- The following equation relates unfoldrN and unfoldr:
--
--
-- fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (WindowsChar, a)) -> a -> (WindowsString, Maybe a)
-- | O(n) take n, applied to a OsString xs,
-- returns the prefix of xs of length n, or xs
-- itself if n > length xs.
take :: Int -> WindowsString -> WindowsString
-- | O(n) takeEnd n xs is equivalent to
-- drop (length xs - n) xs. Takes n
-- elements from end of bytestring.
--
--
-- >>> takeEnd 3 "abcdefg"
-- "efg"
--
-- >>> takeEnd 0 "abcdefg"
-- ""
--
-- >>> takeEnd 4 "abc"
-- "abc"
--
takeEnd :: Int -> WindowsString -> WindowsString
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate.
--
-- takeWhileEnd p is equivalent to reverse .
-- takeWhile p . reverse.
takeWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
-- | Similar to takeWhile, returns the longest (possibly empty)
-- prefix of elements satisfying the predicate.
takeWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if n >
-- length xs.
drop :: Int -> WindowsString -> WindowsString
-- | O(n) dropEnd n xs is equivalent to
-- take (length xs - n) xs. Drops n
-- elements from end of bytestring.
--
--
-- >>> dropEnd 3 "abcdefg"
-- "abcd"
--
-- >>> dropEnd 0 "abcdefg"
-- "abcdefg"
--
-- >>> dropEnd 4 "abc"
-- ""
--
dropEnd :: Int -> WindowsString -> WindowsString
-- | Similar to dropWhileEnd, drops the longest (possibly empty)
-- suffix of elements satisfying the predicate and returns the remainder.
--
-- dropWhileEnd p is equivalent to reverse .
-- dropWhile p . reverse.
dropWhileEnd :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
-- | Similar to dropWhile, drops the longest (possibly empty) prefix
-- of elements satisfying the predicate and returns the remainder.
dropWhile :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
-- | Similar to break, returns the longest (possibly empty) prefix
-- of elements which do not satisfy the predicate and the
-- remainder of the string.
--
-- break p is equivalent to span (not .
-- p) and to (takeWhile (not . p) &&&
-- dropWhile (not . p)).
break :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
-- | Returns the longest (possibly empty) suffix of elements which do
-- not satisfy the predicate and the remainder of the string.
--
-- breakEnd p is equivalent to spanEnd (not .
-- p) and to (takeWhileEnd (not . p) &&&
-- dropWhileEnd (not . p)).
breakEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
-- | Similar to span, returns the longest (possibly empty) prefix of
-- elements satisfying the predicate and the remainder of the string.
--
-- span p is equivalent to break (not .
-- p) and to (takeWhile p &&&
-- dropWhile p).
span :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
-- | Returns the longest (possibly empty) suffix of elements satisfying the
-- predicate and the remainder of the string.
--
-- spanEnd p is equivalent to breakEnd (not .
-- p) and to (takeWhileEnd p &&&
-- dropWhileEnd p).
--
-- We have
--
--
-- spanEnd (not . isSpace) "x y z" == ("x y ", "z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) sbs
-- ==
-- let (x, y) = span (not . isSpace) (reverse sbs) in (reverse y, reverse x)
--
spanEnd :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
-- | O(n) splitAt n sbs is equivalent to
-- (take n sbs, drop n sbs).
splitAt :: Int -> WindowsString -> (WindowsString, WindowsString)
-- | O(n) Break a OsString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- 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 [""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
split :: WindowsChar -> WindowsString -> [WindowsString]
-- | O(n) Splits a OsString 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.
--
--
-- splitWith (==97) "aabbaca" == ["","","bb","c",""] -- fromEnum 'a' == 97
-- splitWith undefined "" == [] -- and not [""]
--
splitWith :: (WindowsChar -> Bool) -> WindowsString -> [WindowsString]
-- | O(n) The stripSuffix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- suffix, and otherwise Nothing.
stripSuffix :: WindowsString -> WindowsString -> Maybe WindowsString
-- | O(n) The stripPrefix function takes two OsStrings and
-- returns Just the remainder of the second iff the first is its
-- prefix, and otherwise Nothing.
stripPrefix :: WindowsString -> WindowsString -> Maybe WindowsString
-- | Check whether one string is a substring of another.
isInfixOf :: WindowsString -> WindowsString -> Bool
-- | O(n) The isPrefixOf function takes two OsStrings and
-- returns True
isPrefixOf :: WindowsString -> WindowsString -> Bool
-- | O(n) The isSuffixOf function takes two OsStrings and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
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:
--
--
-- break (== c) l == breakSubstring (singleton c) l
--
--
-- For example, to tokenise a string, dropping delimiters:
--
--
-- tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
-- where (h,t) = breakSubstring x y
--
--
-- To skip to the first occurrence of a string:
--
--
-- snd (breakSubstring x y)
--
--
-- To take the parts of a string before a delimiter:
--
--
-- fst (breakSubstring x y)
--
--
-- 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)
-- | O(n) elem is the OsString membership predicate.
elem :: WindowsChar -> WindowsString -> Bool
-- | O(n) The find function takes a predicate and a OsString,
-- and returns the first element in matching the predicate, or
-- Nothing if there is no such element.
--
--
-- find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (WindowsChar -> Bool) -> WindowsString -> Maybe WindowsChar
-- | O(n) filter, applied to a predicate and a OsString,
-- returns a OsString containing those characters that satisfy the
-- predicate.
filter :: (WindowsChar -> Bool) -> WindowsString -> WindowsString
-- | O(n) The partition 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.,
--
--
-- partition p bs == (filter p sbs, filter (not . p) sbs)
--
partition :: (WindowsChar -> Bool) -> WindowsString -> (WindowsString, WindowsString)
-- | O(1) OsString index (subscript) operator, starting
-- from 0.
index :: HasCallStack => WindowsString -> Int -> WindowsChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
indexMaybe :: WindowsString -> Int -> Maybe WindowsChar
-- | O(1) OsString index, starting from 0, that returns
-- Just if:
--
--
-- 0 <= n < length bs
--
(!?) :: WindowsString -> Int -> Maybe WindowsChar
-- | O(n) The elemIndex function returns the index of the
-- first element in the given OsString which is equal to the
-- query element, or Nothing if there is no such element.
elemIndex :: WindowsChar -> WindowsString -> Maybe Int
-- | O(n) The elemIndices function extends elemIndex,
-- 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
-- | O(n) The findIndex function takes a predicate and a
-- OsString and returns the index of the first element in the
-- OsString satisfying the predicate.
findIndex :: (WindowsChar -> Bool) -> WindowsString -> Maybe Int
-- | O(n) The findIndices function extends findIndex,
-- by returning the indices of all elements satisfying the predicate, in
-- ascending order.
findIndices :: (WindowsChar -> Bool) -> WindowsString -> [Int]