@nodef/extra-array.web 4.5.0 → 4.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +183 -58
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- An [array] is a collection of values, stored contiguously.<br>
1
+ A collection of array functions that complement JavaScript's built-in [Array`][array] methods.
2
2
 
3
3
  ▌
4
4
  📦 [JSR](https://jsr.io/@nodef/extra-array),
@@ -6,31 +6,24 @@ An [array] is a collection of values, stored contiguously.<br>
6
6
  🌐 [Web](https://cdn.jsdelivr.net/npm/@nodef/extra-array.web),
7
7
  📰 [Docs](https://jsr.io/@nodef/extra-array/doc).
8
8
 
9
- <br>
9
+ This package provides a **comprehensive set of array functions** with which you can **generate** an array, **clone** it, query **about** it, get non-negative **indices**, manage its **length**, **get/set** elements, fully or partially **sort** it, obtain **minimum(s)/maximum(s)**, **compare** it with another array, get a **part** of it, **search a value**, obtain all possible **arrangements** or **random arrangements**, **find** an element, **take/drop** elements or **scan** from its beginning or its end, **search** the index of a part of it, perform **functional** operations, **flatten** multi-level arrays, obtain **prefix sum**, **manipulate** it in various ways, **count/partition** elements, **split** it, **concatenate/join** multiple arrays, **rearrange** elements within it, or perform **set operations** upon it.
10
+
11
+ Following a consistent naming convention, **all functions except `from*()` take the array as the 1st parameter**. Some functions operate on a specified *range* in the array and are named `ranged*()` (such as `rangedPartialSort()`). Functions like [swap] are **pure** and do not modify the array, while functions like [swap$] **do modify (update)** the array itself — the `$` suffix marks mutation. Some functions accept a *map function* for faster comparison (such as [unique]). Further, functions which return an *iterable* instead of an array are prefixed with `i` (such as [isubsequences]). Some names are borrowed from other languages such as *Haskell*, *Python*, *Java*, and *Processing*.
10
12
 
13
+ The additions cover:
11
14
 
12
- This package includes comprehensive set of array functions with which you can
13
- **generate** an array, **clone** it, query **about** it, get non-negative
14
- **indices**, manage its **length**, **get/set** elements, fully or partially
15
- **sort** it, obtain **minimum(s)/maximum(s)**, **compare** it with another
16
- array, get a **part** of it, **search a value**, obtain all possible
17
- **arrangements** or **random arrangements**, **find** an element, **take/drop**
18
- elements or **scan** from its beginning or its end, **search** the index of a
19
- part of it, perform **functional** operations, **flatten** multi-level arrays,
20
- obtain **prefix sum**, **manipulate** it in various ways, **count/partition**
21
- elements, **split** it, **concatenate/join** multiple arrays, **rearrange**
22
- elements within it, or performing **set operations** upon it.
23
-
24
- We use a consistent naming scheme that helps you quickly identify the functions
25
- you need. All functions except `from*()` take array as 1st parameter. Some
26
- functions operate on a specified range in the array and are called `ranged*()`,
27
- such as `rangedPartialSort()`. Functions like `swap()` are pure and do not
28
- modify the array itself, while functions like `swap$()` *do modify (update)* the
29
- array itself. Some functions accept a map function for *faster comparison*, such
30
- as `unique()`. Further, functions which return an iterable instead of an array
31
- are prefixed with `i`, such as `isubsequences()`. We borrow some names from
32
- other programming languages such as *Haskell*, *Python*, *Java*, and
33
- *Processing*.
15
+ - **Generation**: [fromRange], [fromInvocation], [fromApplication], [fromIterable].
16
+ - **Cloning**: [shallowClone], [deepClone].
17
+ - **Inspection**: [is], [keys], [values], [entries].
18
+ - **Access**: [get], [set], [getPath], [swap], [remove] and their mutating `$` variants.
19
+ - **Ordering**: [sort], [partialSort], [isSorted], [minimum], [maximum], [range].
20
+ - **Selection**: [head], [tail], [slice], [take], [drop], [scanWhile].
21
+ - **Search**: [searchValue], [searchInfix], [searchSubsequence], [indexOf], [search].
22
+ - **Transformation**: [map], [filter], [flat], [exclusiveScan], [adjacentCombine].
23
+ - **Manipulation**: [fill], [push], [splice], [copyWithin], [rotate].
24
+ - **Partitioning**: [count], [partition], [split], [cutAt], [chunk].
25
+ - **Combination**: [concat], [zip], [interleave], [cartesianProduct].
26
+ - **Set operations**: [unique], [union], [intersection], [difference], [symmetricDifference].
34
27
 
35
28
  [array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
36
29
 
@@ -39,18 +32,24 @@ other programming languages such as *Haskell*, *Python*, *Java*, and
39
32
  ```javascript
40
33
  import * as xarray from "jsr:@nodef/extra-array";
41
34
 
42
- var x = [1, 2, 3];
43
- xarray.get(x, -1);
35
+
36
+ // 1. Get value at an index (supports negative indices).
37
+ const a = [1, 2, 3];
38
+ xarray.get(a, -1);
44
39
  // → 3
45
40
 
46
- var x = [1, 2, 3, 4];
47
- xarray.swap(x, 0, 1);
41
+
42
+ // 2. Swap two values (pure, does not modify the array).
43
+ xarray.swap([1, 2, 3, 4], 0, 1);
48
44
  // → [ 2, 1, 3, 4 ]
49
45
 
50
- var x = [1, 2, 3, 4];
51
- xarray.rotate(x, 1);
46
+
47
+ // 3. Rotate values (pure).
48
+ xarray.rotate([1, 2, 3, 4], 1);
52
49
  // → [ 2, 3, 4, 1 ]
53
50
 
51
+
52
+ // 4. Obtain all possible arrangements.
54
53
  xarray.permutations([1, 2, 3]);
55
54
  // → [
56
55
  // [], [ 1 ],
@@ -68,9 +67,10 @@ xarray.permutations([1, 2, 3]);
68
67
  <br>
69
68
 
70
69
 
71
-
72
70
  ## Index
73
71
 
72
+ ### Generation
73
+
74
74
  | Property | Description |
75
75
  | ---- | ---- |
76
76
  | [fromRange] | Generate array from given number range. |
@@ -78,23 +78,43 @@ xarray.permutations([1, 2, 3]);
78
78
  | [fromApplication] | Generate array from repeated function application. |
79
79
  | [fromIterable] | Convert an iterable to array. |
80
80
  | [fromIterable$] | Convert an iterable to array! |
81
- | | |
81
+
82
+ ### Cloning
83
+
84
+ | Property | Description |
85
+ | ---- | ---- |
82
86
  | [shallowClone] | Shallow clone an array. |
83
87
  | [deepClone] | Deep clone an array. |
84
- | | |
88
+
89
+ ### Inspection
90
+
91
+ | Property | Description |
92
+ | ---- | ---- |
85
93
  | [is] | Check if value is an array. |
86
94
  | [keys] | Obtain all indices. |
87
95
  | [values] | Get all values. |
88
96
  | [entries] | Obtain all index-value pairs. |
89
- | | |
97
+
98
+ ### Indices
99
+
100
+ | Property | Description |
101
+ | ---- | ---- |
90
102
  | [index] | Get zero-based index for an element in array. |
91
103
  | [indexRange] | Get zero-based index range for part of array. |
92
- | | |
104
+
105
+ ### Length
106
+
107
+ | Property | Description |
108
+ | ---- | ---- |
93
109
  | [isEmpty] | Check if an array is empty. |
94
110
  | [length] | Find the length of an array. |
95
111
  | [resize$] | Resize an array to given length! |
96
112
  | [clear$] | Remove all elements from an array! |
97
- | | |
113
+
114
+ ### Get/Set
115
+
116
+ | Property | Description |
117
+ | ---- | ---- |
98
118
  | [get] | Get value at index. |
99
119
  | [getAll] | Get values at indices. |
100
120
  | [getPath] | Get value at path in a nested array. |
@@ -109,7 +129,11 @@ xarray.permutations([1, 2, 3]);
109
129
  | [remove] | Remove value at index. |
110
130
  | [remove$] | Remove value at index! |
111
131
  | [removePath$] | Remove value at path in a nested array! |
112
- | | |
132
+
133
+ ### Sorting
134
+
135
+ | Property | Description |
136
+ | ---- | ---- |
113
137
  | [isSorted] | Examine if array is sorted. |
114
138
  | [hasUnsortedValue] | Examine if array has an unsorted value. |
115
139
  | [searchUnsortedValue] | Find first index of an unsorted value. |
@@ -117,7 +141,11 @@ xarray.permutations([1, 2, 3]);
117
141
  | [sort$] | Arrange values in order! |
118
142
  | [partialSort] | Partially arrange values in order. |
119
143
  | [partialSort$] | Partially arrange values in order! |
120
- | | |
144
+
145
+ ### Minimum/Maximum
146
+
147
+ | Property | Description |
148
+ | ---- | ---- |
121
149
  | [minimum] | Find first smallest value. |
122
150
  | [minimumEntry] | Find first smallest entry. |
123
151
  | [maximum] | Find first largest value. |
@@ -132,10 +160,18 @@ xarray.permutations([1, 2, 3]);
132
160
  | [searchMaximumValue] | Find first index of maximum value. |
133
161
  | [searchMinimumValues] | Find indices of minimum values. |
134
162
  | [searchMaximumValues] | Find indices of maximum values. |
135
- | | |
163
+
164
+ ### Comparison
165
+
166
+ | Property | Description |
167
+ | ---- | ---- |
136
168
  | [isEqual] | Examine if two arrays are equal. |
137
169
  | [compare] | Compare two arrays (lexicographically). |
138
- | | |
170
+
171
+ ### Parts
172
+
173
+ | Property | Description |
174
+ | ---- | ---- |
139
175
  | [head] | Get first value. |
140
176
  | [tail] | Get values except first. |
141
177
  | [init] | Get values except last. |
@@ -143,7 +179,11 @@ xarray.permutations([1, 2, 3]);
143
179
  | [middle] | Get values from middle. |
144
180
  | [slice] | Get part of an array. |
145
181
  | [slice$] | Get part of an array! |
146
- | | |
182
+
183
+ ### Search
184
+
185
+ | Property | Description |
186
+ | ---- | ---- |
147
187
  | [includes] | Check if array has a value. |
148
188
  | [hasValue] | Examine if array has a value. |
149
189
  | [searchValue] | Find first index of a value. |
@@ -151,7 +191,11 @@ xarray.permutations([1, 2, 3]);
151
191
  | [searchValueAll] | Find indices of value. |
152
192
  | [searchAdjacentDuplicateValue] | Find first index of an adjacent duplicate value. |
153
193
  | [searchMismatchedValue] | Find first index where two arrays differ. |
154
- | | |
194
+
195
+ ### Contains
196
+
197
+ | Property | Description |
198
+ | ---- | ---- |
155
199
  | [hasPrefix] | Examine if array starts with a prefix. |
156
200
  | [hasSuffix] | Examine if array ends with a suffix. |
157
201
  | [hasInfix] | Examine if array contains an infix. |
@@ -166,7 +210,11 @@ xarray.permutations([1, 2, 3]);
166
210
  | [searchInfixRight] | Find last index of an infix. |
167
211
  | [searchInfixAll] | Find indices of an infix. |
168
212
  | [searchSubsequence] | Find first index of a subsequence. |
169
- | | |
213
+
214
+ ### Random
215
+
216
+ | Property | Description |
217
+ | ---- | ---- |
170
218
  | [randomValue] | Pick an arbitrary value. |
171
219
  | [randomPrefix] | Pick an arbitrary prefix. |
172
220
  | [randomSuffix] | Pick an arbitrary suffix. |
@@ -174,10 +222,18 @@ xarray.permutations([1, 2, 3]);
174
222
  | [randomSubsequence] | Pick an arbitrary subsequence. |
175
223
  | [randomPermutation] | Pick an arbitrary permutation. |
176
224
  | [randomPermutation$] | Pick an arbitrary permutation! |
177
- | | |
225
+
226
+ ### Find
227
+
228
+ | Property | Description |
229
+ | ---- | ---- |
178
230
  | [find] | Find first value passing a test. |
179
231
  | [findRight] | Find last value passing a test. |
180
- | | |
232
+
233
+ ### Take/Drop
234
+
235
+ | Property | Description |
236
+ | ---- | ---- |
181
237
  | [take] | Keep first n values only. |
182
238
  | [takeRight] | Keep last n values only. |
183
239
  | [takeWhile] | Keep values from left, while a test passes. |
@@ -186,18 +242,30 @@ xarray.permutations([1, 2, 3]);
186
242
  | [dropRight] | Discard last n values only. |
187
243
  | [dropWhile] | Discard values from left, while a test passes. |
188
244
  | [dropWhileRight] | Discard values from right, while a test passes. |
189
- | | |
245
+
246
+ ### Scan
247
+
248
+ | Property | Description |
249
+ | ---- | ---- |
190
250
  | [scanWhile] | Scan from left, while a test passes. |
191
251
  | [scanWhileRight] | Scan from right, while a test passes. |
192
252
  | [scanUntil] | Scan from left, until a test passes. |
193
253
  | [scanUntilRight] | Scan from right, until a test passes. |
194
- | | |
254
+
255
+ ### Search Indices
256
+
257
+ | Property | Description |
258
+ | ---- | ---- |
195
259
  | [indexOf] | Find first index of a value. |
196
260
  | [lastIndexOf] | Find last index of a value. |
197
261
  | [search] | Find index of first value passing a test. |
198
262
  | [searchRight] | Find index of last value passing a test. |
199
263
  | [searchAll] | Find indices of values passing a test. |
200
- | | |
264
+
265
+ ### Functional
266
+
267
+ | Property | Description |
268
+ | ---- | ---- |
201
269
  | [forEach] | Call a function for each value. |
202
270
  | [some] | Examine if any value satisfies a test. |
203
271
  | [every] | Examine if all values satisfy a test. |
@@ -211,23 +279,39 @@ xarray.permutations([1, 2, 3]);
211
279
  | [reject] | Discard values which pass a test. |
212
280
  | [reject$] | Discard values which pass a test! |
213
281
  | [rejectAt] | Discard values at given indices. |
214
- | | |
282
+
283
+ ### Flatten
284
+
285
+ | Property | Description |
286
+ | ---- | ---- |
215
287
  | [flat] | Flatten nested array to given depth. |
216
288
  | [flatMap] | Flatten nested array, based on map function. |
217
- | | |
289
+
290
+ ### Prefix Scan
291
+
292
+ | Property | Description |
293
+ | ---- | ---- |
218
294
  | [exclusiveScan] | Perform exclusive prefix scan from left to right. |
219
295
  | [exclusiveScan$] | Perform exclusive prefix scan from left to right! |
220
296
  | [inclusiveScan] | Perform inclusive prefix scan from left to right. |
221
297
  | [inclusiveScan$] | Perform inclusive prefix scan from left to right! |
222
298
  | [adjacentCombine] | Combine adjacent values of an array. |
223
299
  | [adjacentCombine$] | Combine adjacent values of an array! |
224
- | | |
300
+
301
+ ### Combine
302
+
303
+ | Property | Description |
304
+ | ---- | ---- |
225
305
  | [intersperse] | Place a separator between every value. |
226
306
  | [interpolate] | Estimate new values between existing ones. |
227
307
  | [intermix] | Place values of an array between another. |
228
308
  | [interleave] | Place values from iterables alternately. |
229
309
  | [zip] | Combine values from arrays. |
230
- | | |
310
+
311
+ ### Manipulate
312
+
313
+ | Property | Description |
314
+ | ---- | ---- |
231
315
  | [fill] | Fill with given value. |
232
316
  | [fill$] | Fill with given value! |
233
317
  | [push] | Add value to the end. |
@@ -246,12 +330,20 @@ xarray.permutations([1, 2, 3]);
246
330
  | [moveWithin$] | Move part of array within! |
247
331
  | [splice] | Remove or replace existing values. |
248
332
  | [splice$] | Remove or replace existing values! |
249
- | | |
333
+
334
+ ### Count/Partition
335
+
336
+ | Property | Description |
337
+ | ---- | ---- |
250
338
  | [count] | Count values which satisfy a test. |
251
339
  | [countEach] | Count occurrences of each distinct value. |
252
340
  | [partition] | Segregate values by test result. |
253
341
  | [partitionEach] | Segregate each distinct value. |
254
- | | |
342
+
343
+ ### Split
344
+
345
+ | Property | Description |
346
+ | ---- | ---- |
255
347
  | [split] | Break array considering test as separator. |
256
348
  | [splitAt] | Break array considering indices as separator. |
257
349
  | [cut] | Break array when test passes. |
@@ -260,18 +352,30 @@ xarray.permutations([1, 2, 3]);
260
352
  | [cutAtRight] | Break array after given indices. |
261
353
  | [group] | Keep similar values together and in order. |
262
354
  | [chunk] | Break array into chunks of given size. |
263
- | | |
355
+
356
+ ### Concatenate/Join
357
+
358
+ | Property | Description |
359
+ | ---- | ---- |
264
360
  | [concat] | Append values from arrays. |
265
361
  | [concat$] | Append values from arrays! |
266
362
  | [join] | Join values together into a string. |
267
- | | |
363
+
364
+ ### Rearrange
365
+
366
+ | Property | Description |
367
+ | ---- | ---- |
268
368
  | [cycle] | Obtain values that cycle through array. |
269
369
  | [repeat] | Repeat an array given times. |
270
370
  | [reverse] | Reverse the values. |
271
371
  | [reverse$] | Reverse the values! |
272
372
  | [rotate] | Rotate values in array. |
273
373
  | [rotate$] | Rotate values in array! |
274
- | | |
374
+
375
+ ### Set Operations
376
+
377
+ | Property | Description |
378
+ | ---- | ---- |
275
379
  | [isUnique] | Examine if there are no duplicate values. |
276
380
  | [isDisjoint] | Examine if arrays have no value in common. |
277
381
  | [unique] | Remove duplicate values. |
@@ -286,8 +390,24 @@ xarray.permutations([1, 2, 3]);
286
390
  <br>
287
391
 
288
392
 
289
- ## References
393
+ ## Story
394
+
395
+ An **array** is a *collection of values* stored **contiguously** in memory. Each value has a *zero-based index*, and the number of values is the array's *length*. In JavaScript, an [Array`][array] is a dynamic, resizable object whose elements may be of any type, including other arrays (hence *nested arrays*). Values are accessed with bracket notation (`a[i]`) or, for nested paths, by chaining indices (`a[i][j][k]`). Because JavaScript arrays are *sparse-capable* but typically dense, contiguous access is fast; iteration with `for...of`, `Array.fromAsync()`, or `Array.from()` yields values in index order.
396
+
397
+ In JavaScript, an array can be **created** with `[]`, `Array.of()`, `Array.from()`, or `new Array(n)` (which fills with *empty slots*), and **inspected** with `Array.isArray()`, `a.length`, `a.keys()`, `a.values()`, and `a.entries()`. Values can be **appended** with `a.push()`, **prepended** with `a.unshift()`, **removed** from either end with `a.pop()`/`a.shift()`, and **spliced** in or out with `a.splice()`. Copies are made with `a.slice()`, and the array itself can be reordered with `a.sort()`, `a.reverse()`, or `a.copyWithin()`. A **part** of the array can be extracted with `a.slice(start, end)`; a **test** applied with `a.some()`, `a.every()`, or `a.find()`; and a **functional transformation** performed with `a.map()`, `a.filter()`, and `a.reduce()`. These built-ins form the *idiomatic* baseline that this package extends.
398
+
399
+ The functions in this package **mirror** these built-ins where possible (`get`, `set`, `slice`, `sort`, `map`, `filter`, `reduce`, `some`, `every`) and **add** a wide range of others that are common in functional and mathematical code: *partial sorting* (as in NumPy's `partition`), *prefix scans* (inclusive and exclusive), *range-based variants* (`ranged*()`), *iterable-returning variants* (`i*()`), *random selection* (`random*()`), and *set operations* (`union`, `intersection`, `difference`, `symmetricDifference`, `cartesianProduct`). The `$` suffix consistently denotes **in-place mutation**, so a call to `xarray.map$(a, fn)` is exactly analogous to `Array.prototype.map` but writes into the original array; the pure form `xarray.map(a, fn)` returns a new array. This separation makes it easy to *opt in* to mutation and to reason about which calls allocate.
400
+
401
+ Because the package is a **single flat module**, every function is reachable from the same import. Groupings in the [Index](#index) above are *by purpose*, not by submodule, so you can scan for the operation you want and then confirm the exact signature in the [@nodef/extra-array` docs](https://jsr.io/@nodef/extra-array/doc).
402
+
403
+ <br>
404
+ <br>
405
+
406
+
407
+ ## See also
290
408
 
409
+ - [MDN: Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
410
+ - [MDN: TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
291
411
  - [Prefix sum array and difference array : Woburn C.I. PEGWiki](https://wcipeg.com/wiki/Prefix_sum_array_and_difference_array)
292
412
  - [How to get the count of each distinct value in a column?](https://stackoverflow.com/q/7053902/1413259)
293
413
  - [How to add region in java script file, visual studio](https://stackoverflow.com/a/51550649/1413259)
@@ -377,10 +497,15 @@ xarray.permutations([1, 2, 3]);
377
497
  [hasSubsequence]: https://jsr.io/@nodef/extra-array/doc/~/hasSubsequence
378
498
  [hasPermutation]: https://jsr.io/@nodef/extra-array/doc/~/hasPermutation
379
499
  [prefixes]: https://jsr.io/@nodef/extra-array/doc/~/prefixes
500
+ [iprefixes]: https://jsr.io/@nodef/extra-array/doc/~/iprefixes
380
501
  [suffixes]: https://jsr.io/@nodef/extra-array/doc/~/suffixes
502
+ [isuffixes]: https://jsr.io/@nodef/extra-array/doc/~/isuffixes
381
503
  [infixes]: https://jsr.io/@nodef/extra-array/doc/~/infixes
504
+ [iinfixes]: https://jsr.io/@nodef/extra-array/doc/~/iinfixes
382
505
  [subsequences]: https://jsr.io/@nodef/extra-array/doc/~/subsequences
506
+ [isubsequences]: https://jsr.io/@nodef/extra-array/doc/~/isubsequences
383
507
  [permutations]: https://jsr.io/@nodef/extra-array/doc/~/permutations
508
+ [ipermutations]: https://jsr.io/@nodef/extra-array/doc/~/ipermutations
384
509
  [searchInfix]: https://jsr.io/@nodef/extra-array/doc/~/searchInfix
385
510
  [searchInfixRight]: https://jsr.io/@nodef/extra-array/doc/~/searchInfixRight
386
511
  [searchInfixAll]: https://jsr.io/@nodef/extra-array/doc/~/searchInfixAll
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nodef/extra-array.web",
3
- "version": "4.5.0",
3
+ "version": "4.5.1",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "main": "./index.js",