content: /*
   * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  package java.lang;
  
  import java.util.Iterator;
  import java.util.Objects;
  import java.util.Spliterator;
  import java.util.Spliterators;
  import java.util.function.Consumer;
  
  /**
   * Implementing this interface allows an object to be the target of
   * the "for-each loop" statement. See
   * <strong>
   * <a href="{@docRoot}/../technotes/guides/language/foreach.html">For-each Loop</a>
   * </strong>
   *
   * @param <T> the type of elements returned by the iterator
   *
   * @since 1.5
   * @jls 14.14.2 The enhanced for statement
   */
  public interface Iterable<T> {
      /**
       * Returns an iterator over elements of type {@code T}.
       *
       * @return an Iterator.
       */
      Iterator<T> iterator();
  
      /**
       * Performs the given action for each element of the {@code Iterable}
       * until all elements have been processed or the action throws an
       * exception.  Unless otherwise specified by the implementing class,
       * actions are performed in the order of iteration (if an iteration order
       * is specified).  Exceptions thrown by the action are relayed to the
       * caller.
       *
       * @implSpec
       * <p>The default implementation behaves as if:
       * <pre>{@code
       *     for (T t : this)
       *         action.accept(t);
       * }</pre>
       *
       * @param action The action to be performed for each element
       * @throws NullPointerException if the specified action is null
       * @since 1.8
       */
      default void forEach(Consumer<? super T> action) {
          Objects.requireNonNull(action);
          for (T t : this) {
              action.accept(t);
          }
      }
  
      /**
       * Creates a {@link Spliterator} over the elements described by this
       * {@code Iterable}.
       *
       * @implSpec
       * The default implementation creates an
       * <em><a href="Spliterator.html#binding">early-binding</a></em>
       * spliterator from the iterable's {@code Iterator}.  The spliterator
       * inherits the <em>fail-fast</em> properties of the iterable's iterator.
       *
       * @implNote
       * The default implementation should usually be overridden.  The
       * spliterator returned by the default implementation has poor splitting
       * capabilities, is unsized, and does not report any spliterator
       * characteristics. Implementing classes can nearly always provide a
       * better implementation.
       *
       * @return a {@code Spliterator} over the elements described by this
       * {@code Iterable}.
       * @since 1.8
       */
      default Spliterator<T> spliterator() {
          return Spliterators.spliteratorUnknownSize(iterator(), 0);
      }
  }
  