com.ajjpj.afoundation.collection.immutable.AMonadicOps Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of a-foundation Show documentation
There is a newer version: 1.0-pre19
package com.ajjpj.afoundation.collection.immutable;

import com.ajjpj.afoundation.function.AFunction1;
import com.ajjpj.afoundation.function.APartialFunction;
import com.ajjpj.afoundation.function.APredicate;

/**
 * This interface contains those functional operations that are supported for all kinds of collections. This is the greatest common
 *  denominator of all a-base collection classes.
 *
 * @author arno
 */
public interface AMonadicOps {
    /**
     * Filters this collection's elements, this method returns a new collection comprised of only those elements that match
     *  a given predicate.
     */
     AMonadicOps filter(APredicate pred) throws E;

    /**
     * Turns a collection of collections into a 'flat' collection, removing one layer of collections.
     */
     AMonadicOps flatten();

    /**
     * Applies a transformation function to each element, creating a new collection instance from the results. For a
     *  collection of strings, this could e.g. be used to create a collection of integer values with each string's length.
     */
     AMonadicOps map(AFunction1 f) throws E;

    /**
     * Maps each element to a collection of values, flattening the results into a single collection. Let there be a
     *  collection of strings. Calling flatMap with a function that splits a string into tokens, the result
     *  would be a collection of all tokens of all original strings.
     */
     AMonadicOps flatMap(AFunction1, E> f) throws E;

    /**
     * Applies a transformation function to all elements of a collection, where the partial function is defined for. Creates a new collection
     *   of the transformed elements only. So the number of result elements may be less than the number of elements in the source collection.
     */
     AMonadicOps collect (APartialFunction pf) throws E;

    /**
     * Wraps a filter around the existing collection, making creation of the result a constant time operation. This comes
     *  at the price that the actual filtering is done for every iteration.
     */
//TODO     AMonadicOps> withFilter(APredicate pred) throws E;

    /**
     * Searches through this collection's elements and returns the first element matching a given predicate. if any.
     */
     AOption find(APredicate pred) throws E;

    /**
     * Returns true iff all elements of the collection match the predicate.
     */
     boolean forAll(APredicate pred) throws E;

    /**
     * Returns true iff at least one element of the collection matches the predicate.
     */
     boolean exists(APredicate pred) throws E;
}