Skip to content

Commit df8c8df

Browse files
authored
Add a "Usage" section to README.md.
1 parent f633cef commit df8c8df

File tree

1 file changed

+74
-0
lines changed

1 file changed

+74
-0
lines changed

README.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,77 @@
11
# immutable-tuple [![Build Status](https://travis-ci.org/benjamn/immutable-tuple.svg?branch=master)](https://travis-ci.org/benjamn/immutable-tuple)
22

33
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

Comments
 (0)