Iterables

Iterable Values

• A value in a for of loop must be iterable:

  for (element of [1, 2, 3])
  for (ch of 'Hello')
  

• A value is iterable if it has a property with key Symbol.iterator

  'Hello'[Symbol.iterator] → [Function: [Symbol.iterator]]

• That's a constructor function for an iterator object:

  const helloIter = 'Hello'[Symbol.iterator]()

• That object has a next method:

  helloIter.next() → { value: 'H', done: false }
  helloIter.next() → { value: 'e', done: false }
  ...
  helloIter.next() → { value: 'o', done: false }
  helloIter.next() → { value: undefined, done: true }
  

Where Iterable Values Are Used

• for (const value of iterable)
• Array spread: [...iterable]
• Array destructuring: [first, second, third] = iterable
• Array.from(iterable)
• Set and map constructor: new Set(iterable)
• yield*
• Any place where a programmer makes use of the iterator constructed by obj[Symbol.iterable]

What Values are Iterable

• Arrays
• Strings
• Sets and maps
• The objects returned by the keys, values, entries methods of arrays, typed arrays, sets, and maps (but not Object)
• DOM data structures
  • Open any web page and run [...document.querySelectorAll('div')] in the console.
• Any value where a programmer provides a constructor for an iterator with the Symbol.iterable key.

Iterators

Implementing an Iterable

• Provide an instance method

  [Symbol.iterator]() { ... }

• In that method, return an object with a next method:

  [Symbol.iterator]() {
    ...
    return {
      next: () => { ... }
    }
  }
  

• That method returns { value: ..., done: ... }

    next: () => {
      ...
      if (...) return { value: some value, done: false }
      else return { value: undefined, done: true }
    }

• Can omit done: false and value: undefined

Example: Range

class Range {
  constructor(from, to) {
    this.from = from
    this.to = to
  }
  [Symbol.iterator]() {
    let current = this.from
    return {
      next: () => {
        if (current < this.to) {
          const result = { value: current }
          current++
          return result
        }
        else
          return { done: true }
      }
    }
  }
}

Closeable Iterators

• If an iterator object has a method called return (!), it is closeable.
• The return method is called when the iteration is terminated even though it hasn't reached the end.

  for (line of lines(filename)) {
    if (line.contains(target)) {
      return line
      // iterator.return() called
    }
    ...
  }

• Also when the loop is abruptly exited through throw, break, labeled continue to an outer loop.
• If you use a closeable iterator, haven't received done: true, and no longer need it, call iterator.return()
• Don't call next after return

Closeable Iterator Implementation

function lines(filename) {
  const file = ... // Open the file
  return {
    [Symbol.iterator]: () => ({
      next: () => {
        if (done) {
          ... // Close the file
          return { done: true }
        }
        else {
          const line = ... // Read a line
          return { value: line }
        }
      },
    ['return']: () => {
        ... // Close the file
        return { done: true } // Must return an object
      }
    })
  }
}

Generators

Generators

• Tedious to write iterators that yield one value with each call to next
• Generators produce all values in a generator function.
• Function is suspended after each yielded value.

  function* rangeGenerator(from, to) {
    for (let i = from; i < to; i++) 
      yield i
  }
  

• * tags this function as a generator function.
• Call the function to obtain an iterator:

  const rangeIter = rangeGenerator(1, 10)
  

• It really is an iterator:

  rangeIter.next() → { value: 1, done: false }
  rangeIter.next() → { value: 2, done: false }
  ...
  rangeIter.next() → { value: 9, done: false }
  rangeIter.next() → { value: undefined, done: true }
  

Generator Function Syntax

• Named or anonymous function:

  function* myGenerator(...)
  const myGenerator = function* (...)

• Object literal:

  { * myGenerator(...) { ... }, ... }
    // Syntactic sugar for myGenerator: function* (...) {...}

• Method in class:

  class MyClass {
    * myGenerator(...) { ... }
    ...
  }
  

• Arrow functions cannot be generators.

Execution Flow

• Calling a generator function doesn't execute its body.
• Instead, you get a generator object.

  const generatorObject = myGenerator(args)
  

• That object has a next method.
  • And methods return, throw
• Calling next runs the body until the first yield statement.
• The call to next returns the value of the yield statement as { value: yielded value, done: false}
• Calling next again picks up after the yield statement and runs until the next yield statement.
• When the generator function returns, next returns { value: return value, done: true }
• When the generator function throws an exception, next throws it.
• Note: In JavaScript, yield is shallow—you can only yield inside the generator function, not a function that is called.

Nested Yield

• It is easy to yield all elements of an array:

  function* arrayGenerator(arr) {
    for (let element of arr) 
      yield element
  }
  

• What if one of the elements is itself an array? The yield* operator yields its elements one at a time:

  function* flatArrayGenerator(arr) {
    for (let element of arr)
      if (Array.isArray(element))
        yield* element
      else
        yield element
  }
  
  let g = flatArrayGenerator([1, [2, [3, 4], 5], 6])
  [...g] → [1, 2, [3, 4], 5, 6]
  

Nested Yield

• So close...
• This works for arbitrary levels of nesting:

  function* reallyFlatArrayGenerator(arr) {
    for (let element of arr)
      if (Array.isArray(element))
        yield* reallyFlatArrayGenerator(element)
      else
        yield element
  }
  
  g = reallyFlatArrayGenerator([1, [2, [3, 4], 5], 6])
  [...g] → [1, 2, 3, 4, 5, 6]
  

• Recursive nested generators make it easy to traverse nested data structures.

Generators as Consumers

• When calling next with an argument, it becomes the value of the yield expression.

  function* sumGenerator() {
    let sum = 0
    while (true) {
      let nextValue = yield sum
      sum += nextValue
    }
  }
  
  const accum = sumGenerator()
  accum.next() // Advance to first yield
  accum.next(3) → 3
  accum.next(4) → 7
  accum.next(5) → 12
  accum.return() // Shut it down
  

• Calling throw on a generator causes the exception to be thrown in the next yield expression.
• Use cases for generators as consumers:
  • Nested loops that pull data.
  • Generators that yield promises.

End of Lesson 9