Java Doc for Arrays.java in  » 6.0-JDK-Core » Collections-Jar-Zip-Logging-regex » java » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The methods in this class all throw a NullPointerException if the specified array reference is null, except where noted.

The documentation for the methods contained in this class includes briefs description of the implementations. Such descriptions should be regarded as implementation notes, rather than parts of the specification. Implementors should feel free to substitute other algorithms, so long as the specification itself is adhered to. (For example, the algorithm used by sort(Object[]) does not have to be a mergesort, but it does have to be stable.)

This class is a member of the Java Collections Framework.
author:
   Josh Bloch
author:
   Neal Gafter
author:
   John Rose
version:
   1.80, 07/14/07
since:
   1.2

The < relation does not provide a total order on all floating-point values; although they are distinct numbers -0.0 == 0.0 is true and a NaN value compares neither less than, greater than, nor equal to any floating-point value, even itself.

The < relation does not provide a total order on all floating-point values; although they are distinct numbers -0.0f == 0.0f is true and a NaN value compares neither less than, greater than, nor equal to any floating-point value, even itself.

This method also provides a convenient way to create a fixed-size list initialized to contain several elements:

 List<String> stooges = Arrays.asList("Larry", "Moe", "Curly");
 

The resulting array is of exactly the same class as the original array.
Parameters:
  original - the array from which a range is to be copied
Parameters:
  from - the initial index of the range to be copied, inclusive
Parameters:
  to - the final index of the range to be copied, exclusive.(This index may lie outside the array.) a new array containing the specified range from the original array,truncated or padded with nulls to obtain the required length
throws:
  ArrayIndexOutOfBoundsException - if from < 0 or from > original.length
throws:
  IllegalArgumentException - if from > to
throws:
  NullPointerException - if original is null
since:
   1.6

Two array references are considered deeply equal if both are null, or if they refer to arrays that contain the same number of elements and all corresponding pairs of elements in the two arrays are deeply equal.

Two possibly null elements e1 and e2 are deeply equal if any of the following conditions hold:

• e1 and e2 are both arrays of object reference types, and Arrays.deepEquals(e1, e2) would return true
• e1 and e2 are arrays of the same primitive type, and the appropriate overloading of Arrays.equals(e1, e2) would return true.
• e1 == e2
• e1.equals(e2) would return true.

If either of the specified arrays contain themselves as elements either directly or indirectly through one or more levels of arrays, the behavior of this method is undefined.
Parameters:
  a1 - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal
See Also:   Arrays.equals(Object[],Object[])
since:
   1.5

For any two arrays a and b such that Arrays.deepEquals(a, b), it is also the case that Arrays.deepHashCode(a) == Arrays.deepHashCode(b).

The computation of the value returned by this method is similar to that of the value returned by List.hashCode on a list containing the same elements as a in the same order, with one difference: If an element e of a is itself an array, its hash code is computed not by calling e.hashCode(), but as by calling the appropriate overloading of Arrays.hashCode(e) if e is an array of a primitive type, or as by calling Arrays.deepHashCode(e) recursively if e is an array of a reference type. If a is null, this method returns 0.
Parameters:
  a - the array whose deep-content-based hash code to compute a deep-content-based hash code for a
See Also:   Arrays.hashCode(Object[])
since:
   1.5

The string representation consists of a list of the array's elements, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (a comma followed by a space). Elements are converted to strings as by String.valueOf(Object), unless they are themselves arrays.

If an element e is an array of a primitive type, it is converted to a string as by invoking the appropriate overloading of Arrays.toString(e). If an element e is an array of a reference type, it is converted to a string as by invoking this method recursively.

To avoid infinite recursion, if the specified array contains itself as an element, or contains an indirect reference to itself through one or more levels of arrays, the self-reference is converted to the string "[...]". For example, an array containing only a reference to itself would be rendered as "[[...]]".

This method returns "null" if the specified array is null.
Parameters:
  a - the array whose string representation to return a string representation of a
See Also:   Arrays.toString(Object[])
since:
   1.5

Parameters:
  a - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal

Parameters:
  a - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal

Parameters:
  a - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal

Parameters:
  a - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal

Parameters:
  a - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal

Parameters:
  a - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal

Two doubles d1 and d2 are considered equal if:

    new Double(d1).equals(new Double(d2))

Two floats f1 and f2 are considered equal if:

    new Float(f1).equals(new Float(f2))

Parameters:
  a - one array to be tested for equality
Parameters:
  a2 - the other array to be tested for equality true if the two arrays are equal

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Long instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Integer instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Short instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Character instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Byte instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Boolean instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Float instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

The value returned by this method is the same value that would be obtained by invoking the List.hashCode hashCode method on a List containing a sequence of Double instances representing the elements of a in the same order. If a is null, this method returns 0.
Parameters:
  a - the array whose hash value to compute a content-based hash code for a
since:
   1.5

For any two arrays a and b such that Arrays.equals(a, b), it is also the case that Arrays.hashCode(a) == Arrays.hashCode(b).

The value returned by this method is equal to the value that would be returned by Arrays.asList(a).hashCode(), unless a is null, in which case 0 is returned.
Parameters:
  a - the array whose content-based hash code to compute a content-based hash code for a
See Also:   Arrays.deepHashCode(Object[])
since:
   1.5

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

The < relation does not provide a total order on all floating-point values; although they are distinct numbers -0.0 == 0.0 is true and a NaN value compares neither less than, greater than, nor equal to any floating-point value, even itself. To allow the sort to proceed, instead of using the < relation to determine ascending numerical order, this method uses the total order imposed by Double.compareTo . This ordering differs from the < relation in that -0.0 is treated as less than 0.0 and NaN is considered greater than any other floating-point value. For the purposes of sorting, all NaN values are considered equivalent and equal.

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted

The < relation does not provide a total order on all floating-point values; although they are distinct numbers -0.0 == 0.0 is true and a NaN value compares neither less than, greater than, nor equal to any floating-point value, even itself. To allow the sort to proceed, instead of using the < relation to determine ascending numerical order, this method uses the total order imposed by Double.compareTo . This ordering differs from the < relation in that -0.0 is treated as less than 0.0 and NaN is considered greater than any other floating-point value. For the purposes of sorting, all NaN values are considered equivalent and equal.

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

The < relation does not provide a total order on all floating-point values; although they are distinct numbers -0.0f == 0.0f is true and a NaN value compares neither less than, greater than, nor equal to any floating-point value, even itself. To allow the sort to proceed, instead of using the < relation to determine ascending numerical order, this method uses the total order imposed by Float.compareTo . This ordering differs from the < relation in that -0.0f is treated as less than 0.0f and NaN is considered greater than any other floating-point value. For the purposes of sorting, all NaN values are considered equivalent and equal.

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted

The < relation does not provide a total order on all floating-point values; although they are distinct numbers -0.0f == 0.0f is true and a NaN value compares neither less than, greater than, nor equal to any floating-point value, even itself. To allow the sort to proceed, instead of using the < relation to determine ascending numerical order, this method uses the total order imposed by Float.compareTo . This ordering differs from the < relation in that -0.0f is treated as less than 0.0f and NaN is considered greater than any other floating-point value. For the purposes of sorting, all NaN values are considered equivalent and equal.

The sorting algorithm is a tuned quicksort, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

The sorting algorithm is a modified mergesort (in which the merge is omitted if the highest element in the low sublist is less than the lowest element in the high sublist). This algorithm offers guaranteed n*log(n) performance.
Parameters:
  a - the array to be sorted
throws:
  ClassCastException - if the array contains elements that are notmutually comparable (for example, strings and integers).

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

The sorting algorithm is a modified mergesort (in which the merge is omitted if the highest element in the low sublist is less than the lowest element in the high sublist). This algorithm offers guaranteed n*log(n) performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length
throws:
  ClassCastException - if the array contains elements that arenot mutually comparable (for example, strings andintegers).

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

The sorting algorithm is a modified mergesort (in which the merge is omitted if the highest element in the low sublist is less than the lowest element in the high sublist). This algorithm offers guaranteed n*log(n) performance.
Parameters:
  a - the array to be sorted
Parameters:
  c - the comparator to determine the order of the array. Anull value indicates that the elements' should be used.
throws:
  ClassCastException - if the array contains elements that arenot mutually comparable using the specified comparator.

This sort is guaranteed to be stable: equal elements will not be reordered as a result of the sort.

The sorting algorithm is a modified mergesort (in which the merge is omitted if the highest element in the low sublist is less than the lowest element in the high sublist). This algorithm offers guaranteed n*log(n) performance.
Parameters:
  a - the array to be sorted
Parameters:
  fromIndex - the index of the first element (inclusive) to besorted
Parameters:
  toIndex - the index of the last element (exclusive) to be sorted
Parameters:
  c - the comparator to determine the order of the array. Anull value indicates that the elements' should be used.
throws:
  ClassCastException - if the array contains elements that are notmutually comparable using the specified comparator.
throws:
  IllegalArgumentException - if fromIndex > toIndex
throws:
  ArrayIndexOutOfBoundsException - if fromIndex < 0 ortoIndex > a.length

The value returned by this method is equal to the value that would be returned by Arrays.asList(a).toString(), unless a is null, in which case "null" is returned.
Parameters:
  a - the array whose string representation to return a string representation of a
See Also:   Arrays.deepToString(Object[])
since:
   1.5