Utils: unicode-ranges

Purpose

Parses CSS/OpenType-style Unicode range notation into a Set<number> of integer codepoints. Font subsetting workflows need to know which codepoints to retain; this utility bridges the human-readable range format (e.g. U+0020-007F) and the numeric representation that font adapters operate on.

Features

Parses single codepoints: U+XXXX
Parses inclusive ranges: U+XXXX-XXXX
Case-insensitive for both the U+ prefix and hex digits
Merges multiple ranges into a single Set<number> with no duplicates
Throws FontCompressError(INVALID_OPTIONS) for malformed syntax or reversed ranges
Zero external dependencies

Usage: Basic Example

import { parseUnicodeRanges } from "@suaveplan/font-compress/utils/unicode-ranges";

// ASCII printable range
const ascii = parseUnicodeRanges(["U+0020-007F"]);
console.log(ascii.has(0x41)); // true  ("A")
console.log(ascii.size);      // 96

Usage: Advanced Example

import { parseUnicodeRanges } from "@suaveplan/font-compress/utils/unicode-ranges";
import { FontCompressError } from "@suaveplan/font-compress";

// Multi-range merge — Latin + Latin Extended
const ranges = parseUnicodeRanges(["U+0020-007F", "U+00A0-00FF"]);
console.log(ranges.size); // 192

// Catching parse errors
try {
    parseUnicodeRanges(["0020-007F"]); // missing U+ prefix
} catch (e) {
    if (e instanceof FontCompressError) {
        console.error(e.code);    // "FONT_COMPRESS.INVALID_OPTIONS"
        console.error(e.message); // describes the bad input
    }
}

API Reference

`parseUnicodeRanges(ranges: string[]): Set<number>`

Parameter	Type	Description
`ranges`	`string[]`	Array of range strings in `U+XXXX` or `U+XXXX-XXXX` format

Returns a Set<number> containing every integer codepoint covered by the union of all input ranges.

Throws FontCompressError with code FONT_COMPRESS.INVALID_OPTIONS when:

A string does not match the U+XXXX or U+XXXX-XXXX pattern
The start codepoint of a range exceeds the end codepoint

Implementation Notes

The regex ^[Uu]\+([0-9A-Fa-f]{1,6})(?:-([0-9A-Fa-f]{1,6}))?$ validates the entire string in a single pass, avoiding character-by-character parsing. Codepoints up to 6 hex digits are supported (U+10FFFF = 1114111), covering the full Unicode range. For very large ranges (e.g. U+0000-FFFF = 65536 entries), callers should be aware that Set construction is O(n) in the number of codepoints.

2.5 KiB Raw Blame History