com.ajjpj.afoundation.collection.immutable.ASortedMap 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;

/**
 * This interface extends {@link AMap}, adding methods that only make sense if there
 *  is an ordering on the keys.
 *
 * It includes only methods that can be implemented efficiently. The 'range' methods
 *  for example return {@link java.lang.Iterable}s instead of full-blown ASortedMap
 *  instances; application code can always use the returned {@link java.lang.Iterable}
 *  to create an {@link ASet} (or {@link ACollection} because that does not even
 *  require any copying) explicitly, showing the cost involved in using source code.
 *
 * @author arno
 */
public interface ASortedMap extends AMap { //TODO ASortedSet
    @Override ASortedMap updated (K key, V value);
    @Override ASortedMap removed (K key);

    /**
     * @return the first entry of the map, i.e. the entry with the 'smallest' key relative
     *          to the underlying sort order - or {@link AOption#none()} if the map is empty.
     */
    AOption> first();

    /**
     * @return the last entry of the map, i.e. the entry with the 'greatest' key relative
     *          to the underlying sort order - or {@link AOption#none()} if the map is empty.
     */
    AOption> last();

    /**
     * @return the first entry with a key 'greater than' a given key relative to the
     *          underlying sort order, or {@link AOption#none()} if there is no such entry.
     */
    AOption> firstGreaterThan (K key);

    /**
     * @return the first entry with a key 'greater than' or equal to a given key relative to the
     *          underlying sort order, or {@link AOption#none()} if there is no such entry.
     */
    AOption> firstGreaterOrEquals (K key);

    /**
     * @return the first entry with a key 'smaller than' a given key relative to the
     *          underlying sort order, or {@link AOption#none()} if there is no such entry.
     */
    AOption> lastSmallerThan (K key);

    /**
     * @return the first entry with a key 'smaller than' or equal to a given key relative to the
     *          underlying sort order, or {@link AOption#none()} if there is no such entry.
     */
    AOption> lastSmallerOrEquals (K key);

    /**
     * @return all entries with keys in the range from {@code fromKey} to {@code toKey}, both
     *          boundaries included.
     */
    Iterable > rangeII (K fromKey, K toKey); // inclusive

    /**
     * @return all entries with keys in the range from {@code fromKey} to {@code toKey}, including
     *          the lower boundary and excluding the upper boundary.
     */
    Iterable > rangeIE (K fromKey, K toKey);

    /**
     * @return all entries with keys in the range from {@code fromKey} to {@code toKey}, excluding
     *          the lower boundary and including the upper boundary.
     */
    Iterable > rangeEI (K fromKey, K toKey);

    /**
     * @return all entries with keys in the range from {@code fromKey} to {@code toKey}, both
     *          boundaries excluded.
     */
    Iterable > rangeEE (K fromKey, K toKey);

    /**
     * @return all entries with keys greater than or equal to a given value.
     */
    Iterable > fromI (K fromKey);

    /**
     * @return all entries with keys strictly greater than to a given value.
     */
    Iterable > fromE (K fromKey);

    /**
     * @return all entries with keys smaller than or equal to a given value.
     */
    Iterable > toI (K toKey);

    /**
     * @return all entries with keys strictly smaller than or equal to a given value.
     */
    Iterable > toE (K toKey);
}