# 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

```typescript
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

```typescript
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.