libjava/java/util/SortedMap.java

   1 /* SortedMap.java -- A map that makes guarantees about the order of its keys
   2    Copyright (C) 1998, 2001 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.util;
  40
  41 /**
  42  * A map which guarantees its key's iteration order. The entries in the
  43  * map are related by the <i>natural ordering</i> of the keys if they
  44  * are Comparable, or by the provided Comparator.  Additional operations
  45  * take advantage of the sorted nature of the map.
  46  * <p>
  47  *
  48  * All keys entered in the map must be mutually comparable; in other words,
  49  * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
  50  * must not throw a ClassCastException. The ordering must be <i>consistent
  51  * with equals</i> (see {@link Comparator} for this definition), if the
  52  * map is to obey the general contract of the Map interface.  If not,
  53  * the results are well-defined, but probably not what you wanted.
  54  * <p>
  55  *
  56  * It is recommended that all implementing classes provide four constructors:
  57  * 1) one that takes no arguments and builds an empty map sorted by natural
  58  * order of the keys; 2) one that takes a Comparator for the sorting order;
  59  * 3) one that takes a Map and sorts according to the natural order of its
  60  * keys; and 4) one that takes a SortedMap and sorts by the same comparator.
  61  * Unfortunately, the Java language does not provide a way to enforce this.
  62  *
  63  * @author Original author unknown
  64  * @author Eric Blake <ebb9@email.byu.edu>
  65  * @see Map
  66  * @see TreeMap
  67  * @see SortedSet
  68  * @see Comparable
  69  * @see Comparator
  70  * @see Collection
  71  * @see ClassCastException
  72  * @since 1.2
  73  * @status updated to 1.4
  74  */
  75 public interface SortedMap extends Map
  76 {
  77   /**
  78    * Returns the comparator used in sorting this map, or null if it is
  79    * the keys' natural ordering.
  80    *
  81    * @return the sorting comparator
  82    */
  83   Comparator comparator();
  84
  85   /**
  86    * Returns the first (lowest sorted) key in the map.
  87    *
  88    * @return the first key
  89    */
  90   Object firstKey();
  91
  92   /**
  93    * Returns a view of the portion of the map strictly less than toKey. The
  94    * view is backed by this map, so changes in one show up in the other.
  95    * The submap supports all optional operations of the original.
  96    * <p>
  97    *
  98    * The returned map throws an IllegalArgumentException any time a key is
  99    * used which is out of the range of toKey. Note that the endpoint is not
 100    * included; if you want the endpoint, pass the successor object in to
 101    * toKey.  For example, for Strings, you can request
 102    * <code>headMap(limit + "\0")</code>.
 103    *
 104    * @param toKey the exclusive upper range of the submap
 105    * @return the submap
 106    * @throws ClassCastException if toKey is not comparable to the map contents
 107    * @throws IllegalArgumentException if this is a subMap, and toKey is out
 108    *         of range
 109    * @throws NullPointerException if toKey is null but the map does not allow
 110    *         null keys
 111    */
 112   SortedMap headMap(Object toKey);
 113
 114   /**
 115    * Returns the last (highest sorted) key in the map.
 116    *
 117    * @return the last key
 118    */
 119   Object lastKey();
 120
 121   /**
 122    * Returns a view of the portion of the map greater than or equal to
 123    * fromKey, and strictly less than toKey. The view is backed by this map,
 124    * so changes in one show up in the other. The submap supports all
 125    * optional operations of the original.
 126    * <p>
 127    *
 128    * The returned map throws an IllegalArgumentException any time a key is
 129    * used which is out of the range of fromKey and toKey. Note that the
 130    * lower endpoint is included, but the upper is not; if you want to
 131    * change the inclusion or exclusion of an endpoint, pass the successor
 132    * object in instead.  For example, for Strings, you can request
 133    * <code>subMap(lowlimit + "\0", highlimit + "\0")</code> to reverse
 134    * the inclusiveness of both endpoints.
 135    *
 136    * @param fromKey the inclusive lower range of the submap
 137    * @param toKey the exclusive upper range of the submap
 138    * @return the submap
 139    * @throws ClassCastException if fromKey or toKey is not comparable to
 140    *         the map contents
 141    * @throws IllegalArgumentException if this is a subMap, and fromKey or
 142    *         toKey is out of range
 143    * @throws NullPointerException if fromKey or toKey is null but the map
 144    *         does not allow null keys
 145    */
 146   SortedMap subMap(Object fromKey, Object toKey);
 147
 148   /**
 149    * Returns a view of the portion of the map greater than or equal to
 150    * fromKey. The view is backed by this map, so changes in one show up
 151    * in the other. The submap supports all optional operations of the original.
 152    * <p>
 153    *
 154    * The returned map throws an IllegalArgumentException any time a key is
 155    * used which is out of the range of fromKey. Note that the endpoint is
 156    * included; if you do not want the endpoint, pass the successor object in
 157    * to fromKey.  For example, for Strings, you can request
 158    * <code>tailMap(limit + "\0")</code>.
 159    *
 160    * @param fromKey the inclusive lower range of the submap
 161    * @return the submap
 162    * @throws ClassCastException if fromKey is not comparable to the map
 163    *         contents
 164    * @throws IllegalArgumentException if this is a subMap, and fromKey is out
 165    *         of range
 166    * @throws NullPointerException if fromKey is null but the map does not allow
 167    *         null keys
 168    */
 169   SortedMap tailMap(Object fromKey);
 170 }