com.bmd.android.collection.iterator.ElementSparseIterable Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of robo-fashion Show documentation
Easily iterate through Android sparse collections
There is a newer version: 3.0.0
/**
 * 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.bmd.android.collection.iterator;

import com.bmd.android.collection.filter.Filter;
import com.bmd.android.collection.filter.FilterBuilder;
import com.bmd.android.collection.translator.Translator;

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

/**
 * This interface extends the {@link com.bmd.android.collection.iterator.SparseIterable} one
 * by adding specific methods handling serialization of the elements to lists and arrays.
 * 
 * Created by davide 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);
}