text-0.11.3.1: An efficient packed Unicode text type.

Portability | GHC
Stability | experimental
Maintainer | bos@serpentine.com
Safe Haskell | Trustworthy

Data.Text.Read

Description

Functions used frequently when reading textual data.

Synopsis

- type Reader a = Text -> Either String (a, Text)
- decimal :: Integral a => Reader a
- hexadecimal :: Integral a => Reader a
- signed :: Num a => Reader a -> Reader a
- rational :: Fractional a => Reader a
- double :: Reader Double

# Documentation

type Reader a = Text -> Either String (a, Text)

Read some text. If the read succeeds, return its value and the remaining text, otherwise an error message.

decimal :: Integral a => Reader a

Read a decimal integer. The input must begin with at least one decimal digit, and is consumed until a non-digit or end of string is reached.

This function does not handle leading sign characters. If you need to handle signed input, use ``signed` `decimal``.

Note: For fixed-width integer types, this function does not attempt to detect overflow, so a sufficiently long input may give incorrect results. If you are worried about overflow, use `Integer` for your result type.

hexadecimal :: Integral a => Reader a

Read a hexadecimal integer, consisting of an optional leading `"0x"` followed by at least one decimal digit. Input is consumed until a non-hex-digit or end of string is reached. This function is case insensitive.

This function does not handle leading sign characters. If you need to handle signed input, use ``signed` `hexadecimal``.

Note: For fixed-width integer types, this function does not attempt to detect overflow, so a sufficiently long input may give incorrect results. If you are worried about overflow, use `Integer` for your result type.

signed :: Num a => Reader a -> Reader a

Read an optional leading sign character (`'-'` or `'+'`) and apply it to the result of applying the given reader.

rational :: Fractional a => Reader a

Read a rational number.

This function accepts an optional leading sign character, followed by at least one decimal digit. The syntax similar to that accepted by the `read` function, with the exception that a trailing `'.'` or `'e'` not followed by a number is not consumed.

Examples (with behaviour identical to `read`):

    rational "3"     == Right (3.0, "")
    rational "3.1"   == Right (3.1, "")
    rational "3e4"   == Right (30000.0, "")
    rational "3.1e4" == Right (31000.0, "")
    rational ".3"    == Left "input does not start with a digit"
    rational "e3"    == Left "input does not start with a digit"

Examples of differences from `read`:

    rational "3.foo" == Right (3.0, ".foo")
    rational "3e"    == Right (3.0, "e")

double :: Reader Double

Read a rational number.

The syntax accepted by this function is the same as for `rational`.

Note: This function is almost ten times faster than `rational`, but is slightly less accurate.

The `Double` type supports about 16 decimal places of accuracy. For 94.2% of numbers, this function and `rational` give identical results, but for the remaining 5.8%, this function loses precision around the 15th decimal place. For 0.001% of numbers, this function will lose precision at the 13th or 14th decimal place.