com.ajjpj.abase.collection.immutable.AMap Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of a-base Show documentation
a-base is a library of basic (hence the name) classes, most notably immutable collection classes with copy-on-write operations
There is a newer version: 1.0-pre11
Show newest version
package com.ajjpj.abase.collection.immutable;

import com.ajjpj.abase.collection.APair;
import com.ajjpj.abase.function.AFunction1;

import java.util.Collection;
import java.util.Iterator;
import java.util.Set;


/**
 * This interface represents immutable maps with mutator methods (updated(), removed()) that return a
 *  new map instance with different members. Since all instances are immutable, they are thread-safe by definition.
 *  They are also useful in recursive algorithms.
 *
 * This interface does not implement java.util.Map since that interface is inherently mutable. There is
 *  however a conversion method to java.util.Map, and AMap implementations have factory methods that
 *  take java.util.Map instances.

 *
 * The AMap contract is not hard-wired to equals() and hashCode() methods.
 *  Implementations are configurable through a pluggable equalityForEquals strategy, which defaults to equals() and hashCode()
 *  however. That allows e.g. using all AMap implementations based on object identity ('==') along the lines of what
 *  java.util.IdentityHashMap does.

 *
 * Implementations (AHashMap in particular) use highly optimized algorithms to minimize 'copying' on modification.
 *
 * @author arno
 */
public interface AMap extends Iterable> {
    int size();
    boolean isEmpty();
    boolean nonEmpty();

    /**
     * Returns true iff the map contains the specified key. The containment check is based on the implementation's
     *  equalityForEquals strategy, which may or may not use equals().
     */
    boolean containsKey(K key);

    /**
     * Returns true iff the map contains the specified value. The containment check is based on the implementation's
     *  equalityForEquals strategy, which may or may not use equals().
     */
    boolean containsValue(V value);

    /**
     * Returns the value stored for a given key. If the map contains the key, the corresponding value is wrapped in
     *  AOption.some(...), otherwise AOption.none() is returned.
     */
    AOption get(K key);

    /**
     * This is the equivalent of calling get(...).get(); implementations throw a NoSuchElementException if there is
     *  no entry for the key.
     */
    V getRequired(K key);

    /**
     * Returns an java.util.Set with the map's keys. The returned object throws
     *  UnsupportedOperationException for all modifying operations.

     *
     * The returned set is not guaranteed to provide uniqueness with regard to equals(). If the
     *  map's equalityForEquals strategy treats two objects as different even if their equals methods return true,
     *  then the returned set may contain both.
     */
    Set keys();

    /**
     * Returns a java.util.Collection with the map's values. Duplicate values are returned as often as they
     *  occur. The returned collection throws UnsupportedOperationException for all modifying operations.
     */
    Collection values();

    /**
     * This method 'adds' a new value for a given key, returning a modified copy of the map while leaving the original
     *  unmodified.
     */
    AMap updated(K key, V value);

    /**
     * This method 'removes' an entry from the map, returning a modified copy of the map while leaving the original
     *  unmodified.
     */
    AMap removed(K key);

    /**
     * Returns an iterator with all key/value pairs stored in the map. This method allows AMap instances to be used
     *  with the for(...: map) syntax introduced with Java 5.
     */
    @Override
    Iterator> iterator();

    /**
     * Returns a read-only java.util.Map view of the AMap. Constructing the view takes constant time (i.e.
     *  there is no copying), lookup and iteration are passed to the underlying AMap. All modifying operations on the
     *  returned Map throw UnsupportedOperationException.
     */
    java.util.Map asJavaUtilMap();

    /**
     * This method wraps an AMap, causing a given defaultValue to be returned for all keys not explicitly present in
     *  the map. Looking up the value for a key not explicitly stored in the map does not modify the map.
     */
    AMap withDefaultValue(V defaultValue);

    /**
     * This method wraps an AMap. If one of the get... methods is called for a key not stored in the map,
     *  a function is called to determine the value to be returned. 
     *
     * NB: This does not cause the calculated value to be stored in the map; repeated calls for the same
     *  key trigger the value's calculation anew each time.
     */
    AMap withDefault(AFunction1 function);
}