#include <coherence/util/NavigableMap.hpp>
Inherits SortedMap.
Inherited by TreeMap [virtual].
Methods lowerKey, floorKey, ceilingKey, and higherKey return only the associated keys. All of these methods are designed for locating, not traversing entries.
Methods subMap, headMap, tailMap differ from the like-named SortedMap methods in accepting additional arguments describing whether lower and upper bounds are inclusive versus exclusive. Sub-maps of any NavigableMap must implement the NavigableMap interface.
This interface additionally defines methods pollFirstEntry pollLastEntry that return and remove the least and greatest mappings, if any exist, else returning NULL.
Implementations of entry-returning methods are expected to return Map.Entry pairs representing snapshots of mappings at the time they were produced, and thus generally do not support the optional Entry.setValue method. Note however that it is possible to change mappings in the associated map using method put.
Methods subMap(Object, Object) subMap(K, K), headMap(Object) headMap(K), and tailMap(Object) tailMap(K) are specified to return SortedMap to allow existing implementations of SortedMap to be compatibly retrofitted to implement NavigableMap, but extensions and implementations of this interface are encouraged to override these methods to return NavigableMap.
Public Types | |
| typedef spec::Handle | Handle |
| NavigableMap Handle definition. | |
| typedef spec::View | View |
| NavigableMap View definition. | |
| typedef spec::Holder | Holder |
| NavigableMap Holder definition. | |
Public Member Functions | |
| virtual Object::View | ceilingKey (Object::View vKey) const =0 |
| Returns the least key greater than or equal to the given key, or NULL if there is no such key. | |
| virtual Object::View | floorKey (Object::View vKey) const =0 |
| Returns the greatest key less than or equal to the given key, or NULL if there is no such key. | |
| virtual Object::View | higherKey (Object::View vKey) const =0 |
| Returns the least key strictly greater than the given key, or NULL if there is no such key. | |
| virtual Object::View | lowerKey (Object::View vKey) const =0 |
| Returns the greatest key strictly less than the given key, or NULL if there is no such key. | |
| virtual Map::Entry::Holder | pollFirstEntry ()=0 |
| Removes and returns a key-value mapping associated with the least key in this map, or NULL if the map is empty. | |
| virtual Map::Entry::Holder | pollLastEntry ()=0 |
| Removes and returns a key-value mapping associated with the greatest key in this map, or NULL if the map is empty. | |
| virtual NavigableMap::Handle | headMap (Object::View vToKey, bool toInclusive)=0 |
| Returns a handle of the portion of the map whose keys are less than (or equal to, if toInclusive is true) vToKey. | |
| virtual NavigableMap::View | headMap (Object::View vToKey, bool toInclusive) const =0 |
| Returns a view of the portion of the map whose keys are less than (or equal to, if toInclusive is true) vToKey. | |
| virtual NavigableMap::Handle | subMap (Object::View vFromKey, bool fromInclusive, Object::View vToKey, bool toInclusive)=0 |
| Returns a handle of the portion of this map whose keys range from vFromKey to vToKey. | |
| virtual NavigableMap::View | subMap (Object::View vFromKey, bool fromInclusive, Object::View vToKey, bool toInclusive) const =0 |
| Returns a view of the portion of this map whose keys range from vFromKey to vToKey. | |
| virtual NavigableMap::Handle | tailMap (Object::View vFromKey, bool fromInclusive)=0 |
| Returns a handle of the portion of the map whose keys are greater than (or equal to, if fromInclusive} is true) vFromKey. | |
| virtual NavigableMap::View | tailMap (Object::View vFromKey, bool fromInclusive) const =0 |
| Returns a view of the portion of the map whose keys are greater than (or equal to, if fromInclusive} is true) vFromKey. | |
| virtual Object::View ceilingKey | ( | Object::View | vKey | ) | const [pure virtual] |
Returns the least key greater than or equal to the given key, or NULL if there is no such key.
| vKey | the key |
| ClassCastException | if the specified key cannot be compared with the keys currently in the map | |
| NullPointerException | if the specified key is NULL and this map does not permit NULL keys |
Implemented in TreeMap.
| virtual Object::View floorKey | ( | Object::View | vKey | ) | const [pure virtual] |
Returns the greatest key less than or equal to the given key, or NULL if there is no such key.
| vKey | the key |
| ClassCastException | if the specified key cannot be compared with the keys currently in the map | |
| NullPointerException | if the specified key is NULL and this map does not permit NULL keys |
Implemented in TreeMap.
| virtual Object::View higherKey | ( | Object::View | vKey | ) | const [pure virtual] |
Returns the least key strictly greater than the given key, or NULL if there is no such key.
| vKey | the key |
| ClassCastException | if the specified key cannot be compared with the keys currently in the map | |
| NullPointerException | if the specified key is NULL and this map does not permit NULL keys |
Implemented in TreeMap.
| virtual Object::View lowerKey | ( | Object::View | vKey | ) | const [pure virtual] |
Returns the greatest key strictly less than the given key, or NULL if there is no such key.
| vKey | the key |
| ClassCastException | if the specified key cannot be compared with the keys currently in the map | |
| NullPointerException | if the specified key is NULL and this map does not permit NULL keys |
Implemented in TreeMap.
| virtual Map::Entry::Holder pollFirstEntry | ( | ) | [pure virtual] |
Removes and returns a key-value mapping associated with the least key in this map, or NULL if the map is empty.
Implemented in TreeMap.
| virtual Map::Entry::Holder pollLastEntry | ( | ) | [pure virtual] |
Removes and returns a key-value mapping associated with the greatest key in this map, or NULL if the map is empty.
Implemented in TreeMap.
| virtual NavigableMap::Handle headMap | ( | Object::View | vToKey, | |
| bool | toInclusive | |||
| ) | [pure virtual] |
Returns a handle of the portion of the map whose keys are less than (or equal to, if toInclusive is true) vToKey.
The handle is backed by this map, so changes in one show up in the other. The sub-map supports all optional operations of the original.
| vToKey | the exclusive upper range of the sub-map | |
| toInclusive | true if the high endpoint is to be included in the returned view |
| ClassCastException | if vToKey is not comparable to the map contents | |
| IllegalArgumentException | if this is a sub-map, and vToKey is out of range | |
| NullPointerException | if vToKey is NULL but the map does not allow NULL keys |
Implemented in TreeMap.
| virtual NavigableMap::View headMap | ( | Object::View | vToKey, | |
| bool | toInclusive | |||
| ) | const [pure virtual] |
Returns a view of the portion of the map whose keys are less than (or equal to, if toInclusive is true) vToKey.
| vToKey | the exclusive upper range of the sub-map | |
| toInclusive | true if the high endpoint is to be included in the returned view |
| ClassCastException | if vToKey is not comparable to the map contents | |
| IllegalArgumentException | if this is a sub-map, and toKey is out of range | |
| NullPointerException | if vToKey is NULL but the map does not allow NULL keys |
Implemented in TreeMap.
| virtual NavigableMap::Handle subMap | ( | Object::View | vFromKey, | |
| bool | fromInclusive, | |||
| Object::View | vToKey, | |||
| bool | toInclusive | |||
| ) | [pure virtual] |
Returns a handle of the portion of this map whose keys range from vFromKey to vToKey.
If vFromKey and vToKey are equal, the returned map is empty unless fromInclusive and toInclusive are both true. The handle is backed by this map, so changes in one show up in the other. The sub-map supports all optional operations of the original.
| vFromKey | the inclusive lower range of the sub-map | |
| fromInclusive | true if the low endpoint is to be included in the returned view | |
| vToKey | the exclusive upper range of the sub-map | |
| toInclusive | true if the high endpoint is to be included in the returned view |
| ClassCastException | if vFromKey or vToKey is not comparable to the map contents | |
| IllegalArgumentException | if this is a sub-map, and vFromKey or vToKey is out of range | |
| NullPointerException | if vFromKey or vToKey is NULL but the map does not allow NULL keys |
Implemented in TreeMap.
| virtual NavigableMap::View subMap | ( | Object::View | vFromKey, | |
| bool | fromInclusive, | |||
| Object::View | vToKey, | |||
| bool | toInclusive | |||
| ) | const [pure virtual] |
Returns a view of the portion of this map whose keys range from vFromKey to vToKey.
If vFromKey and vToKey are equal, the returned map is empty unless fromInclusive and toInclusive are both true.
| vFromKey | the inclusive lower range of the sub-map | |
| fromInclusive | true if the low endpoint is to be included in the returned view | |
| vToKey | the exclusive upper range of the sub-map | |
| toInclusive | true if the high endpoint is to be included in the returned view |
| ClassCastException | if vFromKey or vToKey is not comparable to the map contents | |
| IllegalArgumentException | if this is a sub-map, and vFromKey or vToKey is out of range | |
| NullPointerException | if vFromKey or vToKey is NULL but the map does not allow NULL keys |
Implemented in TreeMap.
| virtual NavigableMap::Handle tailMap | ( | Object::View | vFromKey, | |
| bool | fromInclusive | |||
| ) | [pure virtual] |
Returns a handle of the portion of the map whose keys are greater than (or equal to, if fromInclusive} is true) vFromKey.
The handle is backed by this map, so changes in one show up in the other. The sub-map supports all optional operations of the original.
| vFromKey | the inclusive lower range of the sub-map | |
| fromInclusive | true if the low endpoint is to be included in the returned view |
| ClassCastException | if vFromKey is not comparable to the map contents | |
| IllegalArgumentException | if this is a sub-map, and vFromKey is out of range | |
| NullPointerException | if vFromKey is NULL but the map does not allow NULL keys |
Implemented in TreeMap.
| virtual NavigableMap::View tailMap | ( | Object::View | vFromKey, | |
| bool | fromInclusive | |||
| ) | const [pure virtual] |
Returns a view of the portion of the map whose keys are greater than (or equal to, if fromInclusive} is true) vFromKey.
| vFromKey | the inclusive lower range of the sub-map | |
| fromInclusive | true if the low endpoint is to be included in the returned view |
| ClassCastException | if vFromKey is not comparable to the map contents | |
| IllegalArgumentException | if this is a sub-map, and vFromKey is out of range | |
| NullPointerException | if vFromKey is NULL but the map does not allow NULL keys |
Implemented in TreeMap.