-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | 'Sized' wrappers for text
--
-- Sized wrappers for text.
@package sized-wrapper-text
@version 0.1.0.0
-- | Sized wrappers around Text
--
-- This module is intended to be imported qualified, to avoid
-- name clashes with Prelude functions. eg.
--
--
-- import qualified Data.Text.Sized as NET
--
module Data.Text.Sized
type SizedText s = SizedStrictText s
type SizedStrictText s = Sized s Text
-- | O(n) Convert a 'Sized s String' into a 'SizedStrictText s'.
-- Performs replacement on invalid scalar values.
pack :: Sized s String -> SizedStrictText s
-- | O(n) Convert a 'SizedStrictText s' into a 'Sized s String'.
unpack :: HasCallStack => SizedStrictText s -> Sized s String
-- | Build a Sized value from a singleton value
singleton :: SizedSingleton a => Proxy a -> SizedSingletonElement a -> Sized (Exactly 1) a
-- | O(n) Adds a character to the front of a SizedStrictText.
-- This function is more costly than its List counterpart
-- because it requires copying a new array. Performs replacement on
-- invalid scalar values.
cons :: Char -> SizedStrictText s -> SizedStrictText (Exactly 1 <+> s)
infixr 5 `cons`
-- | O(n) Adds a character to the end of a SizedStrictText.
-- This copies the entire array in the process. Performs replacement on
-- invalid scalar values.
snoc :: SizedStrictText s -> Char -> SizedStrictText (s <+> Exactly 1)
-- | O(1) Returns the first character and rest of a
-- SizedStrictText.
uncons :: (IsNotEmpty s, (Exactly 1 <+> s) ~ s') => SizedStrictText s -> (Char, SizedStrictText s')
-- | O(1) Returns all but the last character and the last character
-- of a SizedStrictText.
unsnoc :: (IsNotEmpty s, (s <+> Exactly 1) ~ s') => SizedStrictText s -> (SizedStrictText s', Char)
-- | O(1) Returns the first character of a SizedStrictText.
head :: IsNotEmpty s => SizedStrictText s -> Char
-- | O(1) Returns the last character of a SizedStrictText.
last :: (IsNotEmpty s, (Exactly 1 <+> s) ~ s') => SizedStrictText s -> Char
-- | O(1) Returns all characters after the head of a
-- SizedStrictText.
tail :: (IsNotEmpty s, (Exactly 1 <+> s) ~ s') => SizedStrictText s -> SizedStrictText s'
-- | O(1) Returns all but the last character of a
-- SizedStrictText.
init :: (IsNotEmpty s, (s <+> Exactly 1) ~ s') => SizedStrictText s -> SizedStrictText s'
-- | O(n) Returns the number of characters in a
-- SizedStrictText.
length :: SizedStrictText s -> Int
-- | O(min(n,c)) Compare the count of characters in a
-- SizedStrictText to a number.
--
--
-- compareLength t c = compare (length t) c
--
--
-- This function gives the same answer as comparing against the result of
-- length, but can short circuit if the count of characters is
-- greater than the number, and hence be more efficient.
compareLength :: (KnownNat n, Includes s n) => SizedStrictText s -> Proxy n -> Ordering
-- | O(n) map f t is the
-- SizedStrictText obtained by applying f to each element
-- of t.
--
-- Example:
--
--
-- >>> let message = pack "I am not angry. Not at all."
--
-- >>> T.map (\c -> if c == '.' then '!' else c) message
-- "I am not angry! Not at all!"
--
--
-- Performs replacement on invalid scalar values.
map :: (Char -> Char) -> SizedStrictText s -> SizedStrictText s
-- | O(n) The intercalate function takes a
-- SizedStrictText and a list of SizedStrictTexts and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
--
-- Example:
--
--
-- >>> T.intercalate "NI!" ["We", "seek", "the", "Holy", "Grail"]
-- "WeNI!seekNI!theNI!HolyNI!Grail"
--
intercalate :: Text -> Sized s [SizedStrictText s'] -> SizedStrictText (s <*> s')
-- | O(n) The intersperse function takes a character and
-- places it between the characters of a SizedStrictText.
--
-- Example:
--
--
-- >>> T.intersperse '.' "SHIELD"
-- "S.H.I.E.L.D"
--
--
-- Performs replacement on invalid scalar values.
intersperse :: Char -> SizedStrictText s -> SizedStrictText ((s <*> Exactly 2) <-> Exactly 1)
-- | O(n) The transpose function transposes the rows and
-- columns of its SizedStrictText argument. Note that this
-- function uses pack, unpack, and the list version of
-- transpose, and is thus not very efficient.
--
-- Examples:
--
--
-- >>> transpose ["green","orange"]
-- ["go","rr","ea","en","ng","e"]
--
--
--
-- >>> transpose ["blue","red"]
-- ["br","le","ud","e"]
--
transpose :: Sized s [SizedStrictText s'] -> Sized s' [SizedStrictText s]
-- | O(n) Reverse the characters of a string.
--
-- Example:
--
--
-- >>> T.reverse "desrever"
-- "reversed"
--
reverse :: HasCallStack => SizedStrictText s -> SizedStrictText s
-- | O(m+n) Replace every non-trustedChangeOverlapping occurrence of
-- needle in haystack with replacement.
--
-- This function behaves as though it was defined as follows:
--
--
-- replace needle replacement haystack =
-- intercalate replacement (splitOn needle haystack)
--
--
-- As this suggests, each occurrence is replaced exactly once. So if
-- needle occurs in replacement, that occurrence will
-- not itself be replaced recursively:
--
--
-- >>> replace "oo" "foo" "oo"
-- "foo"
--
--
-- In cases where several instances of needle overlap, only the
-- first one will be replaced:
--
--
-- >>> replace "ofo" "bar" "ofofo"
-- "barfo"
--
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
replace :: SizedStrictText s0 -> SizedStrictText s1 -> SizedStrictText s2 -> SizedStrictText Unknown
-- | O(n) Convert a string to folded case.
--
-- This function is mainly useful for performing caseless (also known as
-- case insensitive) string comparisons.
--
-- A string x is a caseless match for a string y if and
-- only if:
--
--
-- toCaseFold x == toCaseFold y
--
--
-- The result string may be longer than the input string, and may differ
-- from applying toLower to the input string. For instance, the
-- Armenian small ligature "ﬓ" (men now, U+FB13) is case folded to the
-- sequence "մ" (men, U+0574) followed by "ն" (now, U+0576), while the
-- Greek "µ" (micro sign, U+00B5) is case folded to "μ" (small letter mu,
-- U+03BC) instead of itself.
toCaseFold :: SizedStrictText s -> SizedStrictText s
-- | O(n) Convert a string to lower case, using simple case
-- conversion.
--
-- The result string may be longer than the input string. For instance,
-- "İ" (Latin capital letter I with dot above, U+0130) maps to the
-- sequence "i" (Latin small letter i, U+0069) followed by " ̇"
-- (combining dot above, U+0307).
toLower :: SizedStrictText s -> SizedStrictText s
-- | O(n) Convert a string to upper case, using simple case
-- conversion.
--
-- The result string may be longer than the input string. For instance,
-- the German "ß" (eszett, U+00DF) maps to the two-letter sequence "SS".
toUpper :: SizedStrictText s -> SizedStrictText s
-- | O(n) Convert a string to title case, using simple case
-- conversion.
--
-- The first letter of the input is converted to title case, as is every
-- subsequent letter that immediately follows a non-letter. Every letter
-- that immediately follows another letter is converted to lower case.
--
-- The result string may be longer than the input string. For example,
-- the Latin small ligature fl (U+FB02) is converted to the sequence Latin
-- capital letter F (U+0046) followed by Latin small letter l (U+006C).
--
-- Note: this function does not take language or culture specific
-- rules into account. For instance, in English, different style guides
-- disagree on whether the book name "The Hill of the Red Fox" is
-- correctly title cased—but this function will capitalize every
-- word.
toTitle :: SizedStrictText s -> SizedStrictText s
-- | O(n) Left-justify a string to the given length, using the
-- specified fill character on the right. Performs replacement on invalid
-- scalar values.
--
-- Examples:
--
--
-- >>> justifyLeft 7 'x' "foo"
-- "fooxxxx"
--
--
--
-- >>> justifyLeft 3 'x' "foobar"
-- "foobar"
--
justifyLeft :: KnownNat n => Proxy n -> Char -> SizedStrictText s -> SizedStrictText (AtLeast n)
-- | O(n) Right-justify a string to the given length, using the
-- specified fill character on the left. Performs replacement on invalid
-- scalar values.
--
-- Examples:
--
--
-- >>> justifyRight 7 'x' "bar"
-- "xxxxbar"
--
--
--
-- >>> justifyRight 3 'x' "foobar"
-- "foobar"
--
justifyRight :: KnownNat n => Proxy n -> Char -> SizedStrictText s -> SizedStrictText (AtLeast n)
-- | O(n) Center a string to the given length, using the specified
-- fill character on either side. Performs replacement on invalid scalar
-- values.
--
-- Examples:
--
--
-- >>> center 8 'x' "HS"
-- "xxxHSxxx"
--
center :: KnownNat n => Proxy n -> Char -> SizedStrictText s -> SizedStrictText (AtLeast n)
-- | O(n) foldl, applied to a binary operator, a starting
-- value (typically the left-identity of the operator), and a
-- SizedStrictText, reduces the SizedStrictText using the
-- binary operator, from left to right.
foldl :: (a -> Char -> a) -> a -> SizedStrictText s -> a
-- | O(n) A strict version of foldl.
foldl' :: (a -> Char -> a) -> a -> SizedStrictText s -> a
-- | O(n) A variant of foldl that has no starting value
-- argument.
foldl1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedStrictText s -> Char
-- | O(n) A strict version of foldl1.
foldl1' :: IsNotEmpty s => (Char -> Char -> Char) -> SizedStrictText s -> Char
-- | O(n) foldr, applied to a binary operator, a starting
-- value (typically the right-identity of the operator), and a
-- SizedStrictText, reduces the SizedStrictText using the
-- binary operator, from right to left.
--
-- If the binary operator is strict in its second argument, use
-- foldr' instead.
--
-- foldr is lazy like foldr for lists: evaluation actually
-- traverses the SizedStrictText from left to right, only as far
-- as it needs to. @
--
-- Searches from left to right with short-circuiting behavior can also be
-- defined using foldr (e.g., any, all,
-- find, elem).
foldr :: (Char -> a -> a) -> a -> SizedStrictText s -> a
-- | O(n) A variant of foldr that has no starting value
-- argument.
foldr1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedStrictText s -> Char
-- | O(n) Concatenate a list of SizedStrictTexts.
concat :: Sized s [SizedStrictText s'] -> SizedStrictText (s <*> s')
-- | O(n) Map a function over a SizedStrictText that results
-- in a SizedStrictText, and concatenate the results.
concatMap :: (Char -> SizedStrictText s') -> SizedStrictText s -> SizedStrictText (s <*> s')
-- | O(n) any p t determines whether any
-- character in the SizedStrictText t satisfies the
-- predicate p.
any :: (Char -> Bool) -> SizedStrictText s -> Bool
-- | O(n) all p t determines whether all
-- characters in the SizedStrictText t satisfy the
-- predicate p.
all :: (Char -> Bool) -> SizedStrictText s -> Bool
-- | O(n) maximum returns the maximum value from a
-- SizedStrictText.
maximum :: IsNotEmpty s => SizedStrictText s -> Char
-- | O(n) minimum returns the minimum value from a
-- SizedStrictText.
minimum :: IsNotEmpty s => SizedStrictText s -> Char
-- | O(n) scanl is similar to foldl, but returns a
-- list of successive reduced values from the left. Performs replacement
-- on invalid scalar values.
--
--
-- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
--
-- Properties
--
--
-- head (scanl f z xs) = z
--
--
--
-- last (scanl f z xs) = foldl f z xs
--
scanl :: (Char -> Char -> Char) -> Char -> SizedStrictText s -> SizedStrictText s
-- | O(n) scanl1 is a variant of scanl that has no
-- starting value argument. Performs replacement on invalid scalar
-- values.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedStrictText s -> SizedStrictText s
-- | O(n) scanr is the right-to-left dual of scanl.
-- Performs replacement on invalid scalar values.
--
--
-- scanr f v == reverse . scanl (flip f) v . reverse
--
scanr :: (Char -> Char -> Char) -> Char -> SizedStrictText s -> SizedStrictText s
-- | O(n) scanr1 is a variant of scanr that has no
-- starting value argument. Performs replacement on invalid scalar
-- values.
scanr1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedStrictText s -> SizedStrictText s
-- | O(n) Like a combination of map and foldl'.
-- Applies a function to each element of a SizedStrictText,
-- passing an accumulating parameter from left to right, and returns a
-- final SizedStrictText. Performs replacement on invalid scalar
-- values.
mapAccumL :: forall a s. (a -> Char -> (a, Char)) -> a -> SizedStrictText s -> (a, SizedStrictText s)
-- | The mapAccumR function behaves like a combination of map
-- and a strict foldr; it applies a function to each element of a
-- SizedStrictText, passing an accumulating parameter from right
-- to left, and returning a final value of this accumulator together with
-- the new SizedStrictText. Performs replacement on invalid scalar
-- values.
mapAccumR :: forall a s. (a -> Char -> (a, Char)) -> a -> SizedStrictText s -> (a, SizedStrictText s)
-- | O(n*m) replicate n t is a
-- SizedStrictText consisting of the input t repeated
-- n times, n should be strictly positive.
replicate :: KnownNat n => Proxy n -> SizedStrictText s -> SizedStrictText (s <*> Exactly n)
-- | O(n) take n, applied to a
-- SizedStrictText, returns the prefix of the Text of
-- length n, or the Text itself if n is
-- greater than the length of the SizedStrictText.
take :: (KnownNat n, Includes s n) => Proxy n -> SizedStrictText s -> SizedStrictText (AtMost n)
-- | O(n) takeEnd n t returns the suffix
-- remaining after taking n characters from the end of
-- t.
--
-- Examples:
--
--
-- >>> takeEnd 3 "foobar"
-- "bar"
--
takeEnd :: (KnownNat n, Includes s n) => Proxy n -> SizedStrictText s -> SizedStrictText (AtMost n)
-- | O(n) drop n, applied to a
-- SizedStrictText, returns the suffix of the Text after
-- the first n characters, or the empty Text if
-- n is greater than the length of the SizedStrictText.
drop :: (KnownNat n, Includes s n) => Proxy n -> SizedStrictText s -> SizedStrictText (s <-> Exactly n)
-- | O(n) dropEnd n t returns the prefix
-- remaining after dropping n characters from the end of
-- t.
--
-- Examples:
--
--
-- >>> dropEnd 3 "foobar"
-- "foo"
--
dropEnd :: (KnownNat n, Includes s n) => Proxy n -> SizedStrictText s -> SizedStrictText (s <-> Exactly n)
-- | O(n) takeWhile, applied to a predicate p and a
-- SizedStrictText, returns the longest prefix (possibly empty) of
-- elements that satisfy p.
takeWhile :: (Char -> Bool) -> SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) takeWhileEnd, applied to a predicate p and
-- a SizedStrictText, returns the longest suffix (possibly empty)
-- of elements that satisfy p. Examples:
--
--
-- >>> takeWhileEnd (=='o') "foo"
-- "oo"
--
takeWhileEnd :: (Char -> Bool) -> SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) dropWhile p t returns the suffix
-- remaining after takeWhile p t.
dropWhile :: (Char -> Bool) -> SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) dropWhileEnd p t returns the
-- prefix remaining after dropping characters that satisfy the predicate
-- p from the end of t.
--
-- Examples:
--
--
-- >>> dropWhileEnd (=='.') "foo..."
-- "foo"
--
dropWhileEnd :: (Char -> Bool) -> SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) dropAround p t returns the
-- substring remaining after dropping characters that satisfy the
-- predicate p from both the beginning and end of t.
dropAround :: (Char -> Bool) -> SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) Remove leading and trailing white space from a string.
-- Equivalent to:
--
--
-- dropAround isSpace
--
strip :: SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) Remove leading white space from a string. Equivalent to:
--
--
-- dropWhile isSpace
--
stripStart :: SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) Remove trailing white space from a string. Equivalent to:
--
--
-- dropWhileEnd isSpace
--
stripEnd :: SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n) splitAt n t returns a pair whose first
-- element is a prefix of t of length n, and whose
-- second is the remainder of the string. It is equivalent to
-- (take n t, drop n t).
splitAt :: (KnownNat n, Includes s n) => Proxy n -> SizedStrictText s -> (SizedStrictText (RestrictAtMost s), SizedStrictText (RestrictAtMost s))
-- | O(n+m) Find the first instance of needle (which must
-- be non-null) in haystack. The first element of the
-- returned tuple is the prefix of haystack before
-- needle is matched. The second is the remainder of
-- haystack, starting with the match.
--
-- Examples:
--
--
-- >>> breakOn "::" "a::b::c"
-- ("a","::b::c")
--
--
--
-- >>> breakOn "/" "foobar"
-- ("foobar","")
--
--
-- Laws:
--
--
-- append prefix match == haystack
-- where (prefix, match) = breakOn needle haystack
--
--
-- If you need to break a string by a substring repeatedly (e.g. you want
-- to break on every instance of a substring), use breakOnAll
-- instead, as it has lower startup overhead.
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
breakOn :: SizedStrictText s -> SizedStrictText s' -> (SizedStrictText (RestrictAtMost s), SizedStrictText (RestrictAtMost s))
-- | O(n+m) Similar to breakOn, but searches from the end of
-- the string.
--
-- The first element of the returned tuple is the prefix of
-- haystack up to and including the last match of
-- needle. The second is the remainder of haystack,
-- following the match.
--
--
-- >>> breakOnEnd "::" "a::b::c"
-- ("a::b::","c")
--
breakOnEnd :: SizedStrictText s -> SizedStrictText s' -> (SizedStrictText (RestrictAtMost s), SizedStrictText (RestrictAtMost s))
-- | O(n) break is like span, but the prefix returned
-- is over elements that fail the predicate p.
--
--
-- >>> T.break (=='c') "180cm"
-- ("180","cm")
--
break :: (Char -> Bool) -> SizedStrictText s -> (SizedStrictText (RestrictAtMost s), SizedStrictText (RestrictAtMost s))
-- | O(n) span, applied to a predicate p and text
-- t, returns a pair whose first element is the longest prefix
-- (possibly empty) of t of elements that satisfy p,
-- and whose second is the remainder of the text.
--
--
-- >>> T.span (=='0') "000AB"
-- ("000","AB")
--
span :: (Char -> Bool) -> SizedStrictText s -> (SizedStrictText (RestrictAtMost s), SizedStrictText (RestrictAtMost s))
-- | O(n) Group characters in a string by equality.
group :: SizedStrictText s -> Sized (RestrictAtMost s) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Group characters in a string according to a predicate.
groupBy :: (Char -> Char -> Bool) -> SizedStrictText s -> Sized (RestrictAtMost s) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Return all initial segments of the given
-- SizedStrictText, shortest first.
inits :: SizedStrictText s -> Sized (s <+> Exactly 1) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Return all final segments of the given
-- SizedStrictText, longest first.
tails :: SizedStrictText s -> Sized (s <+> Exactly 1) [SizedStrictText (RestrictAtMost s)]
-- | O(m+n) Break a SizedStrictText into pieces separated by
-- the first Text argument (which cannot be empty), consuming
-- the delimiter. An empty delimiter is invalid, and will cause an error
-- to be raised.
--
-- Examples:
--
--
-- >>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"
-- ["a","b","d","e"]
--
--
--
-- >>> splitOn "aaa" "aaaXaaaXaaaXaaa"
-- ["","X","X","X",""]
--
--
--
-- >>> splitOn "x" "x"
-- ["",""]
--
--
-- and
--
--
-- intercalate s . splitOn s == id
-- splitOn (singleton c) == split (==c)
--
--
-- (Note: the string s to split on above cannot be empty.)
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
splitOn :: SizedStrictText s -> SizedStrictText s' -> Sized (RestrictAtMost s') [SizedStrictText (RestrictAtMost s')]
-- | O(n) Splits a SizedStrictText 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.
--
--
-- >>> split (=='a') "aabbaca"
-- ["","","bb","c",""]
--
--
--
-- >>> split (=='a') ""
-- [""]
--
split :: (Char -> Bool) -> SizedStrictText s -> Sized (RestrictAtMost s) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Splits a SizedStrictText into components of length
-- k. The last element may be shorter than the other chunks,
-- depending on the length of the input. Examples:
--
--
-- >>> chunksOf 3 "foobarbaz"
-- ["foo","bar","baz"]
--
--
--
-- >>> chunksOf 4 "haskell.org"
-- ["hask","ell.","org"]
--
chunksOf :: (KnownNat n, Includes s n) => Proxy n -> SizedStrictText s -> Sized (AtMost d) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Breaks a SizedStrictText up into a list of
-- SizedStrictTexts at newline characters '\n' (LF, line
-- feed). The resulting strings do not contain newlines.
--
-- lines does not treat '\r' (CR, carriage return)
-- as a newline character.
lines :: SizedStrictText s -> Sized (RestrictAtMost s) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Breaks a SizedStrictText up into a list of words,
-- delimited by Chars representing white space.
words :: SizedStrictText s -> Sized (RestrictAtMost s) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Joins lines, after appending a terminating newline to
-- each.
unlines :: Sized s [SizedStrictText s'] -> SizedStrictText (s <*> (s' <+> Exactly 1))
-- | O(n) Joins words using single space characters.
unwords :: Sized s [SizedStrictText s'] -> SizedStrictText (s <*> (s' <+> Exactly 1))
-- | O(n) The isPrefixOf function takes two
-- SizedStrictTexts and returns True if and only if the
-- first is a prefix of the second.
isPrefixOf :: IsMoreGeneral s' s => SizedStrictText s -> SizedStrictText s' -> Bool
-- | O(n) The isSuffixOf function takes two
-- SizedStrictTexts and returns True if and only if the
-- first is a suffix of the second.
isSuffixOf :: IsMoreGeneral s' s => SizedStrictText s -> SizedStrictText s' -> Bool
-- | O(n+m) The isInfixOf function takes two
-- SizedStrictTexts and returns True if and only if the
-- first is contained, wholly and intact, anywhere within the second.
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
isInfixOf :: (IsMoreGeneral s' s, HasCallStack) => SizedStrictText s -> SizedStrictText s' -> Bool
-- | O(n) Return the suffix of the second string if its prefix
-- matches the entire first string.
--
-- Examples:
--
--
-- >>> stripPrefix "foo" "foobar"
-- Just "bar"
--
--
--
-- >>> stripPrefix "" "baz"
-- Just "baz"
--
--
--
-- >>> stripPrefix "foo" "quux"
-- Nothing
--
--
-- This is particularly useful with the ViewPatterns extension
-- to GHC, as follows:
--
--
-- {-# LANGUAGE ViewPatterns #-}
-- import Data.Text.Sized as T
--
-- fnordLength :: SizedStrictText -> Int
-- fnordLength (stripPrefix "fnord" -> Just suf) = T.length suf
-- fnordLength _ = -1
--
stripPrefix :: SizedStrictText s -> SizedStrictText s' -> Maybe (SizedStrictText (s <-> s'))
-- | O(n) Return the prefix of the second string if its suffix
-- matches the entire first string.
--
-- Examples:
--
--
-- >>> stripSuffix "bar" "foobar"
-- Just "foo"
--
--
--
-- >>> stripSuffix "" "baz"
-- Just "baz"
--
--
--
-- >>> stripSuffix "foo" "quux"
-- Nothing
--
--
-- This is particularly useful with the ViewPatterns extension
-- to GHC, as follows:
--
--
-- {-# LANGUAGE ViewPatterns #-}
-- import Data.Text.Sized as T
--
-- quuxLength :: SizedStrictText -> Int
-- quuxLength (stripSuffix "quux" -> Just pre) = T.length pre
-- quuxLength _ = -1
--
stripSuffix :: SizedStrictText s -> SizedStrictText s' -> Maybe (SizedStrictText (s <-> s'))
-- | O(n) Find the longest non-empty common prefix of two strings
-- and return it, along with the suffixes of each string at which they no
-- longer match.
--
-- If the strings do not have a common prefix or either one is empty,
-- this function returns Nothing.
--
-- Examples:
--
--
-- >>> commonPrefixes "foobar" "fooquux"
-- Just ("foo","bar","quux")
--
--
--
-- >>> commonPrefixes "veeble" "fetzer"
-- Nothing
--
--
--
-- >>> commonPrefixes "" "baz"
-- Nothing
--
commonPrefixes :: SizedStrictText s -> SizedStrictText s' -> Maybe (Text, Text, Text)
-- | O(n) filter, applied to a predicate and a
-- SizedStrictText, returns a Text containing those
-- characters that satisfy the predicate.
filter :: (Char -> Bool) -> SizedStrictText s -> SizedStrictText (RestrictAtMost s)
-- | O(n+m) Find all non-overlapping instances of needle in
-- haystack. Each element of the returned list consists of a
-- pair:
--
--
-- - The entire string prior to the kth match (i.e. the
-- prefix)
-- - The kth match, followed by the remainder of the string
--
--
-- Examples:
--
--
-- >>> breakOnAll "::" ""
-- []
--
--
--
-- >>> breakOnAll "/" "a/b/c/"
-- [("a","/b/c/"),("a/b","/c/"),("a/b/c","/")]
--
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
--
-- The needle parameter may not be empty.
breakOnAll :: SizedStrictText s -> SizedStrictText s' -> Sized (RestrictAtMost s) [(SizedStrictText (RestrictAtMost s), SizedStrictText (RestrictAtMost s))]
-- | O(n) The elem function takes a character and a
-- SizedStrictText, and returns True if the element is
-- found in the given SizedStrictText, or False otherwise.
--
-- O(n) The find function takes a predicate and a
-- SizedStrictText, and returns the first element matching the
-- predicate, or Nothing if there is no such element.
find :: (Char -> Bool) -> SizedStrictText s -> Maybe Char
-- | O(n) The partition function takes a predicate and a
-- SizedStrictText, and returns the pair of Texts with
-- elements which do and do not satisfy the predicate, respectively; i.e.
--
--
-- partition p t == (filter p t, filter (not . p) t)
--
partition :: (Char -> Bool) -> SizedStrictText s -> (SizedStrictText (RestrictAtMost s), SizedStrictText (RestrictAtMost s))
-- | O(n) SizedStrictText index (subscript) operator,
-- starting from 0.
index :: (KnownNat n, Includes s n, HasCallStack) => SizedStrictText s -> Proxy n -> Char
-- | O(n) The findIndex function takes a predicate and a
-- SizedStrictText and returns the index of the first element in
-- the SizedStrictText satisfying the predicate.
findIndex :: (Char -> Bool) -> SizedStrictText s -> Maybe Int
-- | O(n+m) The count function returns the number of times
-- the query string appears in the given SizedStrictText. An empty
-- query string is invalid, and will cause an error to be raised.
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
count :: SizedStrictText s -> SizedStrictText s' -> Int
-- | O(n) zip takes two SizedStrictTexts and returns a
-- list of corresponding pairs of bytes. If one input
-- SizedStrictText is short, excess elements of the longer
-- SizedStrictText are discarded. This is equivalent to a pair of
-- unpack operations.
zip :: SizedStrictText s -> SizedStrictText s -> Sized s [(Char, Char)]
-- | O(n) zipWith generalises zip by zipping with the
-- function given as the first argument, instead of a tupling function.
-- Performs replacement on invalid scalar values.
zipWith :: (Char -> Char -> Char) -> SizedStrictText s -> SizedStrictText s -> SizedStrictText s
instance Data.Sized.SizedSingleton Data.Text.Internal.Text
instance Data.Sized.SizedFromContainer Data.Text.Internal.Text
-- | Sized wrappers around Lazy
--
-- This module is intended to be imported qualified, to avoid
-- name clashes with Prelude functions. eg.
--
--
-- import qualified Data.Text.Lazy.Sized as NEL
--
module Data.Text.Lazy.Sized
type SizedText s = SizedLazyText s
type SizedLazyText s = Sized s Text
-- | O(n) Convert a 'Sized String' into a SizedLazyText.
-- Performs replacement on invalid scalar values.
pack :: Sized s String -> SizedLazyText s
-- | O(n) Convert a 'SizedLazyText s' into a 'Sized s String'.
unpack :: HasCallStack => SizedLazyText s -> Sized s String
-- | Build a Sized value from a singleton value
singleton :: SizedSingleton a => Proxy a -> SizedSingletonElement a -> Sized (Exactly 1) a
-- | O(c) Convert a list of strict SizedStrictTexts into a
-- lazy SizedLazyText.
fromChunks :: Sized s [SizedStrictText s'] -> SizedLazyText (s <*> s')
-- | O(n) Convert a lazy SizedLazyText into a list of strict
-- SizedStrictTexts.
toChunks :: SizedLazyText s -> Sized (RestrictAtMost s) [SizedStrictText (RestrictAtMost s)]
-- | O(n) Convert a lazy SizedLazyText into a strict
-- SizedStrictText.
toStrict :: SizedLazyText s -> SizedStrictText s
-- | O(c) Convert a strict SizedStrictText into a lazy
-- SizedLazyText.
fromStrict :: SizedStrictText s -> SizedLazyText s
-- | O(n) Adds a character to the front of a SizedLazyText.
-- This function is more costly than its List counterpart
-- because it requires copying a new array. Performs replacement on
-- invalid scalar values.
cons :: Char -> SizedLazyText s -> SizedLazyText (Exactly 1 <+> s)
infixr 5 `cons`
-- | O(n) Adds a character to the end of a SizedLazyText.
-- This copies the entire array in the process. Performs replacement on
-- invalid scalar values.
snoc :: SizedLazyText s -> Char -> SizedLazyText (s <+> Exactly 1)
-- | O(1) Returns the first character and rest of a
-- SizedLazyText.
uncons :: (IsNotEmpty s, (Exactly 1 <+> s) ~ s') => SizedLazyText s -> (Char, SizedLazyText s')
-- | O(1) Returns all but the last character and the last character
-- of a SizedLazyText.
unsnoc :: (IsNotEmpty s, (s <+> Exactly 1) ~ s') => SizedLazyText s -> (SizedLazyText s', Char)
-- | O(1) Returns the first character of a SizedLazyText.
head :: IsNotEmpty s => SizedLazyText s -> Char
-- | O(1) Returns the last character of a SizedLazyText.
last :: (IsNotEmpty s, (Exactly 1 <+> s) ~ s') => SizedLazyText s -> Char
-- | O(1) Returns all characters after the head of a
-- SizedLazyText.
tail :: (IsNotEmpty s, (Exactly 1 <+> s) ~ s') => SizedLazyText s -> SizedLazyText s'
-- | O(1) Returns all but the last character of a
-- SizedLazyText.
init :: (IsNotEmpty s, (s <+> Exactly 1) ~ s') => SizedLazyText s -> SizedLazyText s'
-- | O(n) Returns the number of characters in a
-- SizedLazyText.
length :: SizedLazyText s -> Int64
-- | O(min(n,c)) Compare the count of characters in a
-- SizedLazyText to a number.
--
--
-- compareLength t c = compare (length t) c
--
--
-- This function gives the same answer as comparing against the result of
-- length, but can short circuit if the count of characters is
-- greater than the number, and hence be more efficient.
compareLength :: (KnownNat n, Includes s n) => SizedLazyText s -> Proxy n -> Ordering
-- | O(n) map f t is the
-- SizedLazyText obtained by applying f to each element
-- of t.
--
-- Example:
--
--
-- >>> let message = pack "I am not angry. Not at all."
--
-- >>> T.map (\c -> if c == '.' then '!' else c) message
-- "I am not angry! Not at all!"
--
--
-- Performs replacement on invalid scalar values.
map :: (Char -> Char) -> SizedLazyText s -> SizedLazyText s
-- | O(n) The intercalate function takes a
-- SizedLazyText and a list of SizedLazyTexts and
-- concatenates the list after interspersing the first argument between
-- each element of the list.
--
-- Example:
--
--
-- >>> T.intercalate "NI!" ["We", "seek", "the", "Holy", "Grail"]
-- "WeNI!seekNI!theNI!HolyNI!Grail"
--
intercalate :: Text -> Sized s [SizedLazyText s'] -> SizedLazyText (s <*> s')
-- | O(n) The intersperse function takes a character and
-- places it between the characters of a SizedLazyText.
--
-- Example:
--
--
-- >>> T.intersperse '.' "SHIELD"
-- "S.H.I.E.L.D"
--
--
-- Performs replacement on invalid scalar values.
intersperse :: Char -> SizedLazyText s -> SizedLazyText ((s <*> Exactly 2) <-> Exactly 1)
-- | O(n) The transpose function transposes the rows and
-- columns of its SizedLazyText argument. Note that this function
-- uses pack, unpack, and the list version of transpose,
-- and is thus not very efficient.
--
-- Examples:
--
--
-- >>> transpose ["green","orange"]
-- ["go","rr","ea","en","ng","e"]
--
--
--
-- >>> transpose ["blue","red"]
-- ["br","le","ud","e"]
--
transpose :: Sized s [SizedLazyText s'] -> Sized s' [SizedLazyText s]
-- | O(n) Reverse the characters of a string.
--
-- Example:
--
--
-- >>> T.reverse "desrever"
-- "reversed"
--
reverse :: HasCallStack => SizedLazyText s -> SizedLazyText s
-- | O(m+n) Replace every non-overlapping occurrence of
-- needle in haystack with replacement.
--
-- This function behaves as though it was defined as follows:
--
--
-- replace needle replacement haystack =
-- intercalate replacement (splitOn needle haystack)
--
--
-- As this suggests, each occurrence is replaced exactly once. So if
-- needle occurs in replacement, that occurrence will
-- not itself be replaced recursively:
--
--
-- >>> replace "oo" "foo" "oo"
-- "foo"
--
--
-- In cases where several instances of needle overlap, only the
-- first one will be replaced:
--
--
-- >>> replace "ofo" "bar" "ofofo"
-- "barfo"
--
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
replace :: SizedLazyText s0 -> SizedLazyText s1 -> SizedLazyText s2 -> SizedLazyText Unknown
-- | O(n) Convert a string to folded case.
--
-- This function is mainly useful for performing caseless (also known as
-- case insensitive) string comparisons.
--
-- A string x is a caseless match for a string y if and
-- only if:
--
--
-- toCaseFold x == toCaseFold y
--
--
-- The result string may be longer than the input string, and may differ
-- from applying toLower to the input string. For instance, the
-- Armenian small ligature "ﬓ" (men now, U+FB13) is case folded to the
-- sequence "մ" (men, U+0574) followed by "ն" (now, U+0576), while the
-- Greek "µ" (micro sign, U+00B5) is case folded to "μ" (small letter mu,
-- U+03BC) instead of itself.
toCaseFold :: SizedLazyText s -> SizedLazyText s
-- | O(n) Convert a string to lower case, using simple case
-- conversion.
--
-- The result string may be longer than the input string. For instance,
-- "İ" (Latin capital letter I with dot above, U+0130) maps to the
-- sequence "i" (Latin small letter i, U+0069) followed by " ̇"
-- (combining dot above, U+0307).
toLower :: SizedLazyText s -> SizedLazyText s
-- | O(n) Convert a string to upper case, using simple case
-- conversion.
--
-- The result string may be longer than the input string. For instance,
-- the German "ß" (eszett, U+00DF) maps to the two-letter sequence "SS".
toUpper :: SizedLazyText s -> SizedLazyText s
-- | O(n) Convert a string to title case, using simple case
-- conversion.
--
-- The first letter of the input is converted to title case, as is every
-- subsequent letter that immediately follows a non-letter. Every letter
-- that immediately follows another letter is converted to lower case.
--
-- The result string may be longer than the input string. For example,
-- the Latin small ligature fl (U+FB02) is converted to the sequence Latin
-- capital letter F (U+0046) followed by Latin small letter l (U+006C).
--
-- Note: this function does not take language or culture specific
-- rules into account. For instance, in English, different style guides
-- disagree on whether the book name "The Hill of the Red Fox" is
-- correctly title cased—but this function will capitalize every
-- word.
toTitle :: SizedLazyText s -> SizedLazyText s
-- | O(n) Left-justify a string to the given length, using the
-- specified fill character on the right. Performs replacement on invalid
-- scalar values.
--
-- Examples:
--
--
-- >>> justifyLeft 7 'x' "foo"
-- "fooxxxx"
--
--
--
-- >>> justifyLeft 3 'x' "foobar"
-- "foobar"
--
justifyLeft :: KnownNat n => Proxy n -> Char -> SizedLazyText s -> SizedLazyText (AtLeast n)
-- | O(n) Right-justify a string to the given length, using the
-- specified fill character on the left. Performs replacement on invalid
-- scalar values.
--
-- Examples:
--
--
-- >>> justifyRight 7 'x' "bar"
-- "xxxxbar"
--
--
--
-- >>> justifyRight 3 'x' "foobar"
-- "foobar"
--
justifyRight :: KnownNat n => Proxy n -> Char -> SizedLazyText s -> SizedLazyText (AtLeast n)
-- | O(n) Center a string to the given length, using the specified
-- fill character on either side. Performs replacement on invalid scalar
-- values.
--
-- Examples:
--
--
-- >>> center 8 'x' "HS"
-- "xxxHSxxx"
--
center :: KnownNat n => Proxy n -> Char -> SizedLazyText s -> SizedLazyText (AtLeast n)
-- | O(n) foldl, applied to a binary operator, a starting
-- value (typically the left-identity of the operator), and a
-- SizedLazyText, reduces the SizedLazyText using the
-- binary operator, from left to right.
foldl :: (a -> Char -> a) -> a -> SizedLazyText s -> a
-- | O(n) A strict version of foldl.
foldl' :: (a -> Char -> a) -> a -> SizedLazyText s -> a
-- | O(n) A variant of foldl that has no starting value
-- argument.
foldl1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedLazyText s -> Char
-- | O(n) A strict version of foldl1.
foldl1' :: IsNotEmpty s => (Char -> Char -> Char) -> SizedLazyText s -> Char
-- | O(n) foldr, applied to a binary operator, a starting
-- value (typically the right-identity of the operator), and a
-- SizedLazyText, reduces the SizedLazyText using the
-- binary operator, from right to left.
--
-- If the binary operator is strict in its second argument, use
-- foldr' instead.
--
-- foldr is lazy like foldr for lists: evaluation actually
-- traverses the SizedLazyText from left to right, only as far as
-- it needs to. @
--
-- Searches from left to right with short-circuiting behavior can also be
-- defined using foldr (e.g., any, all,
-- find, elem).
foldr :: (Char -> a -> a) -> a -> SizedLazyText s -> a
-- | O(n) A variant of foldr that has no starting value
-- argument.
foldr1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedLazyText s -> Char
-- | O(n) Concatenate a list of SizedLazyTexts.
concat :: Sized s [SizedLazyText s'] -> SizedLazyText (s <*> s')
-- | O(n) Map a function over a SizedLazyText that results in
-- a SizedLazyText, and concatenate the results.
concatMap :: (Char -> SizedLazyText s') -> SizedLazyText s -> SizedLazyText (s <*> s')
-- | O(n) any p t determines whether any
-- character in the SizedLazyText t satisfies the
-- predicate p.
any :: (Char -> Bool) -> SizedLazyText s -> Bool
-- | O(n) all p t determines whether all
-- characters in the SizedLazyText t satisfy the
-- predicate p.
all :: (Char -> Bool) -> SizedLazyText s -> Bool
-- | O(n) maximum returns the maximum value from a
-- SizedLazyText.
maximum :: IsNotEmpty s => SizedLazyText s -> Char
-- | O(n) minimum returns the minimum value from a
-- SizedLazyText.
minimum :: IsNotEmpty s => SizedLazyText s -> Char
-- | O(n) scanl is similar to foldl, but returns a
-- list of successive reduced values from the left. Performs replacement
-- on invalid scalar values.
--
--
-- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
--
-- Properties
--
--
-- head (scanl f z xs) = z
--
--
--
-- last (scanl f z xs) = foldl f z xs
--
scanl :: (Char -> Char -> Char) -> Char -> SizedLazyText s -> SizedLazyText s
-- | O(n) scanl1 is a variant of scanl that has no
-- starting value argument. Performs replacement on invalid scalar
-- values.
--
--
-- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedLazyText s -> SizedLazyText s
-- | O(n) scanr is the right-to-left dual of scanl.
-- Performs replacement on invalid scalar values.
--
--
-- scanr f v == reverse . scanl (flip f) v . reverse
--
scanr :: (Char -> Char -> Char) -> Char -> SizedLazyText s -> SizedLazyText s
-- | O(n) scanr1 is a variant of scanr that has no
-- starting value argument. Performs replacement on invalid scalar
-- values.
scanr1 :: IsNotEmpty s => (Char -> Char -> Char) -> SizedLazyText s -> SizedLazyText s
-- | O(n) Like a combination of map and foldl'.
-- Applies a function to each element of a SizedLazyText, passing
-- an accumulating parameter from left to right, and returns a final
-- SizedLazyText. Performs replacement on invalid scalar values.
mapAccumL :: forall a s. (a -> Char -> (a, Char)) -> a -> SizedLazyText s -> (a, SizedLazyText s)
-- | The mapAccumR function behaves like a combination of map
-- and a strict foldr; it applies a function to each element of a
-- SizedLazyText, passing an accumulating parameter from right to
-- left, and returning a final value of this accumulator together with
-- the new SizedLazyText. Performs replacement on invalid scalar
-- values.
mapAccumR :: forall a s. (a -> Char -> (a, Char)) -> a -> SizedLazyText s -> (a, SizedLazyText s)
-- | O(n*m) replicate n t is a
-- SizedLazyText consisting of the input t repeated
-- n times, n should be strictly positive.
replicate :: KnownNat n => Proxy n -> SizedLazyText s -> SizedLazyText (s <*> Exactly n)
-- | cycle ties a finite, SizedLazyText into a circular one,
-- or equivalently, the infinite repetition of the original
-- SizedLazyText.
cycle :: SizedLazyText s -> SizedLazyText (AtLeast 0)
-- | iterate f x returns an infinite SizedLazyText
-- of repeated applications of f to x:
--
--
-- iterate f x == [x, f x, f (f x), ...]
--
iterate :: (Char -> Char) -> Char -> SizedLazyText (AtLeast 0)
-- | O(n) take n, applied to a SizedLazyText,
-- returns the prefix of the Text of length n, or the
-- Text itself if n is greater than the length of the
-- SizedLazyText.
take :: (KnownNat n, Includes s n) => Proxy n -> SizedLazyText s -> SizedLazyText (AtMost n)
-- | O(n) takeEnd n t returns the suffix
-- remaining after taking n characters from the end of
-- t.
--
-- Examples:
--
--
-- >>> takeEnd 3 "foobar"
-- "bar"
--
takeEnd :: (KnownNat n, Includes s n) => Proxy n -> SizedLazyText s -> SizedLazyText (AtMost n)
-- | O(n) drop n, applied to a SizedLazyText,
-- returns the suffix of the Text after the first n
-- characters, or the empty Text if n is greater than
-- the length of the SizedLazyText.
drop :: (KnownNat n, Includes s n) => Proxy n -> SizedLazyText s -> SizedLazyText (s <-> Exactly n)
-- | O(n) dropEnd n t returns the prefix
-- remaining after dropping n characters from the end of
-- t.
--
-- Examples:
--
--
-- >>> dropEnd 3 "foobar"
-- "foo"
--
dropEnd :: (KnownNat n, Includes s n) => Proxy n -> SizedLazyText s -> SizedLazyText (s <-> Exactly n)
-- | O(n) takeWhile, applied to a predicate p and a
-- SizedLazyText, returns the longest prefix (possibly empty) of
-- elements that satisfy p.
takeWhile :: (Char -> Bool) -> SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) takeWhileEnd, applied to a predicate p and
-- a SizedLazyText, returns the longest suffix (possibly empty) of
-- elements that satisfy p. Examples:
--
--
-- >>> takeWhileEnd (=='o') "foo"
-- "oo"
--
takeWhileEnd :: (Char -> Bool) -> SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) dropWhile p t returns the suffix
-- remaining after takeWhile p t.
dropWhile :: (Char -> Bool) -> SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) dropWhileEnd p t returns the
-- prefix remaining after dropping characters that satisfy the predicate
-- p from the end of t.
--
-- Examples:
--
--
-- >>> dropWhileEnd (=='.') "foo..."
-- "foo"
--
dropWhileEnd :: (Char -> Bool) -> SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) dropAround p t returns the
-- substring remaining after dropping characters that satisfy the
-- predicate p from both the beginning and end of t.
dropAround :: (Char -> Bool) -> SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) Remove leading and trailing white space from a string.
-- Equivalent to:
--
--
-- dropAround isSpace
--
strip :: SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) Remove leading white space from a string. Equivalent to:
--
--
-- dropWhile isSpace
--
stripStart :: SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) Remove trailing white space from a string. Equivalent to:
--
--
-- dropWhileEnd isSpace
--
stripEnd :: SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n) splitAt n t returns a pair whose first
-- element is a prefix of t of length n, and whose
-- second is the remainder of the string. It is equivalent to
-- (take n t, drop n t).
splitAt :: (KnownNat n, Includes s n) => Proxy n -> SizedLazyText s -> (SizedLazyText (RestrictAtMost s), SizedLazyText (RestrictAtMost s))
-- | O(n+m) Find the first instance of needle (which must
-- be non-null) in haystack. The first element of the
-- returned tuple is the prefix of haystack before
-- needle is matched. The second is the remainder of
-- haystack, starting with the match.
--
-- Examples:
--
--
-- >>> breakOn "::" "a::b::c"
-- ("a","::b::c")
--
--
--
-- >>> breakOn "/" "foobar"
-- ("foobar","")
--
--
-- Laws:
--
--
-- append prefix match == haystack
-- where (prefix, match) = breakOn needle haystack
--
--
-- If you need to break a string by a substring repeatedly (e.g. you want
-- to break on every instance of a substring), use breakOnAll
-- instead, as it has lower startup overhead.
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
breakOn :: SizedLazyText s -> SizedLazyText s' -> (SizedLazyText (RestrictAtMost s), SizedLazyText (RestrictAtMost s))
-- | O(n+m) Similar to breakOn, but searches from the end of
-- the string.
--
-- The first element of the returned tuple is the prefix of
-- haystack up to and including the last match of
-- needle. The second is the remainder of haystack,
-- following the match.
--
--
-- >>> breakOnEnd "::" "a::b::c"
-- ("a::b::","c")
--
breakOnEnd :: SizedLazyText s -> SizedLazyText s' -> (SizedLazyText (RestrictAtMost s), SizedLazyText (RestrictAtMost s))
-- | O(n) break is like span, but the prefix returned
-- is over elements that fail the predicate p.
--
--
-- >>> T.break (=='c') "180cm"
-- ("180","cm")
--
break :: (Char -> Bool) -> SizedLazyText s -> (SizedLazyText (RestrictAtMost s), SizedLazyText (RestrictAtMost s))
-- | O(n) span, applied to a predicate p and text
-- t, returns a pair whose first element is the longest prefix
-- (possibly empty) of t of elements that satisfy p,
-- and whose second is the remainder of the text.
--
--
-- >>> T.span (=='0') "000AB"
-- ("000","AB")
--
span :: (Char -> Bool) -> SizedLazyText s -> (SizedLazyText (RestrictAtMost s), SizedLazyText (RestrictAtMost s))
-- | O(n) Group characters in a string by equality.
group :: SizedLazyText s -> Sized (RestrictAtMost s) [SizedLazyText (RestrictAtMost s)]
-- | O(n) Group characters in a string according to a predicate.
groupBy :: (Char -> Char -> Bool) -> SizedLazyText s -> Sized (RestrictAtMost s) [SizedLazyText (RestrictAtMost s)]
-- | O(n) Return all initial segments of the given
-- SizedLazyText, shortest first.
inits :: SizedLazyText s -> Sized (s <+> Exactly 1) [SizedLazyText (RestrictAtMost s)]
-- | O(n) Return all final segments of the given
-- SizedLazyText, longest first.
tails :: SizedLazyText s -> Sized (s <+> Exactly 1) [SizedLazyText (RestrictAtMost s)]
-- | O(m+n) Break a SizedLazyText into pieces separated by
-- the first Text argument (which cannot be empty), consuming
-- the delimiter. An empty delimiter is invalid, and will cause an error
-- to be raised.
--
-- Examples:
--
--
-- >>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"
-- ["a","b","d","e"]
--
--
--
-- >>> splitOn "aaa" "aaaXaaaXaaaXaaa"
-- ["","X","X","X",""]
--
--
--
-- >>> splitOn "x" "x"
-- ["",""]
--
--
-- and
--
--
-- intercalate s . splitOn s == id
-- splitOn (singleton c) == split (==c)
--
--
-- (Note: the string s to split on above cannot be empty.)
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
splitOn :: SizedLazyText s -> SizedLazyText s' -> Sized (RestrictAtMost s') [SizedLazyText (RestrictAtMost s')]
-- | O(n) Splits a SizedLazyText 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.
--
--
-- >>> split (=='a') "aabbaca"
-- ["","","bb","c",""]
--
--
--
-- >>> split (=='a') ""
-- [""]
--
split :: (Char -> Bool) -> SizedLazyText s -> Sized (RestrictAtMost s) [SizedLazyText (RestrictAtMost s)]
-- | O(n) Splits a SizedLazyText into components of length
-- k. The last element may be shorter than the other chunks,
-- depending on the length of the input. Examples:
--
--
-- >>> chunksOf 3 "foobarbaz"
-- ["foo","bar","baz"]
--
--
--
-- >>> chunksOf 4 "haskell.org"
-- ["hask","ell.","org"]
--
chunksOf :: (KnownNat n, Includes s n) => Proxy n -> SizedLazyText s -> Sized (AtMost d) [SizedLazyText (RestrictAtMost s)]
-- | O(n) Breaks a SizedLazyText up into a list of
-- SizedLazyTexts at newline characters '\n' (LF, line
-- feed). The resulting strings do not contain newlines.
--
-- lines does not treat '\r' (CR, carriage return)
-- as a newline character.
lines :: SizedLazyText s -> Sized (RestrictAtMost s) [SizedLazyText (RestrictAtMost s)]
-- | O(n) Breaks a SizedLazyText up into a list of words,
-- delimited by Chars representing white space.
words :: SizedLazyText s -> Sized (RestrictAtMost s) [SizedLazyText (RestrictAtMost s)]
-- | O(n) Joins lines, after appending a terminating newline to
-- each.
unlines :: Sized s [SizedLazyText s'] -> SizedLazyText (s <*> (s' <+> Exactly 1))
-- | O(n) Joins words using single space characters.
unwords :: Sized s [SizedLazyText s'] -> SizedLazyText (s <*> (s' <+> Exactly 1))
-- | O(n) The isPrefixOf function takes two
-- SizedLazyTexts and returns True if and only if the first
-- is a prefix of the second.
isPrefixOf :: IsMoreGeneral s' s => SizedLazyText s -> SizedLazyText s' -> Bool
-- | O(n) The isSuffixOf function takes two
-- SizedLazyTexts and returns True if and only if the first
-- is a suffix of the second.
isSuffixOf :: IsMoreGeneral s' s => SizedLazyText s -> SizedLazyText s' -> Bool
-- | O(n+m) The isInfixOf function takes two
-- SizedLazyTexts and returns True if and only if the first
-- is contained, wholly and intact, anywhere within the second.
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
isInfixOf :: (IsMoreGeneral s' s, HasCallStack) => SizedLazyText s -> SizedLazyText s' -> Bool
-- | O(n) Return the suffix of the second string if its prefix
-- matches the entire first string.
--
-- Examples:
--
--
-- >>> stripPrefix "foo" "foobar"
-- Just "bar"
--
--
--
-- >>> stripPrefix "" "baz"
-- Just "baz"
--
--
--
-- >>> stripPrefix "foo" "quux"
-- Nothing
--
--
-- This is particularly useful with the ViewPatterns extension
-- to GHC, as follows:
--
--
-- {-# LANGUAGE ViewPatterns #-}
-- import Data.Text.Sized as T
--
-- fnordLength :: SizedLazyText -> Int
-- fnordLength (stripPrefix "fnord" -> Just suf) = T.length suf
-- fnordLength _ = -1
--
stripPrefix :: SizedLazyText s -> SizedLazyText s' -> Maybe (SizedLazyText (s <-> s'))
-- | O(n) Return the prefix of the second string if its suffix
-- matches the entire first string.
--
-- Examples:
--
--
-- >>> stripSuffix "bar" "foobar"
-- Just "foo"
--
--
--
-- >>> stripSuffix "" "baz"
-- Just "baz"
--
--
--
-- >>> stripSuffix "foo" "quux"
-- Nothing
--
--
-- This is particularly useful with the ViewPatterns extension
-- to GHC, as follows:
--
--
-- {-# LANGUAGE ViewPatterns #-}
-- import Data.Text.Sized as T
--
-- quuxLength :: SizedLazyText -> Int
-- quuxLength (stripSuffix "quux" -> Just pre) = T.length pre
-- quuxLength _ = -1
--
stripSuffix :: SizedLazyText s -> SizedLazyText s' -> Maybe (SizedLazyText (s <-> s'))
-- | O(n) Find the longest non-empty common prefix of two strings
-- and return it, along with the suffixes of each string at which they no
-- longer match.
--
-- If the strings do not have a common prefix or either one is empty,
-- this function returns Nothing.
--
-- Examples:
--
--
-- >>> commonPrefixes "foobar" "fooquux"
-- Just ("foo","bar","quux")
--
--
--
-- >>> commonPrefixes "veeble" "fetzer"
-- Nothing
--
--
--
-- >>> commonPrefixes "" "baz"
-- Nothing
--
commonPrefixes :: SizedLazyText s -> SizedLazyText s' -> Maybe (Text, Text, Text)
-- | O(n) filter, applied to a predicate and a
-- SizedLazyText, returns a Text containing those
-- characters that satisfy the predicate.
filter :: (Char -> Bool) -> SizedLazyText s -> SizedLazyText (RestrictAtMost s)
-- | O(n+m) Find all non-overlapping instances of needle in
-- haystack. Each element of the returned list consists of a
-- pair:
--
--
-- - The entire string prior to the kth match (i.e. the
-- prefix)
-- - The kth match, followed by the remainder of the string
--
--
-- Examples:
--
--
-- >>> breakOnAll "::" ""
-- []
--
--
--
-- >>> breakOnAll "/" "a/b/c/"
-- [("a","/b/c/"),("a/b","/c/"),("a/b/c","/")]
--
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
--
-- The needle parameter may not be empty.
breakOnAll :: SizedLazyText s -> SizedLazyText s' -> Sized (RestrictAtMost s) [(SizedLazyText (RestrictAtMost s), SizedLazyText (RestrictAtMost s))]
-- | O(n) The elem function takes a character and a
-- SizedLazyText, and returns True if the element is found
-- in the given SizedLazyText, or False otherwise.
--
-- O(n) The find function takes a predicate and a
-- SizedLazyText, and returns the first element matching the
-- predicate, or Nothing if there is no such element.
find :: (Char -> Bool) -> SizedLazyText s -> Maybe Char
-- | O(n) The partition function takes a predicate and a
-- SizedLazyText, and returns the pair of Texts with
-- elements which do and do not satisfy the predicate, respectively; i.e.
--
--
-- partition p t == (filter p t, filter (not . p) t)
--
partition :: (Char -> Bool) -> SizedLazyText s -> (SizedLazyText (RestrictAtMost s), SizedLazyText (RestrictAtMost s))
-- | O(n) SizedLazyText index (subscript) operator, starting
-- from 0.
index :: (KnownNat n, Includes s n, HasCallStack) => SizedLazyText s -> Proxy n -> Char
-- | O(n+m) The count function returns the number of times
-- the query string appears in the given SizedLazyText. An empty
-- query string is invalid, and will cause an error to be raised.
--
-- In (unlikely) bad cases, this function's time complexity degrades
-- towards O(n*m).
count :: SizedLazyText s -> SizedLazyText s' -> Int64
-- | O(n) zip takes two SizedLazyTexts and returns a
-- list of corresponding pairs of bytes. If one input
-- SizedLazyText is short, excess elements of the longer
-- SizedLazyText are discarded. This is equivalent to a pair of
-- unpack operations.
zip :: SizedLazyText s -> SizedLazyText s -> Sized s [(Char, Char)]
-- | O(n) zipWith generalises zip by zipping with the
-- function given as the first argument, instead of a tupling function.
-- Performs replacement on invalid scalar values.
zipWith :: (Char -> Char -> Char) -> SizedLazyText s -> SizedLazyText s -> SizedLazyText s
instance Data.Sized.SizedSingleton Data.Text.Internal.Lazy.Text
instance Data.Sized.SizedFromContainer Data.Text.Internal.Lazy.Text
-- | Sized wrappers around Encoding
module Data.Text.Encoding.Sized
-- | Decode a ByteString containing Latin-1 (aka ISO-8859-1) encoded
-- text.
--
-- decodeLatin1 is semantically equivalent to Data.Text.pack .
-- Data.ByteString.Char8.unpack
--
-- This is a total function. However, bear in mind that decoding Latin-1
-- (non-ASCII) characters to UTf-8 requires actual work and is not just
-- buffer copying.
decodeLatin1 :: HasCallStack => Sized s ByteString -> SizedStrictText s
-- | Decode a ByteString containing UTF-8 encoded text that is known
-- to be valid.
--
-- If the input contains any invalid UTF-8 data, an exception will be
-- thrown that cannot be caught in pure code. For more control over the
-- handling of invalid data, use decodeUtf8' or
-- decodeUtf8With.
--
-- This is a partial function: it checks that input is a well-formed
-- UTF-8 sequence and copies buffer or throws an error otherwise.
decodeUtf8 :: Sized s ByteString -> SizedStrictText s
-- | Decode text from little endian UTF-16 encoding.
--
-- If the input contains any invalid little endian UTF-16 data, an
-- exception will be thrown. For more control over the handling of
-- invalid data, use decodeUtf16LEWith.
decodeUtf16LE :: Sized s ByteString -> SizedStrictText s
-- | Decode text from big endian UTF-16 encoding.
--
-- If the input contains any invalid big endian UTF-16 data, an exception
-- will be thrown. For more control over the handling of invalid data,
-- use decodeUtf16BEWith.
decodeUtf16BE :: Sized s ByteString -> SizedStrictText s
-- | Decode text from little endian UTF-32 encoding.
--
-- If the input contains any invalid little endian UTF-32 data, an
-- exception will be thrown. For more control over the handling of
-- invalid data, use decodeUtf32LEWith.
decodeUtf32LE :: Sized s ByteString -> SizedStrictText s
-- | Decode text from big endian UTF-32 encoding.
--
-- If the input contains any invalid big endian UTF-32 data, an exception
-- will be thrown. For more control over the handling of invalid data,
-- use decodeUtf32BEWith.
decodeUtf32BE :: Sized s ByteString -> SizedStrictText s
-- | Decode a ByteString containing UTF-8 encoded text.
--
-- If the input contains any invalid UTF-8 data, the relevant exception
-- will be returned, otherwise the decoded text.
decodeUtf8' :: HasCallStack => Sized s ByteString -> Either UnicodeException (SizedStrictText s)
-- | Decode a ByteString containing UTF-8 encoded text.
--
-- Surrogate code points in replacement character returned by
-- OnDecodeError will be automatically remapped to the replacement
-- char U+FFFD.
decodeUtf8With :: HasCallStack => OnDecodeError -> Sized s ByteString -> SizedStrictText s
-- | Decode text from little endian UTF-16 encoding.
decodeUtf16LEWith :: OnDecodeError -> Sized s ByteString -> SizedStrictText s
-- | Decode text from big endian UTF-16 encoding.
decodeUtf16BEWith :: OnDecodeError -> Sized s ByteString -> SizedStrictText s
-- | Decode text from little endian UTF-32 encoding.
decodeUtf32LEWith :: OnDecodeError -> Sized s ByteString -> SizedStrictText s
-- | Decode text from big endian UTF-32 encoding.
decodeUtf32BEWith :: OnDecodeError -> Sized s ByteString -> SizedStrictText s
-- | Decode, in a stream oriented way, a ByteString containing UTF-8
-- encoded text that is known to be valid.
--
-- If the input contains any invalid UTF-8 data, an exception will be
-- thrown (either by this function or a continuation) that cannot be
-- caught in pure code. For more control over the handling of invalid
-- data, use streamDecodeUtf8With.
streamDecodeUtf8 :: HasCallStack => Sized s ByteString -> Sized s Decoding
-- | Decode, in a stream oriented way, a lazy ByteString containing
-- UTF-8 encoded text.
streamDecodeUtf8With :: HasCallStack => OnDecodeError -> Sized s ByteString -> Sized s Decoding
-- | A stream oriented decoding result.
data Decoding
Some :: Text -> ByteString -> (ByteString -> Decoding) -> Decoding
-- | Encode text using UTF-8 encoding.
encodeUtf8 :: SizedStrictText s -> Sized s ByteString
-- | Encode text using little endian UTF-16 encoding.
encodeUtf16LE :: SizedStrictText s -> Sized s ByteString
-- | Encode text using big endian UTF-16 encoding.
encodeUtf16BE :: SizedStrictText s -> Sized s ByteString
-- | Encode text using little endian UTF-32 encoding.
encodeUtf32LE :: SizedStrictText s -> Sized s ByteString
-- | Encode text using big endian UTF-32 encoding.
encodeUtf32BE :: SizedStrictText s -> Sized s ByteString
-- | Encode text to a ByteString Builder using UTF-8 encoding.
encodeUtf8Builder :: SizedStrictText s -> Sized s Builder
-- | Encode text using UTF-8 encoding and escape the ASCII characters using
-- a BoundedPrim.
--
-- Use this function is to implement efficient encoders for text-based
-- formats like JSON or HTML.
encodeUtf8BuilderEscaped :: BoundedPrim Word8 -> SizedStrictText s -> Sized s Builder