/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.commons.collections4.iterators;
  
  import java.util.Iterator;
  
  import org.apache.commons.collections4.ResettableIterator;
  
  /**
   * Adapter to make an {@link Iterator Iterator} instance appear to be an
   * {@link Iterable Iterable} instance.  The iterable can be constructed in one
   * of two variants:  single use, multiple use.
   *
   * <p>
   * In the single use iterable case, the iterable is only usable for one
   * iterative operation over the source iterator.  Subsequent iterative
   * operations use the same, exhausted source iterator.  To create a single use
   * iterable, construct a new {@link IteratorIterable} using a {@link Iterator}
   * that is NOT a {@link ResettableIterator} iterator:
   * </p>
   *
   * <pre>
   *   Iterator&lt;Integer&gt; iterator = // some non-resettable iterator
   *   Iterable&lt;Integer&gt; iterable = new IteratorIterable&lt;Integer&gt;(iterator);
   * </pre>
   *
   * <p>
   * In the multiple use iterable case, the iterable is usable for any number of
   * iterative operations over the source iterator.  Of special note, even though
   * the iterable supports multiple iterations, it does not support concurrent
   * iterations. To implicitly create a multiple use iterable, construct a new
   * {@link IteratorIterable} using a {@link ResettableIterator} iterator:
   * </p>
   *
   * <pre>
   *   Integer[] array = {Integer.valueOf(1),Integer.valueOf(2),Integer.valueOf(3)};
   *   Iterator&lt;Integer&gt; iterator = IteratorUtils.arrayIterator(array); // a resettable iterator
   *   Iterable&lt;Integer&gt; iterable = new IteratorIterable&lt;Integer&gt;(iterator);
   * </pre>
   *
   * <p>
   * A multiple use iterable can also be explicitly constructed using any
   * {@link Iterator} and specifying {@code true} for the
   * {@code multipleUse} flag:
   * </p>
   *
   * <pre>
   *   Iterator&lt;Integer&gt; iterator = // some non-resettable iterator
   *   Iterable&lt;Integer&gt; iterable = new IteratorIterable&lt;Integer&gt;(iterator, true);
   * </pre>
   *
   * @param <E> the type of elements returned by this iterator.
   * @since 4.0
   */
  public class IteratorIterable<E> implements Iterable<E> {
  
      /**
       * Factory method to create an {@link Iterator Iterator} from another
       * iterator over objects of a different subtype.
       */
      private static <E> Iterator<E> createTypesafeIterator(final Iterator<? extends E> iterator) {
          return new Iterator<E>() {
              @Override
              public boolean hasNext() {
                  return iterator.hasNext();
              }
  
              @Override
              public E next() {
                  return iterator.next();
              }
  
              @Override
              public void remove() {
                  iterator.remove();
              }
          };
      }
  
      /** The iterator being adapted into an iterable. */
      private final Iterator<? extends E> iterator;
  
      /** The iterator parameterized as the {@link #iterator()} return type. */
      private final Iterator<E> typeSafeIterator;
  
     /**
      * Constructs a new {@code IteratorIterable} that will use the given
      * iterator.
      *
      * @param iterator the iterator to use.
      */
     public IteratorIterable(final Iterator<? extends E> iterator) {
         this(iterator, false);
     }
 
     /**
      * Constructs a new {@code IteratorIterable} that will use the given
      * iterator.
      *
      * @param iterator the iterator to use.
      * @param multipleUse {@code true} if the new iterable can be used in multiple iterations
      */
     public IteratorIterable(final Iterator<? extends E> iterator, final boolean multipleUse) {
         if (multipleUse && !(iterator instanceof ResettableIterator)) {
             this.iterator = new ListIteratorWrapper<>(iterator);
         } else {
             this.iterator = iterator;
         }
         this.typeSafeIterator = createTypesafeIterator(this.iterator);
     }
 
     /**
      * Gets the iterator wrapped by this iterable.
      *
      * @return the iterator
      */
     @Override
     public Iterator<E> iterator() {
         if (iterator instanceof ResettableIterator) {
             ((ResettableIterator<? extends E>) iterator).reset();
         }
         return typeSafeIterator;
     }
 }