com.ajjpj.afoundation.collection.immutable.ASet 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.collection.AEquality;
import com.ajjpj.afoundation.function.AFunction1;
import com.ajjpj.afoundation.function.APartialFunction;
import com.ajjpj.afoundation.function.APredicate;


/**
 * This interface represents an immutable set. It inherits most methods from ACollection, but it
 *  prescribes uniqueness semantics.
 *
 * Implementations of {@link ACollection#map(com.ajjpj.afoundation.function.AFunction1)} and
 *  {@link ACollection#flatMap(com.ajjpj.afoundation.function.AFunction1)} do not
 *  return instances of {@code ASet}, but rather generic collections without uniqueness guarantees. If {@code ASet} semantics are
 *  required, call {@link ACollection#toSet()} on the results.
 *
 * @author arno
 */
public interface ASet extends ACollection {
    @Override  ASet filter(APredicate pred) throws E;

    @Override  ASet map(AFunction1 f) throws E;
    @Override  ASet flatMap(AFunction1, E> f) throws E;
    @Override  ASet collect (APartialFunction pf) throws E;

    @Override  ASet flatten ();

    /**
     * @return the specification of equality on which this set maintains uniqueness.
     *         {@link com.ajjpj.afoundation.collection.AEquality#EQUALS} uses {@link Object#equals(Object)}
     *         and represents the 'normal' equality used by {@link java.util.Set}.
     */
    AEquality equalityForEquals();

    /**
     * @return a {@link java.util.Set} 'view' of this set's values, i.e. an read-only instance
     *         of {@link java.util.Set} that contains the exact same elements as this {@code ASet}.
     *         This operation performs no copying, and the returned collection is based
     *         on this {@code ASet}'s equality.
     */
    java.util.Set asJavaUtilSet();

    /**
     * @return a new {@link ASet} that is guaranteed to contain the new element, i.e. to contain an
     *         element which this set's {@link com.ajjpj.afoundation.collection.AEquality} considers
     *         equal to the parameter {@code el}.
     */
    ASet added (T el);

    /**
     * @return a new {@link ASet} that is guaranteed not to contain the parameter {@code el}, i.e. not
     *          to contain an element that this set's {@link com.ajjpj.afoundation.collection.AEquality}
     *          considers equal to the parameter {@code el}.
     */
    ASet removed (T el);
}