> 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.md).

# iterator

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

{% hint style="success" %}
[⭐️ ES6 (2015)](/web/js/feature/es6.md)

object that <mark style="color:yellow;">**can**</mark> [**produce the next iteration result**](/web/js/iteration/iterator/next.md).

* has [next()](/web/js/iteration/iterator/next.md) method that returns an [iteration result](/web/js/iteration/iteration-result.md).\
  (similar to iterator objects conforming to [IteratorProtocol](https://developer.apple.com/documentation/swift/iteratorprotocol) in Swift)
  {% endhint %}

{% tabs %}
{% tab title="⭐️ 重點" %}
{% hint style="danger" %}
[iterator](/web/js/iteration/iterator.md)s [only iterate once](/web/js/iteration/iterator/iterators-only-iterate-once.md)❗️
{% endhint %}

{% hint style="success" %} <mark style="color:yellow;">**iterators**</mark>：

* [str.matchAll()](/web/js/val/prim/str/method/str.matchall.md) - returns an iterator of matching results.
* [Broken mention](broken://pages/wdsR1aBto2o3YMiF3HsH) objects returned by [generator function](/web/js/iteration/generator/func.md)s.
* array.[keys()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys), map.[entries()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries), ...
  {% endhint %}

{% hint style="warning" %}
[iterator](/web/js/iteration/iterator.md)s <mark style="color:orange;">**don't always**</mark> run all the way <mark style="color:yellow;">**to the end**</mark>：

* a <mark style="color:yellow;">**for-of**</mark> loop might be <mark style="color:red;">**terminated**</mark> with a <mark style="color:purple;">**break**</mark>, <mark style="color:purple;">**return**</mark>, or an <mark style="color:red;">**exception**</mark>.
* when [destructuring](/web/js/grammar/op/assign/destruct.md) an [iterable](/web/js/iteration/iterable.md), the [next()](/web/js/iteration/iterator/next.md) method (of an [iterator](/web/js/iteration/iterator.md)) is <mark style="color:red;">**only called enough times**</mark> to obtain values for each variable.
  {% endhint %}

{% hint style="warning" %}
All <mark style="color:yellow;">**iterator protocol methods**</mark>&#x20;

* [next()](/web/js/iteration/iterator/next.md)
* [return()](/web/js/iteration/iterator/return.md) - give iterator a chance to do "<mark style="color:orange;">**cleanup**</mark>" actions.
* <mark style="color:blue;">**throw()**</mark>

are expected to <mark style="color:red;">**return**</mark> an [iteration result](/web/js/iteration/iteration-result.md) object.
{% endhint %}

{% hint style="info" %}
[iterator](/web/js/iteration/iterator.md) for [String](/web/js/val/prim/str.md) works <mark style="color:green;">**correctly**</mark> with <mark style="color:yellow;">**surrogate pairs**</mark>.\
👉 see： [str.slice2()](/web/js/val/prim/str/method/str.slice2.md)
{% endhint %}
{% endtab %}

{% tab title="🔴 主題 " %}

* <mark style="color:yellow;">**features**</mark>
  * [next()](/web/js/iteration/iterator/next.md) - returns an [iteration result](/web/js/iteration/iteration-result.md).
  * [return()](/web/js/iteration/iterator/return.md) - give <mark style="color:purple;">**iterator**</mark> a chance to do <mark style="color:yellow;">**cleanup**</mark> actions.
  * [iterators only iterate once❗️](/web/js/iteration/iterator/iterators-only-iterate-once.md) - <mark style="color:purple;">**iterators**</mark> <mark style="color:red;">**only iterate once**</mark>❗️
  * an <mark style="color:purple;">**iterator**</mark> can be [infinite](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#infinite_iterator).
* <mark style="color:yellow;">**use cases**</mark>
  * [iterable](/web/js/iteration/iterable.md)s use [make-iterator method](/web/js/iteration/iterable/make-iterator-method.md) to make <mark style="color:purple;">**iterators**</mark>.
* <mark style="color:yellow;">**defining iterators**</mark>
  * [encapsulate iterator's state in a closure](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#simple_iterator)
* <mark style="color:yellow;">**extending iterators**</mark>
  * [Iterator](/web/js/iteration/iterator/iterator.md) - <mark style="color:yellow;">**extension**</mark> of built-in <mark style="color:purple;">**iterators ⭐️**</mark>
  * [make iterator iterable](/web/js/iteration/iterator/make-iterable.md)
  * [IteratorPrototype](/web/js/iteration/iterator/iteratorprototype.md) - [prototype](/web/js/val/obj/proto.md) of all <mark style="color:orange;">**built-in**</mark> <mark style="color:purple;">**iterators**</mark>.
* <mark style="color:yellow;">**tyes of iterators**</mark>
  * [iterable iterator](/web/js/iteration/iterator/iterable.md) - an <mark style="color:purple;">**iterator**</mark> that is itself [iterable](/web/js/iteration/iterable.md).
  * [infinite iterator](/web/js/iteration/iterator/infinite.md) - <mark style="color:purple;">**iterator**</mark> can be <mark style="color:orange;">**infinite**</mark>.
    {% endtab %}

{% tab title="🗺️ 圖解" %} <img src="https://2527454625-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfvEFZnSBhKT6fJmus0%2Fuploads%2F30ZWtMWzEaoGZTCvC6hg%2Fiterator.class.svg?alt=media&amp;token=09701dc7-5d3b-433d-ac14-0b2edb998b9a" alt="prototype chain of (built-in) iterators" class="gitbook-drawing">

<img src="https://2527454625-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfvEFZnSBhKT6fJmus0%2Fuploads%2FLDbsdTPR3ENAv8P81akq%2Fiteration-related-types.svg?alt=media&amp;token=6c6da705-70d0-4fd6-97b8-5663b3d61f2d" alt="" class="gitbook-drawing">
{% endtab %}

{% tab title="📗 參考" %}

* [ ] ExploringJS ⟩ [21. Iterables and Iterators](https://exploringjs.com/es6/ch_iteration.html) ⭐️
* [ ] JavaScript: The Definitive Guide ⟩ 12.1 How Iterators Work
* [ ] Swift in Depth ⟩  [Ch. 9 Iterators, sequences, and collections](https://livebook.manning.com/book/swift-in-depth/chapter-9/)
  {% endtab %}

{% tab title="📘 手冊" %}

* [ ] [function\*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*) declaration
* [ ] [Iterators and generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
* [ ] [iterator protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol) ⟩
  * [Array.prototype\[@@iterator\]()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/@@iterator)
    {% endtab %}

{% tab title="👥 相關" %}

* [str.matchAll()](/web/js/val/prim/str/method/str.matchall.md) returns an [iterator](/web/js/iteration/iterator.md) of all matching results. ([⭐️ ES2020](/web/js/feature/es2020.md))
  {% endtab %}

{% tab title="🗣 討論" %}

* [Using map() on an iterator](https://stackoverflow.com/questions/43885365/using-map-on-an-iterator)
  {% endtab %}
  {% endtabs %}