Dart Iterable

Iterable is a collection of elements that are accessed sequentially. These elements are accessible using the iterator getter and stepping through the values using this getter.

Let us understand the setting up of iterable :

• moveNext = It is called to set up the iterator. If the call returns true, we turn to the next element, and if it returns false, that implies there are no more elements.
• current = It refers to the current element when the call to Iterator.moveNext returns true. Remember that the Iterator.current value should be used only when Iterator.moveNext returned true in the most recent call; otherwise, it might throw an exception or return some arbitrary value.                         

We can create more than one iterator using ‘ Iterable ’. We have three types of Iterable : List, Set, and Maps. Every time an Iterable is read, a new iterator is returned. The iterators belonging to the same Iterable should have the same values in the same order. But that’s not true in every case; some Iterable are allowed to be modified. However, we can not change a collection while it is being iterated.

Iterable Constructors

1. Iterable( ) =

This constructor is used to create and Iterable.

Implementation = const Iterable < E > ( ) ;

2. empty( ) =

This constructor creates an empty Iterable that has no elements. Whenever we try to iterate over this empty Iterable, iteration immediately stops.

Implementation = const factory Iterable.empty ( ) = EmptyIterable < E > ;

3. generate( ) =

This constructor creates an Iterable that dynamically generates Iterable. The generated Iterable has count elements, and to determine an element at the index n, we call generator ( n ) that returns the element. Every time we call this generator ( n ), we receive the value at the index n because the values are not cached.

Implementation =

Iterable<E>.generate (
int count ,
[ E generator (
int index
) ? ]
)
     factory Iterable.generate (int count, [E generator (int index)?]) {
             if (count < = 0) return EmptyIterable <E> ( ) ;
                return _GeneratorIterable  <E> ( count, generator ) ;
}

Iterable Properties

1. First =

This property returns the first element of the Iterable equivalent to this.elementAt( 0 ) if it exists. Otherwise, it throws a StateError.

Implementation =

E get first {
  Iterator < E > it = iterator ;
  if ( ! it.moveNext ( ) ) {
    throw IterableElementError.noElement( ) ;
  }
  return it.current ;
}

2. hashCode =

Returns the hash code for a numerical value, and it returns the same value for int and doubles when the value provided is the same.

Implementation = external int get hashchode ;

3. isEmpty =

This property checks whether the Iterable is empty or not and accordingly returns True or False. True if the Iterable has no elements and false if it does have.

We can also compute this using Iterator.moveNext( ) if it returns false, that means the Iterable is empty.

Implementation = bool get isEmpty = > !iterator.moveNext( ) ;

4. isNotempty =

This property checks whether the Iterable is empty or not and accordingly returns True or False. True if the Iterable has at least one element and false if it is empty.

We can also compute this using Iterator.moveNext( ) if it returns true, that means the Iterable is not empty.

Implementation = bool get isNotEmpty = > !isEmpty ;

5. Iterator =

This property returns a new ‘ Iterator ’ that enables iterating through all the elements of the specified ‘ Iterable ’. In the case of the iterators belonging to the same iterable, they must return the same elements in the same order unless any underlying condition is changed.

The order of iteration of the elements of a particular Iterable depends on any specification regarding the same present in its class. For example, the elements of List iterate in the index order. In some cases, there may be no specific order of iteration like in hash-based Set; they can iterate in any order.

Implementation = Iterator < E > get iterator ;

6. last =

This property iterates through all the elements of the Iterable and returns the last element. In case the Iterable is empty, it throws a StateError.

Implementation =

E get last {
  Iterator< E > it = iterator ;
  if ( ! it.moveNext( ) ) {
    throw IterableElementError.noElement( ) ;
  }
  E result ;
  do {
    result = it.current ;
  } while ( it.moveNext( ) ) ;
  return result ;
}

7. length =

This property iterates through all the elements of the Iterable, counts them and returns the number of elements.

Implementation =

int get length {
  assert ( this is ! EfficientLengthIterable ) ;
  int count = 0 ;
  Iterator it = iterator ;
  while ( it.moveNext( ) ) {
    count++ ;
  }
  return count ;
}

8. runtimeType =

Represents the type of runtime an object has.

Implementation = external Type get runtimeType ;

9. Single =

This property iterates through the Iterable and checks whether it has a single element, and returns that element.

In case, the Iterable is empty or has too many elements, this property throws a StateError.

Implementation =

E get single {
  Iterator< E > it = iterator ;
  if ( ! it.moveNext( ) ) throw IterableElementError.noElement( ) ;
  E result = it.current ;
  if ( it.moveNext( ) ) throw IterableElementError.tooMany( ) ;
  return result ;
}

Iterable Methods

1. any( ) =

This method iterates through all the elements and checks whether any element of the Iterable satisfies the ‘ test ’. It returns true if the test returns true, otherwise returns false.

Implementation =

bool any( bool test ( E element ) ) {
  for ( E element in this ) {
    if ( test ( element ) ) return true ;
  }
  return false ;
}

2. cast< R > ( ) =

This method provides a view of the given Iterable as an iterable of R instances.

If this particular Iterable contains the instances of R only, the operation just works fine. Otherwise, if the operations try to access an element that is not an instance of R, the access will throw.

Implementation = Iterable < R > cast < R > (  ) = > Iterable.castFrom < E,  R > ( this ) ;

3. contains( ) =

This method checks whether the collection contains an element equal to the element passed in this method. It iterates through all the elements of the Iterable to check the same.

Implementation =

bool contains ( Object? element ) {
  for ( E e in this ) {
    if ( e == element ) return true ;
  }
  return false ;
}

4. elementAt( ) =

This method returns the element at the given index, which is passed as a parameter to this function.

The index must be non – negative and less than the length of the Iterable. The first element of the Iterable corresponds to the 0^th index.

Implementation =

E elementAt ( int index ) {
  RangeError.checkNotNegative ( index, " index " ) ;
  int elementIndex = 0 ;
  for ( E element in this ) {
    if ( index == elementIndex ) return element ;
    elementIndex++ ;
  }
  throw RangeError.index ( index, this, " index ", null, elementIndex ) ;
}

5. every( ) =

This method checks in iteration order whether each and every element of this given iterable satisfies ‘ test ’, and accordingly returns true or false.

Implementation =

bool every ( bool test ( E element ) ) {
  for ( E element in this ) {
    if ( ! test ( element ) ) return false ;
  }
  return true ;
}

6. expand < T > ( ) =

This method expands each element of the specified Iterable into zero or more elements.  The Iterable received as a result run through the elements returned by toElements for each element in an iteration order.

Implementation =

bool every ( bool test ( E element ) ) {
  for ( E element in this ) {
    if ( ! test ( element ) ) return false ;
  }
  return true ;
}
Iterable < T > expand < T >( Iterable < T > toElements ( E element ) ) = > ExpandIterable < E, T > ( this, toElements ) ;

7. firstWhere( ) =

This method returns the first element of the Iterable that satisfies the predicate ‘ test ’.

In case none of the elements satisfies the ‘ test ’, orElse function’s result is invoked, or it throws StateError.

Implementation =

E firstWhere ( bool test ( E element ), { E orElse ( ) ? } ) {
  for ( E element in this ) {
    if ( test ( element ) ) return element ;
  }
  if ( orElse != null) return orElse( ) ;
  throw IterableElementError.noElement( );
}

8. fold < T > ( ) =

This method combines each element of the collection with an existing value, thereby reducing the whole collection to a single value. It begins iterating with the initial value using the ‘ intialValue ’ property and then iterates through the entire collection.

Implementation =

T fold < T >( T initialValue, T combine ( T previousValue, E element ) ) {
  var value = initialValue ;
  for ( E element in this ) value = combine( value, element ) ;
  return value ;
}

9. where( ) =

This method returns a new Iterable that satisfies the predicate ‘ test ’. The matching elements in the returned iterable have the same order as they have in the iterator.

Implementation =

Iterable < E > where (
bool test (
E element )
) = > WhereIterable < E > ( this, test );

10. toString( ) =

Converts the elements of the Iterable to their equivalent string representation. The default representation contains only the first three elements.  In case the resulting string doesn’t contain more than 80 characters, we include more elements from the beginning of the iterable.

Implementation = String toString( ) = > IterableBase.iterableToShortString ( this, ' ( ' , ' ) ' ) ;