Debian Codegraph @

docs/src/tuple.html

raw
1 <!DOCTYPE html>
2
3 <html>
4 <head>
5 <title>tuple.js</title>
6 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
7 <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
8 <link rel="stylesheet" media="all" href="../docco.css" />
9 </head>
10 <body>
11 <div id="container">
12 <div id="background"></div>
13
14 <ul id="jump_to">
15 <li>
16 <a class="large" href="javascript:void(0);">Jump To &hellip;</a>
17 <a class="small" href="javascript:void(0);">+</a>
18 <div id="jump_wrapper">
19 <div id="jump_page_wrapper">
20 <div id="jump_page">
21
22
23 <a class="source" href="tuple.html">
24 src/tuple.js
25 </a>
26
27
28 <a class="source" href="universal-weak-map.html">
29 src/universal-weak-map.js
30 </a>
31
32
33 <a class="source" href="util.html">
34 src/util.js
35 </a>
36
37 </div>
38 </div>
39 </li>
40 </ul>
41
42 <ul class="sections">
43
44 <li id="title">
45 <div class="annotation">
46 <h1>tuple.js</h1>
47 </div>
48 </li>
49
50
51
52 <li id="section-1">
53 <div class="annotation">
54
55 <div class="pilwrap ">
56 <a class="pilcrow" href="#section-1">&#182;</a>
57 </div>
58 <p>See <a href="universal-weak-map.html"><code>universal-weak-map.js</code></a>.</p>
59
60 </div>
61
62 <div class="content"><div class='highlight'><pre><span class="hljs-keyword">import</span> { UniversalWeakMap } <span class="hljs-keyword">from</span> <span class="hljs-string">"./universal-weak-map.js"</span>;</pre></div></div>
63
64 </li>
65
66
67 <li id="section-2">
68 <div class="annotation">
69
70 <div class="pilwrap ">
71 <a class="pilcrow" href="#section-2">&#182;</a>
72 </div>
73 <p>See <a href="util.html"><code>util.js</code></a>.</p>
74
75 </div>
76
77 <div class="content"><div class='highlight'><pre><span class="hljs-keyword">import</span> {
78 brand,
79 globalKey,
80 forEachArrayMethod,
81 } <span class="hljs-keyword">from</span> <span class="hljs-string">"./util.js"</span>;</pre></div></div>
82
83 </li>
84
85
86 <li id="section-3">
87 <div class="annotation">
88
89 <div class="pilwrap ">
90 <a class="pilcrow" href="#section-3">&#182;</a>
91 </div>
92 <p>When called with any number of arguments, this function returns an
93 object that inherits from <code>tuple.prototype</code> and is guaranteed to be
94 <code>===</code> any other <code>tuple</code> object that has exactly the same items. In
95 computer science jargon, <code>tuple</code> instances are “internalized” or just
96 “interned,” which allows for constant-time equality checking, and makes
97 it possible for tuple objects to be used as <code>Map</code> or <code>WeakMap</code> keys, or
98 stored in a <code>Set</code>.</p>
99
100 </div>
101
102 <div class="content"><div class='highlight'><pre><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">tuple</span>(<span class="hljs-params">...items</span>) </span>{
103 <span class="hljs-keyword">return</span> intern(items);
104 }</pre></div></div>
105
106 </li>
107
108
109 <li id="section-4">
110 <div class="annotation">
111
112 <div class="pilwrap ">
113 <a class="pilcrow" href="#section-4">&#182;</a>
114 </div>
115 <p>Named imports work as well as <code>default</code> imports.</p>
116
117 </div>
118
119 <div class="content"><div class='highlight'><pre><span class="hljs-keyword">export</span> { tuple };</pre></div></div>
120
121 </li>
122
123
124 <li id="section-5">
125 <div class="annotation">
126
127 <div class="pilwrap ">
128 <a class="pilcrow" href="#section-5">&#182;</a>
129 </div>
130 <p>If this package is installed multiple times, there could be mutiple
131 implementations of the <code>tuple</code> function with distinct <code>tuple.prototype</code>
132 objects, but the shared pool of <code>tuple</code> objects must be the same across
133 all implementations. While it would be ideal to use the <code>global</code>
134 object, there’s no reliable way to get the global object across all JS
135 environments without using the <code>Function</code> constructor, so instead we
136 use the global <code>Array</code> constructor as a shared namespace.</p>
137
138 </div>
139
140 <div class="content"><div class='highlight'><pre><span class="hljs-keyword">const</span> root = globalKey <span class="hljs-keyword">in</span> <span class="hljs-built_in">Array</span>
141 ? <span class="hljs-built_in">Array</span>[globalKey]
142 : def(<span class="hljs-built_in">Array</span>, globalKey, <span class="hljs-keyword">new</span> UniversalWeakMap, <span class="hljs-literal">false</span>);
143
144 <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">intern</span>(<span class="hljs-params">array</span>) </span>{
145 <span class="hljs-keyword">let</span> node = root;</pre></div></div>
146
147 </li>
148
149
150 <li id="section-6">
151 <div class="annotation">
152
153 <div class="pilwrap ">
154 <a class="pilcrow" href="#section-6">&#182;</a>
155 </div>
156 <p>Because we are building a tree of <em>weak</em> maps, the tree will not
157 prevent objects in tuples from being garbage collected, since the
158 tree itself will be pruned over time when the corresponding <code>tuple</code>
159 objects become unreachable. In addition to internalization, this
160 property is a key advantage of the <code>immutable-tuple</code> package.</p>
161
162 </div>
163
164 <div class="content"><div class='highlight'><pre> array.forEach(<span class="hljs-function"><span class="hljs-params">item</span> =&gt;</span> {
165 node = node.get(item) || node.set(item, <span class="hljs-keyword">new</span> UniversalWeakMap);
166 });</pre></div></div>
167
168 </li>
169
170
171 <li id="section-7">
172 <div class="annotation">
173
174 <div class="pilwrap ">
175 <a class="pilcrow" href="#section-7">&#182;</a>
176 </div>
177 <p>If a <code>tuple</code> object has already been created for exactly these items,
178 return that object again.</p>
179
180 </div>
181
182 <div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> (node.tuple) {
183 <span class="hljs-keyword">return</span> node.tuple;
184 }
185
186 <span class="hljs-keyword">const</span> t = <span class="hljs-built_in">Object</span>.create(tuple.prototype);</pre></div></div>
187
188 </li>
189
190
191 <li id="section-8">
192 <div class="annotation">
193
194 <div class="pilwrap ">
195 <a class="pilcrow" href="#section-8">&#182;</a>
196 </div>
197 <p>Define immutable items with numeric indexes, and permanently fix the
198 <code>.length</code> property.</p>
199
200 </div>
201
202 <div class="content"><div class='highlight'><pre> array.forEach(<span class="hljs-function">(<span class="hljs-params">item, i</span>) =&gt;</span> def(t, i, item, <span class="hljs-literal">true</span>));
203 def(t, <span class="hljs-string">"length"</span>, array.length, <span class="hljs-literal">false</span>);</pre></div></div>
204
205 </li>
206
207
208 <li id="section-9">
209 <div class="annotation">
210
211 <div class="pilwrap ">
212 <a class="pilcrow" href="#section-9">&#182;</a>
213 </div>
214 <p>Remember this new <code>tuple</code> object so that we can return the same object
215 earlier next time.</p>
216
217 </div>
218
219 <div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> node.tuple = t;
220 }</pre></div></div>
221
222 </li>
223
224
225 <li id="section-10">
226 <div class="annotation">
227
228 <div class="pilwrap ">
229 <a class="pilcrow" href="#section-10">&#182;</a>
230 </div>
231 <p>Convenient helper for defining hidden immutable properties.</p>
232
233 </div>
234
235 <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">def</span>(<span class="hljs-params">obj, name, value, enumerable</span>) </span>{
236 <span class="hljs-built_in">Object</span>.defineProperty(obj, name, {
237 <span class="hljs-attr">value</span>: value,
238 <span class="hljs-attr">enumerable</span>: !! enumerable,
239 <span class="hljs-attr">writable</span>: <span class="hljs-literal">false</span>,
240 <span class="hljs-attr">configurable</span>: <span class="hljs-literal">false</span>
241 });
242 <span class="hljs-keyword">return</span> value;
243 }</pre></div></div>
244
245 </li>
246
247
248 <li id="section-11">
249 <div class="annotation">
250
251 <div class="pilwrap ">
252 <a class="pilcrow" href="#section-11">&#182;</a>
253 </div>
254 <p>Since the <code>immutable-tuple</code> package could be installed multiple times
255 in an application, there is no guarantee that the <code>tuple</code> constructor
256 or <code>tuple.prototype</code> will be unique, so <code>value instanceof tuple</code> is
257 unreliable. Instead, to test if a value is a tuple, you should use
258 <code>tuple.isTuple(value)</code>.</p>
259
260 </div>
261
262 <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">isTuple</span>(<span class="hljs-params">that</span>) </span>{
263 <span class="hljs-keyword">return</span> !! (that &amp;&amp; that[brand] === <span class="hljs-literal">true</span>);
264 }
265
266 def(tuple.prototype, brand, <span class="hljs-literal">true</span>, <span class="hljs-literal">false</span>);
267
268 tuple.isTuple = isTuple;
269
270 <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">toArray</span>(<span class="hljs-params">tuple</span>) </span>{
271 <span class="hljs-keyword">const</span> array = [];
272 <span class="hljs-keyword">let</span> i = tuple.length;
273 <span class="hljs-keyword">while</span> (i--) array[i] = tuple[i];
274 <span class="hljs-keyword">return</span> array;
275 }</pre></div></div>
276
277 </li>
278
279
280 <li id="section-12">
281 <div class="annotation">
282
283 <div class="pilwrap ">
284 <a class="pilcrow" href="#section-12">&#182;</a>
285 </div>
286 <p>Copy all generic non-destructive Array methods to <code>tuple.prototype</code>.
287 This works because (for example) <code>Array.prototype.slice</code> can be invoked
288 against any <code>Array</code>-like object.</p>
289
290 </div>
291
292 <div class="content"><div class='highlight'><pre>forEachArrayMethod(<span class="hljs-function">(<span class="hljs-params">name, desc, mustConvertThisToArray</span>) =&gt;</span> {
293 <span class="hljs-keyword">const</span> method = desc &amp;&amp; desc.value;
294 <span class="hljs-keyword">if</span> (<span class="hljs-keyword">typeof</span> method === <span class="hljs-string">"function"</span>) {
295 desc.value = <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">...args</span>) </span>{
296 <span class="hljs-keyword">const</span> result = method.apply(
297 mustConvertThisToArray ? toArray(<span class="hljs-keyword">this</span>) : <span class="hljs-keyword">this</span>,
298 args
299 );</pre></div></div>
300
301 </li>
302
303
304 <li id="section-13">
305 <div class="annotation">
306
307 <div class="pilwrap ">
308 <a class="pilcrow" href="#section-13">&#182;</a>
309 </div>
310 <p>Of course, <code>tuple.prototype.slice</code> should return a <code>tuple</code> object,
311 not a new <code>Array</code>.</p>
312
313 </div>
314
315 <div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> <span class="hljs-built_in">Array</span>.isArray(result) ? intern(result) : result;
316 };
317 <span class="hljs-built_in">Object</span>.defineProperty(tuple.prototype, name, desc);
318 }
319 });</pre></div></div>
320
321 </li>
322
323
324 <li id="section-14">
325 <div class="annotation">
326
327 <div class="pilwrap ">
328 <a class="pilcrow" href="#section-14">&#182;</a>
329 </div>
330 <p>Like <code>Array.prototype.concat</code>, except for the extra effort required to
331 convert any tuple arguments to arrays, so that</p>
332 <pre><code>tuple(<span class="hljs-number">1</span>).concat(tuple(<span class="hljs-number">2</span>), <span class="hljs-number">3</span>) === tuple(<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>)
333 </code></pre>
334 </div>
335
336 <div class="content"><div class='highlight'><pre><span class="hljs-keyword">const</span> { concat } = <span class="hljs-built_in">Array</span>.prototype;
337 tuple.prototype.concat = <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">...args</span>) </span>{
338 <span class="hljs-keyword">return</span> intern(concat.apply(toArray(<span class="hljs-keyword">this</span>), args.map(
339 <span class="hljs-function"><span class="hljs-params">item</span> =&gt;</span> isTuple(item) ? toArray(item) : item
340 )));
341 };</pre></div></div>
342
343 </li>
344
345 </ul>
346 </div>
347 </body>
348 </html>