com.ajjpj.afoundation.collection.immutable.ASortedMap Maven / Gradle / Ivy
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);
}