SortedMap (Java Platform SE 6)

キーに対して「全体順序付け」を追加提供する Map です。マップの順序付けは、キーの自然順序付けに従って行われるか、ソートマップ構築時に通常提供される Comparator を使って行われます。この順序は、ソートマップのコレクションビュー (entrySet、keySet、values メソッドによって返される) の繰り返し処理時に反映されます。その順序付けを利用するために、追加のオペレーションがいくつか提供されています。このインタフェースはマップで、SortedSet に類似しています。

ソートマップに挿入されるすべてのキーは、Comparable インタフェースを実装するか、指定されたコンパレータによって受け付けられる必要があります。さらに、各キーは「相互に比較可能」である必要があります。つまり、k1.compareTo(k2) (または comparator.compare(k1, k2)) は、ソートマップ内の任意のキー k1 と k2 に対しても ClassCastException をスローすべきではありません。この制約に違反すると、その違反側のメソッドやコンストラクタの呼び出しは ClassCastException をスローします。

あるソートマップが Map インタフェースを正しく実装するには、明示的なコンパレータが提供されているかどうかにかかわらず、そのソートマップによって維持される順序付けが「equals との一貫性」のあるものでなければいけないことに注意してください。(「equals との一貫性」の正確な定義については、Comparable インタフェースまたは Comparator インタフェースを参照)これは Map インタフェースが equals オペレーションに基づいて定義されるためですが、ソートマップはその compareTo メソッドまたは compare メソッドを使用してすべてのキー比較を実行するので、このメソッドによって等価と見なされる 2 つのキーは、ソートマップの見地からすれば同じものです。ツリーマップの動作は、その順序付けが equals と一貫性がない場合でも明確に定義されています。つまり、ツリーマップの動作は Map インタフェースの一般規約に従っていません。

汎用のソートマップ実装クラスはすべて、4 つの標準コンストラクタを提供する必要があります。1) void (引数なしの) コンストラクタ。これは、キーの自然順序付けに従ってソートされた空のソートマップを作成します。2) Comparator 型の単一引数を持つコンストラクタ。これは、指定されたコンパレータに従ってソートされた空のソートマップを作成します。3) Map 型の単一引数を持つコンストラクタ。これは、キーの自然順序付けに従ってソートされた、その引数と同じキーと値のマッピングを含む新しいマップを作成します。4) SortedMap 型の単一引数を持つコンストラクタ。これは、入力のソートマップと同一のキーと値のマッピングと順序付けとを持つ、新しいソートマップを作成します。この推奨を強制する方法はありません。なぜなら、インタフェースにはコンストラクタを含めることができないからです。

注:一部のメソッドは、制限されたキー範囲を持つサブマップを返します。そのような範囲は「片側が開いて」います。つまり、それらの範囲には、下端点は含まれますが上端点は含まれません (該当する場合)。上下端点を含む「閉じた範囲」が必要で、キーの型により直後のキーが計算可能になる場合、単に lowEndpoint ～ successor(highEndpoint) の部分範囲を指定してください。たとえば、m が、キーが文字列のマップであるとします。次の慣用法は、キーが low ～ high の範囲 (上下端点を含む) にある m 内のすべてのキーと値のマッピングを保持するビューを取得します。

   SortedMap<String, V> sub = m.subMap(low, high+"\0");

同様のテクニックを使って、上下端点のどちらも含まない「開いた範囲」を生成できます。次の慣用法は、キーが low ～ high の範囲 (上下端点を含まない) にある m 内のすべてのキーと値のマッピングを保持するビューを取得します。

   SortedMap<String, V> sub = m.subMap(low+"\0", high);

このインタフェースは、Java Collections Framework のメンバーです。

導入されたバージョン:: 1.2
関連項目:: Map, TreeMap, SortedSet, Comparator, Comparable, Collection, ClassCastException

入れ子のクラスの概要

インタフェース java.util.Map から継承された入れ子のクラス/インタフェース
`Map.Entry<K,V>`

メソッドの概要
`Comparator<? super K>`	`comparator()` このマップ内のキーを順序付けするのに使うコンパレータを返します。
`Set<Map.Entry<K,V>>`	`entrySet()` このマップに含まれるマップの `Set` ビューを返します。
`K`	`firstKey()` マップ内に現在ある最初 (下端) のキーを返します。
`SortedMap<K,V>`	`headMap(K toKey)` マップの `toKey` より小さいキーを持つ部分のビューを返します。
`Set<K>`	`keySet()` このマップに含まれるキーの `Set` ビューを返します。
`K`	`lastKey()` マップ内に現在ある最後 (上端) のキーを返します。
`SortedMap<K,V>`	`subMap(K fromKey, K toKey)` マップの `fromKey` (これを含む) ～ `toKey` (これを含まない) のキー範囲を持つ部分のビューを返します。
`SortedMap<K,V>`	`tailMap(K fromKey)` マップの `fromKey` 以上のキーを持つ部分のビューを返します。
`Collection<V>`	`values()` このマップに含まれる値の `Collection` ビューを返します。

インタフェース java.util.Map から継承されたメソッド
`clear, containsKey, containsValue, equals, get, hashCode, isEmpty, put, putAll, remove, size`

メソッドの詳細

comparator

Comparator<? super K> comparator()

このマップ内のキーを順序付けするのに使うコンパレータを返します。ただし、このマップがそのキーの自然順序付けを使う場合は null を返します。

戻り値:: このマップ内のキーを順序付けするのに使うコンパレータ。ただし、このマップがそのキーの自然順序付けを使う場合は null

subMap

SortedMap<K,V> subMap(K fromKey,
                      K toKey)

マップの fromKey (これを含む) ～ toKey (これを含まない) のキー範囲を持つ部分のビューを返します。fromKey と toKey が等しい場合は、空のマップが返されます。返されるマップはこのマップに連動しており、返されるマップでの変更はこのマップに反映され、その逆の場合も同様です。返されるマップは、このマップがサポートするオプションのマップオペレーションをすべてサポートします。

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:: fromKey - 返されるマップ内のキーの下端点 (これを含む); toKey - 返されるマップ内のキーの上端点 (これを含まない)
戻り値:: マップの fromKey (これを含む) ～ toKey (これを含まない) のキー範囲を持つ部分のビュー
例外:: ClassCastException - マップのコンパレータを使用して、fromKey と toKey を相互に比較できない場合 (または、マップに自然順序付けを使用するコンパレータがない場合)実装は、マップ内に現在存在しているキーと fromKey または toKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - fromKey または toKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - fromKey が toKey よりも大きい場合、またはこのマップ自体が制限された範囲を持っており、fromKey または toKey がその範囲の境界の外側にある場合

headMap

SortedMap<K,V> headMap(K toKey)

マップの toKey より小さいキーを持つ部分のビューを返します。返されるマップはこのマップに連動しており、返されるマップでの変更はこのマップに反映され、その逆の場合も同様です。返されるマップは、このマップがサポートするオプションのマップオペレーションをすべてサポートします。

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:: toKey - 返されるマップ内のキーの上端点 (これを含まない)
戻り値:: マップの toKey より小さいキーを持つ部分のビュー
例外:: ClassCastException - toKey がこのマップのコンパレータと互換性がない場合 (または、このマップがコンパレータを持たない場合、toKey が Comparable を実装していない場合)。実装は、マップ内に現在存在しているキーと toKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - toKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - このマップ自体が制限された範囲を持っており、toKey がその範囲の境界の外側にある場合

tailMap

SortedMap<K,V> tailMap(K fromKey)

マップの fromKey 以上のキーを持つ部分のビューを返します。返されるマップはこのマップに連動しており、返されるマップでの変更はこのマップに反映され、その逆の場合も同様です。返されるマップは、このマップがサポートするオプションのマップオペレーションをすべてサポートします。

返されるマップは、その範囲外のキーが挿入されようとすると、IllegalArgumentException をスローします。

パラメータ:: fromKey - 返されるマップ内のキーの下端点 (これを含む)
戻り値:: マップの fromKey 以上のキーを持つ部分のビュー
例外:: ClassCastException - fromKey がこのマップのコンパレータと互換性がない場合 (または、このマップがコンパレータを持たない場合、fromKey が Comparable を実装していない場合)。実装は、マップ内に現在存在しているキーと fromKey とを比較できない場合にこの例外をスローすることができる。ただし、必須ではない; NullPointerException - fromKey が null であり、このマップが null キーを許可しない場合; IllegalArgumentException - このマップ自体が制限された範囲を持っており、fromKey がその範囲の境界の外側にある場合

firstKey

K firstKey()

マップ内に現在ある最初 (下端) のキーを返します。

戻り値:: マップ内に現在ある最初 (下端) のキー
例外:: NoSuchElementException - マップが空の場合

lastKey

K lastKey()

マップ内に現在ある最後 (上端) のキーを返します。

戻り値:: マップ内に現在ある最後 (上端) のキー
例外:: NoSuchElementException - マップが空の場合

keySet

Set<K> keySet()

このマップに含まれるキーの Set ビューを返します。セットの反復子は、キーを昇順で返します。セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。セットの反復処理中にマップが変更された場合、反復処理の結果は定義されません (反復子自身の remove オペレーションを除く)。セットは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Set.remove、removeAll、retainAll、および retainAll オペレーションを通して行います。Set は、add オペレーションや addAll オペレーションはサポートしていません。

定義:: インタフェース Map<K,V> 内の keySet

戻り値:: マップに含まれているキーの、昇順にソートされたセットビュー

values

Collection<V> values()

このマップに含まれる値の Collection ビューを返します。コレクションの反復子は、値を対応するキーの昇順で返します。コレクションはマップと連動しているので、マップに対する変更はコレクションに反映され、またコレクションに対する変更はマップに反映されます。コレクションの反復処理中にマップが変更された場合、反復処理の結果は定義されません (反復子自身の remove オペレーションを除く)。コレクションは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Collection.remove、removeAll、retainAll、および clear オペレーションを通して行います。コレクションは、add オペレーションや addAll オペレーションはサポートしていません。

定義:: インタフェース Map<K,V> 内の values

戻り値:: マップに含まれている値の、キーの昇順にソートされたコレクションビュー

entrySet

Set<Map.Entry<K,V>> entrySet()

このマップに含まれるマップの Set ビューを返します。セットの反復子は、エントリをキーの昇順で返します。セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。セットに対する反復の処理中にマップが変更された場合は、反復処理の結果は定義されません (反復子自身の remove オペレーション、または反復子により返されるマップエントリに対する setValue オペレーションを除く)。セットは、要素の削除をサポートしており、対応するマッピングをマップから削除できます。セットは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Set.remove、removeAll、retainAll、および clear の各オペレーションを通して行います。Set は、add オペレーションや addAll オペレーションはサポートしていません。