1# es6-iterator 2## ECMAScript 6 Iterator interface 3 4### Installation 5 6 $ npm install es6-iterator 7 8To 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 16Abstract Iterator interface. Meant for extensions and not to be used on its own. 17 18Accepts 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 23var Iterator = require('es6-iterator') 24var iterator = new Iterator([1, 2, 3]); 25 26iterator.next(); // { value: 1, done: false } 27iterator.next(); // { value: 2, done: false } 28iterator.next(); // { value: 3, done: false } 29iterator.next(); // { value: undefined, done: true } 30``` 31 32 33#### ArrayIterator(arrayLike[, kind]) _(es6-iterator/array)_ 34 35Dedicated 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 42var ArrayIterator = require('es6-iterator/array') 43var iterator = new ArrayIterator([1, 2, 3], 'key+value'); 44 45iterator.next(); // { value: [0, 1], done: false } 46iterator.next(); // { value: [1, 2], done: false } 47iterator.next(); // { value: [2, 3], done: false } 48iterator.next(); // { value: undefined, done: true } 49``` 50 51May 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 66Assures proper iteration over unicode symbols. 67See: http://mathiasbynens.be/notes/javascript-unicode 68 69```javascript 70var StringIterator = require('es6-iterator/string'); 71var iterator = new StringIterator('foo'); 72 73iterator.next(); // { value: 'f', done: false } 74iterator.next(); // { value: '', done: false } 75iterator.next(); // { value: 'o', done: false } 76iterator.next(); // { value: '', done: false } 77iterator.next(); // { value: 'o', done: false } 78iterator.next(); // { value: '', done: false } 79iterator.next(); // { value: undefined, done: true } 80``` 81 82### Function utilities 83 84#### forOf(iterable, callback[, thisArg]) _(es6-iterator/for-of)_ 85 86Polyfill for ECMAScript 6 [`for...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) statement. 87 88``` 89var forOf = require('es6-iterator/for-of'); 90var result = []; 91 92forOf('', function (monkey) { result.push(monkey); }); 93console.log(result); // ['', '', '']; 94``` 95 96Optionally you can break iteration at any point: 97 98```javascript 99var result = []; 100 101forOf([1,2,3,4]', function (val, doBreak) { 102 result.push(monkey); 103 if (val >= 3) doBreak(); 104}); 105console.log(result); // [1, 2, 3]; 106``` 107 108#### get(obj) _(es6-iterator/get)_ 109 110Return iterator for any iterable object. 111 112```javascript 113var getIterator = require('es6-iterator/get'); 114var iterator = get([1,2,3]); 115 116iterator.next(); // { value: 1, done: false } 117iterator.next(); // { value: 2, done: false } 118iterator.next(); // { value: 3, done: false } 119iterator.next(); // { value: undefined, done: true } 120``` 121 122#### isIterable(obj) _(es6-iterator/is-iterable)_ 123 124Whether _obj_ is iterable 125 126```javascript 127var isIterable = require('es6-iterator/is-iterable'); 128 129isIterable(null); // false 130isIterable(true); // false 131isIterable('str'); // true 132isIterable(['a', 'r', 'r']); // true 133isIterable(new ArrayIterator([])); // true 134``` 135 136#### validIterable(obj) _(es6-iterator/valid-iterable)_ 137 138If _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 144Chain 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 149