git.r.bdr.sh - rbdr/dotfiles/blob

   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