Home › encoding/html_char_utils

Module encoding/html_char_utils

encoding/html_char_utils
Stability: unstable — this module exists to be `html_decode`'s numeric-reference helper, and whether it should be a module at all is the open question. Its two names are RE-EXPORTED by `std/encoding/html`, so the same two functions are reachable at two import paths, and only one of those can be the documented one. Making this private (or folding it into `html.yo`) removes an export, so it is breaking rather than additive — hence the marker rather than a quiet cleanup. `is_valid_entity_code` also has a hole worth closing in the same pass: its range checks are all written against POSITIVE code points, so a negative `i32` falls through to `true` (`issues/stddoc-io-is-valid-entity-code-accepts-negative-code-points.md`). Fixing that changes the predicate's answer, which is why it is named here. The `i32` parameter type is the third thing: a Unicode scalar is naturally a `rune` (or a `u32`), and `i32` is here only because `html_decode`'s numeric parser accumulates into one. Rust would take a `u32` and hand back `Option<char>`. — stable modules only change additively; this one may still change.

HTML character utility functions.

Provides Unicode codepoint validation and conversion for HTML entity processing.

Example

{ is_valid_entity_code, from_code_point } :: import "std/encoding/html_char_utils";

assert(is_valid_entity_code(i32(65)), "A is valid");
s := from_code_point(i32(65));  // "A"

Stability

unstable — this module exists to be html_decode's numeric-reference helper, and whether it should be a module at all is the open question. Its two names are RE-EXPORTED by std/encoding/html, so the same two functions are reachable at two import paths, and only one of those can be the documented one. Making this private (or folding it into html.yo) removes an export, so it is breaking rather than additive — hence the marker rather than a quiet cleanup.

is_valid_entity_code also has a hole worth closing in the same pass: its range checks are all written against POSITIVE code points, so a negative i32 falls through to true (issues/stddoc-io-is-valid-entity-code-accepts-negative-code-points.md). Fixing that changes the predicate's answer, which is why it is named here.

The i32 parameter type is the third thing: a Unicode scalar is naturally a rune (or a u32), and i32 is here only because html_decode's numeric parser accumulates into one. Rust would take a u32 and hand back Option<char>.

Functions

is_valid_entity_code function
fn(c : i32) -> bool

Whether c may stand as the value of an HTML numeric character reference: false for a UTF-16 surrogate, a noncharacter (the FDD0 block and every xFFFE/xFFFF), a C0 or C1 control that HTML does not permit, and anything above U+10FFFF.

Careful with the boundaries — this is NOT "is a Unicode scalar": TAB, LF, CR and \f are permitted (they are legal in HTML text) while \v and U+007F are not, which is WHATWG's numeric-character-reference table rather than a Unicode property.

A NEGATIVE c answers true, which is wrong and is a known defect — every range check here is written against positive values, so a negative falls through to the true arm (issues/stddoc-io-is-valid-entity-code-accepts-negative-code-points.md). Callers reaching this with a value that could be negative — html_decode does, since its hex parser accumulates into an i32 and overflows — should range-check first.

Parameters

NameTypeNotes
ci32

Returns: bool

from_code_point function
fn(c : i32) -> String

Render c as a one-rune String.

LOSSY, not fallible: a value outside U+0000..U+10FFFF (or a surrogate) is substituted with U+FFFD rather than reported, because that is what WHATWG prescribes for an out-of-range numeric reference — so html_decode gets the spec's behaviour by calling straight through. A caller that wants to know the input was bad checks is_valid_entity_code first.

Parameters

NameTypeNotes
ci32

Returns: String