1 | # es6-iterator
|
2 | ## ECMAScript 6 Iterator interface
|
3 |
|
4 | ### Installation
|
5 |
|
6 | $ npm install es6-iterator
|
7 |
|
8 | To port it to Browser or any other (non CJS) environment, use your favorite CJS bundler. No favorite yet? Try: [Browserify](http://browserify.org/), [Webmake](https://github.com/medikoo/modules-webmake) or [Webpack](http://webpack.github.io/)
|
9 |
|
10 | ## API
|
11 |
|
12 | ### Constructors
|
13 |
|
14 | #### Iterator(list) _(es6-iterator)_
|
15 |
|
16 | Abstract Iterator interface. Meant for extensions and not to be used on its own.
|
17 |
|
18 | Accepts any _list_ object (technically object with numeric _length_ property).
|
19 |
|
20 | _Mind it doesn't iterate strings properly, for that use dedicated [StringIterator](#string-iterator)_
|
21 |
|
22 | ```javascript
|
23 | var Iterator = require('es6-iterator')
|
24 | var iterator = new Iterator([1, 2, 3]);
|
25 |
|
26 | iterator.next(); // { value: 1, done: false }
|
27 | iterator.next(); // { value: 2, done: false }
|
28 | iterator.next(); // { value: 3, done: false }
|
29 | iterator.next(); // { value: undefined, done: true }
|
30 | ```
|
31 |
|
32 |
|
33 | #### ArrayIterator(arrayLike[, kind]) _(es6-iterator/array)_
|
34 |
|
35 | Dedicated for arrays and array-likes. Supports three iteration kinds:
|
36 | * __value__ _(default)_ - Iterates values
|
37 | * __key__ - Iterates indexes
|
38 | * __key+value__ - Iterates keys and indexes, each iteration value is in _[key, value]_ form.
|
39 |
|
40 |
|
41 | ```javascript
|
42 | var ArrayIterator = require('es6-iterator/array')
|
43 | var iterator = new ArrayIterator([1, 2, 3], 'key+value');
|
44 |
|
45 | iterator.next(); // { value: [0, 1], done: false }
|
46 | iterator.next(); // { value: [1, 2], done: false }
|
47 | iterator.next(); // { value: [2, 3], done: false }
|
48 | iterator.next(); // { value: undefined, done: true }
|
49 | ```
|
50 |
|
51 | May also be used for _arguments_ objects:
|
52 |
|
53 | ```javascript
|
54 | (function () {
|
55 | var iterator = new ArrayIterator(arguments);
|
56 |
|
57 | iterator.next(); // { value: 1, done: false }
|
58 | iterator.next(); // { value: 2, done: false }
|
59 | iterator.next(); // { value: 3, done: false }
|
60 | iterator.next(); // { value: undefined, done: true }
|
61 | }(1, 2, 3));
|
62 | ```
|
63 |
|
64 | #### StringIterator(str) _(es6-iterator/string)_
|
65 |
|
66 | Assures proper iteration over unicode symbols.
|
67 | See: http://mathiasbynens.be/notes/javascript-unicode
|
68 |
|
69 | ```javascript
|
70 | var StringIterator = require('es6-iterator/string');
|
71 | var iterator = new StringIterator('fπoπoπ');
|
72 |
|
73 | iterator.next(); // { value: 'f', done: false }
|
74 | iterator.next(); // { value: 'π', done: false }
|
75 | iterator.next(); // { value: 'o', done: false }
|
76 | iterator.next(); // { value: 'π', done: false }
|
77 | iterator.next(); // { value: 'o', done: false }
|
78 | iterator.next(); // { value: 'π', done: false }
|
79 | iterator.next(); // { value: undefined, done: true }
|
80 | ```
|
81 |
|
82 | ### Function utilities
|
83 |
|
84 | #### forOf(iterable, callback[, thisArg]) _(es6-iterator/for-of)_
|
85 |
|
86 | Polyfill for ECMAScript 6 [`for...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) statement.
|
87 |
|
88 | ```
|
89 | var forOf = require('es6-iterator/for-of');
|
90 | var result = [];
|
91 |
|
92 | forOf('πππ', function (monkey) { result.push(monkey); });
|
93 | console.log(result); // ['π', 'π', 'π'];
|
94 | ```
|
95 |
|
96 | Optionally you can break iteration at any point:
|
97 |
|
98 | ```javascript
|
99 | var result = [];
|
100 |
|
101 | forOf([1,2,3,4]', function (val, doBreak) {
|
102 | result.push(monkey);
|
103 | if (val >= 3) doBreak();
|
104 | });
|
105 | console.log(result); // [1, 2, 3];
|
106 | ```
|
107 |
|
108 | #### get(obj) _(es6-iterator/get)_
|
109 |
|
110 | Return iterator for any iterable object.
|
111 |
|
112 | ```javascript
|
113 | var getIterator = require('es6-iterator/get');
|
114 | var iterator = get([1,2,3]);
|
115 |
|
116 | iterator.next(); // { value: 1, done: false }
|
117 | iterator.next(); // { value: 2, done: false }
|
118 | iterator.next(); // { value: 3, done: false }
|
119 | iterator.next(); // { value: undefined, done: true }
|
120 | ```
|
121 |
|
122 | #### isIterable(obj) _(es6-iterator/is-iterable)_
|
123 |
|
124 | Whether _obj_ is iterable
|
125 |
|
126 | ```javascript
|
127 | var isIterable = require('es6-iterator/is-iterable');
|
128 |
|
129 | isIterable(null); // false
|
130 | isIterable(true); // false
|
131 | isIterable('str'); // true
|
132 | isIterable(['a', 'r', 'r']); // true
|
133 | isIterable(new ArrayIterator([])); // true
|
134 | ```
|
135 |
|
136 | #### validIterable(obj) _(es6-iterator/valid-iterable)_
|
137 |
|
138 | If _obj_ is an iterable it is returned. Otherwise _TypeError_ is thrown.
|
139 |
|
140 | ### Method extensions
|
141 |
|
142 | #### iterator.chain(iterator1[, β¦iteratorn]) _(es6-iterator/#/chain)_
|
143 |
|
144 | Chain multiple iterators into one.
|
145 |
|
146 | ### Tests [![Build Status](https://travis-ci.org/medikoo/es6-iterator.png)](https://travis-ci.org/medikoo/es6-iterator)
|
147 |
|
148 | $ npm test
|