Data.ByteString.Lex.Integral

bytestring-lexing-0.4.3: Parse and produce literals efficiently from strict or lazy bytestrings.

Portability | Haskell98
Stability | provisional
Maintainer | wren@community.haskell.org
Safe Haskell | None

Data.ByteString.Lex.Integral

Contents

- General combinators
- Decimal conversions
- Hexadecimal conversions
- Octal conversions

Description

Functions for parsing and producing `Integral` values from/to `ByteString`s based on the "Char8" encoding. That is, we assume an ASCII-compatible encoding of alphanumeric characters.

Synopsis

- readSigned :: Num a => (ByteString -> Maybe (a, ByteString)) -> ByteString -> Maybe (a, ByteString)
- readDecimal :: Integral a => ByteString -> Maybe (a, ByteString)
- readDecimal_ :: Integral a => ByteString -> a
- packDecimal :: Integral a => a -> Maybe ByteString
- readHexadecimal :: Integral a => ByteString -> Maybe (a, ByteString)
- packHexadecimal :: Integral a => a -> Maybe ByteString
- asHexadecimal :: ByteString -> ByteString
- readOctal :: Integral a => ByteString -> Maybe (a, ByteString)
- packOctal :: Integral a => a -> Maybe ByteString

# General combinators

readSigned :: Num a => (ByteString -> Maybe (a, ByteString)) -> ByteString -> Maybe (a, ByteString)

Adjust a reading function to recognize an optional leading sign. As with the other functions, we assume an ASCII-compatible encoding of the sign characters.

# Decimal conversions

readDecimal :: Integral a => ByteString -> Maybe (a, ByteString)

Read an unsigned/non-negative integral value in ASCII decimal format. Returns `Nothing` if there is no integer at the beginning of the string, otherwise returns `Just` the integer read and the remainder of the string.

If you are extremely concerned with performance, then it is more performant to use this function at `Int` or `Word` and then to call `fromIntegral` to perform the conversion at the end. However, doing this will make your code succeptible to overflow bugs if the target type is larger than `Int`.

readDecimal_ :: Integral a => ByteString -> a

A variant of `readDecimal` which does not return the tail of the string, and returns `0` instead of `Nothing`. This is twice as fast for `Int64` on 32-bit systems, but has identical performance to `readDecimal` for all other types and architectures.

packDecimal :: Integral a => a -> Maybe ByteString

Convert a non-negative integer into an (unsigned) ASCII decimal string. Returns `Nothing` on negative inputs.

# Hexadecimal conversions

readHexadecimal :: Integral a => ByteString -> Maybe (a, ByteString)

Read a non-negative integral value in ASCII hexadecimal format. Returns `Nothing` if there is no integer at the beginning of the string, otherwise returns `Just` the integer read and the remainder of the string.

This function does not recognize the various hexadecimal sigils like "0x", but because there are so many different variants, those are best handled by helper functions which then use this function for the actual numerical parsing. This function recognizes both upper-case, lower-case, and mixed-case hexadecimal.

packHexadecimal :: Integral a => a -> Maybe ByteString

Convert a non-negative integer into a lower-case ASCII hexadecimal string. Returns `Nothing` on negative inputs.

asHexadecimal :: ByteString -> ByteString

Convert a bitvector into a lower-case ASCII hexadecimal string. This is helpful for visualizing raw binary data, rather than for parsing as such.

# Octal conversions

readOctal :: Integral a => ByteString -> Maybe (a, ByteString)

Read a non-negative integral value in ASCII octal format. Returns `Nothing` if there is no integer at the beginning of the string, otherwise returns `Just` the integer read and the remainder of the string.

This function does not recognize the various octal sigils like "0o", but because there are different variants, those are best handled by helper functions which then use this function for the actual numerical parsing.

packOctal :: Integral a => a -> Maybe ByteString

Convert a non-negative integer into an ASCII octal string. Returns `Nothing` on negative inputs.