1
// Copyright 2014 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Utilities for working with ES6 iterables.
17
 * Note that this file is written ES5-only.
18
 *
19
 * The goal is that this should be a replacement for goog.iter which uses
20
 * a now non-standard approach to iterables.
21
 *
22
 * @see https://goo.gl/Rok5YQ
23
 */
24

25
goog.module('goog.labs.iterable');
26

27

28
/**
29
 * Get the iterator for an iterable.
30
 * @param {!Iterable<VALUE>} iterable
31
 * @return {!Iterator<VALUE>}
32
 * @template VALUE
33
 */
34
exports.getIterator = function(iterable) {
35
  return iterable[goog.global.Symbol.iterator]();
36
};
37

38

39
/**
40
 * Call a function with every value of an iterable.
41
 *
42
 * Warning: this function will never halt if given an iterable that
43
 * is never exhausted.
44
 *
45
 * @param {function(VALUE): void} f
46
 * @param {!Iterable<VALUE>} iterable
47
 * @template VALUE
48
 */
49
exports.forEach = function(f, iterable) {
50
  var iterator = exports.getIterator(iterable);
51
  while (true) {
52
    var next = iterator.next();
53
    if (next.done) {
54
      return;
55
    }
56
    f(next.value);
57
  }
58
};
59

60

61
/**
62
 * Maps the values of one iterable to create another iterable.
63
 *
64
 * When next() is called on the returned iterable, it will call the given
65
 * function {@code f} with the next value of the given iterable
66
 * {@code iterable} until the given iterable is exhausted.
67
 *
68
 * @param {function(this: THIS, VALUE): RESULT} f
69
 * @param {!Iterable<VALUE>} iterable
70
 * @return {!Iterable<RESULT>} The created iterable that gives the mapped
71
 *     values.
72
 * @template THIS, VALUE, RESULT
73
 */
74
exports.map = function(f, iterable) {
75
  return new FactoryIterable(function() {
76
    var iterator = exports.getIterator(iterable);
77
    return new MapIterator(f, iterator);
78
  });
79
};
80

81

82

83
/**
84
 * Helper class for {@code map}.
85
 * @param {function(VALUE): RESULT} f
86
 * @param {!Iterator<VALUE>} iterator
87
 * @constructor
88
 * @implements {Iterator<RESULT>}
89
 * @template VALUE, RESULT
90
 */
91
var MapIterator = function(f, iterator) {
92
  /** @private */
93
  this.func_ = f;
94
  /** @private */
95
  this.iterator_ = iterator;
96
};
97

98

99
/**
100
 * @override
101
 */
102
MapIterator.prototype.next = function() {
103
  var nextObj = this.iterator_.next();
104

105
  if (nextObj.done) {
106
    return {done: true, value: undefined};
107
  }
108

109
  var mappedValue = this.func_(nextObj.value);
110
  return {done: false, value: mappedValue};
111
};
112

113

114

115
/**
116
 * Helper class to create an iterable with a given iterator factory.
117
 * @param {function():!Iterator<VALUE>} iteratorFactory
118
 * @constructor
119
 * @implements {Iterable<VALUE>}
120
 * @template VALUE
121
 */
122
var FactoryIterable = function(iteratorFactory) {
123
  /**
124
   * @private
125
   */
126
  this.iteratorFactory_ = iteratorFactory;
127
};
128

129

130
// TODO(nnaze): For now, this section is not run if Symbol is not defined,
131
// since goog.global.Symbol.iterator will not be defined below.
132
// Determine best course of action if "Symbol" is not available.
133
if (goog.global.Symbol) {
134
  /**
135
   * @return {!Iterator<VALUE>}
136
   */
137
  FactoryIterable.prototype[goog.global.Symbol.iterator] = function() {
138
    return this.iteratorFactory_();
139
  };
140
}
141

142