All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.collect.AbstractIterator Maven / Gradle / Ivy

There is a newer version: 1.45.6
Show newest version
/*
 * Copyright (C) 2007 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
 *
 * 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 com.google.common.collect;

import static com.google.common.base.Preconditions.checkState;

import com.google.common.annotations.GwtCompatible;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.util.NoSuchElementException;
import org.checkerframework.checker.nullness.compatqual.NullableDecl;

/**
 * This class provides a skeletal implementation of the {@code Iterator} interface, to make this
 * interface easier to implement for certain types of data sources.
 *
 * 

{@code Iterator} requires its implementations to support querying the end-of-data status * without changing the iterator's state, using the {@link #hasNext} method. But many data sources, * such as {@link java.io.Reader#read()}, do not expose this information; the only way to discover * whether there is any data left is by trying to retrieve it. These types of data sources are * ordinarily difficult to write iterators for. But using this class, one must implement only the * {@link #computeNext} method, and invoke the {@link #endOfData} method when appropriate. * *

Another example is an iterator that skips over null elements in a backing iterator. This could * be implemented as: * *

{@code
 * public static Iterator skipNulls(final Iterator in) {
 *   return new AbstractIterator() {
 *     protected String computeNext() {
 *       while (in.hasNext()) {
 *         String s = in.next();
 *         if (s != null) {
 *           return s;
 *         }
 *       }
 *       return endOfData();
 *     }
 *   };
 * }
 * }
* *

This class supports iterators that include null elements. * * @author Kevin Bourrillion * @since 2.0 */ // When making changes to this class, please also update the copy at // com.google.common.base.AbstractIterator @GwtCompatible public abstract class AbstractIterator extends UnmodifiableIterator { private State state = State.NOT_READY; /** Constructor for use by subclasses. */ protected AbstractIterator() {} private enum State { /** We have computed the next element and haven't returned it yet. */ READY, /** We haven't yet computed or have already returned the element. */ NOT_READY, /** We have reached the end of the data and are finished. */ DONE, /** We've suffered an exception and are kaput. */ FAILED, } @NullableDecl private T next; /** * Returns the next element. Note: the implementation must call {@link #endOfData()} when * there are no elements left in the iteration. Failure to do so could result in an infinite loop. * *

The initial invocation of {@link #hasNext()} or {@link #next()} calls this method, as does * the first invocation of {@code hasNext} or {@code next} following each successful call to * {@code next}. Once the implementation either invokes {@code endOfData} or throws an exception, * {@code computeNext} is guaranteed to never be called again. * *

If this method throws an exception, it will propagate outward to the {@code hasNext} or * {@code next} invocation that invoked this method. Any further attempts to use the iterator will * result in an {@link IllegalStateException}. * *

The implementation of this method may not invoke the {@code hasNext}, {@code next}, or * {@link #peek()} methods on this instance; if it does, an {@code IllegalStateException} will * result. * * @return the next element if there was one. If {@code endOfData} was called during execution, * the return value will be ignored. * @throws RuntimeException if any unrecoverable error happens. This exception will propagate * outward to the {@code hasNext()}, {@code next()}, or {@code peek()} invocation that invoked * this method. Any further attempts to use the iterator will result in an {@link * IllegalStateException}. */ protected abstract T computeNext(); /** * Implementations of {@link #computeNext} must invoke this method when there are no * elements left in the iteration. * * @return {@code null}; a convenience so your {@code computeNext} implementation can use the * simple statement {@code return endOfData();} */ @CanIgnoreReturnValue protected final T endOfData() { state = State.DONE; return null; } @CanIgnoreReturnValue // TODO(kak): Should we remove this? Some people are using it to prefetch? @Override public final boolean hasNext() { checkState(state != State.FAILED); switch (state) { case DONE: return false; case READY: return true; default: } return tryToComputeNext(); } private boolean tryToComputeNext() { state = State.FAILED; // temporary pessimism next = computeNext(); if (state != State.DONE) { state = State.READY; return true; } return false; } @CanIgnoreReturnValue // TODO(kak): Should we remove this? @Override public final T next() { if (!hasNext()) { throw new NoSuchElementException(); } state = State.NOT_READY; T result = next; next = null; return result; } /** * Returns the next element in the iteration without advancing the iteration, according to the * contract of {@link PeekingIterator#peek()}. * *

Implementations of {@code AbstractIterator} that wish to expose this functionality should * implement {@code PeekingIterator}. */ public final T peek() { if (!hasNext()) { throw new NoSuchElementException(); } return next; } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy