RIO.Text.Partial · rio-0.1.22.0

Basic interface

4 declarations

valuehead :: HasCallStack => Text -> Char

O(1) Returns the first character of a Text, which must be non-empty. This is a partial function, consider using uncons instead.

valuelast :: HasCallStack => Text -> Char

#

O(1) Returns the last character of a Text, which must be non-empty. This is a partial function, consider using unsnoc instead.

valuetail :: HasCallStack => Text -> Text

#

O(1) Returns all characters after the head of a Text, which must be non-empty. This is a partial function, consider using uncons instead.

valueinit :: HasCallStack => Text -> Text

#

O(1) Returns all but the last character of a Text, which must be non-empty. This is a partial function, consider using unsnoc instead.

Transformations

1 declaration

valuereplace

:: HasCallStack
=> Text
needle to search for. If this string is empty, an error will occur.
-> Text
replacement to replace needle with.
-> Text
haystack in which to search.
-> Text

#

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:

Example1 expression

>>> replace "oo" "foo" "oo""foo"

In cases where several instances of needle overlap, only the first one will be replaced:

Example1 expression

>>> replace "ofo" "bar" "ofofo""barfo"

In (unlikely) bad cases, this function's time complexity degrades towards O(n*m).

Folds

3 declarations

valuefoldl1 :: HasCallStack => (Char -> Char -> Char) -> Text -> Char

#

O(n) A variant of foldl that has no starting value argument, and thus must be applied to a non-empty Text.

valuefoldl1' :: HasCallStack => (Char -> Char -> Char) -> Text -> Char

#

O(n) A strict version of foldl1.

valuefoldr1 :: HasCallStack => (Char -> Char -> Char) -> Text -> Char

#

O(n) A variant of foldr that has no starting value argument, and thus must be applied to a non-empty Text.

Special folds

valuemaximum :: HasCallStack => Text -> Char

#

O(n) maximum returns the maximum value from a Text, which must be non-empty.

valueminimum :: HasCallStack => Text -> Char

#

O(n) minimum returns the minimum value from a Text, which must be non-empty.

Substrings

0 declarations

Breaking strings

valuebreakOn :: HasCallStack => Text -> Text -> (Text, Text)

#

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:

Example1 expression

>>> breakOn "::" "a::b::c"("a","::b::c")

Example1 expression

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

valuebreakOnEnd :: HasCallStack => Text -> Text -> (Text, Text)

#

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.

Example1 expression

>>> breakOnEnd "::" "a::b::c"("a::b::","c")

Breaking into many substrings

valuesplitOn

:: HasCallStack
=> Text
String to split on. If this string is empty, an error will occur.
-> Text
Input text.
-> [Text]

#

O(m+n) Break a Text 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:

Example1 expression

>>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"["a","b","d","e"]

Example1 expression

>>> splitOn "aaa"  "aaaXaaaXaaaXaaa"["","X","X","X",""]

Example1 expression

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

Searching

1 declaration

valuebreakOnAll

:: HasCallStack
=> Text
needle to search for
-> Text
haystack in which to search
-> [(Text, Text)]

#

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:

Example1 expression

>>> breakOnAll "::" ""[]

Example1 expression

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

Indexing

1 declaration

valuecount :: HasCallStack => Text -> Text -> Int

#

O(n+m) The count function returns the number of times the query string appears in the given Text. 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).