1 dojo.provide("calitha.collections.ISortedMap");
  2 dojo.require("calitha.collections.IMap");
  3 dojo.require("calitha.exception.VirtualFunctionException");
  4 
  5 /**
  6  * @name calitha.collections.ISortedMap
  7  * @class A Map that further provides a total ordering on its keys.
  8  * <p>
  9  * It is based on the
 10  * <a href="http://java.sun.com/javase/6/docs/api/java/util/SortedMap.html">Java SortedMap 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.IMap
 20  */
 21 dojo.declare("calitha.collections.ISortedMap", calitha.collections.IMap,
 22 /** @lends calitha.collections.ISortedMap# */
 23 {
 24     /**
 25      * @function
 26      * @returns {calitha.collections.IComparator} the comparator used to order the keys in this map,
 27      * or null if this map uses the natural ordering of its keys
 28      * @description  Returns the comparator used to order the keys in this map, or null if this map uses the natural ordering of its keys.
 29      */
 30     comparator: function()
 31     {throw new calitha.exception.VirtualFunctionException(Error());}
 32     ,
 33     /**
 34      * @function
 35      * @returns {Object} the first (lowest) key currently in this map
 36      * @description Returns the first (lowest) key currently in this map.
 37      */
 38     firstKey: function()
 39     {throw new calitha.exception.VirtualFunctionException(Error());}
 40     ,
 41     /**
 42      * @function
 43      * @param toKey high endpoint of the keys in the returned map
 44      * @param inclusive true if the high endpoint is to be included in the returned view 
 45      * @returns {calitha.collections.ISortedMap} a view of the portion of this map whose keys are less than
 46      * (or equal to, if inclusive is true) toKey
 47      * @description Returns a view of the portion of this map whose keys are less than (or equal to, if inclusive is true) toKey.
 48      */
 49     headMap: function(/**Object*/ toKey, /**Boolean*/ inclusive)
 50     {throw new calitha.exception.VirtualFunctionException(Error());}
 51     ,
 52     /**
 53      * @function
 54      * @returns {Object} the last (highest) key currently in this map
 55      * @description Returns the last (highest) key currently in this map.
 56      */
 57     lastKey: function()
 58     {throw new calitha.exception.VirtualFunctionException(Error());}
 59     ,
 60     /**
 61      * @function
 62      * @param fromKey low endpoint (inclusive) of the keys in the returned map
 63      * @param fromInclusive true if the low endpoint is to be included in the returned view
 64      * @param toKey high endpoint of the keys in the returned map
 65      * @param toInclusive true if the high endpoint is to be included in the returned view 
 66      * @returns {calitha.collections.ISortedMap} a view of the portion of this map whose keys range from fromKey to toKey
 67      * @description Returns a view of the portion of this map whose keys range from fromKey to toKey.
 68      */
 69     subMap: function(/**Object*/ fromKey, /**Boolean*/ fromInclusive, /**Object*/ toKey, /**Boolean*/ toInclusive)
 70     {throw new calitha.exception.VirtualFunctionException(Error());}
 71     ,
 72     /**
 73      * @function
 74      * @param fromKey low endpoint of the keys in the returned map
 75      * @param inclusive true if the low endpoint is to be included in the returned view
 76      * @returns {calitha.collections.ISortedMap} a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) fromKey
 77      * @description Returns a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) fromKey.
 78      */
 79     tailMap: function(/**Object*/ fromKey, /**Boolean*/ inclusive)
 80     {throw new calitha.exception.VirtualFunctionException(Error());}
 81 });
 82