com.github.dm.rf.android.iterator.ElementSparseIterable Maven / Gradle / Ivy

Go to download
/**
 * 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.github.dm.rf.android.iterator;

import com.github.dm.rf.android.filter.Filter;
import com.github.dm.rf.android.filter.FilterBuilder;
import com.github.dm.rf.android.translator.Translator;

import java.util.ArrayList;
import java.util.Collection;

/**
 * This interface extends the {@link SparseIterable} one by adding specific methods handling
 * serialization of the elements to lists and arrays.
 * 
 * Created by davide-maestroni on 3/10/14.
 *
 * @param  the element type.
 */
public interface ElementSparseIterable extends SparseIterable {

    @Override
    public FilterBuilder, E> but();

    @Override
    public ElementSparseIterable but(Filter filter);

    @Override
    public ElementSparseIterable doWhile(Condition condition);

    @Override
    public ElementSparseIterable forEach(Action action);

    @Override
    public FilterBuilder, E> only();

    @Override
    public ElementSparseIterable only(Filter filter);

    @Override
    public ElementSparseIterable remove();

    @Override
    public ElementSparseIterable retain();

    @Override
    public ElementSparseIterable reverse();

    /**
     * Fills the specified collection with the elements returned by this iterable, in the iteration
     * order.
     *
     * @param collection the collection to fill.
     * @return this iterable.
     */
    public ElementSparseIterable fill(Collection collection);

    /**
     * Fills the specified array with the elements returned by this iterable, in the iteration
     * order, starting from the index 0 of the array.
     * 

     * Note that, if the elements returned by the iterable cannot be cast to the array elements
     * type, a {@link java.lang.ClassCastException} will be thrown.
     * 

     * Note also that, in case the array is not big enough to contain all the elements, an
     * {@link java.lang.IndexOutOfBoundsException} will be thrown.
     *
     * @param array the array to fill.
     * @param    the array elements type.
     * @return this iterable.
     */
    public  ElementSparseIterable fill(T[] array);

    /**
     * Fills the specified array with the elements returned by this iterable, in the iteration
     * order, starting from the specified offset inside the array.
     * 

     * Note that, if the elements returned by the iterable cannot be cast to the array elements
     * type, a {@link java.lang.ClassCastException} will be thrown.
     * 

     * Note also that, in case the array is not big enough to contain all the elements, an
     * {@link java.lang.IndexOutOfBoundsException} will be thrown.
     *
     * @param array  the array to fill.
     * @param offset the offset from which to start filling the array.
     * @param     the array elements type.
     * @return this iterable.
     */
    public  ElementSparseIterable fill(T[] array, int offset);

    /**
     * Creates and returns a new array filled with the elements returned by this iterable, in the
     * iteration order.
     * 

     * Note that, if the elements returned by the iterable cannot be cast to the array elements
     * type, a {@link java.lang.ClassCastException} will be thrown.
     *
     * @param type the array elements class.
     * @param   the array elements type.
     * @return the new array.
     */
    public  T[] toArray(Class type);

    /**
     * Creates and returns a new list filled with the elements returned by this iterable, in the
     * iteration order.
     *
     * @return the new list.
     */
    public ArrayList toList();

    /**
     * Returns a new iterable whose elements are the same as this ones but translated through the
     * specified translator.
     * 
     * Note that all the filters and the iteration order are retained in the translation.
     *
     * @param translator the translator used to convert the elements.
     * @param         the new iterable elements type.
     * @return the new iterable.
     */
    public  ElementSparseIterable translate(Translator translator);
}