txt: ## iterator.md
  iterator
  
  Combined from primary sources listed below.
  
  # [In role Iterable](#___top "go to top of document")[§](#(role_Iterable)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/Iterable#method_iterator)
  for **method iterator**.
  
  ```raku
  method iterator(--> Iterator:D)
  ```
  
  Method stub that ensures all classes doing the `Iterable` role have a method `iterator`.
  
  It is supposed to return an [`Iterator`](/type/Iterator).
  
  ```raku
  say (1..10).iterator;
  ```
  
  # [In Seq](#___top "go to top of document")[§](#(Seq)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/Seq#method_iterator)
  for **method iterator**.
  
  ```raku
  method iterator(Seq:D:)
  ```
  
  If the `Seq` is not cached, returns the underlying iterator and marks the invocant as consumed. If called on an already consumed sequence, throws an error of type [`X::Seq::Consumed`](/type/X/Seq/Consumed).
  
  Otherwise returns an iterator over the cached list.
  
  # [In Any](#___top "go to top of document")[§](#(Any)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/Any#method_iterator)
  for **method iterator**.
  
  ```raku
  multi method iterator(Any:)
  ```
  
  Returns the object as an iterator after converting it to a list. This is the function called from the `for` statement.
  
  ```raku
  .say for 3; # OUTPUT: «3␤»
  ```
  
  Most subclasses redefine this method for optimization, so it's mostly types that do not actually iterate the ones that actually use this implementation.
  
  # [In Mu](#___top "go to top of document")[§](#(Mu)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/Mu#method_iterator)
  for **method iterator**.
  
  ```raku
  method iterator(--> Iterator)
  ```
  
  Coerces the invocant to a `list` by applying its [`.list`](/routine/list) method and uses [`iterator`](/type/Iterable#method_iterator) on it.
  
  ```raku
  my $it = Mu.iterator;
  say $it.pull-one; # OUTPUT: «(Mu)␤»
  say $it.pull-one; # OUTPUT: «IterationEnd␤»
  ```
  
  # [In role PositionalBindFailover](#___top "go to top of document")[§](#(role_PositionalBindFailover)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/PositionalBindFailover#method_iterator)
  for **method iterator**.
  
  ```raku
  method iterator(PositionalBindFailover:D:) { ... }
  ```
  
  This method stub ensure that a class implementing role `PositionalBindFailover` provides an `iterator` method.
  
  # [In HyperSeq](#___top "go to top of document")[§](#(HyperSeq)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/HyperSeq#method_iterator)
  for **method iterator**.
  
  ```raku
  method iterator(HyperSeq:D: --> Iterator:D)
  ```
  
  Returns the underlying iterator.
  
  # [In Junction](#___top "go to top of document")[§](#(Junction)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/Junction#method_iterator)
  for **method iterator**.
  
  ```raku
  multi method iterator(Junction:D:)
  ```
  
  Returns an iterator over the `Junction` converted to a [`List`](/type/List).
  
  # [In RaceSeq](#___top "go to top of document")[§](#(RaceSeq)_method_iterator "direct link")
  
  See primary documentation
  [in context](/type/RaceSeq#method_iterator)
  for **method iterator**.
  
  ```raku
  method iterator(RaceSeq:D: --> Iterator:D)
  ```
  
  Returns the underlying iterator.
  