> For the complete documentation index, see [llms.txt](https://lochiwei.gitbook.io/web/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lochiwei.gitbook.io/web/js/iteration/iterator/next.md).

# next()

method of an iterator that returns an "iteration result"

[JS](/web/js.md)⟩ [iteration](/web/js/iteration.md) ⟩ [iterator](/web/js/iteration/iterator.md) ⟩ next()

{% hint style="success" %}
a <mark style="color:yellow;">**method**</mark> that <mark style="color:orange;">**returns**</mark> an [iteration result](/web/js/iteration/iteration-result.md).
{% 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&amp;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](/web/js/val/func/argument.md) <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 [value](/web/js/val.md) of the <mark style="color:red;">**previous**</mark> [yield](/web/js/iteration/generator/func/yield.md). ( 👉 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](/web/js/iteration/generator/func/yield.md) <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](/web/js/grammar/statement.md)：

```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](/web/js/iteration/generator.md) object is an [iterable iterator](/web/js/iteration/iterator/iterable.md), 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 %}