-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Same as compact-string except with a small fix so it builds on ghc-6.12
--
-- Fast, packed, strict strings with a list interface. Based on
-- Data.ByteString. Multiple encodings are supported. This is the
-- same package as compact-string-0.3.1 except for a small fix to work
-- with the new Exception library. Once Twan updates that package, this
-- package will be deprecated.
@package compact-string-fix
@version 0.3.2
-- | Internal functions for the CompactString type.
module Data.CompactString.Internal
-- | A String using a compact, strict representation. A CompactString
-- a is encoded using encoding a, for example
-- CompactString UTF8.
newtype CompactString a
CS :: ByteString -> CompactString a
unCS :: CompactString a -> ByteString
data Proxy a
encoding :: CompactString a -> Proxy a
-- | A way to encode characters into bytes
class Encoding a
pokeCharFun :: Encoding a => Proxy a -> Char -> (Int, Ptr Word8 -> IO ())
pokeCharLen :: Encoding a => Proxy a -> Char -> Int
pokeChar :: Encoding a => Proxy a -> Ptr Word8 -> Char -> IO Int
pokeCharRev :: Encoding a => Proxy a -> Ptr Word8 -> Char -> IO Int
peekChar :: Encoding a => Proxy a -> Ptr Word8 -> IO (Int, Char)
peekCharLen :: Encoding a => Proxy a -> Ptr Word8 -> IO Int
peekCharRev :: Encoding a => Proxy a -> Ptr Word8 -> IO (Int, Char)
peekCharLenRev :: Encoding a => Proxy a -> Ptr Word8 -> IO Int
peekCharSafe :: Encoding a => Proxy a -> Int -> Ptr Word8 -> IO (Int, Char)
validateLength :: Encoding a => Proxy a -> Int -> IO ()
copyChar :: Encoding a => Proxy a -> Ptr Word8 -> Ptr Word8 -> IO Int
copyCharRev :: Encoding a => Proxy a -> Ptr Word8 -> Ptr Word8 -> IO Int
containsASCII :: Encoding a => Proxy a -> Bool
validEquality :: Encoding a => Proxy a -> Bool
validOrdering :: Encoding a => Proxy a -> Bool
validSubstring :: Encoding a => Proxy a -> Bool
charCount :: Encoding a => Proxy a -> Int -> Int
byteCount :: Encoding a => Proxy a -> Int -> Int
newSize :: Encoding a => Proxy a -> Int -> Int
doUpLoop :: Encoding a => Proxy a -> AccEFL acc -> acc -> ImperativeLoop acc
doDownLoop :: Encoding a => Proxy a -> AccEFL acc -> acc -> ImperativeLoop acc
doUpLoopFold :: Encoding a => Proxy a -> FoldEFL acc -> acc -> ImperativeLoop_ acc
doDownLoopFold :: Encoding a => Proxy a -> FoldEFL acc -> acc -> ImperativeLoop_ acc
data PairS a b
(:*:) :: {-# UNPACK #-} !a -> {-# UNPACK #-} !b -> PairS a b
data MaybeS a
NothingS :: MaybeS a
JustS :: {-# UNPACK #-} !a -> MaybeS a
unSP :: PairS a b -> (a, b)
-- | Type of loop functions
type AccEFL acc = acc -> Char -> (PairS acc (MaybeS Char))
type FoldEFL acc = acc -> Char -> acc
-- | An imperative loop transforming a string, using an accumulating
-- parameter. See Data.ByteString.Fusion
type ImperativeLoop acc = Ptr Word8 -> Ptr Word8 -> Int -> IO (PairS (PairS acc Int) Int)
-- | ImperativeLoop with no output
type ImperativeLoop_ acc = Ptr Word8 -> Int -> IO acc
-- | A space-efficient representation of a Word8 vector, supporting many
-- efficient operations. A ByteString contains 8-bit characters
-- only.
--
-- Instances of Eq, Ord, Read, Show, Data, Typeable
data ByteString :: *
PS :: {-# UNPACK #-} !ForeignPtr Word8 -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> ByteString
memcpy :: Ptr Word8 -> Ptr Word8 -> CSize -> IO ()
-- | Just like unsafePerformIO, but we inline it. Big performance gains as
-- it exposes lots of things to further inlining. Very unsafe. In
-- particular, you should do no memory allocation inside an
-- inlinePerformIO block. On Hugs this is just
-- unsafePerformIO.
inlinePerformIO :: IO a -> a
-- | Perform a function given a pointer to the buffer of a CompactString
withBuffer :: CompactString a -> (Ptr Word8 -> IO b) -> IO b
-- | Perform a function given a pointer to the last byte in the buffer of a
-- CompactString
withBufferEnd :: CompactString a -> (Ptr Word8 -> IO b) -> IO b
-- | Perform a function given a pointer to the buffer of a CompactString
unsafeWithBuffer :: CompactString a -> (Ptr Word8 -> IO b) -> b
-- | Perform a function given a pointer to the last byte in the buffer of a
-- CompactString
unsafeWithBufferEnd :: CompactString a -> (Ptr Word8 -> IO b) -> b
create :: Int -> (Ptr Word8 -> IO ()) -> IO (CompactString a)
-- | The Prelude.fromEnum method restricted to the type
-- Data.Char.Char.
ord :: Char -> Int
unsafeChr :: Int -> Char
-- | Safe variant of chr, combined with return; does more checks. At least
-- GHC does not check for surrogate pairs
returnChr :: Int -> Word32 -> IO (Int, Char)
-- | plusPtr that preserves the pointer type
plusPtr :: Ptr a -> Int -> Ptr a
peekByteOff :: Storable a => Ptr a -> Int -> IO a
pokeByteOff :: Storable a => Ptr a -> Int -> a -> IO ()
-- | Read a value from the given memory location.
--
-- Note that the peek and poke functions might require properly aligned
-- addresses to function correctly. This is architecture dependent; thus,
-- portable code should ensure that when peeking or poking values of some
-- type a, the alignment constraint for a, as given by
-- the function alignment is fulfilled.
peek :: Storable a => Ptr a -> IO a
-- | Write the given value to the given memory location. Alignment
-- restrictions might apply; see peek.
poke :: Storable a => Ptr a -> a -> IO ()
-- | Fail with an error message including the module name and function
failMessage :: String -> String -> IO a
-- | Raise an errorr, with the message including the module name and
-- function
moduleError :: String -> String -> a
errorEmptyList :: String -> a
-- | Catch exceptions from fail in the IO monad, and wrap them in another
-- monad
unsafeTry :: MonadPlus m => IO a -> m a
-- | Catch exceptions from fail in the IO monad, and wrap them in another
-- monad
unsafeTryIO :: MonadPlus m => IO a -> IO (m a)
-- | Fusable loop functions, mirrors Data.ByteString.Fusion.
module Data.CompactString.Fusion
loopAcc :: (PairS acc arr) -> acc
-- | Projection functions that are fusion friendly (as in, we determine
-- when they are inlined)
loopArr :: (PairS acc arr) -> arr
-- | Data type for accumulators which can be ignored. The rewrite rules
-- rely on the fact that no bottoms of this type are ever constructed;
-- hence, we can assume (_ :: NoAcc) seq x = x.
data NoAcc
NoAcc :: NoAcc
foldEFL :: (acc -> Char -> acc) -> AccEFL acc
mapEFL :: (Char -> Char) -> AccEFL NoAcc
filterEFL :: (Char -> Bool) -> AccEFL NoAcc
scanEFL :: (Char -> Char -> Char) -> AccEFL Char
-- | Element function implementing a map and fold
mapAccumEFL :: (acc -> Char -> (acc, Char)) -> AccEFL acc
-- | Element function implementing a map with index
mapIndexEFL :: (Int -> Char -> Char) -> AccEFL Int
loopUp :: Encoding a => AccEFL acc -> acc -> CompactString a -> PairS acc (CompactString a)
-- | like loopUp, but the size of the buffer can only become smaller
loopUpC :: Encoding a => AccEFL acc -> acc -> CompactString a -> PairS acc (CompactString a)
loopDown :: Encoding a => AccEFL acc -> acc -> CompactString a -> PairS acc (CompactString a)
loopUpFold :: Encoding a => FoldEFL acc -> acc -> CompactString a -> acc
loopDownFold :: Encoding a => FoldEFL acc -> acc -> CompactString a -> acc
-- | Unsafe functions on CompactStrings. All these functions can
-- lead to crashes if not used properly.
module Data.CompactString.Unsafe
-- | A variety of head for non-empty CompactString.
-- unsafeHead omits the check for the empty case, so there is an
-- obligation on the programmer to provide a proof that the CompactString
-- is non-empty.
unsafeHead :: Encoding a => CompactString a -> Char
-- | A variety of last for non-empty CompactString.
-- unsafeLast omits the check for the empty case, so there is an
-- obligation on the programmer to provide a proof that the CompactString
-- is non-empty.
unsafeLast :: Encoding a => CompactString a -> Char
-- | A variety of tail for non-empty CompactString.
-- unsafeTail omits the check for the empty case, so there is an
-- obligation on the programmer to provide a proof that the CompactString
-- is non-empty.
unsafeTail :: Encoding a => CompactString a -> CompactString a
-- | A variety of init for non-empty CompactString.
-- unsafeInit omits the check for the empty case, so there is an
-- obligation on the programmer to provide a proof that the CompactString
-- is non-empty.
unsafeInit :: Encoding a => CompactString a -> CompactString a
-- | Convert a ByteString to a CompactString, does not check whether the
-- ByteString represents a valid string in the encoding a.
unsafeFromByteString :: ByteString -> CompactString a
-- | Different encodings of characters into bytes.
module Data.CompactString.Encodings
-- | Tag representing the UTF-8 encoding. Use CompactString
-- UTF8 for UTF-8 encoded strings.
data UTF8
UTF8 :: UTF8
-- | Tag representing big endian encoding
data BE
BE :: BE
-- | Tag representing little endian encoding
data LE
LE :: LE
-- | The platform native endianness
type Native = LE
-- | Tag representing the UTF-16 encoding
data UTF16 endianness
UTF16 :: endianness -> UTF16 endianness
-- | Tag representing the big endian UTF-16 encoding, aka. UTF-16BE.
type UTF16BE = UTF16 BE
-- | Tag representing the little endian UTF-16 encoding, aka. UTF-16LE.
type UTF16LE = UTF16 LE
-- | Tag representing the platform native UTF-16 encoding.
type UTF16Native = UTF16 Native
-- | Tag representing the UTF-32 encoding
data UTF32 endianness
UTF32 :: endianness -> UTF32 endianness
-- | Tag representing the big endian UTF-32 encoding, aka. UTF-32BE.
type UTF32BE = UTF32 BE
-- | Tag representing the little endian UTF-32 encoding, aka. UTF-32LE.
type UTF32LE = UTF32 LE
-- | Tag representing the platform native UTF-32 encoding.
type UTF32Native = UTF32 Native
-- | Tag representing the ASCII encoding.
data ASCII
ASCII :: ASCII
-- | Tag representing the ISO 8859-1 encoding (latin 1).
data Latin1
Latin1 :: Latin1
-- | Tag representing a custom encoding optimized for memory usage.
--
-- This encoding looks like UTF-8, but is slightly more efficient. It
-- requires at most 3 byes per character, as opposed to 4 for UTF-8.
--
-- Encoding looks like:
--
--
-- 0zzzzzzz -> 0zzzzzzz
-- 00yyyyyy yzzzzzzz -> 1xxxxxxx 1yyyyyyy
-- 000xxxxx xxyyyyyy yzzzzzzz -> 1xxxxxxx 0yyyyyyy 1zzzzzzz
--
--
-- The reasoning behind the tag bits is that this allows the char to be
-- read both forwards and backwards.
data Compact
Compact :: Compact
instance Encoding Compact
instance Encoding Latin1
instance Encoding ASCII
instance Endian e => Encoding (UTF32 e)
instance Endian e => Encoding (UTF16 e)
instance Endian LE
instance Endian BE
instance Encoding UTF8
-- | A time and space-efficient implementation of strings using packed
-- Word8 arrays, suitable for high performance use, both in terms of
-- large data quantities, or high speed requirements.
--
-- This module is intended to be imported qualified, to avoid
-- name clashes with Prelude functions. eg.
--
--
-- import qualified Data.CompactString as C
--
--
-- Internally, CompactStrings are encoded ByteStrings.
module Data.CompactString
-- | A way to encode characters into bytes
class Encoding a
-- | A String using a compact, strict representation. A CompactString
-- a is encoded using encoding a, for example
-- CompactString UTF8.
data CompactString a
-- | O(1) The empty CompactString
empty :: CompactString a
-- | O(1) Convert a Char into a CompactString
singleton :: Encoding a => Char -> CompactString a
-- | O(n) Convert a String into a CompactString.
pack :: Encoding a => String -> CompactString a
-- | O(n) Converts a CompactString to a String.
unpack :: Encoding a => CompactString a -> String
-- | O(n) cons is analogous to (:) for lists, but of
-- different complexity, as it requires a memcpy.
cons :: Encoding a => Char -> CompactString a -> CompactString a
-- | O(n) Append a byte to the end of a CompactString
snoc :: Encoding a => CompactString a -> Char -> CompactString a
-- | O(n) Append two CompactStrings
append :: Encoding a => CompactString a -> CompactString a -> CompactString a
-- | O(1) Extract the first element of a CompactString, which must
-- be non-empty. An exception will be thrown in the case of an empty
-- CompactString.
head :: Encoding a => CompactString a -> Char
-- | O(1) Extract the last element of a ByteString, which must be
-- finite and non-empty. An exception will be thrown in the case of an
-- empty ByteString.
last :: Encoding a => CompactString a -> Char
-- | O(1) Extract the elements after the head of a CompactString,
-- which must be non-empty. An exception will be thrown in the case of an
-- empty CompactString.
tail :: Encoding a => CompactString a -> CompactString a
-- | O(1) Return all the elements of a CompactString except
-- the last one. An exception will be thrown in the case of an empty
-- ByteString.
init :: Encoding a => CompactString a -> CompactString a
-- | O(1) A view of the front of a CompactString.
--
--
-- headView s = if null s then Nothing else Just (head s, tail s)
--
headView :: Encoding a => CompactString a -> Maybe (Char, CompactString a)
-- | O(1) A view of the back of a CompactString.
--
--
-- lastView s = if null s then Nothing else Just (init s, last s)
--
lastView :: Encoding a => CompactString a -> Maybe (CompactString a, Char)
-- | O(1) Test whether a CompactString is empty.
null :: Encoding a => CompactString a -> Bool
-- | O(n) length returns the length of a CompactString as an
-- Int.
length :: Encoding a => CompactString a -> Int
-- | O(n) map f xs is the CompactString obtained by
-- applying f to each element of xs. This function is
-- subject to array fusion.
map :: Encoding a => (Char -> Char) -> CompactString a -> CompactString a
-- | Reverse a CompactString
reverse :: Encoding a => CompactString a -> CompactString a
-- | O(n) The intersperse function takes a Char and a
-- CompactString and `intersperses' that character between the
-- elements of the CompactString. It is analogous to the
-- intersperse function on Lists.
intersperse :: Encoding a => Char -> CompactString a -> CompactString a
-- | O(n) The intercalate function takes a
-- CompactString and a list of CompactStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: Encoding a => CompactString a -> [CompactString a] -> CompactString a
-- | The transpose function transposes the rows and columns of its
-- CompactString argument.
transpose :: Encoding a => [CompactString a] -> [CompactString a]
-- | foldl, applied to a binary operator, a starting value
-- (typically the left-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from left to
-- right. This function is subject to array fusion.
foldl :: Encoding a => (acc -> Char -> acc) -> acc -> CompactString a -> acc
-- | 'foldl\'' is like foldl, but strict in the accumulator. Though
-- actually foldl is also strict in the accumulator.
foldl' :: Encoding a => (acc -> Char -> acc) -> acc -> CompactString a -> acc
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty CompactString.
-- This function is subject to array fusion. An exception will be thrown
-- in the case of an empty CompactString.
foldl1 :: Encoding a => (Char -> Char -> Char) -> CompactString a -> Char
-- | 'foldl1\'' is like foldl1, but strict in the accumulator. An
-- exception will be thrown in the case of an empty CompactString.
foldl1' :: Encoding a => (Char -> Char -> Char) -> CompactString a -> Char
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr :: Encoding a => (Char -> acc -> acc) -> acc -> CompactString a -> acc
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr' :: Encoding a => (Char -> acc -> acc) -> acc -> CompactString a -> acc
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty CompactStrings
-- An exception will be thrown in the case of an empty CompactString.
foldr1 :: Encoding a => (Char -> Char -> Char) -> CompactString a -> Char
-- | 'foldr1\'' is a variant of foldr1, but is strict in the
-- accumulator. An exception will be thrown in the case of an empty
-- CompactString.
foldr1' :: Encoding a => (Char -> Char -> Char) -> CompactString a -> Char
-- | O(n) Concatenate a list of CompactStrings.
concat :: Encoding a => [CompactString a] -> CompactString a
-- | Map a function over a CompactString and concatenate the results
concatMap :: Encoding a => (Char -> CompactString a) -> CompactString a -> CompactString a
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if any element of the CompactString satisfies the
-- predicate.
any :: Encoding a => (Char -> Bool) -> CompactString a -> Bool
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if all elements of the CompactString satisfy the
-- predicate.
all :: Encoding a => (Char -> Bool) -> CompactString a -> Bool
-- | O(n) maximum returns the maximum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
maximum :: Encoding a => CompactString a -> Char
-- | O(n) minimum returns the minimum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
minimum :: Encoding a => CompactString a -> Char
-- | scanl is similar to foldl, but returns a list of
-- successive reduced values from the left. This function will fuse.
--
--
-- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
--
-- Note that
--
--
-- last (scanl f z xs) == foldl f z xs.
--
scanl :: Encoding a => (Char -> Char -> Char) -> Char -> CompactString a -> CompactString a
-- | scanl1 is a variant of scanl that has no starting value
-- argument. This function will fuse.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: Encoding a => (Char -> Char -> Char) -> CompactString a -> CompactString a
-- | scanr is the right-to-left dual of scanl.
scanr :: Encoding a => (Char -> Char -> Char) -> Char -> CompactString a -> CompactString a
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: Encoding a => (Char -> Char -> Char) -> CompactString a -> CompactString a
-- | The mapAccumL function behaves like a combination of map
-- and foldl; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from left to right,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumL :: Encoding a => (acc -> Char -> (acc, Char)) -> acc -> CompactString a -> (acc, CompactString a)
-- | The mapAccumR function behaves like a combination of map
-- and foldr; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from right to left,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumR :: Encoding a => (acc -> Char -> (acc, Char)) -> acc -> CompactString a -> (acc, CompactString a)
-- | O(n) map Char functions, provided with the index at each
-- position.
mapIndexed :: Encoding a => (Int -> Char -> Char) -> CompactString a -> CompactString a
-- | O(n) replicate n x is a CompactString of length
-- n with x the value of every element. The following
-- holds:
--
--
-- replicate w c = unfoldr w (\u -> Just (u,u)) c
--
replicate :: Encoding a => Int -> Char -> CompactString a
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ByteString from a seed value. The function
-- takes the element and returns Nothing if it is done producing
-- the CompactString 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.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: Encoding a => (acc -> Maybe (Char, acc)) -> acc -> CompactString a
-- | O(n) Like unfoldr, unfoldrN builds a ByteString
-- 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 :: Encoding a => Int -> (acc -> Maybe (Char, acc)) -> acc -> (CompactString a, Maybe acc)
-- | O(n) take n, applied to a CompactString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Encoding a => Int -> CompactString a -> CompactString a
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Encoding a => Int -> CompactString a -> CompactString a
-- | O(n) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Encoding a => Int -> CompactString a -> (CompactString a, CompactString a)
-- | takeWhile, applied to a predicate p and a
-- CompactString xs, returns the longest prefix (possibly empty)
-- of xs of elements that satisfy p.
takeWhile :: Encoding a => (Char -> Bool) -> CompactString a -> CompactString a
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs.
dropWhile :: Encoding a => (Char -> Bool) -> CompactString a -> CompactString a
-- | span p xs breaks the ByteString into two segments. It
-- is equivalent to (takeWhile p xs, dropWhile p
-- xs)
span :: Encoding a => (Char -> Bool) -> CompactString a -> (CompactString a, CompactString a)
-- | spanEnd behaves like span but from the end of the
-- CompactString
--
-- We have
--
--
-- spanEnd (not.isSpace) "x y z" == ("x y ","z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) cs
-- ==
-- let (x,y) = span (not.isSpace) (reverse cs) in (reverse y, reverse x)
--
spanEnd :: Encoding a => (Char -> Bool) -> CompactString a -> (CompactString a, CompactString a)
-- | break p is equivalent to span (not .
-- p).
break :: Encoding a => (Char -> Bool) -> CompactString a -> (CompactString a, CompactString a)
-- | breakEnd behaves like break but from the end of the
-- CompactString
--
--
-- breakEnd p == spanEnd (not.p)
--
breakEnd :: Encoding a => (Char -> Bool) -> CompactString a -> (CompactString a, CompactString a)
-- | The group function takes a CompactString and returns a
-- list of CompactStrings such that the concatenation of the result is
-- equal to the argument. Moreover, each sublist in the result contains
-- only equal elements. For example,
--
--
-- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--
--
-- It is a special case of groupBy, which allows the programmer to
-- supply their own equality test.
group :: Encoding a => CompactString a -> [CompactString a]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: Encoding a => (Char -> Char -> Bool) -> CompactString a -> [CompactString a]
-- | O(n) Return all initial segments of the given
-- CompactString, shortest first.
inits :: Encoding a => CompactString a -> [CompactString a]
-- | O(n) Return all final segments of the given
-- CompactString, longest first.
tails :: Encoding a => CompactString a -> [CompactString a]
-- | O(n) Break a ByteString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
-- split 'a' "aXaXaXa" == ["","X","X","X",""]
-- split 'x' "x" == ["",""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- As for all splitting functions in this library, this function does not
-- copy the substrings, it just constructs new CompactString that
-- are slices of the original.
split :: Encoding a => Char -> CompactString a -> [CompactString a]
-- | O(n) Splits a CompactString 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 (=='a') "aabbaca" == ["","","bb","c",""]
-- splitWith (=='a') [] == []
--
splitWith :: Encoding a => (Char -> Bool) -> CompactString a -> [CompactString a]
-- | lines breaks a CompactString up into a list of
-- CompactStrings at newline Chars. The resulting strings do not contain
-- newlines.
lines :: Encoding a => CompactString a -> [CompactString a]
-- | words breaks a ByteString up into a list of words, which were
-- delimited by Chars representing white space. And
--
--
-- words = filter (not . null) . splitWith isSpace
--
words :: Encoding a => CompactString a -> [CompactString a]
-- | unlines is an inverse operation to lines. It joins
-- lines, after appending a terminating newline to each.
unlines :: Encoding a => [CompactString a] -> CompactString a
-- | The unwords function is analogous to the unlines
-- function, on words.
unwords :: Encoding a => [CompactString a] -> CompactString a
-- | O(n) The isPrefixOf function takes two CompactString and
-- returns True iff the first is a prefix of the second.
isPrefixOf :: CompactString a -> CompactString a -> Bool
-- | O(n) The isSuffixOf function takes two CompactString and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
isSuffixOf :: Encoding a => CompactString a -> CompactString a -> Bool
-- | Check whether one string is a substring of another. isInfixOf p
-- s is equivalent to not (null (findSubstrings p s)).
isInfixOf :: Encoding a => CompactString a -> CompactString a -> Bool
-- | Get the first index of a substring in another string, or
-- Nothing if the string is not found. findSubstring p s
-- is equivalent to listToMaybe (findSubstrings p s).
findSubstring :: Encoding a => CompactString a -> CompactString a -> Maybe Int
-- | Find the indexes of all (possibly overlapping) occurances of a
-- substring in a string. This function uses the Knuth-Morris-Pratt
-- string matching algorithm.
findSubstrings :: Encoding a => CompactString a -> CompactString a -> [Int]
-- | O(n) elem is the CompactString membership
-- predicate.
elem :: Encoding a => Char -> CompactString a -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Encoding a => Char -> CompactString a -> Bool
-- | O(n) The find function takes a predicate and a
-- CompactString, 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 `index` n) ; _ -> Nothing
--
find :: Encoding a => (Char -> Bool) -> CompactString a -> Maybe Char
-- | O(n) filter, applied to a predicate and a
-- CompactString, returns a CompactString containing those
-- characters that satisfy the predicate. This function is subject to
-- array fusion.
filter :: Encoding a => (Char -> Bool) -> CompactString a -> CompactString a
-- | O(n) partition, applied to a predicate and a
-- CompactString, returns a pair of CompactStrings. The first
-- containing those characters that satisfy the predicate, the second
-- containg those that don't.
partition :: Encoding a => (Char -> Bool) -> CompactString a -> (CompactString a, CompactString a)
-- | O(n) CompactString index (subscript) operator, starting
-- from 0.
index :: Encoding a => CompactString a -> Int -> Char
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ByteString which is equal to the
-- query element, or Nothing if there is no such element.
elemIndex :: Encoding a => Char -> CompactString a -> 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 :: Encoding a => Char -> CompactString a -> [Int]
-- | O(n) The elemIndexEnd function returns the last index of
-- the element in the given CompactString which is equal to the
-- query element, or Nothing if there is no such element. The
-- following holds:
--
--
-- elemIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--
elemIndexEnd :: Encoding a => Char -> CompactString a -> Maybe Int
-- | The findIndex function takes a predicate and a
-- CompactString and returns the index of the first element in the
-- CompactString satisfying the predicate.
findIndex :: Encoding a => (Char -> Bool) -> CompactString a -> Maybe Int
-- | O(n) The findIndexEnd function returns the last index of
-- the element in the given CompactString which satisfies the
-- predicate, or Nothing if there is no such element. The
-- following holds:
--
--
-- findIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` findIndex c (reverse xs)
--
findIndexEnd :: Encoding a => (Char -> Bool) -> CompactString a -> Maybe Int
-- | The findIndices function extends findIndex, by returning
-- the indices of all elements satisfying the predicate, in ascending
-- order.
findIndices :: Encoding a => (Char -> Bool) -> CompactString a -> [Int]
-- | count returns the number of times its argument appears in the
-- CompactString
--
--
-- count c = length . elemIndices c
--
count :: Encoding a => Char -> CompactString a -> Int
-- | O(n) zip takes two ByteStrings and returns a list of
-- corresponding pairs of bytes. If one input ByteString is short, excess
-- elements of the longer ByteString are discarded. This is equivalent to
-- a pair of unpack operations.
zip :: Encoding a => CompactString a -> CompactString a -> [(Char, Char)]
-- | zipWith generalises zip by zipping with the function
-- given as the first argument, instead of a tupling function. For
-- example, zipWith (+) is applied to two ByteStrings to
-- produce the list of corresponding sums.
zipWith :: Encoding a => (Char -> Char -> b) -> CompactString a -> CompactString a -> [b]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two CompactStrings, to build a 3rd.
-- Rewrite rules are used to automatically covert zipWith into zipWith'
-- when a pack is performed on the result of zipWith, but we also export
-- it for convenience.
zipWith' :: Encoding a => (Char -> Char -> Char) -> CompactString a -> CompactString a -> CompactString a
-- | O(n) unzip transforms a list of pairs of bytes into a
-- pair of CompactStrings. Note that this performs two pack
-- operations.
unzip :: Encoding a => [(Char, Char)] -> (CompactString a, CompactString a)
-- | O(n log n) Sort a CompactString
sort :: Encoding a => CompactString a -> CompactString a
-- | Compare two bytestrings, possibly with a different encoding.
compare' :: (Encoding a, Encoding b) => CompactString a -> CompactString b -> Ordering
-- | Convert a CompactString to a ByteString
toByteString :: Encoding a => CompactString a -> ByteString
-- | Convert a ByteString to a CompactString. Fails if the ByteString is
-- not a valid encoded string.
fromByteString :: (Encoding a, MonadPlus m) => ByteString -> m (CompactString a)
-- | Convert a ByteString to a CompactString. Raises an error if the
-- ByteString is not a valid encoded string.
fromByteString_ :: Encoding a => ByteString -> CompactString a
-- | Validates a CompactString. If the string is invalid, fails, otherwise
-- returns the input.
validate :: (Encoding a, MonadPlus m) => CompactString a -> m (CompactString a)
-- | Validates a CompactString. If the string is invalid, throws an error,
-- otherwise returns the input.
validate_ :: Encoding a => CompactString a -> CompactString a
-- | Convert between two different encodings, fails if conversion is not
-- possible.
recode :: (Encoding a, Encoding b, MonadPlus m) => CompactString a -> m (CompactString b)
-- | Convert between two different encodings, raises an error if conversion
-- is not possible.
recode_ :: (Encoding a, Encoding b) => CompactString a -> CompactString b
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode e = liftM toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Fails if the string is cannot be encoded in the target encoding.
encode :: (Encoding a, Encoding e, MonadPlus m) => e -> CompactString a -> m ByteString
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode_ e = toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encode_ :: (Encoding a, Encoding e) => e -> CompactString a -> ByteString
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode e = recode =<< fromByteString
--
--
-- but it might be faster for some combinations of encodings.
--
-- Fails if the ByteString is not a valid encoded string or if the string
-- can not be represented in the encoding a.
decode :: (Encoding a, Encoding e, MonadPlus m) => e -> ByteString -> m (CompactString a)
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode_ e = recode_ . fromByteString_
--
--
-- but it might be faster for some combinations of encodings.
--
-- Raises an error if the ByteString is not a valid encoded string or if
-- the string can not be represented in the encoding a.
decode_ :: (Encoding a, Encoding e) => e -> ByteString -> CompactString a
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Fails if the string is cannot be encoded in the target encoding.
encodeBOM :: (Encoding a, Encoding e, MonadPlus m) => e -> CompactString a -> m ByteString
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encodeBOM_ :: (Encoding a, Encoding e) => e -> CompactString a -> ByteString
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Fails if the input is not a valid encoded string or if the string can
-- not be represented in the encoding a.
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM :: (Encoding a, MonadPlus m) => ByteString -> m (CompactString a)
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Raises an error if the input is not a valid encoded string or if the
-- string can not be represented in the encoding a.
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM_ :: Encoding a => ByteString -> CompactString a
-- | Read a line from stdin.
getLine :: Encoding a => IO (CompactString a)
-- | getContents. Equivalent to hGetContents stdin
--
-- Input is assumed to be in the encoding a, this may not be
-- appropriate.
getContents :: Encoding a => IO (CompactString a)
-- | Write a CompactString to stdout.
--
-- Output is written in the encoding a, this may not be
-- appropriate.
putStr :: Encoding a => CompactString a -> IO ()
-- | Write a CompactString to stdout, appending a newline character.
--
-- Output is written in the encoding a, this may not be
-- appropriate.
putStrLn :: Encoding a => CompactString a -> IO ()
-- | The interact function takes a function of type CompactString ->
-- CompactString as its argument. The entire input from the standard
-- input device is passed to this function as its argument, and the
-- resulting string is output on the standard output device. It's great
-- for writing one line programs!
interact :: Encoding a => (CompactString a -> CompactString a) -> IO ()
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- Files are assumed to be in the encoding a.
readFile :: Encoding a => FilePath -> IO (CompactString a)
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- The encoding of the file is determined based on a Byte Order Mark, see
-- decodeBOM.
readFile' :: Encoding a => FilePath -> IO (CompactString a)
-- | Write a CompactString to a file.
--
-- Files are written using the encoding a.
writeFile :: Encoding a => FilePath -> CompactString a -> IO ()
-- | Write a CompactString to a file.
--
-- Files are written using the encoding a. A Byte Order Mark is
-- also written.
writeFile' :: Encoding a => FilePath -> CompactString a -> IO ()
-- | Append a CompactString to a file.
--
-- Files are written using the encoding a.
appendFile :: Encoding a => FilePath -> CompactString a -> IO ()
-- | Append a CompactString to a file.
--
-- The encoding of the file is determined based on a Byte Order Mark. If
-- the file is empty, it is written using the encoding a with a
-- Byte Order Mark. If the encoding can not be determined the file is
-- assumed to be UTF-8.
appendFile' :: Encoding a => FilePath -> CompactString a -> IO ()
-- | Read a line from a handle
hGetLine :: Encoding a => Handle -> IO (CompactString a)
-- | Read entire handle contents into a CompactString.
--
-- The handle is interpreted as the encoding a.
hGetContents :: Encoding a => Handle -> IO (CompactString a)
-- | Read entire handle contents into a CompactString.
--
-- The encoding is determined based on a Byte Order Mark, see
-- decodeBOM.
hGetContents' :: Encoding a => Handle -> IO (CompactString a)
-- | Read a CompactString directly from the specified Handle.
--
-- The handle is interpreted as the encoding a.
hGet :: Encoding a => Handle -> Int -> IO (CompactString a)
-- | hGetNonBlocking is identical to hGet, except that it will never
-- block waiting for data to become available, instead it returns only
-- whatever data is available.
--
-- The handle is interpreted as the encoding a.
hGetNonBlocking :: Encoding a => Handle -> Int -> IO (CompactString a)
-- | Outputs a CompactString to the specified Handle.
--
-- Output is written in the encoding a.
hPut :: Encoding a => Handle -> CompactString a -> IO ()
-- | A synonym for hPut, for compatibility
hPutStr :: Encoding a => Handle -> CompactString a -> IO ()
-- | Write a CompactString to a handle, appending a newline byte
--
-- Output is written in the encoding a.
hPutStrLn :: Encoding a => Handle -> CompactString a -> IO ()
instance Encoding a => IsString (CompactString a)
instance Encoding a => Show (CompactString a)
instance Encoding a => Ord (CompactString a)
instance Encoding a => Monoid (CompactString a)
instance Encoding a => Eq (CompactString a)
-- | CompactString specialized to ASCII. Note that not all characters can
-- be encoded in ASCII, if encoding is not possible the function will
-- raise an error..
--
-- This module can be used to reduce the need for type signatures, since
-- in most cases only a single encoding is used.
module Data.CompactString.ASCII
-- | CompactString specialized to ASCII.
type CompactString = CompactString ASCII
-- | O(1) The empty CompactString
empty :: CompactString
-- | O(1) Convert a Char into a CompactString
singleton :: Char -> CompactString
-- | O(n) Convert a String into a CompactString.
pack :: String -> CompactString
-- | O(n) Converts a CompactString to a String.
unpack :: CompactString -> String
-- | O(n) cons is analogous to (:) for lists, but of
-- different complexity, as it requires a memcpy.
cons :: Char -> CompactString -> CompactString
-- | O(n) Append a byte to the end of a CompactString
snoc :: CompactString -> Char -> CompactString
-- | O(n) Append two CompactStrings
append :: CompactString -> CompactString -> CompactString
-- | O(1) Extract the first element of a CompactString, which must
-- be non-empty. An exception will be thrown in the case of an empty
-- CompactString.
head :: CompactString -> Char
-- | O(1) Extract the last element of a ByteString, which must be
-- finite and non-empty. An exception will be thrown in the case of an
-- empty ByteString.
last :: CompactString -> Char
-- | O(1) Extract the elements after the head of a CompactString,
-- which must be non-empty. An exception will be thrown in the case of an
-- empty CompactString.
tail :: CompactString -> CompactString
-- | O(1) Return all the elements of a CompactString except
-- the last one. An exception will be thrown in the case of an empty
-- ByteString.
init :: CompactString -> CompactString
-- | O(1) A view of the front of a CompactString.
--
--
-- headView s = if null s then Nothing else Just (head s, tail s)
--
headView :: CompactString -> Maybe (Char, CompactString)
-- | O(1) A view of the back of a CompactString.
--
--
-- lastView s = if null s then Nothing else Just (init s, last s)
--
lastView :: CompactString -> Maybe (CompactString, Char)
-- | O(1) Test whether a CompactString is empty.
null :: CompactString -> Bool
-- | O(n) length returns the length of a CompactString as an
-- Int.
length :: CompactString -> Int
-- | O(n) map f xs is the CompactString obtained by
-- applying f to each element of xs. This function is
-- subject to array fusion.
map :: (Char -> Char) -> CompactString -> CompactString
-- | Reverse a CompactString
reverse :: CompactString -> CompactString
-- | O(n) The intersperse function takes a Char and a
-- CompactString and `intersperses' that character between the
-- elements of the CompactString. It is analogous to the
-- intersperse function on Lists.
intersperse :: Char -> CompactString -> CompactString
-- | O(n) The intercalate function takes a
-- CompactString and a list of CompactStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: CompactString -> [CompactString] -> CompactString
-- | The transpose function transposes the rows and columns of its
-- CompactString argument.
transpose :: [CompactString] -> [CompactString]
-- | foldl, applied to a binary operator, a starting value
-- (typically the left-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from left to
-- right. This function is subject to array fusion.
foldl :: (acc -> Char -> acc) -> acc -> CompactString -> acc
-- | 'foldl\'' is like foldl, but strict in the accumulator. Though
-- actually foldl is also strict in the accumulator.
foldl' :: (acc -> Char -> acc) -> acc -> CompactString -> acc
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty CompactString.
-- This function is subject to array fusion. An exception will be thrown
-- in the case of an empty CompactString.
foldl1 :: (Char -> Char -> Char) -> CompactString -> Char
-- | 'foldl1\'' is like foldl1, but strict in the accumulator. An
-- exception will be thrown in the case of an empty CompactString.
foldl1' :: (Char -> Char -> Char) -> CompactString -> Char
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr :: (Char -> acc -> acc) -> acc -> CompactString -> acc
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr' :: (Char -> acc -> acc) -> acc -> CompactString -> acc
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty CompactStrings
-- An exception will be thrown in the case of an empty CompactString.
foldr1 :: (Char -> Char -> Char) -> CompactString -> Char
-- | 'foldr1\'' is a variant of foldr1, but is strict in the
-- accumulator. An exception will be thrown in the case of an empty
-- CompactString.
foldr1' :: (Char -> Char -> Char) -> CompactString -> Char
-- | O(n) Concatenate a list of CompactStrings.
concat :: [CompactString] -> CompactString
-- | Map a function over a CompactString and concatenate the results
concatMap :: (Char -> CompactString) -> CompactString -> CompactString
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if any element of the CompactString satisfies the
-- predicate.
any :: (Char -> Bool) -> CompactString -> Bool
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if all elements of the CompactString satisfy the
-- predicate.
all :: (Char -> Bool) -> CompactString -> Bool
-- | O(n) maximum returns the maximum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
maximum :: CompactString -> Char
-- | O(n) minimum returns the minimum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
minimum :: CompactString -> Char
-- | scanl is similar to foldl, but returns a list of
-- successive reduced values from the left. This function will fuse.
--
--
-- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
--
-- Note that
--
--
-- last (scanl f z xs) == foldl f z xs.
--
scanl :: (Char -> Char -> Char) -> Char -> CompactString -> CompactString
-- | scanl1 is a variant of scanl that has no starting value
-- argument. This function will fuse.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Char -> Char -> Char) -> CompactString -> CompactString
-- | scanr is the right-to-left dual of scanl.
scanr :: (Char -> Char -> Char) -> Char -> CompactString -> CompactString
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: (Char -> Char -> Char) -> CompactString -> CompactString
-- | The mapAccumL function behaves like a combination of map
-- and foldl; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from left to right,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> CompactString -> (acc, CompactString)
-- | The mapAccumR function behaves like a combination of map
-- and foldr; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from right to left,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> CompactString -> (acc, CompactString)
-- | O(n) map Char functions, provided with the index at each
-- position.
mapIndexed :: (Int -> Char -> Char) -> CompactString -> CompactString
-- | O(n) replicate n x is a CompactString 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 -> Char -> CompactString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ByteString from a seed value. The function
-- takes the element and returns Nothing if it is done producing
-- the CompactString 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.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (acc -> Maybe (Char, acc)) -> acc -> CompactString
-- | O(n) Like unfoldr, unfoldrN builds a ByteString
-- 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 -> (acc -> Maybe (Char, acc)) -> acc -> (CompactString, Maybe acc)
-- | O(n) take n, applied to a CompactString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Int -> CompactString -> CompactString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Int -> CompactString -> CompactString
-- | O(n) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Int -> CompactString -> (CompactString, CompactString)
-- | takeWhile, applied to a predicate p and a
-- CompactString xs, returns the longest prefix (possibly empty)
-- of xs of elements that satisfy p.
takeWhile :: (Char -> Bool) -> CompactString -> CompactString
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs.
dropWhile :: (Char -> Bool) -> CompactString -> CompactString
-- | span p xs breaks the ByteString into two segments. It
-- is equivalent to (takeWhile p xs, dropWhile p
-- xs)
span :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | spanEnd behaves like span but from the end of the
-- CompactString
--
-- We have
--
--
-- spanEnd (not.isSpace) "x y z" == ("x y ","z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) cs
-- ==
-- let (x,y) = span (not.isSpace) (reverse cs) in (reverse y, reverse x)
--
spanEnd :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | break p is equivalent to span (not .
-- p).
break :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | breakEnd behaves like break but from the end of the
-- CompactString
--
--
-- breakEnd p == spanEnd (not.p)
--
breakEnd :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | The group function takes a CompactString and returns a
-- list of CompactStrings such that the concatenation of the result is
-- equal to the argument. Moreover, each sublist in the result contains
-- only equal elements. For example,
--
--
-- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--
--
-- It is a special case of groupBy, which allows the programmer to
-- supply their own equality test.
group :: CompactString -> [CompactString]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: (Char -> Char -> Bool) -> CompactString -> [CompactString]
-- | O(n) Return all initial segments of the given
-- CompactString, shortest first.
inits :: CompactString -> [CompactString]
-- | O(n) Return all final segments of the given
-- CompactString, longest first.
tails :: CompactString -> [CompactString]
-- | O(n) Break a ByteString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
-- split 'a' "aXaXaXa" == ["","X","X","X",""]
-- split 'x' "x" == ["",""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- As for all splitting functions in this library, this function does not
-- copy the substrings, it just constructs new CompactString that
-- are slices of the original.
split :: Char -> CompactString -> [CompactString]
-- | O(n) Splits a CompactString 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 (=='a') "aabbaca" == ["","","bb","c",""]
-- splitWith (=='a') [] == []
--
splitWith :: (Char -> Bool) -> CompactString -> [CompactString]
-- | lines breaks a CompactString up into a list of
-- CompactStrings at newline Chars. The resulting strings do not contain
-- newlines.
lines :: CompactString -> [CompactString]
-- | words breaks a ByteString up into a list of words, which were
-- delimited by Chars representing white space. And
--
--
-- words = filter (not . null) . splitWith isSpace
--
words :: CompactString -> [CompactString]
-- | unlines is an inverse operation to lines. It joins
-- lines, after appending a terminating newline to each.
unlines :: [CompactString] -> CompactString
-- | The unwords function is analogous to the unlines
-- function, on words.
unwords :: [CompactString] -> CompactString
-- | O(n) The isPrefixOf function takes two CompactString and
-- returns True iff the first is a prefix of the second.
isPrefixOf :: CompactString -> CompactString -> Bool
-- | O(n) The isSuffixOf function takes two CompactString and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
isSuffixOf :: CompactString -> CompactString -> Bool
-- | Check whether one string is a substring of another. isInfixOf p
-- s is equivalent to not (null (findSubstrings p s)).
isInfixOf :: CompactString -> CompactString -> Bool
-- | Get the first index of a substring in another string, or
-- Nothing if the string is not found. findSubstring p s
-- is equivalent to listToMaybe (findSubstrings p s).
findSubstring :: CompactString -> CompactString -> Maybe Int
-- | Find the indexes of all (possibly overlapping) occurances of a
-- substring in a string. This function uses the Knuth-Morris-Pratt
-- string matching algorithm.
findSubstrings :: CompactString -> CompactString -> [Int]
-- | O(n) elem is the CompactString membership
-- predicate.
elem :: Char -> CompactString -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Char -> CompactString -> Bool
-- | O(n) The find function takes a predicate and a
-- CompactString, 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 `index` n) ; _ -> Nothing
--
find :: (Char -> Bool) -> CompactString -> Maybe Char
-- | O(n) filter, applied to a predicate and a
-- CompactString, returns a CompactString containing those
-- characters that satisfy the predicate. This function is subject to
-- array fusion.
filter :: (Char -> Bool) -> CompactString -> CompactString
-- | O(n) partition, applied to a predicate and a
-- CompactString, returns a pair of CompactStrings. The first
-- containing those characters that satisfy the predicate, the second
-- containg those that don't.
partition :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | O(n) CompactString index (subscript) operator, starting
-- from 0.
index :: CompactString -> Int -> Char
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ByteString which is equal to the
-- query element, or Nothing if there is no such element.
elemIndex :: Char -> CompactString -> 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 :: Char -> CompactString -> [Int]
-- | O(n) The elemIndexEnd function returns the last index of
-- the element in the given CompactString which is equal to the
-- query element, or Nothing if there is no such element. The
-- following holds:
--
--
-- elemIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--
elemIndexEnd :: Char -> CompactString -> Maybe Int
-- | The findIndex function takes a predicate and a
-- CompactString and returns the index of the first element in the
-- CompactString satisfying the predicate.
findIndex :: (Char -> Bool) -> CompactString -> Maybe Int
-- | O(n) The findIndexEnd function returns the last index of
-- the element in the given CompactString which satisfies the
-- predicate, or Nothing if there is no such element. The
-- following holds:
--
--
-- findIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` findIndex c (reverse xs)
--
findIndexEnd :: (Char -> Bool) -> CompactString -> Maybe Int
-- | The findIndices function extends findIndex, by returning
-- the indices of all elements satisfying the predicate, in ascending
-- order.
findIndices :: (Char -> Bool) -> CompactString -> [Int]
-- | count returns the number of times its argument appears in the
-- CompactString
--
--
-- count c = length . elemIndices c
--
count :: Char -> CompactString -> Int
-- | O(n) zip takes two ByteStrings and returns a list of
-- corresponding pairs of bytes. If one input ByteString is short, excess
-- elements of the longer ByteString are discarded. This is equivalent to
-- a pair of unpack operations.
zip :: CompactString -> CompactString -> [(Char, Char)]
-- | zipWith generalises zip by zipping with the function
-- given as the first argument, instead of a tupling function. For
-- example, zipWith (+) is applied to two ByteStrings to
-- produce the list of corresponding sums.
zipWith :: (Char -> Char -> b) -> CompactString -> CompactString -> [b]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two CompactStrings, to build a 3rd.
-- Rewrite rules are used to automatically covert zipWith into zipWith'
-- when a pack is performed on the result of zipWith, but we also export
-- it for convenience.
zipWith' :: (Char -> Char -> Char) -> CompactString -> CompactString -> CompactString
-- | O(n) unzip transforms a list of pairs of bytes into a
-- pair of CompactStrings. Note that this performs two pack
-- operations.
unzip :: [(Char, Char)] -> (CompactString, CompactString)
-- | O(n log n) Sort a CompactString
sort :: CompactString -> CompactString
-- | Convert a CompactString to a ByteString
toByteString :: CompactString -> ByteString
-- | Convert a ByteString to a CompactString. Fails if the ByteString is
-- not a valid encoded string.
fromByteString :: MonadPlus m => ByteString -> m (CompactString)
-- | Convert a ByteString to a CompactString. Raises an error if the
-- ByteString is not a valid encoded string.
fromByteString_ :: ByteString -> CompactString
-- | Validates a CompactString. If the string is invalid, fails, otherwise
-- returns the input.
validate :: MonadPlus m => CompactString -> m (CompactString)
-- | Validates a CompactString. If the string is invalid, throws an error,
-- otherwise returns the input.
validate_ :: CompactString -> CompactString
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode e = liftM toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Fails if the string is cannot be encoded in the target encoding.
encode :: (Encoding e, MonadPlus m) => e -> CompactString -> m ByteString
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode_ e = toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encode_ :: Encoding e => e -> CompactString -> ByteString
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode e = recode =<< fromByteString
--
--
-- but it might be faster for some combinations of encodings.
--
-- Fails if the ByteString is not a valid encoded string or if the string
-- can not be represented in ASCII.
decode :: (Encoding e, MonadPlus m) => e -> ByteString -> m (CompactString)
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode_ e = recode_ . fromByteString_
--
--
-- but it might be faster for some combinations of encodings.
--
-- Raises an error if the ByteString is not a valid encoded string or if
-- the string can not be represented in ASCII.
decode_ :: Encoding e => e -> ByteString -> CompactString
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Fails if the string is cannot be encoded in the target encoding.
encodeBOM :: (Encoding e, MonadPlus m) => e -> CompactString -> m ByteString
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encodeBOM_ :: Encoding e => e -> CompactString -> ByteString
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Fails if the input is not a valid encoded string or if the string can
-- not be represented in ASCII.
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM :: MonadPlus m => ByteString -> m (CompactString)
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Raises an error if the input is not a valid encoded string or if the
-- string can not be represented in ASCII.
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM_ :: ByteString -> CompactString
-- | Read a line from stdin.
getLine :: IO (CompactString)
-- | getContents. Equivalent to hGetContents stdin
--
-- Input is assumed to be in ASCII, this may not be appropriate.
getContents :: IO (CompactString)
-- | Write a CompactString to stdout.
--
-- Output is written in ASCII, this may not be appropriate.
putStr :: CompactString -> IO ()
-- | Write a CompactString to stdout, appending a newline character.
--
-- Output is written in ASCII, this may not be appropriate.
putStrLn :: CompactString -> IO ()
-- | The interact function takes a function of type CompactString ->
-- CompactString as its argument. The entire input from the standard
-- input device is passed to this function as its argument, and the
-- resulting string is output on the standard output device. It's great
-- for writing one line programs!
interact :: (CompactString -> CompactString) -> IO ()
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- Files are assumed to be in ASCII.
readFile :: FilePath -> IO (CompactString)
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- The encoding of the file is determined based on a Byte Order Mark, see
-- decodeBOM.
readFile' :: FilePath -> IO (CompactString)
-- | Write a CompactString to a file.
--
-- Files are written using ASCII.
writeFile :: FilePath -> CompactString -> IO ()
-- | Write a CompactString to a file.
--
-- Files are written using ASCII. A Byte Order Mark is also written.
writeFile' :: FilePath -> CompactString -> IO ()
-- | Append a CompactString to a file.
--
-- Files are written using ASCII.
appendFile :: FilePath -> CompactString -> IO ()
-- | Append a CompactString to a file.
--
-- The encoding of the file is determined based on a Byte Order Mark. If
-- the file is empty, it is written using ASCII with a Byte Order Mark.
-- If the encoding can not be determined the file is assumed to be UTF-8.
appendFile' :: FilePath -> CompactString -> IO ()
-- | Read a line from a handle
hGetLine :: Handle -> IO (CompactString)
-- | Read entire handle contents into a CompactString.
--
-- The handle is interpreted as ASCII.
hGetContents :: Handle -> IO (CompactString)
-- | Read entire handle contents into a CompactString.
--
-- The encoding is determined based on a Byte Order Mark, see
-- decodeBOM.
hGetContents' :: Handle -> IO (CompactString)
-- | Read a CompactString directly from the specified Handle.
--
-- The handle is interpreted as ASCII.
hGet :: Handle -> Int -> IO (CompactString)
-- | hGetNonBlocking is identical to hGet, except that it will never
-- block waiting for data to become available, instead it returns only
-- whatever data is available.
--
-- The handle is interpreted as ASCII.
hGetNonBlocking :: Handle -> Int -> IO (CompactString)
-- | Outputs a CompactString to the specified Handle.
--
-- Output is written in ASCII.
hPut :: Handle -> CompactString -> IO ()
-- | A synonym for hPut, for compatibility
hPutStr :: Handle -> CompactString -> IO ()
-- | Write a CompactString to a handle, appending a newline byte
--
-- Output is written in ASCII.
hPutStrLn :: Handle -> CompactString -> IO ()
-- | CompactString specialized to platform native UTF-16.
--
-- This module can be used to reduce the need for type signatures, since
-- in most cases only a single encoding is used.
module Data.CompactString.UTF16
-- | CompactString specialized to UTF-16.
type CompactString = CompactString UTF16Native
-- | O(1) The empty CompactString
empty :: CompactString
-- | O(1) Convert a Char into a CompactString
singleton :: Char -> CompactString
-- | O(n) Convert a String into a CompactString.
pack :: String -> CompactString
-- | O(n) Converts a CompactString to a String.
unpack :: CompactString -> String
-- | O(n) cons is analogous to (:) for lists, but of
-- different complexity, as it requires a memcpy.
cons :: Char -> CompactString -> CompactString
-- | O(n) Append a byte to the end of a CompactString
snoc :: CompactString -> Char -> CompactString
-- | O(n) Append two CompactStrings
append :: CompactString -> CompactString -> CompactString
-- | O(1) Extract the first element of a CompactString, which must
-- be non-empty. An exception will be thrown in the case of an empty
-- CompactString.
head :: CompactString -> Char
-- | O(1) Extract the last element of a ByteString, which must be
-- finite and non-empty. An exception will be thrown in the case of an
-- empty ByteString.
last :: CompactString -> Char
-- | O(1) Extract the elements after the head of a CompactString,
-- which must be non-empty. An exception will be thrown in the case of an
-- empty CompactString.
tail :: CompactString -> CompactString
-- | O(1) Return all the elements of a CompactString except
-- the last one. An exception will be thrown in the case of an empty
-- ByteString.
init :: CompactString -> CompactString
-- | O(1) A view of the front of a CompactString.
--
--
-- headView s = if null s then Nothing else Just (head s, tail s)
--
headView :: CompactString -> Maybe (Char, CompactString)
-- | O(1) A view of the back of a CompactString.
--
--
-- lastView s = if null s then Nothing else Just (init s, last s)
--
lastView :: CompactString -> Maybe (CompactString, Char)
-- | O(1) Test whether a CompactString is empty.
null :: CompactString -> Bool
-- | O(n) length returns the length of a CompactString as an
-- Int.
length :: CompactString -> Int
-- | O(n) map f xs is the CompactString obtained by
-- applying f to each element of xs. This function is
-- subject to array fusion.
map :: (Char -> Char) -> CompactString -> CompactString
-- | Reverse a CompactString
reverse :: CompactString -> CompactString
-- | O(n) The intersperse function takes a Char and a
-- CompactString and `intersperses' that character between the
-- elements of the CompactString. It is analogous to the
-- intersperse function on Lists.
intersperse :: Char -> CompactString -> CompactString
-- | O(n) The intercalate function takes a
-- CompactString and a list of CompactStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: CompactString -> [CompactString] -> CompactString
-- | The transpose function transposes the rows and columns of its
-- CompactString argument.
transpose :: [CompactString] -> [CompactString]
-- | foldl, applied to a binary operator, a starting value
-- (typically the left-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from left to
-- right. This function is subject to array fusion.
foldl :: (acc -> Char -> acc) -> acc -> CompactString -> acc
-- | 'foldl\'' is like foldl, but strict in the accumulator. Though
-- actually foldl is also strict in the accumulator.
foldl' :: (acc -> Char -> acc) -> acc -> CompactString -> acc
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty CompactString.
-- This function is subject to array fusion. An exception will be thrown
-- in the case of an empty CompactString.
foldl1 :: (Char -> Char -> Char) -> CompactString -> Char
-- | 'foldl1\'' is like foldl1, but strict in the accumulator. An
-- exception will be thrown in the case of an empty CompactString.
foldl1' :: (Char -> Char -> Char) -> CompactString -> Char
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr :: (Char -> acc -> acc) -> acc -> CompactString -> acc
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr' :: (Char -> acc -> acc) -> acc -> CompactString -> acc
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty CompactStrings
-- An exception will be thrown in the case of an empty CompactString.
foldr1 :: (Char -> Char -> Char) -> CompactString -> Char
-- | 'foldr1\'' is a variant of foldr1, but is strict in the
-- accumulator. An exception will be thrown in the case of an empty
-- CompactString.
foldr1' :: (Char -> Char -> Char) -> CompactString -> Char
-- | O(n) Concatenate a list of CompactStrings.
concat :: [CompactString] -> CompactString
-- | Map a function over a CompactString and concatenate the results
concatMap :: (Char -> CompactString) -> CompactString -> CompactString
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if any element of the CompactString satisfies the
-- predicate.
any :: (Char -> Bool) -> CompactString -> Bool
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if all elements of the CompactString satisfy the
-- predicate.
all :: (Char -> Bool) -> CompactString -> Bool
-- | O(n) maximum returns the maximum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
maximum :: CompactString -> Char
-- | O(n) minimum returns the minimum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
minimum :: CompactString -> Char
-- | scanl is similar to foldl, but returns a list of
-- successive reduced values from the left. This function will fuse.
--
--
-- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
--
-- Note that
--
--
-- last (scanl f z xs) == foldl f z xs.
--
scanl :: (Char -> Char -> Char) -> Char -> CompactString -> CompactString
-- | scanl1 is a variant of scanl that has no starting value
-- argument. This function will fuse.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Char -> Char -> Char) -> CompactString -> CompactString
-- | scanr is the right-to-left dual of scanl.
scanr :: (Char -> Char -> Char) -> Char -> CompactString -> CompactString
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: (Char -> Char -> Char) -> CompactString -> CompactString
-- | The mapAccumL function behaves like a combination of map
-- and foldl; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from left to right,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> CompactString -> (acc, CompactString)
-- | The mapAccumR function behaves like a combination of map
-- and foldr; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from right to left,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> CompactString -> (acc, CompactString)
-- | O(n) map Char functions, provided with the index at each
-- position.
mapIndexed :: (Int -> Char -> Char) -> CompactString -> CompactString
-- | O(n) replicate n x is a CompactString 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 -> Char -> CompactString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ByteString from a seed value. The function
-- takes the element and returns Nothing if it is done producing
-- the CompactString 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.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (acc -> Maybe (Char, acc)) -> acc -> CompactString
-- | O(n) Like unfoldr, unfoldrN builds a ByteString
-- 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 -> (acc -> Maybe (Char, acc)) -> acc -> (CompactString, Maybe acc)
-- | O(n) take n, applied to a CompactString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Int -> CompactString -> CompactString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Int -> CompactString -> CompactString
-- | O(n) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Int -> CompactString -> (CompactString, CompactString)
-- | takeWhile, applied to a predicate p and a
-- CompactString xs, returns the longest prefix (possibly empty)
-- of xs of elements that satisfy p.
takeWhile :: (Char -> Bool) -> CompactString -> CompactString
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs.
dropWhile :: (Char -> Bool) -> CompactString -> CompactString
-- | span p xs breaks the ByteString into two segments. It
-- is equivalent to (takeWhile p xs, dropWhile p
-- xs)
span :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | spanEnd behaves like span but from the end of the
-- CompactString
--
-- We have
--
--
-- spanEnd (not.isSpace) "x y z" == ("x y ","z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) cs
-- ==
-- let (x,y) = span (not.isSpace) (reverse cs) in (reverse y, reverse x)
--
spanEnd :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | break p is equivalent to span (not .
-- p).
break :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | breakEnd behaves like break but from the end of the
-- CompactString
--
--
-- breakEnd p == spanEnd (not.p)
--
breakEnd :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | The group function takes a CompactString and returns a
-- list of CompactStrings such that the concatenation of the result is
-- equal to the argument. Moreover, each sublist in the result contains
-- only equal elements. For example,
--
--
-- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--
--
-- It is a special case of groupBy, which allows the programmer to
-- supply their own equality test.
group :: CompactString -> [CompactString]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: (Char -> Char -> Bool) -> CompactString -> [CompactString]
-- | O(n) Return all initial segments of the given
-- CompactString, shortest first.
inits :: CompactString -> [CompactString]
-- | O(n) Return all final segments of the given
-- CompactString, longest first.
tails :: CompactString -> [CompactString]
-- | O(n) Break a ByteString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
-- split 'a' "aXaXaXa" == ["","X","X","X",""]
-- split 'x' "x" == ["",""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- As for all splitting functions in this library, this function does not
-- copy the substrings, it just constructs new CompactString that
-- are slices of the original.
split :: Char -> CompactString -> [CompactString]
-- | O(n) Splits a CompactString 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 (=='a') "aabbaca" == ["","","bb","c",""]
-- splitWith (=='a') [] == []
--
splitWith :: (Char -> Bool) -> CompactString -> [CompactString]
-- | lines breaks a CompactString up into a list of
-- CompactStrings at newline Chars. The resulting strings do not contain
-- newlines.
lines :: CompactString -> [CompactString]
-- | words breaks a ByteString up into a list of words, which were
-- delimited by Chars representing white space. And
--
--
-- words = filter (not . null) . splitWith isSpace
--
words :: CompactString -> [CompactString]
-- | unlines is an inverse operation to lines. It joins
-- lines, after appending a terminating newline to each.
unlines :: [CompactString] -> CompactString
-- | The unwords function is analogous to the unlines
-- function, on words.
unwords :: [CompactString] -> CompactString
-- | O(n) The isPrefixOf function takes two CompactString and
-- returns True iff the first is a prefix of the second.
isPrefixOf :: CompactString -> CompactString -> Bool
-- | O(n) The isSuffixOf function takes two CompactString and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
isSuffixOf :: CompactString -> CompactString -> Bool
-- | Check whether one string is a substring of another. isInfixOf p
-- s is equivalent to not (null (findSubstrings p s)).
isInfixOf :: CompactString -> CompactString -> Bool
-- | Get the first index of a substring in another string, or
-- Nothing if the string is not found. findSubstring p s
-- is equivalent to listToMaybe (findSubstrings p s).
findSubstring :: CompactString -> CompactString -> Maybe Int
-- | Find the indexes of all (possibly overlapping) occurances of a
-- substring in a string. This function uses the Knuth-Morris-Pratt
-- string matching algorithm.
findSubstrings :: CompactString -> CompactString -> [Int]
-- | O(n) elem is the CompactString membership
-- predicate.
elem :: Char -> CompactString -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Char -> CompactString -> Bool
-- | O(n) The find function takes a predicate and a
-- CompactString, 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 `index` n) ; _ -> Nothing
--
find :: (Char -> Bool) -> CompactString -> Maybe Char
-- | O(n) filter, applied to a predicate and a
-- CompactString, returns a CompactString containing those
-- characters that satisfy the predicate. This function is subject to
-- array fusion.
filter :: (Char -> Bool) -> CompactString -> CompactString
-- | O(n) partition, applied to a predicate and a
-- CompactString, returns a pair of CompactStrings. The first
-- containing those characters that satisfy the predicate, the second
-- containg those that don't.
partition :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | O(n) CompactString index (subscript) operator, starting
-- from 0.
index :: CompactString -> Int -> Char
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ByteString which is equal to the
-- query element, or Nothing if there is no such element.
elemIndex :: Char -> CompactString -> 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 :: Char -> CompactString -> [Int]
-- | O(n) The elemIndexEnd function returns the last index of
-- the element in the given CompactString which is equal to the
-- query element, or Nothing if there is no such element. The
-- following holds:
--
--
-- elemIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--
elemIndexEnd :: Char -> CompactString -> Maybe Int
-- | The findIndex function takes a predicate and a
-- CompactString and returns the index of the first element in the
-- CompactString satisfying the predicate.
findIndex :: (Char -> Bool) -> CompactString -> Maybe Int
-- | O(n) The findIndexEnd function returns the last index of
-- the element in the given CompactString which satisfies the
-- predicate, or Nothing if there is no such element. The
-- following holds:
--
--
-- findIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` findIndex c (reverse xs)
--
findIndexEnd :: (Char -> Bool) -> CompactString -> Maybe Int
-- | The findIndices function extends findIndex, by returning
-- the indices of all elements satisfying the predicate, in ascending
-- order.
findIndices :: (Char -> Bool) -> CompactString -> [Int]
-- | count returns the number of times its argument appears in the
-- CompactString
--
--
-- count c = length . elemIndices c
--
count :: Char -> CompactString -> Int
-- | O(n) zip takes two ByteStrings and returns a list of
-- corresponding pairs of bytes. If one input ByteString is short, excess
-- elements of the longer ByteString are discarded. This is equivalent to
-- a pair of unpack operations.
zip :: CompactString -> CompactString -> [(Char, Char)]
-- | zipWith generalises zip by zipping with the function
-- given as the first argument, instead of a tupling function. For
-- example, zipWith (+) is applied to two ByteStrings to
-- produce the list of corresponding sums.
zipWith :: (Char -> Char -> b) -> CompactString -> CompactString -> [b]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two CompactStrings, to build a 3rd.
-- Rewrite rules are used to automatically covert zipWith into zipWith'
-- when a pack is performed on the result of zipWith, but we also export
-- it for convenience.
zipWith' :: (Char -> Char -> Char) -> CompactString -> CompactString -> CompactString
-- | O(n) unzip transforms a list of pairs of bytes into a
-- pair of CompactStrings. Note that this performs two pack
-- operations.
unzip :: [(Char, Char)] -> (CompactString, CompactString)
-- | O(n log n) Sort a CompactString
sort :: CompactString -> CompactString
-- | Convert a CompactString to a ByteString
toByteString :: CompactString -> ByteString
-- | Convert a ByteString to a CompactString. Fails if the ByteString is
-- not a valid encoded string.
fromByteString :: MonadPlus m => ByteString -> m (CompactString)
-- | Convert a ByteString to a CompactString. Raises an error if the
-- ByteString is not a valid encoded string.
fromByteString_ :: ByteString -> CompactString
-- | Validates a CompactString. If the string is invalid, fails, otherwise
-- returns the input.
validate :: MonadPlus m => CompactString -> m (CompactString)
-- | Validates a CompactString. If the string is invalid, throws an error,
-- otherwise returns the input.
validate_ :: CompactString -> CompactString
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode e = liftM toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Fails if the string is cannot be encoded in the target encoding.
encode :: (Encoding e, MonadPlus m) => e -> CompactString -> m ByteString
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode_ e = toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encode_ :: Encoding e => e -> CompactString -> ByteString
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode e = recode =<< fromByteString
--
--
-- but it might be faster for some combinations of encodings.
--
-- Fails if the ByteString is not a valid encoded string
decode :: (Encoding e, MonadPlus m) => e -> ByteString -> m (CompactString)
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode_ e = recode_ . fromByteString_
--
--
-- but it might be faster for some combinations of encodings.
--
-- Raises an error if the ByteString is not a valid encoded string
decode_ :: Encoding e => e -> ByteString -> CompactString
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Fails if the string is cannot be encoded in the target encoding.
encodeBOM :: (Encoding e, MonadPlus m) => e -> CompactString -> m ByteString
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encodeBOM_ :: Encoding e => e -> CompactString -> ByteString
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Fails if the input is not a valid encoded string
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM :: MonadPlus m => ByteString -> m (CompactString)
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Raises an error if the input is not a valid encoded string
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM_ :: ByteString -> CompactString
-- | Read a line from stdin.
getLine :: IO (CompactString)
-- | getContents. Equivalent to hGetContents stdin
--
-- Input is assumed to be in UTF-16, this may not be appropriate.
getContents :: IO (CompactString)
-- | Write a CompactString to stdout.
--
-- Output is written in UTF-16, this may not be appropriate.
putStr :: CompactString -> IO ()
-- | Write a CompactString to stdout, appending a newline character.
--
-- Output is written in UTF-16, this may not be appropriate.
putStrLn :: CompactString -> IO ()
-- | The interact function takes a function of type CompactString ->
-- CompactString as its argument. The entire input from the standard
-- input device is passed to this function as its argument, and the
-- resulting string is output on the standard output device. It's great
-- for writing one line programs!
interact :: (CompactString -> CompactString) -> IO ()
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- Files are assumed to be in UTF-16.
readFile :: FilePath -> IO (CompactString)
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- The encoding of the file is determined based on a Byte Order Mark, see
-- decodeBOM.
readFile' :: FilePath -> IO (CompactString)
-- | Write a CompactString to a file.
--
-- Files are written using UTF-16.
writeFile :: FilePath -> CompactString -> IO ()
-- | Write a CompactString to a file.
--
-- Files are written using UTF-16. A Byte Order Mark is also written.
writeFile' :: FilePath -> CompactString -> IO ()
-- | Append a CompactString to a file.
--
-- Files are written using UTF-16.
appendFile :: FilePath -> CompactString -> IO ()
-- | Append a CompactString to a file.
--
-- The encoding of the file is determined based on a Byte Order Mark. If
-- the file is empty, it is written using UTF-16 with a Byte Order Mark.
-- If the encoding can not be determined the file is assumed to be UTF-8.
appendFile' :: FilePath -> CompactString -> IO ()
-- | Read a line from a handle
hGetLine :: Handle -> IO (CompactString)
-- | Read entire handle contents into a CompactString.
--
-- The handle is interpreted as UTF-16.
hGetContents :: Handle -> IO (CompactString)
-- | Read entire handle contents into a CompactString.
--
-- The encoding is determined based on a Byte Order Mark, see
-- decodeBOM.
hGetContents' :: Handle -> IO (CompactString)
-- | Read a CompactString directly from the specified Handle.
--
-- The handle is interpreted as UTF-16.
hGet :: Handle -> Int -> IO (CompactString)
-- | hGetNonBlocking is identical to hGet, except that it will never
-- block waiting for data to become available, instead it returns only
-- whatever data is available.
--
-- The handle is interpreted as UTF-16.
hGetNonBlocking :: Handle -> Int -> IO (CompactString)
-- | Outputs a CompactString to the specified Handle.
--
-- Output is written in UTF-16.
hPut :: Handle -> CompactString -> IO ()
-- | A synonym for hPut, for compatibility
hPutStr :: Handle -> CompactString -> IO ()
-- | Write a CompactString to a handle, appending a newline byte
--
-- Output is written in UTF-16.
hPutStrLn :: Handle -> CompactString -> IO ()
-- | CompactString specialized to UTF-8.
--
-- This module can be used to reduce the need for type signatures, since
-- in most cases only a single encoding is used.
module Data.CompactString.UTF8
-- | CompactString specialized to UTF-8.
type CompactString = CompactString UTF8
-- | O(1) The empty CompactString
empty :: CompactString
-- | O(1) Convert a Char into a CompactString
singleton :: Char -> CompactString
-- | O(n) Convert a String into a CompactString.
pack :: String -> CompactString
-- | O(n) Converts a CompactString to a String.
unpack :: CompactString -> String
-- | O(n) cons is analogous to (:) for lists, but of
-- different complexity, as it requires a memcpy.
cons :: Char -> CompactString -> CompactString
-- | O(n) Append a byte to the end of a CompactString
snoc :: CompactString -> Char -> CompactString
-- | O(n) Append two CompactStrings
append :: CompactString -> CompactString -> CompactString
-- | O(1) Extract the first element of a CompactString, which must
-- be non-empty. An exception will be thrown in the case of an empty
-- CompactString.
head :: CompactString -> Char
-- | O(1) Extract the last element of a ByteString, which must be
-- finite and non-empty. An exception will be thrown in the case of an
-- empty ByteString.
last :: CompactString -> Char
-- | O(1) Extract the elements after the head of a CompactString,
-- which must be non-empty. An exception will be thrown in the case of an
-- empty CompactString.
tail :: CompactString -> CompactString
-- | O(1) Return all the elements of a CompactString except
-- the last one. An exception will be thrown in the case of an empty
-- ByteString.
init :: CompactString -> CompactString
-- | O(1) A view of the front of a CompactString.
--
--
-- headView s = if null s then Nothing else Just (head s, tail s)
--
headView :: CompactString -> Maybe (Char, CompactString)
-- | O(1) A view of the back of a CompactString.
--
--
-- lastView s = if null s then Nothing else Just (init s, last s)
--
lastView :: CompactString -> Maybe (CompactString, Char)
-- | O(1) Test whether a CompactString is empty.
null :: CompactString -> Bool
-- | O(n) length returns the length of a CompactString as an
-- Int.
length :: CompactString -> Int
-- | O(n) map f xs is the CompactString obtained by
-- applying f to each element of xs. This function is
-- subject to array fusion.
map :: (Char -> Char) -> CompactString -> CompactString
-- | Reverse a CompactString
reverse :: CompactString -> CompactString
-- | O(n) The intersperse function takes a Char and a
-- CompactString and `intersperses' that character between the
-- elements of the CompactString. It is analogous to the
-- intersperse function on Lists.
intersperse :: Char -> CompactString -> CompactString
-- | O(n) The intercalate function takes a
-- CompactString and a list of CompactStrings and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
intercalate :: CompactString -> [CompactString] -> CompactString
-- | The transpose function transposes the rows and columns of its
-- CompactString argument.
transpose :: [CompactString] -> [CompactString]
-- | foldl, applied to a binary operator, a starting value
-- (typically the left-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from left to
-- right. This function is subject to array fusion.
foldl :: (acc -> Char -> acc) -> acc -> CompactString -> acc
-- | 'foldl\'' is like foldl, but strict in the accumulator. Though
-- actually foldl is also strict in the accumulator.
foldl' :: (acc -> Char -> acc) -> acc -> CompactString -> acc
-- | foldl1 is a variant of foldl that has no starting value
-- argument, and thus must be applied to non-empty CompactString.
-- This function is subject to array fusion. An exception will be thrown
-- in the case of an empty CompactString.
foldl1 :: (Char -> Char -> Char) -> CompactString -> Char
-- | 'foldl1\'' is like foldl1, but strict in the accumulator. An
-- exception will be thrown in the case of an empty CompactString.
foldl1' :: (Char -> Char -> Char) -> CompactString -> Char
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr :: (Char -> acc -> acc) -> acc -> CompactString -> acc
-- | foldr, applied to a binary operator, a starting value
-- (typically the right-identity of the operator), and a CompactString,
-- reduces the CompactString using the binary operator, from right to
-- left.
foldr' :: (Char -> acc -> acc) -> acc -> CompactString -> acc
-- | foldr1 is a variant of foldr that has no starting value
-- argument, and thus must be applied to non-empty CompactStrings
-- An exception will be thrown in the case of an empty CompactString.
foldr1 :: (Char -> Char -> Char) -> CompactString -> Char
-- | 'foldr1\'' is a variant of foldr1, but is strict in the
-- accumulator. An exception will be thrown in the case of an empty
-- CompactString.
foldr1' :: (Char -> Char -> Char) -> CompactString -> Char
-- | O(n) Concatenate a list of CompactStrings.
concat :: [CompactString] -> CompactString
-- | Map a function over a CompactString and concatenate the results
concatMap :: (Char -> CompactString) -> CompactString -> CompactString
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if any element of the CompactString satisfies the
-- predicate.
any :: (Char -> Bool) -> CompactString -> Bool
-- | O(n) Applied to a predicate and a CompactString, any
-- determines if all elements of the CompactString satisfy the
-- predicate.
all :: (Char -> Bool) -> CompactString -> Bool
-- | O(n) maximum returns the maximum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
maximum :: CompactString -> Char
-- | O(n) minimum returns the minimum value from a
-- CompactString An exception will be thrown in the case of an
-- empty CompactString.
minimum :: CompactString -> Char
-- | scanl is similar to foldl, but returns a list of
-- successive reduced values from the left. This function will fuse.
--
--
-- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
--
-- Note that
--
--
-- last (scanl f z xs) == foldl f z xs.
--
scanl :: (Char -> Char -> Char) -> Char -> CompactString -> CompactString
-- | scanl1 is a variant of scanl that has no starting value
-- argument. This function will fuse.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Char -> Char -> Char) -> CompactString -> CompactString
-- | scanr is the right-to-left dual of scanl.
scanr :: (Char -> Char -> Char) -> Char -> CompactString -> CompactString
-- | scanr1 is a variant of scanr that has no starting value
-- argument.
scanr1 :: (Char -> Char -> Char) -> CompactString -> CompactString
-- | The mapAccumL function behaves like a combination of map
-- and foldl; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from left to right,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumL :: (acc -> Char -> (acc, Char)) -> acc -> CompactString -> (acc, CompactString)
-- | The mapAccumR function behaves like a combination of map
-- and foldr; it applies a function to each element of a
-- CompactString, passing an accumulating parameter from right to left,
-- and returning a final value of this accumulator together with the new
-- CompactString.
mapAccumR :: (acc -> Char -> (acc, Char)) -> acc -> CompactString -> (acc, CompactString)
-- | O(n) map Char functions, provided with the index at each
-- position.
mapIndexed :: (Int -> Char -> Char) -> CompactString -> CompactString
-- | O(n) replicate n x is a CompactString 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 -> Char -> CompactString
-- | O(n), where n is the length of the result. The
-- unfoldr function is analogous to the List 'unfoldr'.
-- unfoldr builds a ByteString from a seed value. The function
-- takes the element and returns Nothing if it is done producing
-- the CompactString 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.
--
-- Examples:
--
--
-- unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
-- == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (acc -> Maybe (Char, acc)) -> acc -> CompactString
-- | O(n) Like unfoldr, unfoldrN builds a ByteString
-- 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 -> (acc -> Maybe (Char, acc)) -> acc -> (CompactString, Maybe acc)
-- | O(n) take n, applied to a CompactString
-- xs, returns the prefix of xs of length n,
-- or xs itself if n > length xs.
take :: Int -> CompactString -> CompactString
-- | O(n) drop n xs returns the suffix of
-- xs after the first n elements, or empty if
-- n > length xs.
drop :: Int -> CompactString -> CompactString
-- | O(n) splitAt n xs is equivalent to
-- (take n xs, drop n xs).
splitAt :: Int -> CompactString -> (CompactString, CompactString)
-- | takeWhile, applied to a predicate p and a
-- CompactString xs, returns the longest prefix (possibly empty)
-- of xs of elements that satisfy p.
takeWhile :: (Char -> Bool) -> CompactString -> CompactString
-- | dropWhile p xs returns the suffix remaining after
-- takeWhile p xs.
dropWhile :: (Char -> Bool) -> CompactString -> CompactString
-- | span p xs breaks the ByteString into two segments. It
-- is equivalent to (takeWhile p xs, dropWhile p
-- xs)
span :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | spanEnd behaves like span but from the end of the
-- CompactString
--
-- We have
--
--
-- spanEnd (not.isSpace) "x y z" == ("x y ","z")
--
--
-- and
--
--
-- spanEnd (not . isSpace) cs
-- ==
-- let (x,y) = span (not.isSpace) (reverse cs) in (reverse y, reverse x)
--
spanEnd :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | break p is equivalent to span (not .
-- p).
break :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | breakEnd behaves like break but from the end of the
-- CompactString
--
--
-- breakEnd p == spanEnd (not.p)
--
breakEnd :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | The group function takes a CompactString and returns a
-- list of CompactStrings such that the concatenation of the result is
-- equal to the argument. Moreover, each sublist in the result contains
-- only equal elements. For example,
--
--
-- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--
--
-- It is a special case of groupBy, which allows the programmer to
-- supply their own equality test.
group :: CompactString -> [CompactString]
-- | The groupBy function is the non-overloaded version of
-- group.
groupBy :: (Char -> Char -> Bool) -> CompactString -> [CompactString]
-- | O(n) Return all initial segments of the given
-- CompactString, shortest first.
inits :: CompactString -> [CompactString]
-- | O(n) Return all final segments of the given
-- CompactString, longest first.
tails :: CompactString -> [CompactString]
-- | O(n) Break a ByteString into pieces separated by the
-- byte argument, consuming the delimiter. I.e.
--
--
-- split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
-- split 'a' "aXaXaXa" == ["","X","X","X",""]
-- split 'x' "x" == ["",""]
--
--
-- and
--
--
-- intercalate [c] . split c == id
-- split == splitWith . (==)
--
--
-- As for all splitting functions in this library, this function does not
-- copy the substrings, it just constructs new CompactString that
-- are slices of the original.
split :: Char -> CompactString -> [CompactString]
-- | O(n) Splits a CompactString 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 (=='a') "aabbaca" == ["","","bb","c",""]
-- splitWith (=='a') [] == []
--
splitWith :: (Char -> Bool) -> CompactString -> [CompactString]
-- | lines breaks a CompactString up into a list of
-- CompactStrings at newline Chars. The resulting strings do not contain
-- newlines.
lines :: CompactString -> [CompactString]
-- | words breaks a ByteString up into a list of words, which were
-- delimited by Chars representing white space. And
--
--
-- words = filter (not . null) . splitWith isSpace
--
words :: CompactString -> [CompactString]
-- | unlines is an inverse operation to lines. It joins
-- lines, after appending a terminating newline to each.
unlines :: [CompactString] -> CompactString
-- | The unwords function is analogous to the unlines
-- function, on words.
unwords :: [CompactString] -> CompactString
-- | O(n) The isPrefixOf function takes two CompactString and
-- returns True iff the first is a prefix of the second.
isPrefixOf :: CompactString -> CompactString -> Bool
-- | O(n) The isSuffixOf function takes two CompactString and
-- returns True iff the first is a suffix of the second.
--
-- The following holds:
--
--
-- isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
isSuffixOf :: CompactString -> CompactString -> Bool
-- | Check whether one string is a substring of another. isInfixOf p
-- s is equivalent to not (null (findSubstrings p s)).
isInfixOf :: CompactString -> CompactString -> Bool
-- | Get the first index of a substring in another string, or
-- Nothing if the string is not found. findSubstring p s
-- is equivalent to listToMaybe (findSubstrings p s).
findSubstring :: CompactString -> CompactString -> Maybe Int
-- | Find the indexes of all (possibly overlapping) occurances of a
-- substring in a string. This function uses the Knuth-Morris-Pratt
-- string matching algorithm.
findSubstrings :: CompactString -> CompactString -> [Int]
-- | O(n) elem is the CompactString membership
-- predicate.
elem :: Char -> CompactString -> Bool
-- | O(n) notElem is the inverse of elem
notElem :: Char -> CompactString -> Bool
-- | O(n) The find function takes a predicate and a
-- CompactString, 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 `index` n) ; _ -> Nothing
--
find :: (Char -> Bool) -> CompactString -> Maybe Char
-- | O(n) filter, applied to a predicate and a
-- CompactString, returns a CompactString containing those
-- characters that satisfy the predicate. This function is subject to
-- array fusion.
filter :: (Char -> Bool) -> CompactString -> CompactString
-- | O(n) partition, applied to a predicate and a
-- CompactString, returns a pair of CompactStrings. The first
-- containing those characters that satisfy the predicate, the second
-- containg those that don't.
partition :: (Char -> Bool) -> CompactString -> (CompactString, CompactString)
-- | O(n) CompactString index (subscript) operator, starting
-- from 0.
index :: CompactString -> Int -> Char
-- | O(n) The elemIndex function returns the index of the
-- first element in the given ByteString which is equal to the
-- query element, or Nothing if there is no such element.
elemIndex :: Char -> CompactString -> 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 :: Char -> CompactString -> [Int]
-- | O(n) The elemIndexEnd function returns the last index of
-- the element in the given CompactString which is equal to the
-- query element, or Nothing if there is no such element. The
-- following holds:
--
--
-- elemIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--
elemIndexEnd :: Char -> CompactString -> Maybe Int
-- | The findIndex function takes a predicate and a
-- CompactString and returns the index of the first element in the
-- CompactString satisfying the predicate.
findIndex :: (Char -> Bool) -> CompactString -> Maybe Int
-- | O(n) The findIndexEnd function returns the last index of
-- the element in the given CompactString which satisfies the
-- predicate, or Nothing if there is no such element. The
-- following holds:
--
--
-- findIndexEnd c xs ==
-- (-) (length xs - 1) `fmap` findIndex c (reverse xs)
--
findIndexEnd :: (Char -> Bool) -> CompactString -> Maybe Int
-- | The findIndices function extends findIndex, by returning
-- the indices of all elements satisfying the predicate, in ascending
-- order.
findIndices :: (Char -> Bool) -> CompactString -> [Int]
-- | count returns the number of times its argument appears in the
-- CompactString
--
--
-- count c = length . elemIndices c
--
count :: Char -> CompactString -> Int
-- | O(n) zip takes two ByteStrings and returns a list of
-- corresponding pairs of bytes. If one input ByteString is short, excess
-- elements of the longer ByteString are discarded. This is equivalent to
-- a pair of unpack operations.
zip :: CompactString -> CompactString -> [(Char, Char)]
-- | zipWith generalises zip by zipping with the function
-- given as the first argument, instead of a tupling function. For
-- example, zipWith (+) is applied to two ByteStrings to
-- produce the list of corresponding sums.
zipWith :: (Char -> Char -> b) -> CompactString -> CompactString -> [b]
-- | A specialised version of zipWith for the common case of a
-- simultaneous map over two CompactStrings, to build a 3rd.
-- Rewrite rules are used to automatically covert zipWith into zipWith'
-- when a pack is performed on the result of zipWith, but we also export
-- it for convenience.
zipWith' :: (Char -> Char -> Char) -> CompactString -> CompactString -> CompactString
-- | O(n) unzip transforms a list of pairs of bytes into a
-- pair of CompactStrings. Note that this performs two pack
-- operations.
unzip :: [(Char, Char)] -> (CompactString, CompactString)
-- | O(n log n) Sort a CompactString
sort :: CompactString -> CompactString
-- | Convert a CompactString to a ByteString
toByteString :: CompactString -> ByteString
-- | Convert a ByteString to a CompactString. Fails if the ByteString is
-- not a valid encoded string.
fromByteString :: MonadPlus m => ByteString -> m (CompactString)
-- | Convert a ByteString to a CompactString. Raises an error if the
-- ByteString is not a valid encoded string.
fromByteString_ :: ByteString -> CompactString
-- | Validates a CompactString. If the string is invalid, fails, otherwise
-- returns the input.
validate :: MonadPlus m => CompactString -> m (CompactString)
-- | Validates a CompactString. If the string is invalid, throws an error,
-- otherwise returns the input.
validate_ :: CompactString -> CompactString
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode e = liftM toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Fails if the string is cannot be encoded in the target encoding.
encode :: (Encoding e, MonadPlus m) => e -> CompactString -> m ByteString
-- | Encode a CompactString to a ByteString using the given encoding.
--
--
-- encode_ e = toByteString . recode
--
--
-- But it might be faster for some combinations of encodings.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encode_ :: Encoding e => e -> CompactString -> ByteString
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode e = recode =<< fromByteString
--
--
-- but it might be faster for some combinations of encodings.
--
-- Fails if the ByteString is not a valid encoded string
decode :: (Encoding e, MonadPlus m) => e -> ByteString -> m (CompactString)
-- | Decode a ByteString to a CompactString using the given encoding.
--
--
-- decode_ e = recode_ . fromByteString_
--
--
-- but it might be faster for some combinations of encodings.
--
-- Raises an error if the ByteString is not a valid encoded string
decode_ :: Encoding e => e -> ByteString -> CompactString
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Fails if the string is cannot be encoded in the target encoding.
encodeBOM :: (Encoding e, MonadPlus m) => e -> CompactString -> m ByteString
-- | Encode a CompactString using the given encoding, and add a Byte
-- Order Mark. Byte Order Marks are common on Windows, but not on other
-- platforms.
--
-- Raises an error if the string is cannot be encoded in the target
-- encoding.
encodeBOM_ :: Encoding e => e -> CompactString -> ByteString
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Fails if the input is not a valid encoded string
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM :: MonadPlus m => ByteString -> m (CompactString)
-- | Decode a ByteString into a CompactString, by
-- investigating the Byte Order Mark. If there is no BOM assumes UTF-8.
-- Raises an error if the input is not a valid encoded string
--
-- For portability, this function should be prefered over decode
-- UTF8 when reading files.
decodeBOM_ :: ByteString -> CompactString
-- | Read a line from stdin.
getLine :: IO (CompactString)
-- | getContents. Equivalent to hGetContents stdin
--
-- Input is assumed to be in UTF-8, this may not be appropriate.
getContents :: IO (CompactString)
-- | Write a CompactString to stdout.
--
-- Output is written in UTF-8, this may not be appropriate.
putStr :: CompactString -> IO ()
-- | Write a CompactString to stdout, appending a newline character.
--
-- Output is written in UTF-8, this may not be appropriate.
putStrLn :: CompactString -> IO ()
-- | The interact function takes a function of type CompactString ->
-- CompactString as its argument. The entire input from the standard
-- input device is passed to this function as its argument, and the
-- resulting string is output on the standard output device. It's great
-- for writing one line programs!
interact :: (CompactString -> CompactString) -> IO ()
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- Files are assumed to be in UTF-8.
readFile :: FilePath -> IO (CompactString)
-- | Read an entire file strictly into a CompactString. This is far
-- more efficient than reading the characters into a String and
-- then using pack. Files are read using 'text mode' on Windows.
--
-- The encoding of the file is determined based on a Byte Order Mark, see
-- decodeBOM.
readFile' :: FilePath -> IO (CompactString)
-- | Write a CompactString to a file.
--
-- Files are written using UTF-8.
writeFile :: FilePath -> CompactString -> IO ()
-- | Write a CompactString to a file.
--
-- Files are written using UTF-8. A Byte Order Mark is also written.
writeFile' :: FilePath -> CompactString -> IO ()
-- | Append a CompactString to a file.
--
-- Files are written using UTF-8.
appendFile :: FilePath -> CompactString -> IO ()
-- | Append a CompactString to a file.
--
-- The encoding of the file is determined based on a Byte Order Mark. If
-- the file is empty, it is written using UTF-8 with a Byte Order Mark.
-- If the encoding can not be determined the file is assumed to be UTF-8.
appendFile' :: FilePath -> CompactString -> IO ()
-- | Read a line from a handle
hGetLine :: Handle -> IO (CompactString)
-- | Read entire handle contents into a CompactString.
--
-- The handle is interpreted as UTF-8.
hGetContents :: Handle -> IO (CompactString)
-- | Read entire handle contents into a CompactString.
--
-- The encoding is determined based on a Byte Order Mark, see
-- decodeBOM.
hGetContents' :: Handle -> IO (CompactString)
-- | Read a CompactString directly from the specified Handle.
--
-- The handle is interpreted as UTF-8.
hGet :: Handle -> Int -> IO (CompactString)
-- | hGetNonBlocking is identical to hGet, except that it will never
-- block waiting for data to become available, instead it returns only
-- whatever data is available.
--
-- The handle is interpreted as UTF-8.
hGetNonBlocking :: Handle -> Int -> IO (CompactString)
-- | Outputs a CompactString to the specified Handle.
--
-- Output is written in UTF-8.
hPut :: Handle -> CompactString -> IO ()
-- | A synonym for hPut, for compatibility
hPutStr :: Handle -> CompactString -> IO ()
-- | Write a CompactString to a handle, appending a newline byte
--
-- Output is written in UTF-8.
hPutStrLn :: Handle -> CompactString -> IO ()