ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/TreeSet.java

Comparing jsr166/src/main/java/util/TreeSet.java (file contents):
Revision 1.19 by jsr166, Mon Dec 5 02:56:59 2005 UTC vs.
Revision 1.26 by jsr166, Sun May 20 07:54:01 2007 UTC

#	Line 1 | Line 1
1		/*
2	<	* %W% %E%
2	>	* Copyright 1998-2006 Sun Microsystems, Inc.  All Rights Reserved.
3	>	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4		*
5	<	* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
6	<	* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
5	>	* This code is free software; you can redistribute it and/or modify it
6	>	* under the terms of the GNU General Public License version 2 only, as
7	>	* published by the Free Software Foundation.  Sun designates this
8	>	* particular file as subject to the "Classpath" exception as provided
9	>	* by Sun in the LICENSE file that accompanied this code.
10	>	*
11	>	* This code is distributed in the hope that it will be useful, but WITHOUT
12	>	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13	>	* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14	>	* version 2 for more details (a copy is included in the LICENSE file that
15	>	* accompanied this code).
16	>	*
17	>	* You should have received a copy of the GNU General Public License version
18	>	* 2 along with this work; if not, write to the Free Software Foundation,
19	>	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20	>	*
21	>	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22	>	* CA 95054 USA or visit www.sun.com if you need additional information or
23	>	* have any questions.
24		*/
25
26		package java.util;
9	–	import java.util.*; // for javadoc (till 6280605 is fixed)
27
28		/**
29		* A {@link NavigableSet} implementation based on a {@link TreeMap}.
#	Line 15 | Line 32 | import java.util.*; // for javadoc (till
32		* time, depending on which constructor is used.
33		*
34		* <p>This implementation provides guaranteed log(n) time cost for the basic
35	<	* operations (<tt>add</tt>, <tt>remove</tt> and <tt>contains</tt>).
35	>	* operations ({@code add}, {@code remove} and {@code contains}).
36		*
37		* <p>Note that the ordering maintained by a set (whether or not an explicit
38		* comparator is provided) must be <i>consistent with equals</i> if it is to
39	<	* correctly implement the <tt>Set</tt> interface.  (See <tt>Comparable</tt>
40	<	* or <tt>Comparator</tt> for a precise definition of <i>consistent with
41	<	* equals</i>.)  This is so because the <tt>Set</tt> interface is defined in
42	<	* terms of the <tt>equals</tt> operation, but a <tt>TreeSet</tt> instance
43	<	* performs all element comparisons using its <tt>compareTo</tt> (or
44	<	* <tt>compare</tt>) method, so two elements that are deemed equal by this method
39	>	* correctly implement the {@code Set} interface.  (See {@code Comparable}
40	>	* or {@code Comparator} for a precise definition of <i>consistent with
41	>	* equals</i>.)  This is so because the {@code Set} interface is defined in
42	>	* terms of the {@code equals} operation, but a {@code TreeSet} instance
43	>	* performs all element comparisons using its {@code compareTo} (or
44	>	* {@code compare}) method, so two elements that are deemed equal by this method
45		* are, from the standpoint of the set, equal.  The behavior of a set
46		* <i>is</i> well-defined even if its ordering is inconsistent with equals; it
47	<	* just fails to obey the general contract of the <tt>Set</tt> interface.
47	>	* just fails to obey the general contract of the {@code Set} interface.
48		*
49		* <p><strong>Note that this implementation is not synchronized.</strong>
50		* If multiple threads access a tree set concurrently, and at least one
#	Line 40 | Line 57 | import java.util.*; // for javadoc (till
57		* unsynchronized access to the set: <pre>
58		*   SortedSet s = Collections.synchronizedSortedSet(new TreeSet(...));</pre>
59		*
60	<	* <p>The iterators returned by this class's <tt>iterator</tt> method are
60	>	* <p>The iterators returned by this class's {@code iterator} method are
61		* <i>fail-fast</i>: if the set is modified at any time after the iterator is
62	<	* created, in any way except through the iterator's own <tt>remove</tt>
62	>	* created, in any way except through the iterator's own {@code remove}
63		* method, the iterator will throw a {@link ConcurrentModificationException}.
64		* Thus, in the face of concurrent modification, the iterator fails quickly
65		* and cleanly, rather than risking arbitrary, non-deterministic behavior at
#	Line 51 | Line 68 | import java.util.*; // for javadoc (till
68		* <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
69		* as it is, generally speaking, impossible to make any hard guarantees in the
70		* presence of unsynchronized concurrent modification.  Fail-fast iterators
71	<	* throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
71	>	* throw {@code ConcurrentModificationException} on a best-effort basis.
72		* Therefore, it would be wrong to write a program that depended on this
73		* exception for its correctness:   <i>the fail-fast behavior of iterators
74		* should be used only to detect bugs.</i>
75		*
76		* <p>This class is a member of the
77	<	* <a href="{@docRoot}/../guide/collections/index.html">
77	>	* <a href="{@docRoot}/../technotes/guides/collections/index.html">
78		* Java Collections Framework</a>.
79		*
80		* @param <E> the type of elements maintained by this set
#	Line 73 | Line 90 | import java.util.*; // for javadoc (till
90		* @since   1.2
91		*/
92
93	<	public class TreeSet<E>
77	<	extends AbstractSet<E>
93	>	public class TreeSet<E> extends AbstractSet<E>
94		implements NavigableSet<E>, Cloneable, java.io.Serializable
95		{
96	<	private transient NavigableMap<E,Object> m; // The backing Map
96	>	/**
97	>	* The backing map.
98	>	*/
99	>	private transient NavigableMap<E,Object> m;
100
101		// Dummy value to associate with an Object in the backing Map
102		private static final Object PRESENT = new Object();
#	Line 85 | Line 104 | public class TreeSet<E>
104		/**
105		* Constructs a set backed by the specified navigable map.
106		*/
107	<	private TreeSet(NavigableMap<E,Object> m) {
107	>	TreeSet(NavigableMap<E,Object> m) {
108		this.m = m;
109		}
110
#	Line 94 | Line 113 | public class TreeSet<E>
113		* natural ordering of its elements.  All elements inserted into
114		* the set must implement the {@link Comparable} interface.
115		* Furthermore, all such elements must be <i>mutually
116	<	* comparable</i>: <tt>e1.compareTo(e2)</tt> must not throw a
117	<	* <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
118	<	* <tt>e2</tt> in the set.  If the user attempts to add an element
116	>	* comparable</i>: {@code e1.compareTo(e2)} must not throw a
117	>	* {@code ClassCastException} for any elements {@code e1} and
118	>	* {@code e2} in the set.  If the user attempts to add an element
119		* to the set that violates this constraint (for example, the user
120		* attempts to add a string element to a set whose elements are
121	<	* integers), the <tt>add(Object)</tt> call will throw a
122	<	* <tt>ClassCastException</tt>.
121	>	* integers), the {@code add} call will throw a
122	>	* {@code ClassCastException}.
123		*/
124		public TreeSet() {
125		this(new TreeMap<E,Object>());
#	Line 109 | Line 128 | public class TreeSet<E>
128		/**
129		* Constructs a new, empty tree set, sorted according to the specified
130		* comparator.  All elements inserted into the set must be <i>mutually
131	<	* comparable</i> by the specified comparator: <tt>comparator.compare(e1,
132	<	* e2)</tt> must not throw a <tt>ClassCastException</tt> for any elements
133	<	* <tt>e1</tt> and <tt>e2</tt> in the set.  If the user attempts to add
131	>	* comparable</i> by the specified comparator: {@code comparator.compare(e1,
132	>	* e2)} must not throw a {@code ClassCastException} for any elements
133	>	* {@code e1} and {@code e2} in the set.  If the user attempts to add
134		* an element to the set that violates this constraint, the
135	<	* <tt>add(Object)</tt> call will throw a <tt>ClassCastException</tt>.
135	>	* {@code add} call will throw a {@code ClassCastException}.
136		*
137		* @param comparator the comparator that will be used to order this set.
138	<	*        If <tt>null</tt>, the {@linkplain Comparable natural
138	>	*        If {@code null}, the {@linkplain Comparable natural
139		*        ordering} of the elements will be used.
140		*/
141		public TreeSet(Comparator<? super E> comparator) {
#	Line 128 | Line 147 | public class TreeSet<E>
147		* collection, sorted according to the <i>natural ordering</i> of its
148		* elements.  All elements inserted into the set must implement the
149		* {@link Comparable} interface.  Furthermore, all such elements must be
150	<	* <i>mutually comparable</i>: <tt>e1.compareTo(e2)</tt> must not throw a
151	<	* <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
152	<	* <tt>e2</tt> in the set.
150	>	* <i>mutually comparable</i>: {@code e1.compareTo(e2)} must not throw a
151	>	* {@code ClassCastException} for any elements {@code e1} and
152	>	* {@code e2} in the set.
153		*
154		* @param c collection whose elements will comprise the new set
155	<	* @throws ClassCastException if the elements in <tt>c</tt> are
155	>	* @throws ClassCastException if the elements in {@code c} are
156		*         not {@link Comparable}, or are not mutually comparable
157		* @throws NullPointerException if the specified collection is null
158		*/
#	Line 160 | Line 179 | public class TreeSet<E>
179		* @return an iterator over the elements in this set in ascending order
180		*/
181		public Iterator<E> iterator() {
182	<	return m.keySet().iterator();
182	>	return m.navigableKeySet().iterator();
183		}
184
185		/**
#	Line 174 | Line 193 | public class TreeSet<E>
193		}
194
195		/**
196	+	* @since 1.6
197	+	*/
198	+	public NavigableSet<E> descendingSet() {
199	+	return new TreeSet(m.descendingMap());
200	+	}
201	+
202	+	/**
203		* Returns the number of elements in this set (its cardinality).
204		*
205		* @return the number of elements in this set (its cardinality)
#	Line 183 | Line 209 | public class TreeSet<E>
209		}
210
211		/**
212	<	* Returns <tt>true</tt> if this set contains no elements.
212	>	* Returns {@code true} if this set contains no elements.
213		*
214	<	* @return <tt>true</tt> if this set contains no elements
214	>	* @return {@code true} if this set contains no elements
215		*/
216		public boolean isEmpty() {
217		return m.isEmpty();
218		}
219
220		/**
221	<	* Returns <tt>true</tt> if this set contains the specified element.
222	<	* More formally, returns <tt>true</tt> if and only if this set
223	<	* contains an element <tt>e</tt> such that
221	>	* Returns {@code true} if this set contains the specified element.
222	>	* More formally, returns {@code true} if and only if this set
223	>	* contains an element {@code e} such that
224		* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
225		*
226		* @param o object to be checked for containment in this set
227	<	* @return <tt>true</tt> if this set contains the specified element
227	>	* @return {@code true} if this set contains the specified element
228		* @throws ClassCastException if the specified object cannot be compared
229		*         with the elements currently in the set
230		* @throws NullPointerException if the specified element is null
#	Line 211 | Line 237 | public class TreeSet<E>
237
238		/**
239		* Adds the specified element to this set if it is not already present.
240	<	* More formally, adds the specified element <tt>e</tt> to this set if
241	<	* the set contains no element <tt>e2</tt> such that
240	>	* More formally, adds the specified element {@code e} to this set if
241	>	* the set contains no element {@code e2} such that
242		* <tt>(e==null&nbsp;?&nbsp;e2==null&nbsp;:&nbsp;e.equals(e2))</tt>.
243		* If this set already contains the element, the call leaves the set
244	<	* unchanged and returns <tt>false</tt>.
244	>	* unchanged and returns {@code false}.
245		*
246		* @param e element to be added to this set
247	<	* @return <tt>true</tt> if this set did not already contain the specified
247	>	* @return {@code true} if this set did not already contain the specified
248		*         element
249		* @throws ClassCastException if the specified object cannot be compared
250		*         with the elements currently in this set
#	Line 232 | Line 258 | public class TreeSet<E>
258
259		/**
260		* Removes the specified element from this set if it is present.
261	<	* More formally, removes an element <tt>e</tt> such that
261	>	* More formally, removes an element {@code e} such that
262		* <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>,
263	<	* if this set contains such an element.  Returns <tt>true</tt> if
263	>	* if this set contains such an element.  Returns {@code true} if
264		* this set contained the element (or equivalently, if this set
265		* changed as a result of the call).  (This set will not contain the
266		* element once the call returns.)
267		*
268		* @param o object to be removed from this set, if present
269	<	* @return <tt>true</tt> if this set contained the specified element
269	>	* @return {@code true} if this set contained the specified element
270		* @throws ClassCastException if the specified object cannot be compared
271		*         with the elements currently in this set
272		* @throws NullPointerException if the specified element is null
#	Line 263 | Line 289 | public class TreeSet<E>
289		* Adds all of the elements in the specified collection to this set.
290		*
291		* @param c collection containing elements to be added to this set
292	<	* @return <tt>true</tt> if this set changed as a result of the call
292	>	* @return {@code true} if this set changed as a result of the call
293		* @throws ClassCastException if the elements provided cannot be compared
294		*         with the elements currently in the set
295		* @throws NullPointerException if the specified collection is null or
#	Line 289 | Line 315 | public class TreeSet<E>
315
316		/**
317		* @throws ClassCastException {@inheritDoc}
318	<	* @throws NullPointerException if <tt>fromElement</tt> or
319	<	*         <tt>toElement</tt> is null and this set uses natural ordering,
320	<	*         or its comparator does not permit null elements
318	>	* @throws NullPointerException if {@code fromElement} or {@code toElement}
319	>	*         is null and this set uses natural ordering, or its comparator
320	>	*         does not permit null elements
321		* @throws IllegalArgumentException {@inheritDoc}
322		* @since 1.6
323		*/
324	<	public NavigableSet<E> navigableSubSet(E fromElement, E toElement) {
325	<	return new TreeSet<E>(m.navigableSubMap(fromElement, toElement));
324	>	public NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
325	>	E toElement,   boolean toInclusive) {
326	>	return new TreeSet<E>(m.subMap(fromElement, fromInclusive,
327	>	toElement,   toInclusive));
328		}
329
330		/**
331		* @throws ClassCastException {@inheritDoc}
332	<	* @throws NullPointerException if <tt>toElement</tt> is null and
332	>	* @throws NullPointerException if {@code toElement} is null and
333		*         this set uses natural ordering, or its comparator does
334		*         not permit null elements
335		* @throws IllegalArgumentException {@inheritDoc}
336		* @since 1.6
337		*/
338	<	public NavigableSet<E> navigableHeadSet(E toElement) {
339	<	return new TreeSet<E>(m.navigableHeadMap(toElement));
338	>	public NavigableSet<E> headSet(E toElement, boolean inclusive) {
339	>	return new TreeSet<E>(m.headMap(toElement, inclusive));
340		}
341
342		/**
343		* @throws ClassCastException {@inheritDoc}
344	<	* @throws NullPointerException if <tt>fromElement</tt> is null and
344	>	* @throws NullPointerException if {@code fromElement} is null and
345		*         this set uses natural ordering, or its comparator does
346		*         not permit null elements
347		* @throws IllegalArgumentException {@inheritDoc}
348		* @since 1.6
349		*/
350	<	public NavigableSet<E> navigableTailSet(E fromElement) {
351	<	return new TreeSet<E>(m.navigableTailMap(fromElement));
350	>	public NavigableSet<E> tailSet(E fromElement, boolean inclusive) {
351	>	return new TreeSet<E>(m.tailMap(fromElement, inclusive));
352		}
353
354		/**
327	–	* Equivalent to {@link #navigableSubSet} but with a return type
328	–	* conforming to the <tt>SortedSet</tt> interface.
329	–	*
330	–	* <p>{@inheritDoc}
331	–	*
355		* @throws ClassCastException {@inheritDoc}
356	<	* @throws NullPointerException if <tt>fromElement</tt> or
357	<	*         <tt>toElement</tt> is null and this set uses natural ordering,
356	>	* @throws NullPointerException if {@code fromElement} or
357	>	*         {@code toElement} is null and this set uses natural ordering,
358		*         or its comparator does not permit null elements
359		* @throws IllegalArgumentException {@inheritDoc}
360		*/
361		public SortedSet<E> subSet(E fromElement, E toElement) {
362	<	return new TreeSet<E>(m.navigableSubMap(fromElement, toElement));
362	>	return subSet(fromElement, true, toElement, false);
363		}
364
365		/**
343	–	* Equivalent to {@link #navigableHeadSet} but with a return type
344	–	* conforming to the <tt>SortedSet</tt> interface.
345	–	*
346	–	* <p>{@inheritDoc}
347	–	*
366		* @throws ClassCastException {@inheritDoc}
367	<	* @throws NullPointerException if <tt>toElement</tt> is null
367	>	* @throws NullPointerException if {@code toElement} is null
368		*         and this set uses natural ordering, or its comparator does
369		*         not permit null elements
370		* @throws IllegalArgumentException {@inheritDoc}
371		*/
372		public SortedSet<E> headSet(E toElement) {
373	<	return new TreeSet<E>(m.navigableHeadMap(toElement));
373	>	return headSet(toElement, false);
374		}
375
376		/**
359	–	* Equivalent to {@link #navigableTailSet} but with a return type
360	–	* conforming to the <tt>SortedSet</tt> interface.
361	–	*
362	–	* <p>{@inheritDoc}
363	–	*
377		* @throws ClassCastException {@inheritDoc}
378	<	* @throws NullPointerException if <tt>fromElement</tt> is null
378	>	* @throws NullPointerException if {@code fromElement} is null
379		*         and this set uses natural ordering, or its comparator does
380		*         not permit null elements
381		* @throws IllegalArgumentException {@inheritDoc}
382		*/
383		public SortedSet<E> tailSet(E fromElement) {
384	<	return new TreeSet<E>(m.navigableTailMap(fromElement));
384	>	return tailSet(fromElement, true);
385		}
386
387		public Comparator<? super E> comparator() {
#	Line 452 | Line 465 | public class TreeSet<E>
465		}
466
467		/**
468	<	* Returns a shallow copy of this <tt>TreeSet</tt> instance. (The elements
468	>	* Returns a shallow copy of this {@code TreeSet} instance. (The elements
469		* themselves are not cloned.)
470		*
471		* @return a shallow copy of this set
#	Line 466 | Line 479 | public class TreeSet<E>
479		}
480
481		clone.m = new TreeMap<E,Object>(m);
469	–
482		return clone;
483		}
484
485		/**
486	<	* Save the state of the <tt>TreeSet</tt> instance to a stream (that is,
486	>	* Save the state of the {@code TreeSet} instance to a stream (that is,
487		* serialize it).
488		*
489		* @serialData Emits the comparator used to order this set, or
490	<	*             <tt>null</tt> if it obeys its elements' natural ordering
490	>	*             {@code null} if it obeys its elements' natural ordering
491		*             (Object), followed by the size of the set (the number of
492		*             elements it contains) (int), followed by all of its
493		*             elements (each an Object) in order (as determined by the
#	Line 499 | Line 511 | public class TreeSet<E>
511		}
512
513		/**
514	<	* Reconstitute the <tt>TreeSet</tt> instance from a stream (that is,
514	>	* Reconstitute the {@code TreeSet} instance from a stream (that is,
515		* deserialize it).
516		*/
517		private void readObject(java.io.ObjectInputStream s)

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines