net.sf.staccatocommons.collections.stream.Searchable 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 java.util.NoSuchElementException;

import net.sf.staccatocommons.defs.Evaluable;
import net.sf.staccatocommons.defs.Thunk;
import net.sf.staccatocommons.lang.None;
import net.sf.staccatocommons.lang.Option;
import net.sf.staccatocommons.restrictions.check.NonNull;

/**
 * {@link Stream} interface for searching for elements
 * 
 * @author flbulgarelli
 * @param 
 */
public interface Searchable {

  /**
   * Returns any element in this {@link Stream}.
   * 
   * Any does not mean a random element, but just any of all elements contained,
   * without having it any particular interest over the rest. Most ordered or
   * sorted implementations will just retrieve the first element.
   * 
   * @return any element contained by this {@link Stream}
   * @throws NoSuchElementException
   *           if this {@link Stream} has no elements.
   */
  A any();

  /**
   * Returns any element of the given {@link Stream}, just like {@link #any()},
   * but as an option. If {@link Stream} has no elements, instead of throwing a
   * {@link NoSuchElementException}, it returns {@link None}
   * 
   * @return Option.some(element) if there is at least one element,
   *         or Option.none(), otherwise.
   */
  @NonNull
  Option anyOrNone();

  /**
   * Shorthand for anyOrNone().valueOrNull()
   * 
   * @return anyOrNone().valueOrNull()
   */
  A anyOrNull();

  /**
   * Shorthand for anyOrNone().valueOrElse(thunk)
   * 
   * @param thunk
   * 
   * @return anyOrNone().valueOrElse(thunk)
   */
  A anyOrElse(@NonNull Thunk thunk);

  /**
   * Shorthand for anyOrNone().valueOrElse(value)
   * 
   * @param value
   * @return anyOrNone().valueOrElse(value)
   */
  A anyOrElse(A value);

  /**
   * Looks for a element that satisfies the given {@link Evaluable}. If such
   * element does not exist, throws {@link NoSuchElementException}
   * 
   * @param predicate
   * @return the first elements that the predicate satisfies, if exists.
   * @throws NoSuchElementException
   *           if no element matches the predicate. As a particular case, this
   *           method will throw it if {@link Stream} has not elements,
   *           regardless of the predicate
   */
  A find(@NonNull Evaluable predicate);

  /**
   * Looks for an element that satisfies the given {@link Evaluable}. If such
   * element exists, returns some(element). Otherwise, returns
   * {@link None}.
   * 
   * @param predicate
   * @return None if no element matches the predicate, or some(element) if at
   *         least one exists. As a particular case, this method will return
   *         {@link None} if {@link Stream} is empty, regardless of the given
   *         predicate
   */
  @NonNull
  Option findOrNone(@NonNull Evaluable predicate);

  /**
   * Looks for an element that satisfies the given {@link Evaluable}. If such
   * element exists, returns it. Otherwise, returns null.
   * 
   * @param predicate
   * @return null if no element matches the predicate, or an element that
   *         satisfies it, if at least one exists. As a particular case, this
   *         method will return null if {@link Stream} is empty, regardless of
   *         the given predicate
   */
  A findOrNull(@NonNull Evaluable predicate);

  /**
   * Looks for an element that satisfies the given {@link Evaluable}. If such
   * element exists, returns it. Otherwise, returns the given thunk's value.
   * 
   * @param predicate
   * @return thunk.value() if no element matches the predicate, or
   *         an element that satisfies it, if at least one exists. As a
   *         particular case, this method will return the thunk's value if
   *         {@link Stream} is empty, regardless of the given predicate
   */
  A findOrElse(@NonNull Evaluable predicate, @NonNull Thunk thunk);

  /**
   * Looks for an element that satisfies the given {@link Evaluable}. If such
   * element exists, returns it. Otherwise, returns the given
   * element .
   * 
   * @param predicate
   * @return findOrElse(predicate, Thunks.constant(element))
   */
  A findOrElse(@NonNull Evaluable predicate, @NonNull A element);

}