Apache-2.0 licensed by Chris Martin
Maintained by Chris Martin, Julie Moronuki
This version can be pinned in stack with:ascii-,1795

Module documentation for

What is ASCII?

The American Standard Code for Information Interchange (ASCII) comprises a set of 128 characters, each represented by 7 bits. 33 of these characters are “control codes”; a few of these are still in use, but most are obsolete relics of the early days of computing. The other 95 are “printable characters” such as letters and numbers, mostly corresponding to the keys on an American English keyboard.

Nowadays instead of ASCII we typically work with text using an encoding such as UTF-8 that can represent the entire Unicode character set, which includes over a hundred thousand characters and is not limited to the symbols of any particular writing system or culture. However, ASCII is still relevant to network protocols; for example, we can see it in the specification of HTTP.

There is a convenient relationship between ASCII and Unicode: the ASCII characters are the first 128 characters of the much larger Unicode character set. The C0 Controls and Basic Latin section of the Unicode standard contains a list of all the ASCII characters.

Haskell packages

This repository contains the main API, the ASCII module in the ascii package, which is an amalgamation of smaller packages in other repositories.

  • If you only need the ASCII Char type, you can use the ascii-char package, which is minimal so that it can be kept stable.

  • The ascii-group package defines the Group type (Control and Printable), and the ascii-case package defines the Case type (UpperCase and LowerCase). These package are also small and stable.

  • The ascii-predicates package provides additional ways of categorizing characters similar to what you can find in the base package.

  • For case-insensitivity, use the ascii-caseless package.

  • The ascii-superset package defines CharSuperset and StringSuperset classes to generalize types that represent characters and strings, respectively, in character sets larger than ASCII. It also defines the ASCII type constructor, which is used to indicate that a value from some ASCII superset is confined to ASCII.

  • The ascii-numbers package provides utilities for working with numbers represented using ASCII digits 0-9, ASCII letters A-F to represent hexadecimal digits 10-15, and the HyphenMinus character for negation.

  • The ascii-th package provides a quasi-quoter that allows one to safely and conveniently express ASCII string literals. The generated expressions are polymorphic and can take the form of any type belonging to the StringSuperset class, including [ASCII.Char], String, ByteString, and Text.

Changes (2023-06-26)

Upgrade language to GHC2021 (2023-03-01)

Rename toAsciiCharMaybe to toCharMaybe

Add toCharListMaybe (2023-02-08)

Raise ascii-superset to 1.3. This removes the ASCII.Lift module.

Raise ascii-numbers to 1.2.

From the ASCII module, the Lift class and lift function are removed.

The removed lift function is replaced with the lift function from ASCII.Refinement. If you were using lift specialized as ASCII a -> a, then this is not a breaking change. Otherwise, migrate by using one the new functions below.

fromChar        :: FromChar char               => Char      -> char
fromCharList    :: FromString string           => [Char]    -> string
fromDigit       :: DigitSuperset char          => Digit     -> char
fromDigitList   :: DigitStringSuperset string  => [Digit]   -> string
fromHexChar     :: HexCharSuperset char        => HexChar   -> char
fromHexCharList :: HexStringSuperset string    => [HexChar] -> string

forgetCase      :: ASCII'case letterCase superset -> ASCII superset (2023-02-08)

Raise ascii-superset to 1.2.7

Adds module ASCII.Superset.Text

Added to the ASCII module:

  • Class ToText
  • Functions toStrictText, toLazyText, toUnicodeCharList (2023-02-07)

Raise ascii-superset to 1.2.6

Added class StringSupersetConversion and the following function:

convertRefinedString ::
    StringSupersetConversion a b => ASCII a -> ASCII b (2023-01-25)

New functions: asciiByteStringToText and asciiByteStringToTextLazy (2023-01-06)

Raise ascii-superset version to 1.2.5. This adds a new instance:

instance Lift (ASCII'case letterCase superset) (ASCII superset) (2023-01-06)

Raise ascii-th version to 1.2.0. This changes the constraints on lower and upper quasi-quotations in an expression context. Previously, the constraint was FromString. The constraints are now ToCasefulString 'LowerCase and ToCasefulString 'UpperCase respectively. This expands the range of types inhabited by lower/uppercase quotes to include ASCII'lower and ASCII'upper, which were previously not able to be expressed using quasi-quotations. (2023-01-05)

Raise ascii-superset version from 1.2.0 to 1.2.4. This adds classes ToCasefulChar and ToCasefulString to the ASCII.Superset module. It also adds some instances for the various other superset classes. (2023-01-05)

Change test suite from hedgehog to hspec (2023-01-05)

Raise ascii-char version to 1.0.1. This adds Word8 conversions to the ASCII.Char module. (2023-01-03)

Additions to the ASCII module: disregardCase, ASCII'case, ASCII'upper, ASCII'lower, KnownCase (..), refineCharToCase, refineStringToCase

Update ascii-superset to 1.2.0. This adds CharSuperset (toCaseChar), StringSuperset (toCaseString), refineCharToCase, and refineStringToCase.

The constraint on toCaseChar is relaxed from CharIso to CharSuperset. The constraint on toCaseString is relaxed from StringIso to StringSuperset. (2023-01-03)

Update ascii-th to 1.1.1.

This adds, most notably, to the ASCII.QuasiQuoters module. The new quasi-quoters are caseless, lower, and upper. These are also re-exported from the ASCII module. (2023-01-03)

Update ascii-superset to 1.1.0.

This adds several classes to the ASCII.Superset module: ToChar, FromChar, ToString, FromString, ToCaselessChar, and ToCaselessString.

This is a breaking change because these are superclasses of the existing CharSuperset and StringSuperset classes, and they take methods from them. (2023-01-02)

Update ascii-superset to 1.0.2. This adds the ASCII.CaseRefinement module. (2023-01-02)

Add the ASCII.Caseless module (re-exported from the ascii-caseless package)

Additions to the ASCII module:

  • CaselessChar (2022-12-30)

Metadata changes only (2022-12-23)

Bump version of ascii-case to 1.0.1. This adds the following function to the ASCII.Case module:

opposite :: Case -> Case (2022-05-04)

Add isVisible :: Char -> Bool. Visible characters include all print characters other than Space. (2022-04-29)

Add type UnicodeChar = Data.Char.Char type alias to ASCII module (2022-04-29)

New polymorphic narrowing functions:

  • toAsciiCharMaybe :: CharSuperset char => char -> Maybe Char
  • toDigitMaybe :: DigitSuperset char => char -> Maybe Digit
  • toHexCharMaybe :: HexCharSuperset char => char -> Maybe HexChar

New monomorphic character conversion functions:

  • digitToWord8 :: Digit -> Word8
  • word8ToDigitMaybe :: Word8 -> Maybe Digit
  • word8ToDigitUnsafe :: Word8 -> Digit
  • digitToChar :: Digit -> Char
  • charToDigitMaybe :: Char -> Maybe Digit
  • charToDigitUnsafe :: Char -> Digit
  • digitToUnicode :: Digit -> Unicode.Char
  • unicodeToDigitMaybe :: Unicode.Char -> Maybe Digit
  • unicodeToDigitUnsafe :: Unicode.Char -> Digit
  • hexCharToWord8 :: HexChar -> Word8
  • word8ToHexCharMaybe :: Word8 -> Maybe HexChar
  • word8ToHexCharUnsafe :: Word8 -> HexChar
  • hexCharToChar :: HexChar -> Char
  • charToHexCharMaybe :: Char -> Maybe HexChar
  • charToHexCharUnsafe :: Char -> HexChar
  • hexCharToUnicode :: HexChar -> Unicode.Char
  • unicodeToHexCharMaybe :: Unicode.Char -> Maybe HexChar
  • unicodeToHexCharUnsafe :: Unicode.Char -> HexChar (2022-04-20)

Update to ascii-numbers version 1.1.0. The major change is that there are now Lift instances for Digit and HexChar.

Added functions digitString and hexCharString

Add dependency on ascii-numbers

New modules:

  • ASCII.Decimal
  • ASCII.Hexadecimal

New types:

  • Digit
  • HexChar

New classes:

  • DigitSuperset
  • DigitStringSuperset
  • HexCharSuperset
  • HexStringSuperset

New functions:

  • showIntegralDecimal

  • showIntegralHexadecimal

  • readIntegralDecimal

  • readIntegralHexadecimal

  • showNaturalDigits

  • readNaturalDigits

  • showNaturalHexChars

  • readNaturalHexChars

  • showNaturalDecimal

  • showNaturalHexadecimal

  • readNaturalDecimal

  • readNaturalHexadecimal

Dropped support for old versions:

  • Drop support for base 4.11 (GHC 8.4)
  • Drop support for base 4.12 (GHC 8.6)

Switch test-suite over to hedgehog

Support GHC 9.2

New functions:

  • isAlphaNum
  • isLetter
  • isDigit
  • isOctDigit
  • isHexDigit
  • isSpace
  • isPunctuation
  • isSymbol

The dependency on the ‘data-ascii’ package is removed, and the following modules are no longer re-exported:

  • Data.Ascii
  • Data.Ascii.Blaze
  • Data.Ascii.ByteString
  • Data.Ascii.Word8

Add a test suite

Raise text lower bound to 1.2.3

Support GHC 9.0

Support bytestring-0.11

New functions:

  • byteStringToUnicodeStringMaybe
  • unicodeStringToByteStringMaybe
  • byteListToUnicodeStringMaybe
  • unicodeStringToByteListMaybe
  • convertCharMaybe
  • convertCharOrFail
  • convertStringMaybe
  • convertStringOrFail

Support GHC 8.10

Completely redesigned the library