< prev index next >
src/java.base/share/classes/java/util/Collections.java
Print this page
*** 42,70 ****
* This class consists exclusively of static methods that operate on or return
* collections. It contains polymorphic algorithms that operate on
* collections, "wrappers", which return a new collection backed by a
* specified collection, and a few other odds and ends.
*
! * <p>The methods of this class all throw a <tt>NullPointerException</tt>
* if the collections or class objects provided to them are null.
*
* <p>The documentation for the polymorphic algorithms contained in this class
* generally includes a brief description of the <i>implementation</i>. Such
* descriptions should be regarded as <i>implementation notes</i>, rather than
* parts of the <i>specification</i>. Implementors should feel free to
* substitute other algorithms, so long as the specification itself is adhered
! * to. (For example, the algorithm used by <tt>sort</tt> does not have to be
* a mergesort, but it does have to be <i>stable</i>.)
*
* <p>The "destructive" algorithms contained in this class, that is, the
* algorithms that modify the collection on which they operate, are specified
! * to throw <tt>UnsupportedOperationException</tt> if the collection does not
! * support the appropriate mutation primitive(s), such as the <tt>set</tt>
* method. These algorithms may, but are not required to, throw this
* exception if an invocation would have no effect on the collection. For
! * example, invoking the <tt>sort</tt> method on an unmodifiable list that is
! * already sorted may or may not throw <tt>UnsupportedOperationException</tt>.
*
* <p>This class is a member of the
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
* Java Collections Framework</a>.
*
--- 42,70 ----
* This class consists exclusively of static methods that operate on or return
* collections. It contains polymorphic algorithms that operate on
* collections, "wrappers", which return a new collection backed by a
* specified collection, and a few other odds and ends.
*
! * <p>The methods of this class all throw a {@code NullPointerException}
* if the collections or class objects provided to them are null.
*
* <p>The documentation for the polymorphic algorithms contained in this class
* generally includes a brief description of the <i>implementation</i>. Such
* descriptions should be regarded as <i>implementation notes</i>, rather than
* parts of the <i>specification</i>. Implementors should feel free to
* substitute other algorithms, so long as the specification itself is adhered
! * to. (For example, the algorithm used by {@code sort} does not have to be
* a mergesort, but it does have to be <i>stable</i>.)
*
* <p>The "destructive" algorithms contained in this class, that is, the
* algorithms that modify the collection on which they operate, are specified
! * to throw {@code UnsupportedOperationException} if the collection does not
! * support the appropriate mutation primitive(s), such as the {@code set}
* method. These algorithms may, but are not required to, throw this
* exception if an invocation would have no effect on the collection. For
! * example, invoking the {@code sort} method on an unmodifiable list that is
! * already sorted may or may not throw {@code UnsupportedOperationException}.
*
* <p>This class is a member of the
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
* Java Collections Framework</a>.
*
*** 193,206 ****
*
* @param <T> the class of the objects in the list
* @param list the list to be searched.
* @param key the key to be searched for.
* @return the index of the search key, if it is contained in the list;
! * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
* <i>insertion point</i> is defined as the point at which the
* key would be inserted into the list: the index of the first
! * element greater than the key, or <tt>list.size()</tt> if all
* elements in the list are less than the specified key. Note
* that this guarantees that the return value will be >= 0 if
* and only if the key is found.
* @throws ClassCastException if the list contains elements that are not
* <i>mutually comparable</i> (for example, strings and
--- 193,206 ----
*
* @param <T> the class of the objects in the list
* @param list the list to be searched.
* @param key the key to be searched for.
* @return the index of the search key, if it is contained in the list;
! * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
* <i>insertion point</i> is defined as the point at which the
* key would be inserted into the list: the index of the first
! * element greater than the key, or {@code list.size()} if all
* elements in the list are less than the specified key. Note
* that this guarantees that the return value will be >= 0 if
* and only if the key is found.
* @throws ClassCastException if the list contains elements that are not
* <i>mutually comparable</i> (for example, strings and
*** 294,310 ****
*
* @param <T> the class of the objects in the list
* @param list the list to be searched.
* @param key the key to be searched for.
* @param c the comparator by which the list is ordered.
! * A <tt>null</tt> value indicates that the elements'
* {@linkplain Comparable natural ordering} should be used.
* @return the index of the search key, if it is contained in the list;
! * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
* <i>insertion point</i> is defined as the point at which the
* key would be inserted into the list: the index of the first
! * element greater than the key, or <tt>list.size()</tt> if all
* elements in the list are less than the specified key. Note
* that this guarantees that the return value will be >= 0 if
* and only if the key is found.
* @throws ClassCastException if the list contains elements that are not
* <i>mutually comparable</i> using the specified comparator,
--- 294,310 ----
*
* @param <T> the class of the objects in the list
* @param list the list to be searched.
* @param key the key to be searched for.
* @param c the comparator by which the list is ordered.
! * A {@code null} value indicates that the elements'
* {@linkplain Comparable natural ordering} should be used.
* @return the index of the search key, if it is contained in the list;
! * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
* <i>insertion point</i> is defined as the point at which the
* key would be inserted into the list: the index of the first
! * element greater than the key, or {@code list.size()} if all
* elements in the list are less than the specified key. Note
* that this guarantees that the return value will be >= 0 if
* and only if the key is found.
* @throws ClassCastException if the list contains elements that are not
* <i>mutually comparable</i> using the specified comparator,
*** 366,376 ****
*
* This method runs in linear time.
*
* @param list the list whose elements are to be reversed.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the <tt>set</tt> operation.
*/
@SuppressWarnings({"rawtypes", "unchecked"})
public static void reverse(List<?> list) {
int size = list.size();
if (size < REVERSE_THRESHOLD || list instanceof RandomAccess) {
--- 366,376 ----
*
* This method runs in linear time.
*
* @param list the list whose elements are to be reversed.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the {@code set} operation.
*/
@SuppressWarnings({"rawtypes", "unchecked"})
public static void reverse(List<?> list) {
int size = list.size();
if (size < REVERSE_THRESHOLD || list instanceof RandomAccess) {
*** 414,424 ****
* quadratic behavior that would result from shuffling a "sequential
* access" list in place.
*
* @param list the list to be shuffled.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the <tt>set</tt> operation.
*/
public static void shuffle(List<?> list) {
Random rnd = r;
if (rnd == null)
r = rnd = new Random(); // harmless race.
--- 414,424 ----
* quadratic behavior that would result from shuffling a "sequential
* access" list in place.
*
* @param list the list to be shuffled.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the {@code set} operation.
*/
public static void shuffle(List<?> list) {
Random rnd = r;
if (rnd == null)
r = rnd = new Random(); // harmless race.
*** 446,456 ****
* access" list in place.
*
* @param list the list to be shuffled.
* @param rnd the source of randomness to use to shuffle the list.
* @throws UnsupportedOperationException if the specified list or its
! * list-iterator does not support the <tt>set</tt> operation.
*/
@SuppressWarnings({"rawtypes", "unchecked"})
public static void shuffle(List<?> list, Random rnd) {
int size = list.size();
if (size < SHUFFLE_THRESHOLD || list instanceof RandomAccess) {
--- 446,456 ----
* access" list in place.
*
* @param list the list to be shuffled.
* @param rnd the source of randomness to use to shuffle the list.
* @throws UnsupportedOperationException if the specified list or its
! * list-iterator does not support the {@code set} operation.
*/
@SuppressWarnings({"rawtypes", "unchecked"})
public static void shuffle(List<?> list, Random rnd) {
int size = list.size();
if (size < SHUFFLE_THRESHOLD || list instanceof RandomAccess) {
*** 481,491 ****
* the list unchanged.)
*
* @param list The list in which to swap elements.
* @param i the index of one element to be swapped.
* @param j the index of the other element to be swapped.
! * @throws IndexOutOfBoundsException if either <tt>i</tt> or <tt>j</tt>
* is out of range (i < 0 || i >= list.size()
* || j < 0 || j >= list.size()).
* @since 1.4
*/
@SuppressWarnings({"rawtypes", "unchecked"})
--- 481,491 ----
* the list unchanged.)
*
* @param list The list in which to swap elements.
* @param i the index of one element to be swapped.
* @param j the index of the other element to be swapped.
! * @throws IndexOutOfBoundsException if either {@code i} or {@code j}
* is out of range (i < 0 || i >= list.size()
* || j < 0 || j >= list.size()).
* @since 1.4
*/
@SuppressWarnings({"rawtypes", "unchecked"})
*** 514,524 ****
*
* @param <T> the class of the objects in the list
* @param list the list to be filled with the specified element.
* @param obj The element with which to fill the specified list.
* @throws UnsupportedOperationException if the specified list or its
! * list-iterator does not support the <tt>set</tt> operation.
*/
public static <T> void fill(List<? super T> list, T obj) {
int size = list.size();
if (size < FILL_THRESHOLD || list instanceof RandomAccess) {
--- 514,524 ----
*
* @param <T> the class of the objects in the list
* @param list the list to be filled with the specified element.
* @param obj The element with which to fill the specified list.
* @throws UnsupportedOperationException if the specified list or its
! * list-iterator does not support the {@code set} operation.
*/
public static <T> void fill(List<? super T> list, T obj) {
int size = list.size();
if (size < FILL_THRESHOLD || list instanceof RandomAccess) {
*** 546,556 ****
* @param dest The destination list.
* @param src The source list.
* @throws IndexOutOfBoundsException if the destination list is too small
* to contain the entire source List.
* @throws UnsupportedOperationException if the destination list's
! * list-iterator does not support the <tt>set</tt> operation.
*/
public static <T> void copy(List<? super T> dest, List<? extends T> src) {
int srcSize = src.size();
if (srcSize > dest.size())
throw new IndexOutOfBoundsException("Source does not fit in dest");
--- 546,556 ----
* @param dest The destination list.
* @param src The source list.
* @throws IndexOutOfBoundsException if the destination list is too small
* to contain the entire source List.
* @throws UnsupportedOperationException if the destination list's
! * list-iterator does not support the {@code set} operation.
*/
public static <T> void copy(List<? super T> dest, List<? extends T> src) {
int srcSize = src.size();
if (srcSize > dest.size())
throw new IndexOutOfBoundsException("Source does not fit in dest");
*** 570,584 ****
}
/**
* Returns the minimum element of the given collection, according to the
* <i>natural ordering</i> of its elements. All elements in the
! * collection must implement the <tt>Comparable</tt> interface.
* Furthermore, all elements in the collection must be <i>mutually
! * comparable</i> (that is, <tt>e1.compareTo(e2)</tt> must not throw a
! * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
! * <tt>e2</tt> in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
--- 570,584 ----
}
/**
* Returns the minimum element of the given collection, according to the
* <i>natural ordering</i> of its elements. All elements in the
! * collection must implement the {@code Comparable} interface.
* Furthermore, all elements in the collection must be <i>mutually
! * comparable</i> (that is, {@code e1.compareTo(e2)} must not throw a
! * {@code ClassCastException} for any elements {@code e1} and
! * {@code e2} in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
*** 605,625 ****
/**
* Returns the minimum element of the given collection, according to the
* order induced by the specified comparator. All elements in the
* collection must be <i>mutually comparable</i> by the specified
! * comparator (that is, <tt>comp.compare(e1, e2)</tt> must not throw a
! * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
! * <tt>e2</tt> in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
* @param coll the collection whose minimum element is to be determined.
* @param comp the comparator with which to determine the minimum element.
! * A <tt>null</tt> value indicates that the elements' <i>natural
* ordering</i> should be used.
* @return the minimum element of the given collection, according
* to the specified comparator.
* @throws ClassCastException if the collection contains elements that are
* not <i>mutually comparable</i> using the specified comparator.
--- 605,625 ----
/**
* Returns the minimum element of the given collection, according to the
* order induced by the specified comparator. All elements in the
* collection must be <i>mutually comparable</i> by the specified
! * comparator (that is, {@code comp.compare(e1, e2)} must not throw a
! * {@code ClassCastException} for any elements {@code e1} and
! * {@code e2} in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
* @param coll the collection whose minimum element is to be determined.
* @param comp the comparator with which to determine the minimum element.
! * A {@code null} value indicates that the elements' <i>natural
* ordering</i> should be used.
* @return the minimum element of the given collection, according
* to the specified comparator.
* @throws ClassCastException if the collection contains elements that are
* not <i>mutually comparable</i> using the specified comparator.
*** 643,657 ****
}
/**
* Returns the maximum element of the given collection, according to the
* <i>natural ordering</i> of its elements. All elements in the
! * collection must implement the <tt>Comparable</tt> interface.
* Furthermore, all elements in the collection must be <i>mutually
! * comparable</i> (that is, <tt>e1.compareTo(e2)</tt> must not throw a
! * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
! * <tt>e2</tt> in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
--- 643,657 ----
}
/**
* Returns the maximum element of the given collection, according to the
* <i>natural ordering</i> of its elements. All elements in the
! * collection must implement the {@code Comparable} interface.
* Furthermore, all elements in the collection must be <i>mutually
! * comparable</i> (that is, {@code e1.compareTo(e2)} must not throw a
! * {@code ClassCastException} for any elements {@code e1} and
! * {@code e2} in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
*** 678,698 ****
/**
* Returns the maximum element of the given collection, according to the
* order induced by the specified comparator. All elements in the
* collection must be <i>mutually comparable</i> by the specified
! * comparator (that is, <tt>comp.compare(e1, e2)</tt> must not throw a
! * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
! * <tt>e2</tt> in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
* @param coll the collection whose maximum element is to be determined.
* @param comp the comparator with which to determine the maximum element.
! * A <tt>null</tt> value indicates that the elements' <i>natural
* ordering</i> should be used.
* @return the maximum element of the given collection, according
* to the specified comparator.
* @throws ClassCastException if the collection contains elements that are
* not <i>mutually comparable</i> using the specified comparator.
--- 678,698 ----
/**
* Returns the maximum element of the given collection, according to the
* order induced by the specified comparator. All elements in the
* collection must be <i>mutually comparable</i> by the specified
! * comparator (that is, {@code comp.compare(e1, e2)} must not throw a
! * {@code ClassCastException} for any elements {@code e1} and
! * {@code e2} in the collection).<p>
*
* This method iterates over the entire collection, hence it requires
* time proportional to the size of the collection.
*
* @param <T> the class of the objects in the collection
* @param coll the collection whose maximum element is to be determined.
* @param comp the comparator with which to determine the maximum element.
! * A {@code null} value indicates that the elements' <i>natural
* ordering</i> should be used.
* @return the maximum element of the given collection, according
* to the specified comparator.
* @throws ClassCastException if the collection contains elements that are
* not <i>mutually comparable</i> using the specified comparator.
*** 715,750 ****
return candidate;
}
/**
* Rotates the elements in the specified list by the specified distance.
! * After calling this method, the element at index <tt>i</tt> will be
! * the element previously at index <tt>(i - distance)</tt> mod
! * <tt>list.size()</tt>, for all values of <tt>i</tt> between <tt>0</tt>
! * and <tt>list.size()-1</tt>, inclusive. (This method has no effect on
* the size of the list.)
*
! * <p>For example, suppose <tt>list</tt> comprises<tt> [t, a, n, k, s]</tt>.
! * After invoking <tt>Collections.rotate(list, 1)</tt> (or
! * <tt>Collections.rotate(list, -4)</tt>), <tt>list</tt> will comprise
! * <tt>[s, t, a, n, k]</tt>.
*
* <p>Note that this method can usefully be applied to sublists to
* move one or more elements within a list while preserving the
* order of the remaining elements. For example, the following idiom
! * moves the element at index <tt>j</tt> forward to position
! * <tt>k</tt> (which must be greater than or equal to <tt>j</tt>):
* <pre>
* Collections.rotate(list.subList(j, k+1), -1);
* </pre>
! * To make this concrete, suppose <tt>list</tt> comprises
! * <tt>[a, b, c, d, e]</tt>. To move the element at index <tt>1</tt>
! * (<tt>b</tt>) forward two positions, perform the following invocation:
* <pre>
* Collections.rotate(l.subList(1, 4), -1);
* </pre>
! * The resulting list is <tt>[a, c, d, b, e]</tt>.
*
* <p>To move more than one element forward, increase the absolute value
* of the rotation distance. To move elements backward, use a positive
* shift distance.
*
--- 715,750 ----
return candidate;
}
/**
* Rotates the elements in the specified list by the specified distance.
! * After calling this method, the element at index {@code i} will be
! * the element previously at index {@code (i - distance)} mod
! * {@code list.size()}, for all values of {@code i} between {@code 0}
! * and {@code list.size()-1}, inclusive. (This method has no effect on
* the size of the list.)
*
! * <p>For example, suppose {@code list} comprises{@code [t, a, n, k, s]}.
! * After invoking {@code Collections.rotate(list, 1)} (or
! * {@code Collections.rotate(list, -4)}), {@code list} will comprise
! * {@code [s, t, a, n, k]}.
*
* <p>Note that this method can usefully be applied to sublists to
* move one or more elements within a list while preserving the
* order of the remaining elements. For example, the following idiom
! * moves the element at index {@code j} forward to position
! * {@code k} (which must be greater than or equal to {@code j}):
* <pre>
* Collections.rotate(list.subList(j, k+1), -1);
* </pre>
! * To make this concrete, suppose {@code list} comprises
! * {@code [a, b, c, d, e]}. To move the element at index {@code 1}
! * ({@code b}) forward two positions, perform the following invocation:
* <pre>
* Collections.rotate(l.subList(1, 4), -1);
* </pre>
! * The resulting list is {@code [a, c, d, b, e]}.
*
* <p>To move more than one element forward, increase the absolute value
* of the rotation distance. To move elements backward, use a positive
* shift distance.
*
*** 753,775 ****
* element into the location it should go, and then repeatedly exchanges
* the displaced element into the location it should go until a displaced
* element is swapped into the first element. If necessary, the process
* is repeated on the second and successive elements, until the rotation
* is complete. If the specified list is large and doesn't implement the
! * <tt>RandomAccess</tt> interface, this implementation breaks the
! * list into two sublist views around index <tt>-distance mod size</tt>.
* Then the {@link #reverse(List)} method is invoked on each sublist view,
* and finally it is invoked on the entire list. For a more complete
* description of both algorithms, see Section 2.3 of Jon Bentley's
* <i>Programming Pearls</i> (Addison-Wesley, 1986).
*
* @param list the list to be rotated.
* @param distance the distance to rotate the list. There are no
* constraints on this value; it may be zero, negative, or
! * greater than <tt>list.size()</tt>.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the <tt>set</tt> operation.
* @since 1.4
*/
public static void rotate(List<?> list, int distance) {
if (list instanceof RandomAccess || list.size() < ROTATE_THRESHOLD)
rotate1(list, distance);
--- 753,775 ----
* element into the location it should go, and then repeatedly exchanges
* the displaced element into the location it should go until a displaced
* element is swapped into the first element. If necessary, the process
* is repeated on the second and successive elements, until the rotation
* is complete. If the specified list is large and doesn't implement the
! * {@code RandomAccess} interface, this implementation breaks the
! * list into two sublist views around index {@code -distance mod size}.
* Then the {@link #reverse(List)} method is invoked on each sublist view,
* and finally it is invoked on the entire list. For a more complete
* description of both algorithms, see Section 2.3 of Jon Bentley's
* <i>Programming Pearls</i> (Addison-Wesley, 1986).
*
* @param list the list to be rotated.
* @param distance the distance to rotate the list. There are no
* constraints on this value; it may be zero, negative, or
! * greater than {@code list.size()}.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the {@code set} operation.
* @since 1.4
*/
public static void rotate(List<?> list, int distance) {
if (list instanceof RandomAccess || list.size() < ROTATE_THRESHOLD)
rotate1(list, distance);
*** 815,839 ****
reverse(list);
}
/**
* Replaces all occurrences of one specified value in a list with another.
! * More formally, replaces with <tt>newVal</tt> each element <tt>e</tt>
! * in <tt>list</tt> such that
! * <tt>(oldVal==null ? e==null : oldVal.equals(e))</tt>.
* (This method has no effect on the size of the list.)
*
* @param <T> the class of the objects in the list
* @param list the list in which replacement is to occur.
* @param oldVal the old value to be replaced.
! * @param newVal the new value with which <tt>oldVal</tt> is to be
* replaced.
! * @return <tt>true</tt> if <tt>list</tt> contained one or more elements
! * <tt>e</tt> such that
! * <tt>(oldVal==null ? e==null : oldVal.equals(e))</tt>.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the <tt>set</tt> operation.
* @since 1.4
*/
public static <T> boolean replaceAll(List<T> list, T oldVal, T newVal) {
boolean result = false;
int size = list.size();
--- 815,839 ----
reverse(list);
}
/**
* Replaces all occurrences of one specified value in a list with another.
! * More formally, replaces with {@code newVal} each element {@code e}
! * in {@code list} such that
! * {@code (oldVal==null ? e==null : oldVal.equals(e))}.
* (This method has no effect on the size of the list.)
*
* @param <T> the class of the objects in the list
* @param list the list in which replacement is to occur.
* @param oldVal the old value to be replaced.
! * @param newVal the new value with which {@code oldVal} is to be
* replaced.
! * @return {@code true} if {@code list} contained one or more elements
! * {@code e} such that
! * {@code (oldVal==null ? e==null : oldVal.equals(e))}.
* @throws UnsupportedOperationException if the specified list or
! * its list-iterator does not support the {@code set} operation.
* @since 1.4
*/
public static <T> boolean replaceAll(List<T> list, T oldVal, T newVal) {
boolean result = false;
int size = list.size();
*** 875,896 ****
}
/**
* Returns the starting position of the first occurrence of the specified
* target list within the specified source list, or -1 if there is no
! * such occurrence. More formally, returns the lowest index <tt>i</tt>
* such that {@code source.subList(i, i+target.size()).equals(target)},
* or -1 if there is no such index. (Returns -1 if
* {@code target.size() > source.size()})
*
* <p>This implementation uses the "brute force" technique of scanning
* over the source list, looking for a match with the target at each
* location in turn.
*
* @param source the list in which to search for the first occurrence
! * of <tt>target</tt>.
! * @param target the list to search for as a subList of <tt>source</tt>.
* @return the starting position of the first occurrence of the specified
* target list within the specified source list, or -1 if there
* is no such occurrence.
* @since 1.4
*/
--- 875,896 ----
}
/**
* Returns the starting position of the first occurrence of the specified
* target list within the specified source list, or -1 if there is no
! * such occurrence. More formally, returns the lowest index {@code i}
* such that {@code source.subList(i, i+target.size()).equals(target)},
* or -1 if there is no such index. (Returns -1 if
* {@code target.size() > source.size()})
*
* <p>This implementation uses the "brute force" technique of scanning
* over the source list, looking for a match with the target at each
* location in turn.
*
* @param source the list in which to search for the first occurrence
! * of {@code target}.
! * @param target the list to search for as a subList of {@code source}.
* @return the starting position of the first occurrence of the specified
* target list within the specified source list, or -1 if there
* is no such occurrence.
* @since 1.4
*/
*** 928,949 ****
}
/**
* Returns the starting position of the last occurrence of the specified
* target list within the specified source list, or -1 if there is no such
! * occurrence. More formally, returns the highest index <tt>i</tt>
* such that {@code source.subList(i, i+target.size()).equals(target)},
* or -1 if there is no such index. (Returns -1 if
* {@code target.size() > source.size()})
*
* <p>This implementation uses the "brute force" technique of iterating
* over the source list, looking for a match with the target at each
* location in turn.
*
* @param source the list in which to search for the last occurrence
! * of <tt>target</tt>.
! * @param target the list to search for as a subList of <tt>source</tt>.
* @return the starting position of the last occurrence of the specified
* target list within the specified source list, or -1 if there
* is no such occurrence.
* @since 1.4
*/
--- 928,949 ----
}
/**
* Returns the starting position of the last occurrence of the specified
* target list within the specified source list, or -1 if there is no such
! * occurrence. More formally, returns the highest index {@code i}
* such that {@code source.subList(i, i+target.size()).equals(target)},
* or -1 if there is no such index. (Returns -1 if
* {@code target.size() > source.size()})
*
* <p>This implementation uses the "brute force" technique of iterating
* over the source list, looking for a match with the target at each
* location in turn.
*
* @param source the list in which to search for the last occurrence
! * of {@code target}.
! * @param target the list to search for as a subList of {@code source}.
* @return the starting position of the last occurrence of the specified
* target list within the specified source list, or -1 if there
* is no such occurrence.
* @since 1.4
*/
*** 991,1005 ****
* Returns an unmodifiable view of the specified collection. This method
* allows modules to provide users with "read-only" access to internal
* collections. Query operations on the returned collection "read through"
* to the specified collection, and attempts to modify the returned
* collection, whether direct or via its iterator, result in an
! * <tt>UnsupportedOperationException</tt>.<p>
*
* The returned collection does <i>not</i> pass the hashCode and equals
* operations through to the backing collection, but relies on
! * <tt>Object</tt>'s <tt>equals</tt> and <tt>hashCode</tt> methods. This
* is necessary to preserve the contracts of these operations in the case
* that the backing collection is a set or a list.<p>
*
* The returned collection will be serializable if the specified collection
* is serializable.
--- 991,1005 ----
* Returns an unmodifiable view of the specified collection. This method
* allows modules to provide users with "read-only" access to internal
* collections. Query operations on the returned collection "read through"
* to the specified collection, and attempts to modify the returned
* collection, whether direct or via its iterator, result in an
! * {@code UnsupportedOperationException}.<p>
*
* The returned collection does <i>not</i> pass the hashCode and equals
* operations through to the backing collection, but relies on
! * {@code Object}'s {@code equals} and {@code hashCode} methods. This
* is necessary to preserve the contracts of these operations in the case
* that the backing collection is a set or a list.<p>
*
* The returned collection will be serializable if the specified collection
* is serializable.
*** 1103,1113 ****
/**
* Returns an unmodifiable view of the specified set. This method allows
* modules to provide users with "read-only" access to internal sets.
* Query operations on the returned set "read through" to the specified
* set, and attempts to modify the returned set, whether direct or via its
! * iterator, result in an <tt>UnsupportedOperationException</tt>.<p>
*
* The returned set will be serializable if the specified set
* is serializable.
*
* @param <T> the class of the objects in the set
--- 1103,1113 ----
/**
* Returns an unmodifiable view of the specified set. This method allows
* modules to provide users with "read-only" access to internal sets.
* Query operations on the returned set "read through" to the specified
* set, and attempts to modify the returned set, whether direct or via its
! * iterator, result in an {@code UnsupportedOperationException}.<p>
*
* The returned set will be serializable if the specified set
* is serializable.
*
* @param <T> the class of the objects in the set
*** 1134,1145 ****
* Returns an unmodifiable view of the specified sorted set. This method
* allows modules to provide users with "read-only" access to internal
* sorted sets. Query operations on the returned sorted set "read
* through" to the specified sorted set. Attempts to modify the returned
* sorted set, whether direct, via its iterator, or via its
! * <tt>subSet</tt>, <tt>headSet</tt>, or <tt>tailSet</tt> views, result in
! * an <tt>UnsupportedOperationException</tt>.<p>
*
* The returned sorted set will be serializable if the specified sorted set
* is serializable.
*
* @param <T> the class of the objects in the set
--- 1134,1145 ----
* Returns an unmodifiable view of the specified sorted set. This method
* allows modules to provide users with "read-only" access to internal
* sorted sets. Query operations on the returned sorted set "read
* through" to the specified sorted set. Attempts to modify the returned
* sorted set, whether direct, via its iterator, or via its
! * {@code subSet}, {@code headSet}, or {@code tailSet} views, result in
! * an {@code UnsupportedOperationException}.<p>
*
* The returned sorted set will be serializable if the specified sorted set
* is serializable.
*
* @param <T> the class of the objects in the set
*** 1271,1281 ****
* Returns an unmodifiable view of the specified list. This method allows
* modules to provide users with "read-only" access to internal
* lists. Query operations on the returned list "read through" to the
* specified list, and attempts to modify the returned list, whether
* direct or via its iterator, result in an
! * <tt>UnsupportedOperationException</tt>.<p>
*
* The returned list will be serializable if the specified list
* is serializable. Similarly, the returned list will implement
* {@link RandomAccess} if the specified list does.
*
--- 1271,1281 ----
* Returns an unmodifiable view of the specified list. This method allows
* modules to provide users with "read-only" access to internal
* lists. Query operations on the returned list "read through" to the
* specified list, and attempts to modify the returned list, whether
* direct or via its iterator, result in an
! * {@code UnsupportedOperationException}.<p>
*
* The returned list will be serializable if the specified list
* is serializable. Similarly, the returned list will implement
* {@link RandomAccess} if the specified list does.
*
*** 1417,1427 ****
* Returns an unmodifiable view of the specified map. This method
* allows modules to provide users with "read-only" access to internal
* maps. Query operations on the returned map "read through"
* to the specified map, and attempts to modify the returned
* map, whether direct or via its collection views, result in an
! * <tt>UnsupportedOperationException</tt>.<p>
*
* The returned map will be serializable if the specified map
* is serializable.
*
* @param <K> the class of the map keys
--- 1417,1427 ----
* Returns an unmodifiable view of the specified map. This method
* allows modules to provide users with "read-only" access to internal
* maps. Query operations on the returned map "read through"
* to the specified map, and attempts to modify the returned
* map, whether direct or via its collection views, result in an
! * {@code UnsupportedOperationException}.<p>
*
* The returned map will be serializable if the specified map
* is serializable.
*
* @param <K> the class of the map keys
*** 1767,1778 ****
* Returns an unmodifiable view of the specified sorted map. This method
* allows modules to provide users with "read-only" access to internal
* sorted maps. Query operations on the returned sorted map "read through"
* to the specified sorted map. Attempts to modify the returned
* sorted map, whether direct, via its collection views, or via its
! * <tt>subMap</tt>, <tt>headMap</tt>, or <tt>tailMap</tt> views, result in
! * an <tt>UnsupportedOperationException</tt>.<p>
*
* The returned sorted map will be serializable if the specified sorted map
* is serializable.
*
* @param <K> the class of the map keys
--- 1767,1778 ----
* Returns an unmodifiable view of the specified sorted map. This method
* allows modules to provide users with "read-only" access to internal
* sorted maps. Query operations on the returned sorted map "read through"
* to the specified sorted map. Attempts to modify the returned
* sorted map, whether direct, via its collection views, or via its
! * {@code subMap}, {@code headMap}, or {@code tailMap} views, result in
! * an {@code UnsupportedOperationException}.<p>
*
* The returned sorted map will be serializable if the specified sorted map
* is serializable.
*
* @param <K> the class of the map keys
*** 2146,2157 ****
* sorted set. In order to guarantee serial access, it is critical that
* <strong>all</strong> access to the backing sorted set is accomplished
* through the returned sorted set (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
! * sorted set when iterating over it or any of its <tt>subSet</tt>,
! * <tt>headSet</tt>, or <tt>tailSet</tt> views.
* <pre>
* SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
* ...
* synchronized (s) {
* Iterator i = s.iterator(); // Must be in the synchronized block
--- 2146,2157 ----
* sorted set. In order to guarantee serial access, it is critical that
* <strong>all</strong> access to the backing sorted set is accomplished
* through the returned sorted set (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
! * sorted set when iterating over it or any of its {@code subSet},
! * {@code headSet}, or {@code tailSet} views.
* <pre>
* SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
* ...
* synchronized (s) {
* Iterator i = s.iterator(); // Must be in the synchronized block
*** 2698,2709 ****
* <strong>all</strong> access to the backing sorted map is accomplished
* through the returned sorted map (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
* sorted map when iterating over any of its collection views, or the
! * collections views of any of its <tt>subMap</tt>, <tt>headMap</tt> or
! * <tt>tailMap</tt> views.
* <pre>
* SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
* ...
* Set s = m.keySet(); // Needn't be in synchronized block
* ...
--- 2698,2709 ----
* <strong>all</strong> access to the backing sorted map is accomplished
* through the returned sorted map (or its views).<p>
*
* It is imperative that the user manually synchronize on the returned
* sorted map when iterating over any of its collection views, or the
! * collections views of any of its {@code subMap}, {@code headMap} or
! * {@code tailMap} views.
* <pre>
* SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
* ...
* Set s = m.keySet(); // Needn't be in synchronized block
* ...
*** 4404,4414 ****
* <pre>
* List<String> s = Collections.emptyList();
* </pre>
*
* @implNote
! * Implementations of this method need not create a separate <tt>List</tt>
* object for each call. Using this method is likely to have comparable
* cost to using the like-named field. (Unlike this method, the field does
* not provide type safety.)
*
* @param <T> type of elements, if there were any, in the list
--- 4404,4414 ----
* <pre>
* List<String> s = Collections.emptyList();
* </pre>
*
* @implNote
! * Implementations of this method need not create a separate {@code List}
* object for each call. Using this method is likely to have comparable
* cost to using the like-named field. (Unlike this method, the field does
* not provide type safety.)
*
* @param <T> type of elements, if there were any, in the list
*** 4844,4854 ****
* specified value. The returned map is serializable.
*
* @param <K> the class of the map keys
* @param <V> the class of the map values
* @param key the sole key to be stored in the returned map.
! * @param value the value to which the returned map maps <tt>key</tt>.
* @return an immutable map containing only the specified key-value
* mapping.
* @since 1.3
*/
public static <K,V> Map<K,V> singletonMap(K key, V value) {
--- 4844,4854 ----
* specified value. The returned map is serializable.
*
* @param <K> the class of the map keys
* @param <V> the class of the map values
* @param key the sole key to be stored in the returned map.
! * @param value the value to which the returned map maps {@code key}.
* @return an immutable map containing only the specified key-value
* mapping.
* @since 1.3
*/
public static <K,V> Map<K,V> singletonMap(K key, V value) {
*** 4962,4982 ****
}
// Miscellaneous
/**
! * Returns an immutable list consisting of <tt>n</tt> copies of the
* specified object. The newly allocated data object is tiny (it contains
* a single reference to the data object). This method is useful in
! * combination with the <tt>List.addAll</tt> method to grow lists.
* The returned list is serializable.
*
* @param <T> the class of the object to copy and of the objects
* in the returned list.
* @param n the number of elements in the returned list.
* @param o the element to appear repeatedly in the returned list.
! * @return an immutable list consisting of <tt>n</tt> copies of the
* specified object.
* @throws IllegalArgumentException if {@code n < 0}
* @see List#addAll(Collection)
* @see List#addAll(int, Collection)
*/
--- 4962,4982 ----
}
// Miscellaneous
/**
! * Returns an immutable list consisting of {@code n} copies of the
* specified object. The newly allocated data object is tiny (it contains
* a single reference to the data object). This method is useful in
! * combination with the {@code List.addAll} method to grow lists.
* The returned list is serializable.
*
* @param <T> the class of the object to copy and of the objects
* in the returned list.
* @param n the number of elements in the returned list.
* @param o the element to appear repeatedly in the returned list.
! * @return an immutable list consisting of {@code n} copies of the
* specified object.
* @throws IllegalArgumentException if {@code n < 0}
* @see List#addAll(Collection)
* @see List#addAll(int, Collection)
*/
*** 5093,5103 ****
* The returned comparator is serializable.
*
* @param <T> the class of the objects compared by the comparator
* @return A comparator that imposes the reverse of the <i>natural
* ordering</i> on a collection of objects that implement
! * the <tt>Comparable</tt> interface.
* @see Comparable
*/
@SuppressWarnings("unchecked")
public static <T> Comparator<T> reverseOrder() {
return (Comparator<T>) ReverseComparator.REVERSE_ORDER;
--- 5093,5103 ----
* The returned comparator is serializable.
*
* @param <T> the class of the objects compared by the comparator
* @return A comparator that imposes the reverse of the <i>natural
* ordering</i> on a collection of objects that implement
! * the {@code Comparable} interface.
* @see Comparable
*/
@SuppressWarnings("unchecked")
public static <T> Comparator<T> reverseOrder() {
return (Comparator<T>) ReverseComparator.REVERSE_ORDER;
*** 5257,5274 ****
}
/**
* Returns the number of elements in the specified collection equal to the
* specified object. More formally, returns the number of elements
! * <tt>e</tt> in the collection such that
! * <tt>(o == null ? e == null : o.equals(e))</tt>.
*
* @param c the collection in which to determine the frequency
! * of <tt>o</tt>
* @param o the object whose frequency is to be determined
* @return the number of elements in {@code c} equal to {@code o}
! * @throws NullPointerException if <tt>c</tt> is null
* @since 1.5
*/
public static int frequency(Collection<?> c, Object o) {
int result = 0;
if (o == null) {
--- 5257,5274 ----
}
/**
* Returns the number of elements in the specified collection equal to the
* specified object. More formally, returns the number of elements
! * {@code e} in the collection such that
! * {@code (o == null ? e == null : o.equals(e))}.
*
* @param c the collection in which to determine the frequency
! * of {@code o}
* @param o the object whose frequency is to be determined
* @return the number of elements in {@code c} equal to {@code o}
! * @throws NullPointerException if {@code c} is null
* @since 1.5
*/
public static int frequency(Collection<?> c, Object o) {
int result = 0;
if (o == null) {
*** 5375,5404 ****
/**
* Adds all of the specified elements to the specified collection.
* Elements to be added may be specified individually or as an array.
* The behavior of this convenience method is identical to that of
! * <tt>c.addAll(Arrays.asList(elements))</tt>, but this method is likely
* to run significantly faster under most implementations.
*
* <p>When elements are specified individually, this method provides a
* convenient way to add a few elements to an existing collection:
* <pre>
* Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
* </pre>
*
* @param <T> the class of the elements to add and of the collection
! * @param c the collection into which <tt>elements</tt> are to be inserted
! * @param elements the elements to insert into <tt>c</tt>
! * @return <tt>true</tt> if the collection changed as a result of the call
! * @throws UnsupportedOperationException if <tt>c</tt> does not support
! * the <tt>add</tt> operation
! * @throws NullPointerException if <tt>elements</tt> contains one or more
! * null values and <tt>c</tt> does not permit null elements, or
! * if <tt>c</tt> or <tt>elements</tt> are <tt>null</tt>
* @throws IllegalArgumentException if some property of a value in
! * <tt>elements</tt> prevents it from being added to <tt>c</tt>
* @see Collection#addAll(Collection)
* @since 1.5
*/
@SafeVarargs
public static <T> boolean addAll(Collection<? super T> c, T... elements) {
--- 5375,5404 ----
/**
* Adds all of the specified elements to the specified collection.
* Elements to be added may be specified individually or as an array.
* The behavior of this convenience method is identical to that of
! * {@code c.addAll(Arrays.asList(elements))}, but this method is likely
* to run significantly faster under most implementations.
*
* <p>When elements are specified individually, this method provides a
* convenient way to add a few elements to an existing collection:
* <pre>
* Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
* </pre>
*
* @param <T> the class of the elements to add and of the collection
! * @param c the collection into which {@code elements} are to be inserted
! * @param elements the elements to insert into {@code c}
! * @return {@code true} if the collection changed as a result of the call
! * @throws UnsupportedOperationException if {@code c} does not support
! * the {@code add} operation
! * @throws NullPointerException if {@code elements} contains one or more
! * null values and {@code c} does not permit null elements, or
! * if {@code c} or {@code elements} are {@code null}
* @throws IllegalArgumentException if some property of a value in
! * {@code elements} prevents it from being added to {@code c}
* @see Collection#addAll(Collection)
* @since 1.5
*/
@SafeVarargs
public static <T> boolean addAll(Collection<? super T> c, T... elements) {
*** 5416,5428 ****
* is no need to use this method on a {@link Map} implementation that
* already has a corresponding {@link Set} implementation (such as {@link
* HashMap} or {@link TreeMap}).
*
* <p>Each method invocation on the set returned by this method results in
! * exactly one method invocation on the backing map or its <tt>keySet</tt>
! * view, with one exception. The <tt>addAll</tt> method is implemented
! * as a sequence of <tt>put</tt> invocations on the backing map.
*
* <p>The specified map must be empty at the time this method is invoked,
* and should not be accessed directly after this method returns. These
* conditions are ensured if the map is created empty, passed directly
* to this method, and no reference to the map is retained, as illustrated
--- 5416,5428 ----
* is no need to use this method on a {@link Map} implementation that
* already has a corresponding {@link Set} implementation (such as {@link
* HashMap} or {@link TreeMap}).
*
* <p>Each method invocation on the set returned by this method results in
! * exactly one method invocation on the backing map or its {@code keySet}
! * view, with one exception. The {@code addAll} method is implemented
! * as a sequence of {@code put} invocations on the backing map.
*
* <p>The specified map must be empty at the time this method is invoked,
* and should not be accessed directly after this method returns. These
* conditions are ensured if the map is created empty, passed directly
* to this method, and no reference to the map is retained, as illustrated
*** 5434,5444 ****
*
* @param <E> the class of the map keys and of the objects in the
* returned set
* @param map the backing map
* @return the set backed by the map
! * @throws IllegalArgumentException if <tt>map</tt> is not empty
* @since 1.6
*/
public static <E> Set<E> newSetFromMap(Map<E, Boolean> map) {
return new SetFromMap<>(map);
}
--- 5434,5444 ----
*
* @param <E> the class of the map keys and of the objects in the
* returned set
* @param map the backing map
* @return the set backed by the map
! * @throws IllegalArgumentException if {@code map} is not empty
* @since 1.6
*/
public static <E> Set<E> newSetFromMap(Map<E, Boolean> map) {
return new SetFromMap<>(map);
}
*** 5503,5516 ****
}
}
/**
* Returns a view of a {@link Deque} as a Last-in-first-out (Lifo)
! * {@link Queue}. Method <tt>add</tt> is mapped to <tt>push</tt>,
! * <tt>remove</tt> is mapped to <tt>pop</tt> and so on. This
* view can be useful when you would like to use a method
! * requiring a <tt>Queue</tt> but you need Lifo ordering.
*
* <p>Each method invocation on the queue returned by this method
* results in exactly one method invocation on the backing deque, with
* one exception. The {@link Queue#addAll addAll} method is
* implemented as a sequence of {@link Deque#addFirst addFirst}
--- 5503,5516 ----
}
}
/**
* Returns a view of a {@link Deque} as a Last-in-first-out (Lifo)
! * {@link Queue}. Method {@code add} is mapped to {@code push},
! * {@code remove} is mapped to {@code pop} and so on. This
* view can be useful when you would like to use a method
! * requiring a {@code Queue} but you need Lifo ordering.
*
* <p>Each method invocation on the queue returned by this method
* results in exactly one method invocation on the backing deque, with
* one exception. The {@link Queue#addAll addAll} method is
* implemented as a sequence of {@link Deque#addFirst addFirst}
< prev index next >