Skip to content

Commit

Permalink
Reformat FluentIterable, moving some "Stream equivalent" sections above
Browse files Browse the repository at this point in the history 
@tags so that they appear properly.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=114900720
  • Loading branch information
@cpovirk
cpovirk committed Feb 17, 2016
1 parent 9555846 commit 529027a
Showing 1 changed file with 68 additions and 75 deletions.
143 changes: 68 additions & 75 deletions guava/src/com/google/common/collect/FluentIterable.java
View file
@@ -1,17 +1,15 @@
/*
* Copyright (C) 2008 The Guava Authors
*
* Licensed 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
* Licensed 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.
* 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 com.google.common.collect;
Expand Down Expand Up @@ -55,8 +53,8 @@
* array (for example {@link #toList})
* </ul>
*
* <p>Several lesser-used features are currently available only as static methods on the {@link
* Iterables} class.
* <p>Several lesser-used features are currently available only as static methods on the
* {@link Iterables} class.
*
* <a name="streams"></a>
* <h3>Comparison to streams</h3>
Expand All @@ -68,8 +66,8 @@
* <ul>
* <li>A stream is <i>single-use</i>; it becomes invalid as soon as any "terminal operation" such as
* {@code findFirst()} or {@code iterator()} is invoked. (Even though {@code Stream} contains
* all the right method <i>signatures</i> to implement {@link Iterable}, it does not actually
* do so, to avoid implying repeat-iterability.) {@code FluentIterable}, on the other hand, is
* all the right method <i>signatures</i> to implement {@link Iterable}, it does not actually do
* so, to avoid implying repeat-iterability.) {@code FluentIterable}, on the other hand, is
* multiple-use, and does implement {@link Iterable}.
* <li>Streams offer many features not found here, including {@code min/max}, {@code
* distinct}, {@code reduce}, {@code sorted}, the very powerful {@code collect}, and built-in
Expand Down Expand Up @@ -125,8 +123,8 @@ protected FluentIterable() {
}

/**
* Returns a fluent iterable that wraps {@code iterable}, or {@code iterable} itself if it
* is already a {@code FluentIterable}.
* Returns a fluent iterable that wraps {@code iterable}, or {@code iterable} itself if it is
* already a {@code FluentIterable}.
*
* <p><b>{@code Stream} equivalent:</b> {@code iterable.stream()} if {@code iterable} is a
* {@link Collection}; {@code StreamSupport.stream(iterable.spliterator(), false)} otherwise.
Expand Down Expand Up @@ -335,21 +333,21 @@ public final boolean contains(@Nullable Object target) {
}

/**
* Returns a fluent iterable whose {@code Iterator} cycles indefinitely over the elements of
* this fluent iterable.
* Returns a fluent iterable whose {@code Iterator} cycles indefinitely over the elements of this
* fluent iterable.
*
* <p>That iterator supports {@code remove()} if {@code iterable.iterator()} does. After
* {@code remove()} is called, subsequent cycles omit the removed element, which is no longer in
* this fluent iterable. The iterator's {@code hasNext()} method returns {@code true} until
* this fluent iterable is empty.
* this fluent iterable. The iterator's {@code hasNext()} method returns {@code true} until this
* fluent iterable is empty.
*
* <p><b>Warning:</b> Typical uses of the resulting iterator may produce an infinite loop. You
* should use an explicit {@code break} or be certain that you will eventually remove all the
* elements.
*
* <p><b>{@code Stream} equivalent:</b> if the source iterable has only a single element {@code
* element}, use {@code Stream.generate(() -> element)}. Otherwise, if the source iterable has
* a {@code stream} method (for example, if it is a {@link Collection}), use
* element}, use {@code Stream.generate(() -> element)}. Otherwise, if the source iterable has a
* {@code stream} method (for example, if it is a {@link Collection}), use
* {@code Stream.generate(iterable::stream).flatMap(s -> s)}.
*/
public final FluentIterable<E> cycle() {
Expand Down Expand Up @@ -386,8 +384,8 @@ public final FluentIterable<E> append(E... elements) {
}

/**
* Returns the elements from this fluent iterable that satisfy a predicate. The
* resulting fluent iterable's iterator does not support {@code remove()}.
* Returns the elements from this fluent iterable that satisfy a predicate. The resulting fluent
* iterable's iterator does not support {@code remove()}.
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.filter(predicate)} (same).
*/
Expand All @@ -398,8 +396,6 @@ public final FluentIterable<E> filter(Predicate<? super E> predicate) {
/**
* Returns the elements from this fluent iterable that are instances of class {@code type}.
*
* @param type the type of elements desired
*
* <p><b>{@code Stream} equivalent:</b> <pre> {@code
*
* @SuppressWarnings("unchecked") // safe by runtime check
Expand All @@ -409,6 +405,8 @@ public final FluentIterable<E> filter(Predicate<? super E> predicate) {
*
* @SuppressWarnings("unchecked") // safe by runtime check
* Stream<MyType> result = (Stream) stream.filter(e -> e instanceof MyType);}</pre>
*
* @param type the type of elements desired
*/
@GwtIncompatible // Class.isInstance
public final <T> FluentIterable<T> filter(Class<T> type) {
Expand All @@ -425,8 +423,8 @@ public final boolean anyMatch(Predicate<? super E> predicate) {
}

/**
* Returns {@code true} if every element in this fluent iterable satisfies the predicate.
* If this fluent iterable is empty, {@code true} is returned.
* Returns {@code true} if every element in this fluent iterable satisfies the predicate. If this
* fluent iterable is empty, {@code true} is returned.
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.allMatch(predicate)} (same).
*/
Expand All @@ -435,8 +433,8 @@ public final boolean allMatch(Predicate<? super E> predicate) {
}

/**
* Returns an {@link Optional} containing the first element in this fluent iterable that
* satisfies the given predicate, if such an element exists.
* Returns an {@link Optional} containing the first element in this fluent iterable that satisfies
* the given predicate, if such an element exists.
*
* <p><b>Warning:</b> avoid using a {@code predicate} that matches {@code null}. If {@code null}
* is matched in this fluent iterable, a {@link NullPointerException} will be thrown.
Expand All @@ -448,8 +446,8 @@ public final Optional<E> firstMatch(Predicate<? super E> predicate) {
}

/**
* Returns a fluent iterable that applies {@code function} to each element of this
* fluent iterable.
* Returns a fluent iterable that applies {@code function} to each element of this fluent
* iterable.
*
* <p>The returned fluent iterable's iterator supports {@code remove()} if this iterable's
* iterator does. After a successful {@code remove()} call, this fluent iterable no longer
Expand All @@ -462,13 +460,12 @@ public final <T> FluentIterable<T> transform(Function<? super E, T> function) {
}

/**
* Applies {@code function} to each element of this fluent iterable and returns
* a fluent iterable with the concatenated combination of results. {@code function}
* returns an Iterable of results.
* Applies {@code function} to each element of this fluent iterable and returns a fluent iterable
* with the concatenated combination of results. {@code function} returns an Iterable of results.
*
* <p>The returned fluent iterable's iterator supports {@code remove()} if this
* function-returned iterables' iterator does. After a successful {@code remove()} call,
* the returned fluent iterable no longer contains the corresponding element.
* <p>The returned fluent iterable's iterator supports {@code remove()} if this function-returned
* iterables' iterator does. After a successful {@code remove()} call, the returned fluent
* iterable no longer contains the corresponding element.
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.flatMap(function)} (using a function that
* produces streams, not iterables).
Expand All @@ -481,8 +478,8 @@ public <T> FluentIterable<T> transformAndConcat(
}

/**
* Returns an {@link Optional} containing the first element in this fluent iterable.
* If the iterable is empty, {@code Optional.absent()} is returned.
* Returns an {@link Optional} containing the first element in this fluent iterable. If the
* iterable is empty, {@code Optional.absent()} is returned.
*
* <p><b>{@code Stream} equivalent:</b> if the goal is to obtain any element, {@code
* stream.findAny()}; if it must specifically be the <i>first</i> element, {@code
Expand All @@ -497,8 +494,8 @@ public final Optional<E> first() {
}

/**
* Returns an {@link Optional} containing the last element in this fluent iterable.
* If the iterable is empty, {@code Optional.absent()} is returned.
* Returns an {@link Optional} containing the last element in this fluent iterable. If the
* iterable is empty, {@code Optional.absent()} is returned.
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.reduce((a, b) -> b)}.
*
Expand All @@ -522,9 +519,8 @@ public final Optional<E> last() {
}

/*
* TODO(kevinb): consider whether this "optimization" is worthwhile. Users
* with SortedSets tend to know they are SortedSets and probably would not
* call this method.
* TODO(kevinb): consider whether this "optimization" is worthwhile. Users with SortedSets tend
* to know they are SortedSets and probably would not call this method.
*/
if (iterable instanceof SortedSet) {
SortedSet<E> sortedSet = (SortedSet<E>) iterable;
Expand All @@ -540,21 +536,19 @@ public final Optional<E> last() {
}

/**
* Returns a view of this fluent iterable that skips its first {@code numberToSkip}
* elements. If this fluent iterable contains fewer than {@code numberToSkip} elements,
* the returned fluent iterable skips all of its elements.
* Returns a view of this fluent iterable that skips its first {@code numberToSkip} elements. If
* this fluent iterable contains fewer than {@code numberToSkip} elements, the returned fluent
* iterable skips all of its elements.
*
* <p>Modifications to this fluent iterable before a call to {@code iterator()} are
* reflected in the returned fluent iterable. That is, the its iterator skips the first
* {@code numberToSkip} elements that exist when the iterator is created, not when {@code skip()}
* is called.
* <p>Modifications to this fluent iterable before a call to {@code iterator()} are reflected in
* the returned fluent iterable. That is, the its iterator skips the first {@code numberToSkip}
* elements that exist when the iterator is created, not when {@code skip()} is called.
*
* <p>The returned fluent iterable's iterator supports {@code remove()} if the
* {@code Iterator} of this fluent iterable supports it. Note that it is <i>not</i>
* possible to delete the last skipped element by immediately calling {@code remove()} on the
* returned fluent iterable's iterator, as the {@code Iterator} contract states that a call
* to {@code * remove()} before a call to {@code next()} will throw an
* {@link IllegalStateException}.
* <p>The returned fluent iterable's iterator supports {@code remove()} if the {@code Iterator} of
* this fluent iterable supports it. Note that it is <i>not</i> possible to delete the last
* skipped element by immediately calling {@code remove()} on the returned fluent iterable's
* iterator, as the {@code Iterator} contract states that a call to {@code * remove()} before a
* call to {@code next()} will throw an {@link IllegalStateException}.
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.skip(numberToSkip)} (same).
*/
Expand All @@ -563,11 +557,10 @@ public final FluentIterable<E> skip(int numberToSkip) {
}

/**
* Creates a fluent iterable with the first {@code size} elements of this
* fluent iterable. If this fluent iterable does not contain that many elements,
* the returned fluent iterable will have the same behavior as this fluent iterable.
* The returned fluent iterable's iterator supports {@code remove()} if this
* fluent iterable's iterator does.
* Creates a fluent iterable with the first {@code size} elements of this fluent iterable. If this
* fluent iterable does not contain that many elements, the returned fluent iterable will have the
* same behavior as this fluent iterable. The returned fluent iterable's iterator supports
* {@code remove()} if this fluent iterable's iterator does.
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.limit(maxSize)} (same).
*
Expand Down Expand Up @@ -601,7 +594,7 @@ public final ImmutableList<E> toList() {

/**
* Returns an {@code ImmutableList} containing all of the elements from this {@code
* FluentIterable} in the order specified by {@code comparator}. To produce an {@code
* FluentIterable} in the order specified by {@code comparator}. To produce an {@code
* ImmutableList} sorted by its natural ordering, use {@code toSortedList(Ordering.natural())}.
*
* <p><b>{@code Stream} equivalent:</b>
Expand Down Expand Up @@ -685,18 +678,18 @@ public final <V> ImmutableMap<E, V> toMap(Function<? super E, V> valueFunction)
* In the returned multimap, keys appear in the order they are first encountered, and the values
* corresponding to each key appear in the same order as they are encountered.
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.collect(Collectors.groupingBy(keyFunction))}
* behaves similarly, but returns a mutable {@code Map<K, List<E>>} instead, and may not preserve
* the order of entries).
*
* @param keyFunction the function used to produce the key for each value
* @throws NullPointerException if any of the following cases is true:
* <ul>
* <li>{@code keyFunction} is null
* <li>An element in this fluent iterable is null
* <li>{@code keyFunction} returns {@code null} for any element of this iterable
* <li>{@code keyFunction} is null
* <li>An element in this fluent iterable is null
* <li>{@code keyFunction} returns {@code null} for any element of this iterable
* </ul>
*
* <p><b>{@code Stream} equivalent:</b> {@code stream.collect(Collectors.groupingBy(keyFunction))}
* behaves similarly, but returns a mutable {@code Map<K, List<E>>} instead, and may not preserve
* the order of entries).
*
* @since 14.0
*/
public final <K> ImmutableListMultimap<K, E> index(Function<? super E, K> keyFunction) {
Expand Down Expand Up @@ -727,10 +720,10 @@ public final <K> ImmutableListMultimap<K, E> index(Function<? super E, K> keyFun
* @param keyFunction the function used to produce the key for each value
* @return a map mapping the result of evaluating the function {@code
* keyFunction} on each value in this fluent iterable to that value
* @throws IllegalArgumentException if {@code keyFunction} produces the same
* key for more than one value in this fluent iterable
* @throws NullPointerException if any elements of this fluent iterable is null, or
* if {@code keyFunction} produces {@code null} for any value
* @throws IllegalArgumentException if {@code keyFunction} produces the same key for more than one
* value in this fluent iterable
* @throws NullPointerException if any elements of this fluent iterable is null, or if
* {@code keyFunction} produces {@code null} for any value
* @since 14.0
*/
public final <K> ImmutableMap<K, E> uniqueIndex(Function<? super E, K> keyFunction) {
Expand All @@ -746,8 +739,8 @@ public final <K> ImmutableMap<K, E> uniqueIndex(Function<? super E, K> keyFuncti
* len -> (E[]) Array.newInstance(type, len))}.
*
* @param type the type of the elements
* @return a newly-allocated array into which all the elements of this fluent iterable have
* been copied
* @return a newly-allocated array into which all the elements of this fluent iterable have been
* copied
*/
@GwtIncompatible // Array.newArray(Class, int)
public final E[] toArray(Class<E> type) {
Expand Down

0 comments on commit 529027a

Please sign in to comment.