---
description: method of an iterator that returns an "iteration result"
---

# next()

[JS](../..)⟩ [iteration](..) ⟩ [iterator]() ⟩ next()

{% hint style="success" %}
a <mark style="color:yellow;">**method**</mark> that <mark style="color:orange;">**returns**</mark> an [iteration-result](../iteration-result "mention").
{% endhint %}

{% tabs %}
{% tab title="🗺️ 圖表" %}
<img src="https://2527454625-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfvEFZnSBhKT6fJmus0%2Fuploads%2FHD46fUd2ti328InwY3EU%2Fvalue.of.yield.expr.svg?alt=media&#x26;token=8a2ba13f-909e-4d8b-9019-9f5b2182c159" alt="value of yield expression vs. the next() method" class="gitbook-drawing">
{% endtab %}

{% tab title="⭐️ 重點" %}
{% hint style="success" %}
<mark style="color:yellow;">**the**</mark> [argument](../../val/func/argument "mention") <mark style="color:yellow;">**to the**</mark><mark style="color:yellow;">**&#x20;**</mark><mark style="color:yellow;"><mark style="color:purple;">**next()**<mark style="color:purple;"></mark><mark style="color:yellow;">**&#x20;**</mark><mark style="color:yellow;">**method：**</mark>

* is the [val](../../val "mention") of the <mark style="color:red;">**previous**</mark> [yield](../generator/func/yield "mention"). ( 👉 see： [#fan-li](#fan-li "mention") )
* is <mark style="color:orange;">**ignored**</mark> in the <mark style="color:yellow;">**first call**</mark> of <mark style="color:purple;">**next()**</mark> method.\
  (since there's <mark style="color:red;">**no**</mark> <mark style="color:yellow;">**previous**</mark> [yield](../generator/func/yield "mention") <mark style="color:red;">**yet**</mark>)
* can be considered as a <mark style="color:yellow;">**new starting point**</mark> for the <mark style="color:orange;">**current**</mark>**&#x20;**<mark style="color:purple;">**next()**</mark>**&#x20;**<mark style="color:orange;">**call**</mark>.\
  (<mark style="color:red;">**except**</mark> for the <mark style="color:yellow;">**first call**</mark>, in which the <mark style="color:yellow;">**argument is**</mark>**&#x20;**<mark style="color:red;">**ignored**</mark>)
{% endhint %}

{% hint style="danger" %}
the <mark style="color:blue;">**const**</mark> [statement](../../grammar/statement "mention")：

```javascript
const arg2 = yield 1;     // generator code
```

has <mark style="color:red;">**two**</mark>**&#x20;**<mark style="color:yellow;">**execution contexts**</mark>：

```javascript
 yield 1     // in the context of #1 next() call.
 const arg2  // in the context of #2 next() call.
```
{% endhint %}
{% endtab %}

{% tab title="💈範例" %}
* replit：[value of yield expression (2)](https://replit.com/@pegasusroe/value-of-yield-expr-2#index.js)

```javascript
const { log } = console;

// generator code
function* ints() {

    // argument to the `next(arg)` method
    // ---------------------------------------------
    // `arg`:
    //    • is the "value" of PREVIOUS "yield expression".
    //    • is ignored in the first call of next().
    //      (since there's NO previous yield expression)
    //    • can be considered a "new starting point" for
    //      the "current" call of next() method.
    //      (except for the first call, in which `arg` is ignored)

                                    // #1 next() call
                                    // ---------------
    //                    ╭─1─╮     //   1. value for #1 call
    const arg2   =  yield   1  ;    //      (execution stops at Y.E.)
    //   ╰─ 2 ─╯   ╰── Y.E. ──╯     //   Y.E. : yield expression
    
                                    // #2 next() call
                                    // --------------
                                    //   2. argument sent in by #2 call
    //                   ╭── 3 ──╮  //   3. value for #2 call
    const arg3   = yield [2, arg2]; //      (execution stops at Y.E.)
    //   ╰─ 4 ─╯   ╰──── Y.E. ───╯  // 

                                    // #3 next() call
                                    // --------------
    //     ╭── 5 ──╮                //   4. argument sent in by #3 call        
    return [3, arg3];               //   5. "done" value for #3 call
                                    //      (the iteration is finished)
}

// table settings
const headers = ['   ', 'value', 'done'];
const n = headers.length;    // number of columns
const [colWidth, pad, ext] = [5, 1, 0];
const line = '-'.repeat(colWidth*n + pad*(n-1) + ext);
log(`    value  done`);
log(line);

// log iteration result
function logResult(r, i) {
    let value = r.value === undefined ? 'x' : String(r.value);
    value = value.padEnd(5, ' ');
    const done = (r.done ? '✅' : '❌').padEnd(4, ' ');
    log(`#${i}:  ${value}  ${done}`);
}

// main
let it = ints(); 

const r1 = it.next('a');    // #1 next() call
logResult(r1, 1);

const r2 = it.next('b');    // #2 next() call
logResult(r2, 2);

const r3 = it.next('c');    // #3 next() call
logResult(r3, 3);

// output:
//
//     value  done
// -----------------
// #1:  1      ❌   
// #2:  2,b    ❌   
// #3:  3,c    ✅ 
```
{% endtab %}

{% tab title="👥 相關" %}
* a [generator](../generator "mention") object is an [iterable](iterable "mention"), so it has this method too.
{% endtab %}

{% tab title="📘 手冊" %}
* [ ] [Generator.prototype.next()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/next)
* [ ] [iterator protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol)
* [ ] [yield](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield)
{% endtab %}
{% endtabs %}
