rio-0.1.8.0: A standard library for Haskell

Safe Haskell | Safe
Language | Haskell2010

RIO.Text.Partial

Contents

- Basic interface
- Transformations
- Folds
  - Special folds
- Substrings
  - Breaking strings
  - Breaking into many substrings
- Searching
- Indexing

Description

This module exports all the partial functions from Data.Text

Synopsis

- head :: Text -> Char
- last :: Text -> Char
- tail :: Text -> Text
- init :: Text -> Text
- replace :: Text -> Text -> Text -> Text
- foldl1 :: (Char -> Char -> Char) -> Text -> Char
- foldl1' :: (Char -> Char -> Char) -> Text -> Char
- foldr1 :: (Char -> Char -> Char) -> Text -> Char
- maximum :: Text -> Char
- minimum :: Text -> Char
- breakOn :: Text -> Text -> (Text, Text)
- breakOnEnd :: Text -> Text -> (Text, Text)
- splitOn :: Text -> Text -> [Text]
- breakOnAll :: Text -> Text -> [(Text, Text)]
- count :: Text -> Text -> Int

# Basic interface

head :: Text -> Char Source #

O(1) Returns the first character of a `Text`, which must be non-empty. Subject to fusion.

last :: Text -> Char Source #

O(1) Returns the last character of a `Text`, which must be non-empty. Subject to fusion.

tail :: Text -> Text Source #

O(1) Returns all characters after the head of a `Text`, which must be non-empty. Subject to fusion.

init :: Text -> Text Source #

O(1) Returns all but the last character of a `Text`, which must be non-empty. Subject to fusion.

# Transformations

replace Source #

Arguments

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

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

# Folds

foldl1 :: (Char -> Char -> Char) -> Text -> Char Source #

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

foldl1' :: (Char -> Char -> Char) -> Text -> Char Source #

O(n) A strict version of `foldl1`. Subject to fusion.

foldr1 :: (Char -> Char -> Char) -> Text -> Char Source #

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

## Special folds

maximum :: Text -> Char Source #

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

minimum :: Text -> Char Source #

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

# Substrings

## Breaking strings

breakOn :: Text -> Text -> (Text, Text) Source #

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

breakOnEnd :: Text -> Text -> (Text, Text) Source #

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

## Breaking into many substrings

splitOn Source #

Arguments

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

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

# Searching

breakOnAll Source #

Arguments

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

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

# Indexing

count :: Text -> Text -> Int Source #

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