| 1 | import type { BytesLike } from "./index.js";
|
| 2 | /**
|
| 3 | * The stanard normalization forms.
|
| 4 | */
|
| 5 | export type UnicodeNormalizationForm = "NFC" | "NFD" | "NFKC" | "NFKD";
|
| 6 | /**
|
| 7 | * When using the UTF-8 error API the following errors can be intercepted
|
| 8 | * and processed as the %%reason%% passed to the [[Utf8ErrorFunc]].
|
| 9 | *
|
| 10 | * **``"UNEXPECTED_CONTINUE"``** - a continuation byte was present where there
|
| 11 | * was nothing to continue.
|
| 12 | *
|
| 13 | * **``"BAD_PREFIX"``** - an invalid (non-continuation) byte to start a
|
| 14 | * UTF-8 codepoint was found.
|
| 15 | *
|
| 16 | * **``"OVERRUN"``** - the string is too short to process the expected
|
| 17 | * codepoint length.
|
| 18 | *
|
| 19 | * **``"MISSING_CONTINUE"``** - a missing continuation byte was expected but
|
| 20 | * not found. The %%offset%% indicates the index the continuation byte
|
| 21 | * was expected at.
|
| 22 | *
|
| 23 | * **``"OUT_OF_RANGE"``** - the computed code point is outside the range
|
| 24 | * for UTF-8. The %%badCodepoint%% indicates the computed codepoint, which was
|
| 25 | * outside the valid UTF-8 range.
|
| 26 | *
|
| 27 | * **``"UTF16_SURROGATE"``** - the UTF-8 strings contained a UTF-16 surrogate
|
| 28 | * pair. The %%badCodepoint%% is the computed codepoint, which was inside the
|
| 29 | * UTF-16 surrogate range.
|
| 30 | *
|
| 31 | * **``"OVERLONG"``** - the string is an overlong representation. The
|
| 32 | * %%badCodepoint%% indicates the computed codepoint, which has already
|
| 33 | * been bounds checked.
|
| 34 | *
|
| 35 | *
|
| 36 | * @returns string
|
| 37 | */
|
| 38 | export type Utf8ErrorReason = "UNEXPECTED_CONTINUE" | "BAD_PREFIX" | "OVERRUN" | "MISSING_CONTINUE" | "OUT_OF_RANGE" | "UTF16_SURROGATE" | "OVERLONG";
|
| 39 | /**
|
| 40 | * A callback that can be used with [[toUtf8String]] to analysis or
|
| 41 | * recovery from invalid UTF-8 data.
|
| 42 | *
|
| 43 | * Parsing UTF-8 data is done through a simple Finite-State Machine (FSM)
|
| 44 | * which calls the ``Utf8ErrorFunc`` if a fault is detected.
|
| 45 | *
|
| 46 | * The %%reason%% indicates where in the FSM execution the fault
|
| 47 | * occurred and the %%offset%% indicates where the input failed.
|
| 48 | *
|
| 49 | * The %%bytes%% represents the raw UTF-8 data that was provided and
|
| 50 | * %%output%% is the current array of UTF-8 code-points, which may
|
| 51 | * be updated by the ``Utf8ErrorFunc``.
|
| 52 | *
|
| 53 | * The value of the %%badCodepoint%% depends on the %%reason%%. See
|
| 54 | * [[Utf8ErrorReason]] for details.
|
| 55 | *
|
| 56 | * The function should return the number of bytes that should be skipped
|
| 57 | * when control resumes to the FSM.
|
| 58 | */
|
| 59 | export type Utf8ErrorFunc = (reason: Utf8ErrorReason, offset: number, bytes: Uint8Array, output: Array<number>, badCodepoint?: number) => number;
|
| 60 | /**
|
| 61 | * A handful of popular, built-in UTF-8 error handling strategies.
|
| 62 | *
|
| 63 | * **``"error"``** - throws on ANY illegal UTF-8 sequence or
|
| 64 | * non-canonical (overlong) codepoints (this is the default)
|
| 65 | *
|
| 66 | * **``"ignore"``** - silently drops any illegal UTF-8 sequence
|
| 67 | * and accepts non-canonical (overlong) codepoints
|
| 68 | *
|
| 69 | * **``"replace"``** - replace any illegal UTF-8 sequence with the
|
| 70 | * UTF-8 replacement character (i.e. ``"\\ufffd"``) and accepts
|
| 71 | * non-canonical (overlong) codepoints
|
| 72 | *
|
| 73 | * @returns: Record<"error" | "ignore" | "replace", Utf8ErrorFunc>
|
| 74 | */
|
| 75 | export declare const Utf8ErrorFuncs: Readonly<Record<"error" | "ignore" | "replace", Utf8ErrorFunc>>;
|
| 76 | /**
|
| 77 | * Returns the UTF-8 byte representation of %%str%%.
|
| 78 | *
|
| 79 | * If %%form%% is specified, the string is normalized.
|
| 80 | */
|
| 81 | export declare function toUtf8Bytes(str: string, form?: UnicodeNormalizationForm): Uint8Array;
|
| 82 | /**
|
| 83 | * Returns the string represented by the UTF-8 data %%bytes%%.
|
| 84 | *
|
| 85 | * When %%onError%% function is specified, it is called on UTF-8
|
| 86 | * errors allowing recovery using the [[Utf8ErrorFunc]] API.
|
| 87 | * (default: [error](Utf8ErrorFuncs))
|
| 88 | */
|
| 89 | export declare function toUtf8String(bytes: BytesLike, onError?: Utf8ErrorFunc): string;
|
| 90 | /**
|
| 91 | * Returns the UTF-8 code-points for %%str%%.
|
| 92 | *
|
| 93 | * If %%form%% is specified, the string is normalized.
|
| 94 | */
|
| 95 | export declare function toUtf8CodePoints(str: string, form?: UnicodeNormalizationForm): Array<number>;
|
| 96 | //# sourceMappingURL=utf8.d.ts.map |
| \ | No newline at end of file |