Data.Text.Read

Functions used frequently when reading textual data.

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.