Skip to main content

19  ascii standard library

The ascii module provides single-byte ASCII classification, case conversion, and hexadecimal digit encoding and decoding routines. It has no dependencies, does not allocate memory, and operates directly on integer byte values (0..255).

#use ascii

19.1 Function catalog

Category Function Signature Return Type Description
Classification ascii::is_ascii(c) Int => <> Flag <> True if 0 <= c <= 127
ascii::is_digit(c) Int => <> Flag <> True if ASCII digit ('0'..'9', 48..57)
ascii::is_upper(c) Int => <> Flag <> True if ASCII uppercase letter ('A'..'Z', 65..90)
ascii::is_lower(c) Int => <> Flag <> True if ASCII lowercase letter ('a'..'z', 97..122)
ascii::is_alpha(c) Int => <> Flag <> True if ASCII letter ('A'..'Z' or 'a'..'z')
ascii::is_alnum(c) Int => <> Flag <> True if ASCII letter or digit
ascii::is_hex(c) Int => <> Flag <> True if ASCII hexadecimal digit (0..9, a..f, A..F)
Case conversion ascii::to_lower(c) Int => Int Int Converts uppercase ASCII to lowercase; other inputs unchanged
ascii::to_upper(c) Int => Int Int Converts lowercase ASCII to uppercase; other inputs unchanged
Hex conversion ascii::hex_value(c) Int => <Int|> Option <Int|> Numeric value of hex digit 0..15, or absent <--> if invalid
ascii::hex_digit_lower(n) Int => <Int|> Option <Int|> Checked lowercase ASCII hex byte for 0 <= n <= 15
ascii::hex_digit_upper(n) Int => <Int|> Option <Int|> Checked uppercase ASCII hex byte for 0 <= n <= 15
ascii::hex_char_lower(n) Int => Int Int Lowercase ASCII hex byte (precondition: 0 <= n <= 15)
ascii::hex_char_upper(n) Int => Int Int Uppercase ASCII hex byte (precondition: 0 <= n <= 15)

19.2 Contracts & distinctions

  • Invalid-input safety: Classification predicates return <-> (false) for negative inputs and values outside their respective ASCII ranges. Case conversions leave negative and out-of-range inputs unchanged.
  • Unicode distinction: ascii::is_alpha and ascii::is_digit classify only ASCII bytes ('A'..'Z', 'a'..'z', '0'..'9'). For Unicode category classification across all Unicode scripts, use the unicode module (unicode::is_alpha, unicode::is_digit).
  • Hex conversion: hex_value returns <+ value +> for ASCII '0'..'9', 'a'..'f', and 'A'..'F', and <--> for all other inputs. hex_digit_lower and hex_digit_upper return <--> for values outside 0..15.

19.3 Example usage

#use ascii
#use io

// Classification
is_d = ascii::is_digit(53) // '5'
io::out(is_d | "digit" | "not digit")

// Case conversion
lower = ascii::to_lower(65) // 'A' -> 'a'
io::out(lower)

// Hexadecimal decoding
h = ascii::hex_value(102) // 'f'
io::out(h | _ | -1)