1 /*

        2  * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights reserved.

        3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

        4  *

        5  * This code is free software; you can redistribute it and/or modify it

        6  * under the terms of the GNU General Public License version 2 only, as

        7  * published by the Free Software Foundation.  Oracle designates this

        8  * particular file as subject to the "Classpath" exception as provided

        9  * by Oracle in the LICENSE file that accompanied this code.

       10  *

       11  * This code is distributed in the hope that it will be useful, but WITHOUT

       12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

       13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

       14  * version 2 for more details (a copy is included in the LICENSE file that

       15  * accompanied this code).

       16  *

       17  * You should have received a copy of the GNU General Public License version

       18  * 2 along with this work; if not, write to the Free Software Foundation,

       19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

       20  *

       21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

       22  * or visit www.oracle.com if you need additional information or have any

       23  * questions.

       24  */

       25 package java.lang;

       26 

       27 import java.util.Iterables;

       28 import java.util.Iterator;

       29 import java.util.Comparator;

       30 import java.util.Fillable;

       31 import java.util.functions.*;

       32 

       33 /**

       34  * Implementing this interface allows an object to be the target of

       35  * the "for-each loop" statement. See

       36  * <strong>

       37  * <a href="{@docRoot}/../technotes/guides/language/foreach.html">For-each Loop</a>

       38  * </strong>

       39  *

       40  * @param <T> the type of elements returned by the iterator

       41  *

       42  * @since 1.5

       43  */

       44 public interface Iterable<T> {

       45 

       46     /**

       47      * Returns an iterator over elements of type {@code T}.

       48      *

       49      * @return an Iterator.

       50      */

       51     Iterator<T> iterator();

       52 

       53     /**

       54      * Return {@code true} if this Iterable contains no elements.

       55      *

       56      * @since 1.8

       57      *

       58      * @return {@code true} if this Iterable contains no elements.

       59      */

       60     boolean isEmpty() default Iterables.isEmpty;

       61 

       62     /**

       63      * Filter elements according to the provided {@code predicate} and return a

       64      * an Iterable view of the filtered elements. The filtered view will reflect

       65      * changes in this Iterable.

       66      *

       67      * @since 1.8

       68      *

       69      * @param predicate Decides which elements should be included in the

       70      * resulting Iterable view. Each element with a {@code true} result will be

       71      * included in the resulting view.

       72      * @return An Iterable view of the filtered elements.

       73      */

       74     Iterable<T> filter(Predicate<? super T> predicate) default Iterables.filter;

       75 

       76     /**

       77      * Performs the operation specified by {@code block} upon each element.

       78      *

       79      * @since 1.8

       80      *

       81      * @param block The operation to be performed upon each each element.

       82      * @return This Iterable.

       83      */

       84     Iterable<T> forEach(Block<? super T> block) default Iterables.forEach;

       85 

       86     /**

       87      * Map elements using the provided {@code mapper} and return an Iterable

       88      * view of the mapped elements. The mappeds view will reflect changes in

       89      * this Iterable.

       90      *

       91      * @since 1.8

       92      *

       93      * @param <U> Type of the returned elements.

       94      * @param mapper Performs the mapping between elements of type {@code T}

       95      * and elements of type {@code U}.

       96      * @return An Iterable view consisting of the mapped elements.

       97      */

       98      <U> Iterable<U> map(Mapper<? super T, ? extends U> mapper) default Iterables.map;

       99 

      100     /**

      101      * Reduce elements to a single value.

      102      *

      103      * @since 1.8

      104      *

      105      * @param reducer Reduces elements to a result of type {@code U}.

      106      * @param base Initial value for reducer.

      107      * @return The reduced value of the elements.

      108      */

      109     T reduce(T base, Operator<T> reducer) default Iterables.reduce;

      110 

      111     <U> U mapReduce(Mapper<? super T, ? extends U> mapper, U base, Operator<U> reducer) default Iterables.mapReduce;

      112     int mapReduce(IntMapper<? super T> mapper, int base, IntOperator reducer) default Iterables.mapReduce;

      113     long mapReduce(LongMapper<? super T> mapper, long base, LongOperator reducer) default Iterables.mapReduce;

      114     double mapReduce(DoubleMapper<? super T> mapper, double base, DoubleOperator reducer) default Iterables.mapReduce;

      115 

      116     /**

      117      * All elements are added to the specified collection.

      118      *

      119      * @param <A> Type of target container.

      120      * @param target The collection to which the elements are added.

      121      * @return The provided collection.

      122      *

      123      * @since 1.8

      124      */

      125     <A extends Fillable<? super T>> A into(A target) default Iterables.into;

      126 

      127     /**

      128      * Returns {@code true} if any of the elements match the provided predicate.

      129      *

      130      * @param filter a predicate against which returns {@code true} for

      131      * matching elements.

      132      * @return {@code true} if any elements returned {@code true} for the

      133      * provided predicate.

      134      */

      135     public boolean anyMatch(Predicate<? super T> filter) default Iterables.anyMatch;

      136 

      137     /**

      138      * Returns {@code true} if none of the elements match the provided predicate.

      139      *

      140      * @param filter a predicate against which returns {@code true} for

      141      * matching elements.

      142      * @return {@code true} if all elements of this collection returned

      143      * {@code true} for the provided predicate.

      144      */

      145     public boolean noneMatch(Predicate<? super T> filter) default Iterables.noneMatch;

      146 

      147     /**

      148      * Returns {@code true} if all of the elements match the provided predicate.

      149      *

      150      * @param filter a predicate against which returns {@code true} for

      151      * matching elements.

      152      * @return {@code true} if all elements returned {@code true} for the provided predicate.

      153      */

      154     public boolean allMatch(Predicate<? super T> filter) default Iterables.allMatch;

      155 

      156     // public Iterable<T> sorted() default Iterables.sorted;

      157 

      158     public Iterable<T> sorted(Comparator<? super T> comparator) default Iterables.sorted;

      159 

      160     public Iterable<T> uniqueElements() default Iterables.uniqueElements;

      161 }