1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
//! §B.2.1 — `escape` and `unescape`, the percent-escaping that predates §19.2.6's.
//!
//! # Why these are not `encodeURI` under an older name
//!
//! They escape **code units**, where §19.2.6 escapes the octets of a UTF-8 encoding. That is the
//! whole difference and it is visible immediately: `escape("\u{1F600}")` is `"%uD83D%uDE00"` —
//! the two halves of the surrogate pair, each spelled on its own — while
//! `encodeURIComponent` of the same string is `"%F0%9F%98%80"`, the one code point it is. So
//! `escape` has a third form that §19.2.6 has no need of, `%uXXXX`, and no notion of a code point
//! at all.
//!
//! Which is why neither of them can fail. An unpaired surrogate is just a code unit here and gets
//! its own `%uD800`; there is no encoding to be invalid, so `URIError` never arises and
//! [`unescape`] answers something for every string in the language.
//!
//! # What `unescape` does with what it cannot read
//!
//! Nothing — it copies it through. `unescape("%")` is `"%"`, `unescape("%zz")` is `"%zz"`, and
//! `unescape("%u12")` is `"%u12"`. That is not leniency bolted on: §B.2.1.2 has no failure
//! outcome, so a `%` that does not begin an escape is an ordinary character and the walk moves on
//! by one. `decodeURI` throws for every one of those, which is the sharpest way to see that these
//! two families are separate rather than related.
//!
//! The two length conditions are asymmetric in the specification and the asymmetry is real:
//! `%uXXXX` needs `k + 5 < len` and `%XX` needs `k + 3 ≤ len`. Both say "the escape fits", counted
//! once from the last index and once from the length — see [`unescape`], where they are written as
//! one kind of question so the difference cannot be a bug.
//!
//! # Annex B, and why they are here at all
//!
//! Normative optional, and every browser has them because the web does. DR-0008's position is that
//! ViperJS implements Annex B where strictness alone decides it; these need no host flag and no
//! strictness, so they cost two functions and a table.
use define_method;
use crate;
use crateRealm;
use crate;
use crateVm;
/// The code unit `%`.
const PERCENT: u16 = 0x25;
/// The code unit `u`, which is what tells the four-digit form from the two-digit one.
const LOWER_U: u16 = 0x75;
/// The punctuation §B.2.1.1 leaves alone, beside the ASCII word characters.
///
/// **Not** §19.2.6.1's `uriMark`, and the difference is the point: this set has `@`, `+` and `/`,
/// which are exactly the reserved characters a URI *component* escaper must escape, and lacks
/// `!~'()`, which a URI escaper leaves alone. Two sets chosen for two different jobs a decade
/// apart, overlapping in `-`, `.` and `*` by coincidence rather than by derivation.
///
/// The underscore is not here because it is an ASCII **word** character and is covered by
/// [`word_character`] — which is the clause's own phrasing, and worth keeping as such: written as
/// `is_ascii_alphanumeric` plus a punctuation list, `_` falls between the two and is escaped, and
/// the only thing that says so is test262's `unmodified.js` spelling the set out in full.
const UNESCAPED: & = b"@*+-./";
/// Build §B.2.1's two functions onto the global object.
/// §B.2.1.1 `escape(string)`.
///
/// Three outcomes per code unit and no fourth: the unescaped set passes through, anything under
/// 256 becomes `%XX`, and everything else becomes `%uXXXX`. Nothing here can fail.
/// §B.2.1.2 `unescape(string)`.
///
/// Reads `%uXXXX` and `%XX`, and copies through every `%` that begins neither. There is no third
/// outcome and no error: what cannot be read is a character like any other.
/// The value of `count` hexadecimal digits at `position`, or `None` if they are not all there.
///
/// One function for both forms, which is what makes the specification's two length conditions —
/// `k + 5 < len` for four digits and `k + 3 ≤ len` for two — the same question asked once. Written
/// as two comparisons they differ by where they count from and would be two chances to be off by
/// one; written as "is there a slice of this length" they cannot.
/// An **ASCII word character** — a letter, a digit or `_`.
///
/// Its own function because `is_ascii_alphanumeric` is not it: the underscore is the difference,
/// and it is the one member of the set that no reader checks and every escaper needs. §22.2.2.9's
/// `\w` is the same set, spelled the same way.
/// The value of one hexadecimal digit, in either case.
/// The low nibble of `byte` as an uppercase hexadecimal digit.
///
/// Takes a whole byte and keeps four bits of it so that every caller can shift and hand it the
/// result, rather than masking at six call sites and getting one of them wrong.
/// `ToString` the argument, walk its units, and put the answer back on the heap.
///
/// Step 1 for both, and it is the only step either of them can fail at: neither walk has a failure
/// outcome, so a throw out of here is the argument's `toString` and nothing else.