net.sf.staccatocommons.collections.stream.Zippeable Maven / Gradle / Ivy

Go to download
/*
 Copyright (c) 2011, The Staccato-Commons Team

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
 the Free Software Foundation; version 3 of the License.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Lesser General Public License for more details.
 */
package net.sf.staccatocommons.collections.stream;

import net.sf.staccatocommons.collections.iterable.Iterables;
import net.sf.staccatocommons.collections.restrictions.Projection;
import net.sf.staccatocommons.defs.Applicable2;
import net.sf.staccatocommons.defs.function.Function2;
import net.sf.staccatocommons.lang.tuple.Pair;
import net.sf.staccatocommons.restrictions.check.NonNull;

/**
 * {@link Stream} interface for zipping
 * 
 * @author flbulgarelli
 * 
 */
public interface Zippeable {

  /**
   * Returns a {@link Stream} formed by the result of applying the given
   * function to each pair of elements from this and
   * the given iterable.
   * 
   * If any if either this or the given iterable is shorter than
   * the other one, the remaining elements are discarded.
   * 
   * @param 
   *          the type to the iterable to zip with this
   *          {@link Stream}
   * @param 
   *          the resulting Stream element type
   * @param iterable
   *          the {@link Iterable} to zip with this Stream
   * @param function
   *          the function to apply to each pair
   * @return a new Stream formed applying the given {@link Applicable2} to each
   *         pair this Stream and the given iterable. The resulting Stream size
   *         is the minimum of both iterables sizes, or infinite, if both this
   *         and iterable are
   * @see Iterables#zip(Iterable, Iterable)
   */
  @Projection
   Stream zip(@NonNull Iterable iterable, Function2 function);

  /**
   * Returns a {@link Stream} formed by by pair of element from
   * this and the given iterable.
   * 
   * If any if either this or the given iterable is shorter than
   * the other one, the remaining elements are discarded.
   * 
   * @param 
   *          the type to the iterable to zip with this
   *          {@link Stream}
   * @param iterable
   * @return a new Stream formed applying the given {@link Applicable2} to each
   *         pair this Stream and the given iterable. The resulting Stream size
   *         is the minimum of both iterables sizes, or infinite, if both this
   *         and iterable are
   * @see Iterables#zip(Iterable, Iterable)
   * @see #zip(Iterable, Function2)
   */
  @Projection
   Stream> zip(@NonNull Iterable iterable);

}