|
1 | 1 | # immutable-tuple [](https://travis-ci.org/benjamn/immutable-tuple)
|
2 | 2 |
|
3 | 3 | Immutable finite list objects with constant-time equality testing (`===`) and no memory leaks.
|
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +First install the package from npm: |
| 8 | + |
| 9 | +```sh |
| 10 | +npm install immutable-tuple |
| 11 | +``` |
| 12 | + |
| 13 | +or clone it from GitHub and then run `npm install` to compile the source code: |
| 14 | + |
| 15 | +```sh |
| 16 | +git clone https://github.com/benjamn/immutable-tuple.git |
| 17 | +cd immutable-tuple |
| 18 | +npm install |
| 19 | +npm test # if skeptical |
| 20 | +``` |
| 21 | + |
| 22 | +The npm package exports a single function called `tuple`, both as a `default` export and as an equivalent named export, so all of the following import styles will work: |
| 23 | + |
| 24 | +```js |
| 25 | +import tuple from "immutable-tuple"; |
| 26 | +import { tuple } from "immutable-tuple"; |
| 27 | +const { tuple } = require("immutable-tuple"); |
| 28 | +const tuple = require("immutable-tuple").tuple; |
| 29 | + |
| 30 | +// Note that this style will *not* work: |
| 31 | +const tuple = require("immutable-tuple"); |
| 32 | +``` |
| 33 | + |
| 34 | +The `tuple` function takes any number of arguments, and returns a unique, immutable object that inherits from `tuple.prototype` and is guaranteed to be `===` any other `tuple` object created from the same sequence of arguments: |
| 35 | + |
| 36 | +```js |
| 37 | +const obj = { asdf: 1234 }; |
| 38 | +const t1 = tuple(1, "asdf", obj); |
| 39 | +const t2 = tuple(1, "asdf", obj); |
| 40 | +assert(t1 === t2); |
| 41 | + |
| 42 | +assert.strictEqual( |
| 43 | + tuple(t1, t2), |
| 44 | + tuple(t2, t1) |
| 45 | +); |
| 46 | +``` |
| 47 | + |
| 48 | +Because `tuple` objects are identical when (and only when) their elements are identical, any two tuples can be compared for equality in constant time, regardless of how many elements they contain. |
| 49 | + |
| 50 | +The `tuple` object has a fixed numeric `.length` property, and its elements may be accessed using array index notation: |
| 51 | + |
| 52 | +```js |
| 53 | +assert.strictEqual(t1.length, 3); |
| 54 | +t1.forEach((x, i) => assert.strictEqual(x, t2[i])); |
| 55 | +``` |
| 56 | + |
| 57 | +Every non-destructive method of `Array.prototype` is also supported by `tuple.prototype`, including `sort` and `reverse`, which return a modified copy of the `tuple` without altering the original: |
| 58 | + |
| 59 | +```js |
| 60 | +assert.strictEqual( |
| 61 | + tuple(6, 2, 8, 1, 3, 0).sort(), |
| 62 | + tuple(0, 1, 2, 3, 6, 8) |
| 63 | +); |
| 64 | + |
| 65 | +assert.strictEqual( |
| 66 | + tuple(1).concat(2, tuple(3, 4), 5), |
| 67 | + tuple(1, 2, 3, 4, 5) |
| 68 | +); |
| 69 | +``` |
| 70 | + |
| 71 | +While the identity, number, and order of elements in the `tuple` is fixed, please note that the contents of the individual elements are not frozen in any way: |
| 72 | + |
| 73 | +```js |
| 74 | +const obj = { asdf: 1234 }; |
| 75 | +tuple(1, "asdf", obj)[2].asdf = "oyez"; |
| 76 | +assert.strictEqual(obj.asdf, "oyez"); |
| 77 | +``` |
0 commit comments