txt: ## iterating.md
  Iterating
  
  Functionalities available for visiting all items in a complex data structure
  
  # [The](#Iterating "go to top of document") [`Iterator`](/type/Iterator) and [`Iterable`](/type/Iterable) roles[§](#The_Iterator_and_Iterable_roles "direct link")
  
  Raku is a functional language, but functions need something to hold on to when working on complex data structures. In particular, they need a uniform interface that can be applied to all data structures in the same way. One of these kind of interfaces is provided by the [`Iterator`](/type/Iterator) and [`Iterable`](/type/Iterable) roles.
  
  The [`Iterable`](/type/Iterable) role is relatively simple. It provides a stub for the `iterator` method, which is the one actually used by statements such as `for`. `for` will call `.iterator` on the variable it precedes, and then run a block once for every item. Other methods, such as array assignment, will make the [`Iterable`](/type/Iterable) class behave in the same way.
  
  ```raku
  class DNA does Iterable {
      has $.chain;
      method new ($chain where {
                         $chain ~~ /^^ <[ACGT]>+ $$ / and
                         $chain.chars %% 3 } ) {
          self.bless( :$chain );
      }
  
      method iterator(DNA:D:){ $.chain.comb.rotor(3).iterator }
  };
  
  my @longer-chain =  DNA.new('ACGTACGTT');
  say @longer-chain.raku;
  # OUTPUT: «[("A", "C", "G"), ("T", "A", "C"), ("G", "T", "T")]␤»
  
  say  @longer-chain».join("").join("|"); # OUTPUT: «ACG|TAC|GTT␤»
  
  ```
  
  In this example, which is an extension of the [example in `Iterable` that shows how `for` calls `.iterator`](/type/Iterable), the `iterator` method will be called in the appropriate context only when the created object is assigned to a [`Positional`](/type/Positional) variable, `@longer-chain`; this variable is an [`Array`](/type/Array) and we operate on it as such in the last example.
  
  The (maybe a bit confusingly named) [`Iterator`](/type/Iterator) role is a bit more complex than [`Iterable`](/type/Iterable). First, it provides a constant, `IterationEnd`. Then, it also provides a series of [methods](/type/Iterator#Methods) such as `.pull-one`, which allows for a finer operation of iteration in several contexts: adding or eliminating items, or skipping over them to access other items. In fact, the role provides a default implementation for all the other methods, so the only one that has to be defined is precisely `pull-one`, of which only a stub is provided by the role. While [`Iterable`](/type/Iterable) provides the high-level interface loops will be working with, [`Iterator`](/type/Iterator) provides the lower-level functions that will be called in every iteration of the loop. Let's extend the previous example with this role.
  
  ```raku
  class DNA does Iterable does Iterator {
      has $.chain;
      has Int $!index = 0;
  
      method new ($chain where {
                         $chain ~~ /^^ <[ACGT]>+ $$ / and
                         $chain.chars %% 3 } ) {
          self.bless( :$chain );
      }
  
      method iterator( ){ self }
      method pull-one( --> Mu){
          if $!index < $.chain.chars {
              my $codon = $.chain.comb.rotor(3)[$!index div 3];
              $!index += 3;
              return $codon;
          } else {
              return IterationEnd;
          }
      }
  };
  
  my $a := DNA.new('GAATCC');
  .say for $a; # OUTPUT: «(G A A)␤(T C C)␤»
  
  ```
  
  We declare a `DNA` class which does the two roles, [`Iterator`](/type/Iterator) and [`Iterable`](/type/Iterable); the class will include a string that will be constrained to have a length that is a multiple of 3 and composed only of ACGT.
  
  Let us look at the `pull-one` method. This one is going to be called every time a new iteration occurs, so it must keep the state of the last one. An `$.index` attribute will hold that state across invocations; `pull-one` will check if the end of the chain has been reached and will return the `IterationEnd` constant provided by the role. Implementing this low-level interface, in fact, simplifies the implementation of the [`Iterable`](/type/Iterable) interface. Now the iterator will be the object itself, since we can call `pull-one` on it to access every member in turn; `.iterator` will thus return just `self`; this is possible since the object will be, at the same time, [`Iterable`](/type/Iterable) and [`Iterator`](/type/Iterator).
  
  This need not always be the case, and in most cases `.iterator` will have to build an iterator type to be returned (that will, for instance, keep track of the iteration state, which we are doing now in the main class), such as we did in the previous example; however, this example shows the minimal code needed to build a class that fulfills the iterator and iterable roles.
  
  # [How to iterate: contextualizing and topic variables](#Iterating "go to top of document")[§](#How_to_iterate:_contextualizing_and_topic_variables "direct link")
  
  `for` and other loops place the item produced in every iteration into the [topic variable `$_`](/language/variables#index-entry-topic_variable), or capture them into the variables that are declared along with the block. These variables can be directly used inside the loop, without needing to declare them, by using the [`^` twigil](/syntax/$CIRCUMFLEX_ACCENT#(Traps_to_avoid)_twigil_^).
  
  Implicit iteration occurs when using the [sequence operator](/language/operators#infix_...).
  
  ```raku
  say 1,1,1, { $^a²+2*$^b+$^c } … * > 300; # OUTPUT: «(1 1 1 4 7 16 46 127 475)
  ```
  
  The generating block is being run once while the condition to finish the sequence, in this case the term being bigger than 300, is not met. This has the side effect of running a loop, but also creating a list that is output.
  
  This can be done more systematically through the use of the [`gather/take` blocks](/syntax/gather take), which are a different kind of iterating construct that instead of running in sink context, returns an item every iteration. This [Advent Calendar tutorial](https://perl6advent.wordpress.com/2009/12/23/day-23-lazy-fruits-from-the-gather-of-eden/) explains use cases for this kind of loops; in fact, gather is not so much a looping construct, but a statement prefix that collects the items produced by `take` and creates a list out of them.
  
  # [`Classic` loops and why we do not like them](#Iterating "go to top of document")[§](#Classic_loops_and_why_we_do_not_like_them "direct link")
  
  Classic `for` loops, with a loop variable being incremented, can be done in Raku through the [`loop` keyword](/language/control#loop). Other [repeat](/language/control#repeat/while,_repeat/until) and [while](/language/control#while,_until) loops are also possible.
  
  However, in general, they are discouraged. Raku is a functional and concurrent language; when coding in Raku, you should look at loops in a functional way: processing, one by one, the items produced by an iterator, that is, feeding an item to a block without any kind of secondary effects. This functional view allows also easy parallelization of the operation via the [`hyper`](/routine/hyper) or [`race`](/routine/race) auto-threading methods.
  
  If you feel more comfortable with your good old loops, the language allows you to use them. However, it is considered better practice in Raku to try and use, whenever possible, functional and concurrent iterating constructs.
  
  *Note:* Since version 6.d loops can produce a list of values from the values of last statements.
  