# iterator

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

{% hint style="success" %}
[es6](../feature/es6 "mention")

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

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

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

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

* [str.matchall](../val/prim/str/method/str.matchall "mention") - returns an iterator of matching results.
* [Broken link](broken-reference "mention") objects returned by [func](generator/func "mention")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](iterator "mention")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](../grammar/op/assign/destruct) an [iterable](iterable "mention"), the [next](iterator/next "mention") method (of an [iterator](iterator "mention")) 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](iterator/next "mention")
* [return](iterator/return "mention") - 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](iteration-result "mention") object.
{% endhint %}

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

{% tab title="🔴 主題 " %}
* <mark style="color:yellow;">**features**</mark>
  * [next](iterator/next "mention") - returns an [iteration-result](iteration-result "mention").
  * [return](iterator/return "mention") - give <mark style="color:purple;">**iterator**</mark> a chance to do <mark style="color:yellow;">**cleanup**</mark> actions.
  * [iterators-only-iterate-once](iterator/iterators-only-iterate-once "mention") - <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](iterable "mention")s use [make-iterator-method](iterable/make-iterator-method "mention") 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](iterator/iterator "mention") - <mark style="color:yellow;">**extension**</mark> of built-in <mark style="color:purple;">**iterators ⭐️**</mark>
  * [make-iterable](iterator/make-iterable "mention")
  * [iteratorprototype](iterator/iteratorprototype "mention") - [prototype](../val/obj/proto) 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/iterable "mention") - an <mark style="color:purple;">**iterator**</mark> that is itself [iterable](iterable "mention").
  * [infinite](iterator/infinite "mention") - <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&#x26;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&#x26;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](../val/prim/str/method/str.matchall "mention") returns an [iterator](iterator "mention") of all matching results. ([es2020](../feature/es2020 "mention"))
{% endtab %}

{% tab title="🗣 討論" %}
* [Using map() on an iterator](https://stackoverflow.com/questions/43885365/using-map-on-an-iterator)
{% endtab %}
{% endtabs %}
