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

/*
 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.Comparator;
import java.util.NoSuchElementException;

import net.sf.staccatocommons.collections.restrictions.Projection;
import net.sf.staccatocommons.defs.Applicable;
import net.sf.staccatocommons.restrictions.check.NonNull;

/**
 * @author flbulgarelli
 * 
 */
public interface Sortable {

  /**
   * Sorts this Stream, using their element's natural ordering
   * 
   * @return a new {@link Stream}
   */
  @Projection
  Stream sort();

  /**
   * Sorts this Stream, using the given comparator
   * 
   * @param comparator
   * @return a new {@link Stream}
   */
  @Projection
  Stream sortBy(@NonNull Comparator comparator);

  /**
   * Sorts this Stream, using Compare.on(function) as comparator
   * 
   * @param 
   * @param function
   * @return a new {@link Stream}
   */
  @Projection
  > Stream sortOn(Applicable function);

  /**
   * Answers the min element of the stream, using the given
   * comparator to compare elements.
   * 
   * @param comparator
   * @return the minimum element.
   * @throws NoSuchElementException
   *           if the stream is empty.
   */
  @NonNull
  A minimumBy(@NonNull Comparator comparator) throws NoSuchElementException;

  /**
   * Answers the minimum element of the stream, using the given
   * Compare.on(function) to compare elements.
   * 
   * @param function
   * @return the minimum element.
   * @throws NoSuchElementException
   *           if the stream is empty.
   */
  > A minimumOn(@NonNull Applicable function) throws NoSuchElementException;

  /**
   * Answers the minimum element of the stream, using elements natural order.
   * 
   * @return the minimum element.
   * @throws NoSuchElementException
   *           if the stream is empty.
   * @throws ClassCastException
   *           if elements are not comparable
   */
  @NonNull
  A minimum() throws ClassCastException, NoSuchElementException;

  /**
   * Answers the maximum element of the stream, using the given
   * comparator to compare elements.
   * 
   * @param comparator
   * @return the maximum element.
   * @throws NoSuchElementException
   *           if the stream is empty.
   */
  @NonNull
  A maximumBy(@NonNull Comparator comparator) throws NoSuchElementException;

  /**
   * Answers the maximum element of the stream, using the given
   * Compare.on(function) to compare elements.
   * 
   * @param function
   * @return the maximum element.
   * @throws NoSuchElementException
   *           if the stream is empty.
   */
  > A maximumOn(@NonNull Applicable function) throws NoSuchElementException;

  /**
   * Answers the maximum element of the stream, using elements natural order.
   * 
   * @return the maximum element.
   * @throws NoSuchElementException
   *           if the stream is empty.
   * @throws ClassCastException
   *           if elements are not comparable
   */
  @NonNull
  A maximum() throws ClassCastException, NoSuchElementException;

}