1 dojo.provide("calitha.collections.INavigableMap");
  2 dojo.require("calitha.collections.ISortedMap");
  3 dojo.require("calitha.exception.VirtualFunctionException");
  4 
  5 /**
  6  * @name calitha.collections.INavigableMap
  7  * @class A SortedMap extended with navigation methods returning the closest matches for given search targets.
  8  * <p>
  9  * It is based on the
 10  * <a href="http://java.sun.com/javase/6/docs/api/java/util/NavigableMap.html">Java NavigableMap interface</a>.
 11  * Differences are:
 12  * <p>
 13  * <ul>
 14  * <li>In Java it is the NavigableMap interface that has methods with extra inclusive parameters for subMap and such.
 15  * Those methods have been put in this ISortedMap class to replace those same methods without the inclusive parameters.
 16  * This is done because overloading methods with inheritance too would be too confusing. And the methods with inclusive
 17  * parameters are more clear anyway.
 18  * </ul>
 19  * @extends calitha.collections.ISortedMap
 20  */
 21 dojo.declare("calitha.collections.INavigableMap", calitha.collections.ISortedMap,
 22 /** @lends calitha.collections.INavigableMap# */
 23 {
 24     /**
 25      * @function
 26      * @param key the key 
 27      * @returns {calitha.collections.imap.IEntry} an entry with the least key greater than or equal to key, or null if there is no such key 
 28      * @description Returns a key-value mapping associated with the least key greater than or equal to the given key,
 29      * or null if there is no such key.
 30      */
 31     ceilingEntry: function(/**Object*/ key)
 32     {throw new calitha.exception.VirtualFunctionException(Error());}
 33     ,
 34     /**
 35      * @function
 36      * @param key the key
 37      * @returns {calitha.collections.imap.IEntry} the least key greater than or equal to key, or null if there is no such key
 38      * @description Returns the least key greater than or equal to the given key, or null if there is no such key.
 39      */
 40     ceilingKey: function(/**Object*/ key)
 41     {throw new calitha.exception.VirtualFunctionException(Error());}
 42     ,
 43     /**
 44      * @function
 45      * @returns {calitha.collections.INavigableSet} a reverse order navigable set view of the keys in this map
 46      * @description Returns a reverse order NavigableSet view of the keys contained in this map.
 47      */
 48     descendingKeySet: function()
 49     {throw new calitha.exception.VirtualFunctionException(Error());}
 50     ,
 51     /**
 52      * @function
 53      * @returns {calitha.collections.INavigableMap} a reverse order view of this map
 54      * @description Returns a reverse order view of the mappings contained in this map.
 55      */
 56     descendingMap: function()
 57     {throw new calitha.exception.VirtualFunctionException(Error());}
 58     ,
 59     /**
 60      * @function
 61      * @returns {calitha.collections.imap.IEntry} an entry with the least key, or null if this map is empty
 62      * @description Returns a key-value mapping associated with the least key in this map, or null if the map is empty.
 63      */
 64     firstEntry: function()
 65     {throw new calitha.exception.VirtualFunctionException(Error());}
 66     ,
 67     /**
 68      * @function
 69      * @param key the key 
 70      * @returns {calitha.collections.imap.IEntry} an entry with the greatest key less than or equal to key, or null if there is no such key
 71      * @description Returns a key-value mapping associated with the greatest key less than or equal to the given key,
 72      * or null if there is no such key.
 73      */
 74     floorEntry: function(/**Object*/ key)
 75     {throw new calitha.exception.VirtualFunctionException(Error());}
 76     ,
 77     /**
 78      * @function
 79      * @param key the key
 80      * @returns {Object} the greatest key less than or equal to key, or null if there is no such key 
 81      * @description Returns the greatest key less than or equal to the given key, or null if there is no such key.
 82      */
 83     floorKey: function(/**Object*/ key)
 84     {throw new calitha.exception.VirtualFunctionException(Error());}
 85     ,
 86     /**
 87      * @function
 88      * @param key the key 
 89      * @returns {calitha.collections.imap.IEntry} an entry with the least key greater than key, or null if there is no such key
 90      * @description Returns a key-value mapping associated with the least key strictly greater than the given key,
 91      * or null if there is no such key.
 92      */
 93     higherEntry: function(/**Object*/ key)
 94     {throw new calitha.exception.VirtualFunctionException(Error());}
 95     ,
 96     /**
 97      * @function
 98      * @param key the key 
 99      * @returns {Object} the least key greater than key, or null if there is no such key
100      * @description Returns the least key strictly greater than the given key, or null if there is no such key.
101      */
102     higherKey: function(/**Object*/ key)
103     {throw new calitha.exception.VirtualFunctionException(Error());}
104     ,
105     /**
106      * @function
107      * @returns {calitha.collections.imap.IEntry} an entry with the greatest key, or null if this map is empty
108      * @description Returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.
109      */
110     lastEntry: function()
111     {throw new calitha.exception.VirtualFunctionException(Error());}
112     ,
113     /**
114      * @function
115      * @param key the key
116      * @returns {calitha.collections.imap.IEntry} an entry with the greatest key less than key, or null if there is no such key 
117      * @description Returns a key-value mapping associated with the greatest key strictly less than the given key,
118      * or null if there is no such key.
119      */
120     lowerEntry: function(/**Object*/ key)
121     {throw new calitha.exception.VirtualFunctionException(Error());}
122     ,
123     /**
124      * @function
125      * @param key the key
126      * @returns {Object} the greatest key less than key, or null if there is no such key
127      * @description Returns the greatest key strictly less than the given key, or null if there is no such key.
128      */
129     lowerKey: function(/**Object*/ key)
130     {throw new calitha.exception.VirtualFunctionException(Error());}
131     ,
132     /**
133      * @function
134      * @returns {calitha.collections.INavigableSet} a navigable set view of the keys in this map
135      * @description Returns a NavigableSet view of the keys contained in this map.
136      */
137     navigableKeySet: function()
138     {throw new calitha.exception.VirtualFunctionException(Error());}
139     ,
140     /**
141      * @function
142      * @returns {calitha.collections.imap.IEntry} the removed first entry of this map, or null if this map is empty
143      * @description Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty.
144      */
145     pollFirstEntry: function()
146     {throw new calitha.exception.VirtualFunctionException(Error());}
147     ,
148     /**
149      * @function
150      * @returns {calitha.collections.imap.IEntry} the removed last entry of this map, or null if this map is empty
151      * @description Removes and returns a key-value mapping associated with the greatest key in this map,
152      * or null if the map is empty.
153      */
154     pollLastEntry: function()
155     {throw new calitha.exception.VirtualFunctionException(Error());}
156 });
157