1755 Objects.requireNonNull(op);
1756 rangeCheck(array.length, fromIndex, toIndex);
1757 if (fromIndex < toIndex)
1758 new ArrayPrefixHelpers.IntCumulateTask
1759 (null, op, array, fromIndex, toIndex).invoke();
1760 }
1761
1762 // Searching
1763
1764 /**
1765 * Searches the specified array of longs for the specified value using the
1766 * binary search algorithm. The array must be sorted (as
1767 * by the {@link #sort(long[])} method) prior to making this call. If it
1768 * is not sorted, the results are undefined. If the array contains
1769 * multiple elements with the specified value, there is no guarantee which
1770 * one will be found.
1771 *
1772 * @param a the array to be searched
1773 * @param key the value to be searched for
1774 * @return index of the search key, if it is contained in the array;
1775 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
1776 * <i>insertion point</i> is defined as the point at which the
1777 * key would be inserted into the array: the index of the first
1778 * element greater than the key, or <tt>a.length</tt> if all
1779 * elements in the array are less than the specified key. Note
1780 * that this guarantees that the return value will be >= 0 if
1781 * and only if the key is found.
1782 */
1783 public static int binarySearch(long[] a, long key) {
1784 return binarySearch0(a, 0, a.length, key);
1785 }
1786
1787 /**
1788 * Searches a range of
1789 * the specified array of longs for the specified value using the
1790 * binary search algorithm.
1791 * The range must be sorted (as
1792 * by the {@link #sort(long[], int, int)} method)
1793 * prior to making this call. If it
1794 * is not sorted, the results are undefined. If the range contains
1795 * multiple elements with the specified value, there is no guarantee which
1796 * one will be found.
1797 *
1798 * @param a the array to be searched
1799 * @param fromIndex the index of the first element (inclusive) to be
1800 * searched
1801 * @param toIndex the index of the last element (exclusive) to be searched
1802 * @param key the value to be searched for
1803 * @return index of the search key, if it is contained in the array
1804 * within the specified range;
1805 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
1806 * <i>insertion point</i> is defined as the point at which the
1807 * key would be inserted into the array: the index of the first
1808 * element in the range greater than the key,
1809 * or <tt>toIndex</tt> if all
1810 * elements in the range are less than the specified key. Note
1811 * that this guarantees that the return value will be >= 0 if
1812 * and only if the key is found.
1813 * @throws IllegalArgumentException
1814 * if {@code fromIndex > toIndex}
1815 * @throws ArrayIndexOutOfBoundsException
1816 * if {@code fromIndex < 0 or toIndex > a.length}
1817 * @since 1.6
1818 */
1819 public static int binarySearch(long[] a, int fromIndex, int toIndex,
1820 long key) {
1821 rangeCheck(a.length, fromIndex, toIndex);
1822 return binarySearch0(a, fromIndex, toIndex, key);
1823 }
1824
1825 // Like public version, but without range checks.
1826 private static int binarySearch0(long[] a, int fromIndex, int toIndex,
1827 long key) {
1828 int low = fromIndex;
1829 int high = toIndex - 1;
1836 low = mid + 1;
1837 else if (midVal > key)
1838 high = mid - 1;
1839 else
1840 return mid; // key found
1841 }
1842 return -(low + 1); // key not found.
1843 }
1844
1845 /**
1846 * Searches the specified array of ints for the specified value using the
1847 * binary search algorithm. The array must be sorted (as
1848 * by the {@link #sort(int[])} method) prior to making this call. If it
1849 * is not sorted, the results are undefined. If the array contains
1850 * multiple elements with the specified value, there is no guarantee which
1851 * one will be found.
1852 *
1853 * @param a the array to be searched
1854 * @param key the value to be searched for
1855 * @return index of the search key, if it is contained in the array;
1856 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
1857 * <i>insertion point</i> is defined as the point at which the
1858 * key would be inserted into the array: the index of the first
1859 * element greater than the key, or <tt>a.length</tt> if all
1860 * elements in the array are less than the specified key. Note
1861 * that this guarantees that the return value will be >= 0 if
1862 * and only if the key is found.
1863 */
1864 public static int binarySearch(int[] a, int key) {
1865 return binarySearch0(a, 0, a.length, key);
1866 }
1867
1868 /**
1869 * Searches a range of
1870 * the specified array of ints for the specified value using the
1871 * binary search algorithm.
1872 * The range must be sorted (as
1873 * by the {@link #sort(int[], int, int)} method)
1874 * prior to making this call. If it
1875 * is not sorted, the results are undefined. If the range contains
1876 * multiple elements with the specified value, there is no guarantee which
1877 * one will be found.
1878 *
1879 * @param a the array to be searched
1880 * @param fromIndex the index of the first element (inclusive) to be
1881 * searched
1882 * @param toIndex the index of the last element (exclusive) to be searched
1883 * @param key the value to be searched for
1884 * @return index of the search key, if it is contained in the array
1885 * within the specified range;
1886 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
1887 * <i>insertion point</i> is defined as the point at which the
1888 * key would be inserted into the array: the index of the first
1889 * element in the range greater than the key,
1890 * or <tt>toIndex</tt> if all
1891 * elements in the range are less than the specified key. Note
1892 * that this guarantees that the return value will be >= 0 if
1893 * and only if the key is found.
1894 * @throws IllegalArgumentException
1895 * if {@code fromIndex > toIndex}
1896 * @throws ArrayIndexOutOfBoundsException
1897 * if {@code fromIndex < 0 or toIndex > a.length}
1898 * @since 1.6
1899 */
1900 public static int binarySearch(int[] a, int fromIndex, int toIndex,
1901 int key) {
1902 rangeCheck(a.length, fromIndex, toIndex);
1903 return binarySearch0(a, fromIndex, toIndex, key);
1904 }
1905
1906 // Like public version, but without range checks.
1907 private static int binarySearch0(int[] a, int fromIndex, int toIndex,
1908 int key) {
1909 int low = fromIndex;
1910 int high = toIndex - 1;
1917 low = mid + 1;
1918 else if (midVal > key)
1919 high = mid - 1;
1920 else
1921 return mid; // key found
1922 }
1923 return -(low + 1); // key not found.
1924 }
1925
1926 /**
1927 * Searches the specified array of shorts for the specified value using
1928 * the binary search algorithm. The array must be sorted
1929 * (as by the {@link #sort(short[])} method) prior to making this call. If
1930 * it is not sorted, the results are undefined. If the array contains
1931 * multiple elements with the specified value, there is no guarantee which
1932 * one will be found.
1933 *
1934 * @param a the array to be searched
1935 * @param key the value to be searched for
1936 * @return index of the search key, if it is contained in the array;
1937 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
1938 * <i>insertion point</i> is defined as the point at which the
1939 * key would be inserted into the array: the index of the first
1940 * element greater than the key, or <tt>a.length</tt> if all
1941 * elements in the array are less than the specified key. Note
1942 * that this guarantees that the return value will be >= 0 if
1943 * and only if the key is found.
1944 */
1945 public static int binarySearch(short[] a, short key) {
1946 return binarySearch0(a, 0, a.length, key);
1947 }
1948
1949 /**
1950 * Searches a range of
1951 * the specified array of shorts for the specified value using
1952 * the binary search algorithm.
1953 * The range must be sorted
1954 * (as by the {@link #sort(short[], int, int)} method)
1955 * prior to making this call. If
1956 * it is not sorted, the results are undefined. If the range contains
1957 * multiple elements with the specified value, there is no guarantee which
1958 * one will be found.
1959 *
1960 * @param a the array to be searched
1961 * @param fromIndex the index of the first element (inclusive) to be
1962 * searched
1963 * @param toIndex the index of the last element (exclusive) to be searched
1964 * @param key the value to be searched for
1965 * @return index of the search key, if it is contained in the array
1966 * within the specified range;
1967 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
1968 * <i>insertion point</i> is defined as the point at which the
1969 * key would be inserted into the array: the index of the first
1970 * element in the range greater than the key,
1971 * or <tt>toIndex</tt> if all
1972 * elements in the range are less than the specified key. Note
1973 * that this guarantees that the return value will be >= 0 if
1974 * and only if the key is found.
1975 * @throws IllegalArgumentException
1976 * if {@code fromIndex > toIndex}
1977 * @throws ArrayIndexOutOfBoundsException
1978 * if {@code fromIndex < 0 or toIndex > a.length}
1979 * @since 1.6
1980 */
1981 public static int binarySearch(short[] a, int fromIndex, int toIndex,
1982 short key) {
1983 rangeCheck(a.length, fromIndex, toIndex);
1984 return binarySearch0(a, fromIndex, toIndex, key);
1985 }
1986
1987 // Like public version, but without range checks.
1988 private static int binarySearch0(short[] a, int fromIndex, int toIndex,
1989 short key) {
1990 int low = fromIndex;
1991 int high = toIndex - 1;
1998 low = mid + 1;
1999 else if (midVal > key)
2000 high = mid - 1;
2001 else
2002 return mid; // key found
2003 }
2004 return -(low + 1); // key not found.
2005 }
2006
2007 /**
2008 * Searches the specified array of chars for the specified value using the
2009 * binary search algorithm. The array must be sorted (as
2010 * by the {@link #sort(char[])} method) prior to making this call. If it
2011 * is not sorted, the results are undefined. If the array contains
2012 * multiple elements with the specified value, there is no guarantee which
2013 * one will be found.
2014 *
2015 * @param a the array to be searched
2016 * @param key the value to be searched for
2017 * @return index of the search key, if it is contained in the array;
2018 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2019 * <i>insertion point</i> is defined as the point at which the
2020 * key would be inserted into the array: the index of the first
2021 * element greater than the key, or <tt>a.length</tt> if all
2022 * elements in the array are less than the specified key. Note
2023 * that this guarantees that the return value will be >= 0 if
2024 * and only if the key is found.
2025 */
2026 public static int binarySearch(char[] a, char key) {
2027 return binarySearch0(a, 0, a.length, key);
2028 }
2029
2030 /**
2031 * Searches a range of
2032 * the specified array of chars for the specified value using the
2033 * binary search algorithm.
2034 * The range must be sorted (as
2035 * by the {@link #sort(char[], int, int)} method)
2036 * prior to making this call. If it
2037 * is not sorted, the results are undefined. If the range contains
2038 * multiple elements with the specified value, there is no guarantee which
2039 * one will be found.
2040 *
2041 * @param a the array to be searched
2042 * @param fromIndex the index of the first element (inclusive) to be
2043 * searched
2044 * @param toIndex the index of the last element (exclusive) to be searched
2045 * @param key the value to be searched for
2046 * @return index of the search key, if it is contained in the array
2047 * within the specified range;
2048 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2049 * <i>insertion point</i> is defined as the point at which the
2050 * key would be inserted into the array: the index of the first
2051 * element in the range greater than the key,
2052 * or <tt>toIndex</tt> if all
2053 * elements in the range are less than the specified key. Note
2054 * that this guarantees that the return value will be >= 0 if
2055 * and only if the key is found.
2056 * @throws IllegalArgumentException
2057 * if {@code fromIndex > toIndex}
2058 * @throws ArrayIndexOutOfBoundsException
2059 * if {@code fromIndex < 0 or toIndex > a.length}
2060 * @since 1.6
2061 */
2062 public static int binarySearch(char[] a, int fromIndex, int toIndex,
2063 char key) {
2064 rangeCheck(a.length, fromIndex, toIndex);
2065 return binarySearch0(a, fromIndex, toIndex, key);
2066 }
2067
2068 // Like public version, but without range checks.
2069 private static int binarySearch0(char[] a, int fromIndex, int toIndex,
2070 char key) {
2071 int low = fromIndex;
2072 int high = toIndex - 1;
2079 low = mid + 1;
2080 else if (midVal > key)
2081 high = mid - 1;
2082 else
2083 return mid; // key found
2084 }
2085 return -(low + 1); // key not found.
2086 }
2087
2088 /**
2089 * Searches the specified array of bytes for the specified value using the
2090 * binary search algorithm. The array must be sorted (as
2091 * by the {@link #sort(byte[])} method) prior to making this call. If it
2092 * is not sorted, the results are undefined. If the array contains
2093 * multiple elements with the specified value, there is no guarantee which
2094 * one will be found.
2095 *
2096 * @param a the array to be searched
2097 * @param key the value to be searched for
2098 * @return index of the search key, if it is contained in the array;
2099 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2100 * <i>insertion point</i> is defined as the point at which the
2101 * key would be inserted into the array: the index of the first
2102 * element greater than the key, or <tt>a.length</tt> if all
2103 * elements in the array are less than the specified key. Note
2104 * that this guarantees that the return value will be >= 0 if
2105 * and only if the key is found.
2106 */
2107 public static int binarySearch(byte[] a, byte key) {
2108 return binarySearch0(a, 0, a.length, key);
2109 }
2110
2111 /**
2112 * Searches a range of
2113 * the specified array of bytes for the specified value using the
2114 * binary search algorithm.
2115 * The range must be sorted (as
2116 * by the {@link #sort(byte[], int, int)} method)
2117 * prior to making this call. If it
2118 * is not sorted, the results are undefined. If the range contains
2119 * multiple elements with the specified value, there is no guarantee which
2120 * one will be found.
2121 *
2122 * @param a the array to be searched
2123 * @param fromIndex the index of the first element (inclusive) to be
2124 * searched
2125 * @param toIndex the index of the last element (exclusive) to be searched
2126 * @param key the value to be searched for
2127 * @return index of the search key, if it is contained in the array
2128 * within the specified range;
2129 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2130 * <i>insertion point</i> is defined as the point at which the
2131 * key would be inserted into the array: the index of the first
2132 * element in the range greater than the key,
2133 * or <tt>toIndex</tt> if all
2134 * elements in the range are less than the specified key. Note
2135 * that this guarantees that the return value will be >= 0 if
2136 * and only if the key is found.
2137 * @throws IllegalArgumentException
2138 * if {@code fromIndex > toIndex}
2139 * @throws ArrayIndexOutOfBoundsException
2140 * if {@code fromIndex < 0 or toIndex > a.length}
2141 * @since 1.6
2142 */
2143 public static int binarySearch(byte[] a, int fromIndex, int toIndex,
2144 byte key) {
2145 rangeCheck(a.length, fromIndex, toIndex);
2146 return binarySearch0(a, fromIndex, toIndex, key);
2147 }
2148
2149 // Like public version, but without range checks.
2150 private static int binarySearch0(byte[] a, int fromIndex, int toIndex,
2151 byte key) {
2152 int low = fromIndex;
2153 int high = toIndex - 1;
2161 else if (midVal > key)
2162 high = mid - 1;
2163 else
2164 return mid; // key found
2165 }
2166 return -(low + 1); // key not found.
2167 }
2168
2169 /**
2170 * Searches the specified array of doubles for the specified value using
2171 * the binary search algorithm. The array must be sorted
2172 * (as by the {@link #sort(double[])} method) prior to making this call.
2173 * If it is not sorted, the results are undefined. If the array contains
2174 * multiple elements with the specified value, there is no guarantee which
2175 * one will be found. This method considers all NaN values to be
2176 * equivalent and equal.
2177 *
2178 * @param a the array to be searched
2179 * @param key the value to be searched for
2180 * @return index of the search key, if it is contained in the array;
2181 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2182 * <i>insertion point</i> is defined as the point at which the
2183 * key would be inserted into the array: the index of the first
2184 * element greater than the key, or <tt>a.length</tt> if all
2185 * elements in the array are less than the specified key. Note
2186 * that this guarantees that the return value will be >= 0 if
2187 * and only if the key is found.
2188 */
2189 public static int binarySearch(double[] a, double key) {
2190 return binarySearch0(a, 0, a.length, key);
2191 }
2192
2193 /**
2194 * Searches a range of
2195 * the specified array of doubles for the specified value using
2196 * the binary search algorithm.
2197 * The range must be sorted
2198 * (as by the {@link #sort(double[], int, int)} method)
2199 * prior to making this call.
2200 * If it is not sorted, the results are undefined. If the range contains
2201 * multiple elements with the specified value, there is no guarantee which
2202 * one will be found. This method considers all NaN values to be
2203 * equivalent and equal.
2204 *
2205 * @param a the array to be searched
2206 * @param fromIndex the index of the first element (inclusive) to be
2207 * searched
2208 * @param toIndex the index of the last element (exclusive) to be searched
2209 * @param key the value to be searched for
2210 * @return index of the search key, if it is contained in the array
2211 * within the specified range;
2212 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2213 * <i>insertion point</i> is defined as the point at which the
2214 * key would be inserted into the array: the index of the first
2215 * element in the range greater than the key,
2216 * or <tt>toIndex</tt> if all
2217 * elements in the range are less than the specified key. Note
2218 * that this guarantees that the return value will be >= 0 if
2219 * and only if the key is found.
2220 * @throws IllegalArgumentException
2221 * if {@code fromIndex > toIndex}
2222 * @throws ArrayIndexOutOfBoundsException
2223 * if {@code fromIndex < 0 or toIndex > a.length}
2224 * @since 1.6
2225 */
2226 public static int binarySearch(double[] a, int fromIndex, int toIndex,
2227 double key) {
2228 rangeCheck(a.length, fromIndex, toIndex);
2229 return binarySearch0(a, fromIndex, toIndex, key);
2230 }
2231
2232 // Like public version, but without range checks.
2233 private static int binarySearch0(double[] a, int fromIndex, int toIndex,
2234 double key) {
2235 int low = fromIndex;
2236 int high = toIndex - 1;
2252 low = mid + 1;
2253 else // (0.0, -0.0) or (NaN, !NaN)
2254 high = mid - 1;
2255 }
2256 }
2257 return -(low + 1); // key not found.
2258 }
2259
2260 /**
2261 * Searches the specified array of floats for the specified value using
2262 * the binary search algorithm. The array must be sorted
2263 * (as by the {@link #sort(float[])} method) prior to making this call. If
2264 * it is not sorted, the results are undefined. If the array contains
2265 * multiple elements with the specified value, there is no guarantee which
2266 * one will be found. This method considers all NaN values to be
2267 * equivalent and equal.
2268 *
2269 * @param a the array to be searched
2270 * @param key the value to be searched for
2271 * @return index of the search key, if it is contained in the array;
2272 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2273 * <i>insertion point</i> is defined as the point at which the
2274 * key would be inserted into the array: the index of the first
2275 * element greater than the key, or <tt>a.length</tt> if all
2276 * elements in the array are less than the specified key. Note
2277 * that this guarantees that the return value will be >= 0 if
2278 * and only if the key is found.
2279 */
2280 public static int binarySearch(float[] a, float key) {
2281 return binarySearch0(a, 0, a.length, key);
2282 }
2283
2284 /**
2285 * Searches a range of
2286 * the specified array of floats for the specified value using
2287 * the binary search algorithm.
2288 * The range must be sorted
2289 * (as by the {@link #sort(float[], int, int)} method)
2290 * prior to making this call. If
2291 * it is not sorted, the results are undefined. If the range contains
2292 * multiple elements with the specified value, there is no guarantee which
2293 * one will be found. This method considers all NaN values to be
2294 * equivalent and equal.
2295 *
2296 * @param a the array to be searched
2297 * @param fromIndex the index of the first element (inclusive) to be
2298 * searched
2299 * @param toIndex the index of the last element (exclusive) to be searched
2300 * @param key the value to be searched for
2301 * @return index of the search key, if it is contained in the array
2302 * within the specified range;
2303 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2304 * <i>insertion point</i> is defined as the point at which the
2305 * key would be inserted into the array: the index of the first
2306 * element in the range greater than the key,
2307 * or <tt>toIndex</tt> if all
2308 * elements in the range are less than the specified key. Note
2309 * that this guarantees that the return value will be >= 0 if
2310 * and only if the key is found.
2311 * @throws IllegalArgumentException
2312 * if {@code fromIndex > toIndex}
2313 * @throws ArrayIndexOutOfBoundsException
2314 * if {@code fromIndex < 0 or toIndex > a.length}
2315 * @since 1.6
2316 */
2317 public static int binarySearch(float[] a, int fromIndex, int toIndex,
2318 float key) {
2319 rangeCheck(a.length, fromIndex, toIndex);
2320 return binarySearch0(a, fromIndex, toIndex, key);
2321 }
2322
2323 // Like public version, but without range checks.
2324 private static int binarySearch0(float[] a, int fromIndex, int toIndex,
2325 float key) {
2326 int low = fromIndex;
2327 int high = toIndex - 1;
2349 }
2350
2351 /**
2352 * Searches the specified array for the specified object using the binary
2353 * search algorithm. The array must be sorted into ascending order
2354 * according to the
2355 * {@linkplain Comparable natural ordering}
2356 * of its elements (as by the
2357 * {@link #sort(Object[])} method) prior to making this call.
2358 * If it is not sorted, the results are undefined.
2359 * (If the array contains elements that are not mutually comparable (for
2360 * example, strings and integers), it <i>cannot</i> be sorted according
2361 * to the natural ordering of its elements, hence results are undefined.)
2362 * If the array contains multiple
2363 * elements equal to the specified object, there is no guarantee which
2364 * one will be found.
2365 *
2366 * @param a the array to be searched
2367 * @param key the value to be searched for
2368 * @return index of the search key, if it is contained in the array;
2369 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2370 * <i>insertion point</i> is defined as the point at which the
2371 * key would be inserted into the array: the index of the first
2372 * element greater than the key, or <tt>a.length</tt> if all
2373 * elements in the array are less than the specified key. Note
2374 * that this guarantees that the return value will be >= 0 if
2375 * and only if the key is found.
2376 * @throws ClassCastException if the search key is not comparable to the
2377 * elements of the array.
2378 */
2379 public static int binarySearch(Object[] a, Object key) {
2380 return binarySearch0(a, 0, a.length, key);
2381 }
2382
2383 /**
2384 * Searches a range of
2385 * the specified array for the specified object using the binary
2386 * search algorithm.
2387 * The range must be sorted into ascending order
2388 * according to the
2389 * {@linkplain Comparable natural ordering}
2390 * of its elements (as by the
2391 * {@link #sort(Object[], int, int)} method) prior to making this
2392 * call. If it is not sorted, the results are undefined.
2393 * (If the range contains elements that are not mutually comparable (for
2394 * example, strings and integers), it <i>cannot</i> be sorted according
2395 * to the natural ordering of its elements, hence results are undefined.)
2396 * If the range contains multiple
2397 * elements equal to the specified object, there is no guarantee which
2398 * one will be found.
2399 *
2400 * @param a the array to be searched
2401 * @param fromIndex the index of the first element (inclusive) to be
2402 * searched
2403 * @param toIndex the index of the last element (exclusive) to be searched
2404 * @param key the value to be searched for
2405 * @return index of the search key, if it is contained in the array
2406 * within the specified range;
2407 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2408 * <i>insertion point</i> is defined as the point at which the
2409 * key would be inserted into the array: the index of the first
2410 * element in the range greater than the key,
2411 * or <tt>toIndex</tt> if all
2412 * elements in the range are less than the specified key. Note
2413 * that this guarantees that the return value will be >= 0 if
2414 * and only if the key is found.
2415 * @throws ClassCastException if the search key is not comparable to the
2416 * elements of the array within the specified range.
2417 * @throws IllegalArgumentException
2418 * if {@code fromIndex > toIndex}
2419 * @throws ArrayIndexOutOfBoundsException
2420 * if {@code fromIndex < 0 or toIndex > a.length}
2421 * @since 1.6
2422 */
2423 public static int binarySearch(Object[] a, int fromIndex, int toIndex,
2424 Object key) {
2425 rangeCheck(a.length, fromIndex, toIndex);
2426 return binarySearch0(a, fromIndex, toIndex, key);
2427 }
2428
2429 // Like public version, but without range checks.
2430 private static int binarySearch0(Object[] a, int fromIndex, int toIndex,
2431 Object key) {
2447 return mid; // key found
2448 }
2449 return -(low + 1); // key not found.
2450 }
2451
2452 /**
2453 * Searches the specified array for the specified object using the binary
2454 * search algorithm. The array must be sorted into ascending order
2455 * according to the specified comparator (as by the
2456 * {@link #sort(Object[], Comparator) sort(T[], Comparator)}
2457 * method) prior to making this call. If it is
2458 * not sorted, the results are undefined.
2459 * If the array contains multiple
2460 * elements equal to the specified object, there is no guarantee which one
2461 * will be found.
2462 *
2463 * @param <T> the class of the objects in the array
2464 * @param a the array to be searched
2465 * @param key the value to be searched for
2466 * @param c the comparator by which the array is ordered. A
2467 * <tt>null</tt> value indicates that the elements'
2468 * {@linkplain Comparable natural ordering} should be used.
2469 * @return index of the search key, if it is contained in the array;
2470 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2471 * <i>insertion point</i> is defined as the point at which the
2472 * key would be inserted into the array: the index of the first
2473 * element greater than the key, or <tt>a.length</tt> if all
2474 * elements in the array are less than the specified key. Note
2475 * that this guarantees that the return value will be >= 0 if
2476 * and only if the key is found.
2477 * @throws ClassCastException if the array contains elements that are not
2478 * <i>mutually comparable</i> using the specified comparator,
2479 * or the search key is not comparable to the
2480 * elements of the array using this comparator.
2481 */
2482 public static <T> int binarySearch(T[] a, T key, Comparator<? super T> c) {
2483 return binarySearch0(a, 0, a.length, key, c);
2484 }
2485
2486 /**
2487 * Searches a range of
2488 * the specified array for the specified object using the binary
2489 * search algorithm.
2490 * The range must be sorted into ascending order
2491 * according to the specified comparator (as by the
2492 * {@link #sort(Object[], int, int, Comparator)
2493 * sort(T[], int, int, Comparator)}
2494 * method) prior to making this call.
2495 * If it is not sorted, the results are undefined.
2496 * If the range contains multiple elements equal to the specified object,
2497 * there is no guarantee which one will be found.
2498 *
2499 * @param <T> the class of the objects in the array
2500 * @param a the array to be searched
2501 * @param fromIndex the index of the first element (inclusive) to be
2502 * searched
2503 * @param toIndex the index of the last element (exclusive) to be searched
2504 * @param key the value to be searched for
2505 * @param c the comparator by which the array is ordered. A
2506 * <tt>null</tt> value indicates that the elements'
2507 * {@linkplain Comparable natural ordering} should be used.
2508 * @return index of the search key, if it is contained in the array
2509 * within the specified range;
2510 * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
2511 * <i>insertion point</i> is defined as the point at which the
2512 * key would be inserted into the array: the index of the first
2513 * element in the range greater than the key,
2514 * or <tt>toIndex</tt> if all
2515 * elements in the range are less than the specified key. Note
2516 * that this guarantees that the return value will be >= 0 if
2517 * and only if the key is found.
2518 * @throws ClassCastException if the range contains elements that are not
2519 * <i>mutually comparable</i> using the specified comparator,
2520 * or the search key is not comparable to the
2521 * elements in the range using this comparator.
2522 * @throws IllegalArgumentException
2523 * if {@code fromIndex > toIndex}
2524 * @throws ArrayIndexOutOfBoundsException
2525 * if {@code fromIndex < 0 or toIndex > a.length}
2526 * @since 1.6
2527 */
2528 public static <T> int binarySearch(T[] a, int fromIndex, int toIndex,
2529 T key, Comparator<? super T> c) {
2530 rangeCheck(a.length, fromIndex, toIndex);
2531 return binarySearch0(a, fromIndex, toIndex, key, c);
2532 }
2533
2534 // Like public version, but without range checks.
2540 int low = fromIndex;
2541 int high = toIndex - 1;
2542
2543 while (low <= high) {
2544 int mid = (low + high) >>> 1;
2545 T midVal = a[mid];
2546 int cmp = c.compare(midVal, key);
2547 if (cmp < 0)
2548 low = mid + 1;
2549 else if (cmp > 0)
2550 high = mid - 1;
2551 else
2552 return mid; // key found
2553 }
2554 return -(low + 1); // key not found.
2555 }
2556
2557 // Equality Testing
2558
2559 /**
2560 * Returns <tt>true</tt> if the two specified arrays of longs are
2561 * <i>equal</i> to one another. Two arrays are considered equal if both
2562 * arrays contain the same number of elements, and all corresponding pairs
2563 * of elements in the two arrays are equal. In other words, two arrays
2564 * are equal if they contain the same elements in the same order. Also,
2565 * two array references are considered equal if both are <tt>null</tt>.
2566 *
2567 * @param a one array to be tested for equality
2568 * @param a2 the other array to be tested for equality
2569 * @return <tt>true</tt> if the two arrays are equal
2570 */
2571 public static boolean equals(long[] a, long[] a2) {
2572 if (a==a2)
2573 return true;
2574 if (a==null || a2==null)
2575 return false;
2576
2577 int length = a.length;
2578 if (a2.length != length)
2579 return false;
2580
2581 for (int i=0; i<length; i++)
2582 if (a[i] != a2[i])
2583 return false;
2584
2585 return true;
2586 }
2587
2588 /**
2589 * Returns <tt>true</tt> if the two specified arrays of ints are
2590 * <i>equal</i> to one another. Two arrays are considered equal if both
2591 * arrays contain the same number of elements, and all corresponding pairs
2592 * of elements in the two arrays are equal. In other words, two arrays
2593 * are equal if they contain the same elements in the same order. Also,
2594 * two array references are considered equal if both are <tt>null</tt>.
2595 *
2596 * @param a one array to be tested for equality
2597 * @param a2 the other array to be tested for equality
2598 * @return <tt>true</tt> if the two arrays are equal
2599 */
2600 public static boolean equals(int[] a, int[] a2) {
2601 if (a==a2)
2602 return true;
2603 if (a==null || a2==null)
2604 return false;
2605
2606 int length = a.length;
2607 if (a2.length != length)
2608 return false;
2609
2610 for (int i=0; i<length; i++)
2611 if (a[i] != a2[i])
2612 return false;
2613
2614 return true;
2615 }
2616
2617 /**
2618 * Returns <tt>true</tt> if the two specified arrays of shorts are
2619 * <i>equal</i> to one another. Two arrays are considered equal if both
2620 * arrays contain the same number of elements, and all corresponding pairs
2621 * of elements in the two arrays are equal. In other words, two arrays
2622 * are equal if they contain the same elements in the same order. Also,
2623 * two array references are considered equal if both are <tt>null</tt>.
2624 *
2625 * @param a one array to be tested for equality
2626 * @param a2 the other array to be tested for equality
2627 * @return <tt>true</tt> if the two arrays are equal
2628 */
2629 public static boolean equals(short[] a, short a2[]) {
2630 if (a==a2)
2631 return true;
2632 if (a==null || a2==null)
2633 return false;
2634
2635 int length = a.length;
2636 if (a2.length != length)
2637 return false;
2638
2639 for (int i=0; i<length; i++)
2640 if (a[i] != a2[i])
2641 return false;
2642
2643 return true;
2644 }
2645
2646 /**
2647 * Returns <tt>true</tt> if the two specified arrays of chars are
2648 * <i>equal</i> to one another. Two arrays are considered equal if both
2649 * arrays contain the same number of elements, and all corresponding pairs
2650 * of elements in the two arrays are equal. In other words, two arrays
2651 * are equal if they contain the same elements in the same order. Also,
2652 * two array references are considered equal if both are <tt>null</tt>.
2653 *
2654 * @param a one array to be tested for equality
2655 * @param a2 the other array to be tested for equality
2656 * @return <tt>true</tt> if the two arrays are equal
2657 */
2658 @HotSpotIntrinsicCandidate
2659 public static boolean equals(char[] a, char[] a2) {
2660 if (a==a2)
2661 return true;
2662 if (a==null || a2==null)
2663 return false;
2664
2665 int length = a.length;
2666 if (a2.length != length)
2667 return false;
2668
2669 for (int i=0; i<length; i++)
2670 if (a[i] != a2[i])
2671 return false;
2672
2673 return true;
2674 }
2675
2676 /**
2677 * Returns <tt>true</tt> if the two specified arrays of bytes are
2678 * <i>equal</i> to one another. Two arrays are considered equal if both
2679 * arrays contain the same number of elements, and all corresponding pairs
2680 * of elements in the two arrays are equal. In other words, two arrays
2681 * are equal if they contain the same elements in the same order. Also,
2682 * two array references are considered equal if both are <tt>null</tt>.
2683 *
2684 * @param a one array to be tested for equality
2685 * @param a2 the other array to be tested for equality
2686 * @return <tt>true</tt> if the two arrays are equal
2687 */
2688 public static boolean equals(byte[] a, byte[] a2) {
2689 if (a==a2)
2690 return true;
2691 if (a==null || a2==null)
2692 return false;
2693
2694 int length = a.length;
2695 if (a2.length != length)
2696 return false;
2697
2698 for (int i=0; i<length; i++)
2699 if (a[i] != a2[i])
2700 return false;
2701
2702 return true;
2703 }
2704
2705 /**
2706 * Returns <tt>true</tt> if the two specified arrays of booleans are
2707 * <i>equal</i> to one another. Two arrays are considered equal if both
2708 * arrays contain the same number of elements, and all corresponding pairs
2709 * of elements in the two arrays are equal. In other words, two arrays
2710 * are equal if they contain the same elements in the same order. Also,
2711 * two array references are considered equal if both are <tt>null</tt>.
2712 *
2713 * @param a one array to be tested for equality
2714 * @param a2 the other array to be tested for equality
2715 * @return <tt>true</tt> if the two arrays are equal
2716 */
2717 public static boolean equals(boolean[] a, boolean[] a2) {
2718 if (a==a2)
2719 return true;
2720 if (a==null || a2==null)
2721 return false;
2722
2723 int length = a.length;
2724 if (a2.length != length)
2725 return false;
2726
2727 for (int i=0; i<length; i++)
2728 if (a[i] != a2[i])
2729 return false;
2730
2731 return true;
2732 }
2733
2734 /**
2735 * Returns <tt>true</tt> if the two specified arrays of doubles are
2736 * <i>equal</i> to one another. Two arrays are considered equal if both
2737 * arrays contain the same number of elements, and all corresponding pairs
2738 * of elements in the two arrays are equal. In other words, two arrays
2739 * are equal if they contain the same elements in the same order. Also,
2740 * two array references are considered equal if both are <tt>null</tt>.
2741 *
2742 * Two doubles <tt>d1</tt> and <tt>d2</tt> are considered equal if:
2743 * <pre> <tt>new Double(d1).equals(new Double(d2))</tt></pre>
2744 * (Unlike the <tt>==</tt> operator, this method considers
2745 * <tt>NaN</tt> equals to itself, and 0.0d unequal to -0.0d.)
2746 *
2747 * @param a one array to be tested for equality
2748 * @param a2 the other array to be tested for equality
2749 * @return <tt>true</tt> if the two arrays are equal
2750 * @see Double#equals(Object)
2751 */
2752 public static boolean equals(double[] a, double[] a2) {
2753 if (a==a2)
2754 return true;
2755 if (a==null || a2==null)
2756 return false;
2757
2758 int length = a.length;
2759 if (a2.length != length)
2760 return false;
2761
2762 for (int i=0; i<length; i++)
2763 if (Double.doubleToLongBits(a[i])!=Double.doubleToLongBits(a2[i]))
2764 return false;
2765
2766 return true;
2767 }
2768
2769 /**
2770 * Returns <tt>true</tt> if the two specified arrays of floats are
2771 * <i>equal</i> to one another. Two arrays are considered equal if both
2772 * arrays contain the same number of elements, and all corresponding pairs
2773 * of elements in the two arrays are equal. In other words, two arrays
2774 * are equal if they contain the same elements in the same order. Also,
2775 * two array references are considered equal if both are <tt>null</tt>.
2776 *
2777 * Two floats <tt>f1</tt> and <tt>f2</tt> are considered equal if:
2778 * <pre> <tt>new Float(f1).equals(new Float(f2))</tt></pre>
2779 * (Unlike the <tt>==</tt> operator, this method considers
2780 * <tt>NaN</tt> equals to itself, and 0.0f unequal to -0.0f.)
2781 *
2782 * @param a one array to be tested for equality
2783 * @param a2 the other array to be tested for equality
2784 * @return <tt>true</tt> if the two arrays are equal
2785 * @see Float#equals(Object)
2786 */
2787 public static boolean equals(float[] a, float[] a2) {
2788 if (a==a2)
2789 return true;
2790 if (a==null || a2==null)
2791 return false;
2792
2793 int length = a.length;
2794 if (a2.length != length)
2795 return false;
2796
2797 for (int i=0; i<length; i++)
2798 if (Float.floatToIntBits(a[i])!=Float.floatToIntBits(a2[i]))
2799 return false;
2800
2801 return true;
2802 }
2803
2804 /**
2805 * Returns <tt>true</tt> if the two specified arrays of Objects are
2806 * <i>equal</i> to one another. The two arrays are considered equal if
2807 * both arrays contain the same number of elements, and all corresponding
2808 * pairs of elements in the two arrays are equal. Two objects <tt>e1</tt>
2809 * and <tt>e2</tt> are considered <i>equal</i> if <tt>(e1==null ? e2==null
2810 * : e1.equals(e2))</tt>. In other words, the two arrays are equal if
2811 * they contain the same elements in the same order. Also, two array
2812 * references are considered equal if both are <tt>null</tt>.
2813 *
2814 * @param a one array to be tested for equality
2815 * @param a2 the other array to be tested for equality
2816 * @return <tt>true</tt> if the two arrays are equal
2817 */
2818 public static boolean equals(Object[] a, Object[] a2) {
2819 if (a==a2)
2820 return true;
2821 if (a==null || a2==null)
2822 return false;
2823
2824 int length = a.length;
2825 if (a2.length != length)
2826 return false;
2827
2828 for (int i=0; i<length; i++) {
2829 Object o1 = a[i];
2830 Object o2 = a2[i];
2831 if (!(o1==null ? o2==null : o1.equals(o2)))
2832 return false;
2833 }
2834
2835 return true;
2836 }
2837
2838 // Filling
2839
2840 /**
2841 * Assigns the specified long value to each element of the specified array
2842 * of longs.
2843 *
2844 * @param a the array to be filled
2845 * @param val the value to be stored in all elements of the array
2846 */
2847 public static void fill(long[] a, long val) {
2848 for (int i = 0, len = a.length; i < len; i++)
2849 a[i] = val;
2850 }
2851
2852 /**
2853 * Assigns the specified long value to each element of the specified
2854 * range of the specified array of longs. The range to be filled
2855 * extends from index <tt>fromIndex</tt>, inclusive, to index
2856 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
2857 * range to be filled is empty.)
2858 *
2859 * @param a the array to be filled
2860 * @param fromIndex the index of the first element (inclusive) to be
2861 * filled with the specified value
2862 * @param toIndex the index of the last element (exclusive) to be
2863 * filled with the specified value
2864 * @param val the value to be stored in all elements of the array
2865 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
2866 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
2867 * <tt>toIndex > a.length</tt>
2868 */
2869 public static void fill(long[] a, int fromIndex, int toIndex, long val) {
2870 rangeCheck(a.length, fromIndex, toIndex);
2871 for (int i = fromIndex; i < toIndex; i++)
2872 a[i] = val;
2873 }
2874
2875 /**
2876 * Assigns the specified int value to each element of the specified array
2877 * of ints.
2878 *
2879 * @param a the array to be filled
2880 * @param val the value to be stored in all elements of the array
2881 */
2882 public static void fill(int[] a, int val) {
2883 for (int i = 0, len = a.length; i < len; i++)
2884 a[i] = val;
2885 }
2886
2887 /**
2888 * Assigns the specified int value to each element of the specified
2889 * range of the specified array of ints. The range to be filled
2890 * extends from index <tt>fromIndex</tt>, inclusive, to index
2891 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
2892 * range to be filled is empty.)
2893 *
2894 * @param a the array to be filled
2895 * @param fromIndex the index of the first element (inclusive) to be
2896 * filled with the specified value
2897 * @param toIndex the index of the last element (exclusive) to be
2898 * filled with the specified value
2899 * @param val the value to be stored in all elements of the array
2900 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
2901 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
2902 * <tt>toIndex > a.length</tt>
2903 */
2904 public static void fill(int[] a, int fromIndex, int toIndex, int val) {
2905 rangeCheck(a.length, fromIndex, toIndex);
2906 for (int i = fromIndex; i < toIndex; i++)
2907 a[i] = val;
2908 }
2909
2910 /**
2911 * Assigns the specified short value to each element of the specified array
2912 * of shorts.
2913 *
2914 * @param a the array to be filled
2915 * @param val the value to be stored in all elements of the array
2916 */
2917 public static void fill(short[] a, short val) {
2918 for (int i = 0, len = a.length; i < len; i++)
2919 a[i] = val;
2920 }
2921
2922 /**
2923 * Assigns the specified short value to each element of the specified
2924 * range of the specified array of shorts. The range to be filled
2925 * extends from index <tt>fromIndex</tt>, inclusive, to index
2926 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
2927 * range to be filled is empty.)
2928 *
2929 * @param a the array to be filled
2930 * @param fromIndex the index of the first element (inclusive) to be
2931 * filled with the specified value
2932 * @param toIndex the index of the last element (exclusive) to be
2933 * filled with the specified value
2934 * @param val the value to be stored in all elements of the array
2935 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
2936 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
2937 * <tt>toIndex > a.length</tt>
2938 */
2939 public static void fill(short[] a, int fromIndex, int toIndex, short val) {
2940 rangeCheck(a.length, fromIndex, toIndex);
2941 for (int i = fromIndex; i < toIndex; i++)
2942 a[i] = val;
2943 }
2944
2945 /**
2946 * Assigns the specified char value to each element of the specified array
2947 * of chars.
2948 *
2949 * @param a the array to be filled
2950 * @param val the value to be stored in all elements of the array
2951 */
2952 public static void fill(char[] a, char val) {
2953 for (int i = 0, len = a.length; i < len; i++)
2954 a[i] = val;
2955 }
2956
2957 /**
2958 * Assigns the specified char value to each element of the specified
2959 * range of the specified array of chars. The range to be filled
2960 * extends from index <tt>fromIndex</tt>, inclusive, to index
2961 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
2962 * range to be filled is empty.)
2963 *
2964 * @param a the array to be filled
2965 * @param fromIndex the index of the first element (inclusive) to be
2966 * filled with the specified value
2967 * @param toIndex the index of the last element (exclusive) to be
2968 * filled with the specified value
2969 * @param val the value to be stored in all elements of the array
2970 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
2971 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
2972 * <tt>toIndex > a.length</tt>
2973 */
2974 public static void fill(char[] a, int fromIndex, int toIndex, char val) {
2975 rangeCheck(a.length, fromIndex, toIndex);
2976 for (int i = fromIndex; i < toIndex; i++)
2977 a[i] = val;
2978 }
2979
2980 /**
2981 * Assigns the specified byte value to each element of the specified array
2982 * of bytes.
2983 *
2984 * @param a the array to be filled
2985 * @param val the value to be stored in all elements of the array
2986 */
2987 public static void fill(byte[] a, byte val) {
2988 for (int i = 0, len = a.length; i < len; i++)
2989 a[i] = val;
2990 }
2991
2992 /**
2993 * Assigns the specified byte value to each element of the specified
2994 * range of the specified array of bytes. The range to be filled
2995 * extends from index <tt>fromIndex</tt>, inclusive, to index
2996 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
2997 * range to be filled is empty.)
2998 *
2999 * @param a the array to be filled
3000 * @param fromIndex the index of the first element (inclusive) to be
3001 * filled with the specified value
3002 * @param toIndex the index of the last element (exclusive) to be
3003 * filled with the specified value
3004 * @param val the value to be stored in all elements of the array
3005 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
3006 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
3007 * <tt>toIndex > a.length</tt>
3008 */
3009 public static void fill(byte[] a, int fromIndex, int toIndex, byte val) {
3010 rangeCheck(a.length, fromIndex, toIndex);
3011 for (int i = fromIndex; i < toIndex; i++)
3012 a[i] = val;
3013 }
3014
3015 /**
3016 * Assigns the specified boolean value to each element of the specified
3017 * array of booleans.
3018 *
3019 * @param a the array to be filled
3020 * @param val the value to be stored in all elements of the array
3021 */
3022 public static void fill(boolean[] a, boolean val) {
3023 for (int i = 0, len = a.length; i < len; i++)
3024 a[i] = val;
3025 }
3026
3027 /**
3028 * Assigns the specified boolean value to each element of the specified
3029 * range of the specified array of booleans. The range to be filled
3030 * extends from index <tt>fromIndex</tt>, inclusive, to index
3031 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
3032 * range to be filled is empty.)
3033 *
3034 * @param a the array to be filled
3035 * @param fromIndex the index of the first element (inclusive) to be
3036 * filled with the specified value
3037 * @param toIndex the index of the last element (exclusive) to be
3038 * filled with the specified value
3039 * @param val the value to be stored in all elements of the array
3040 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
3041 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
3042 * <tt>toIndex > a.length</tt>
3043 */
3044 public static void fill(boolean[] a, int fromIndex, int toIndex,
3045 boolean val) {
3046 rangeCheck(a.length, fromIndex, toIndex);
3047 for (int i = fromIndex; i < toIndex; i++)
3048 a[i] = val;
3049 }
3050
3051 /**
3052 * Assigns the specified double value to each element of the specified
3053 * array of doubles.
3054 *
3055 * @param a the array to be filled
3056 * @param val the value to be stored in all elements of the array
3057 */
3058 public static void fill(double[] a, double val) {
3059 for (int i = 0, len = a.length; i < len; i++)
3060 a[i] = val;
3061 }
3062
3063 /**
3064 * Assigns the specified double value to each element of the specified
3065 * range of the specified array of doubles. The range to be filled
3066 * extends from index <tt>fromIndex</tt>, inclusive, to index
3067 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
3068 * range to be filled is empty.)
3069 *
3070 * @param a the array to be filled
3071 * @param fromIndex the index of the first element (inclusive) to be
3072 * filled with the specified value
3073 * @param toIndex the index of the last element (exclusive) to be
3074 * filled with the specified value
3075 * @param val the value to be stored in all elements of the array
3076 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
3077 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
3078 * <tt>toIndex > a.length</tt>
3079 */
3080 public static void fill(double[] a, int fromIndex, int toIndex,double val){
3081 rangeCheck(a.length, fromIndex, toIndex);
3082 for (int i = fromIndex; i < toIndex; i++)
3083 a[i] = val;
3084 }
3085
3086 /**
3087 * Assigns the specified float value to each element of the specified array
3088 * of floats.
3089 *
3090 * @param a the array to be filled
3091 * @param val the value to be stored in all elements of the array
3092 */
3093 public static void fill(float[] a, float val) {
3094 for (int i = 0, len = a.length; i < len; i++)
3095 a[i] = val;
3096 }
3097
3098 /**
3099 * Assigns the specified float value to each element of the specified
3100 * range of the specified array of floats. The range to be filled
3101 * extends from index <tt>fromIndex</tt>, inclusive, to index
3102 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
3103 * range to be filled is empty.)
3104 *
3105 * @param a the array to be filled
3106 * @param fromIndex the index of the first element (inclusive) to be
3107 * filled with the specified value
3108 * @param toIndex the index of the last element (exclusive) to be
3109 * filled with the specified value
3110 * @param val the value to be stored in all elements of the array
3111 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
3112 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
3113 * <tt>toIndex > a.length</tt>
3114 */
3115 public static void fill(float[] a, int fromIndex, int toIndex, float val) {
3116 rangeCheck(a.length, fromIndex, toIndex);
3117 for (int i = fromIndex; i < toIndex; i++)
3118 a[i] = val;
3119 }
3120
3121 /**
3122 * Assigns the specified Object reference to each element of the specified
3123 * array of Objects.
3124 *
3125 * @param a the array to be filled
3126 * @param val the value to be stored in all elements of the array
3127 * @throws ArrayStoreException if the specified value is not of a
3128 * runtime type that can be stored in the specified array
3129 */
3130 public static void fill(Object[] a, Object val) {
3131 for (int i = 0, len = a.length; i < len; i++)
3132 a[i] = val;
3133 }
3134
3135 /**
3136 * Assigns the specified Object reference to each element of the specified
3137 * range of the specified array of Objects. The range to be filled
3138 * extends from index <tt>fromIndex</tt>, inclusive, to index
3139 * <tt>toIndex</tt>, exclusive. (If <tt>fromIndex==toIndex</tt>, the
3140 * range to be filled is empty.)
3141 *
3142 * @param a the array to be filled
3143 * @param fromIndex the index of the first element (inclusive) to be
3144 * filled with the specified value
3145 * @param toIndex the index of the last element (exclusive) to be
3146 * filled with the specified value
3147 * @param val the value to be stored in all elements of the array
3148 * @throws IllegalArgumentException if <tt>fromIndex > toIndex</tt>
3149 * @throws ArrayIndexOutOfBoundsException if <tt>fromIndex < 0</tt> or
3150 * <tt>toIndex > a.length</tt>
3151 * @throws ArrayStoreException if the specified value is not of a
3152 * runtime type that can be stored in the specified array
3153 */
3154 public static void fill(Object[] a, int fromIndex, int toIndex, Object val) {
3155 rangeCheck(a.length, fromIndex, toIndex);
3156 for (int i = fromIndex; i < toIndex; i++)
3157 a[i] = val;
3158 }
3159
3160 // Cloning
3161
3162 /**
3163 * Copies the specified array, truncating or padding with nulls (if necessary)
3164 * so the copy has the specified length. For all indices that are
3165 * valid in both the original array and the copy, the two arrays will
3166 * contain identical values. For any indices that are valid in the
3167 * copy but not the original, the copy will contain <tt>null</tt>.
3168 * Such indices will exist if and only if the specified length
3169 * is greater than that of the original array.
3170 * The resulting array is of exactly the same class as the original array.
3171 *
3172 * @param <T> the class of the objects in the array
3173 * @param original the array to be copied
3174 * @param newLength the length of the copy to be returned
3175 * @return a copy of the original array, truncated or padded with nulls
3176 * to obtain the specified length
3177 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3178 * @throws NullPointerException if <tt>original</tt> is null
3179 * @since 1.6
3180 */
3181 @SuppressWarnings("unchecked")
3182 public static <T> T[] copyOf(T[] original, int newLength) {
3183 return (T[]) copyOf(original, newLength, original.getClass());
3184 }
3185
3186 /**
3187 * Copies the specified array, truncating or padding with nulls (if necessary)
3188 * so the copy has the specified length. For all indices that are
3189 * valid in both the original array and the copy, the two arrays will
3190 * contain identical values. For any indices that are valid in the
3191 * copy but not the original, the copy will contain <tt>null</tt>.
3192 * Such indices will exist if and only if the specified length
3193 * is greater than that of the original array.
3194 * The resulting array is of the class <tt>newType</tt>.
3195 *
3196 * @param <U> the class of the objects in the original array
3197 * @param <T> the class of the objects in the returned array
3198 * @param original the array to be copied
3199 * @param newLength the length of the copy to be returned
3200 * @param newType the class of the copy to be returned
3201 * @return a copy of the original array, truncated or padded with nulls
3202 * to obtain the specified length
3203 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3204 * @throws NullPointerException if <tt>original</tt> is null
3205 * @throws ArrayStoreException if an element copied from
3206 * <tt>original</tt> is not of a runtime type that can be stored in
3207 * an array of class <tt>newType</tt>
3208 * @since 1.6
3209 */
3210 @HotSpotIntrinsicCandidate
3211 public static <T,U> T[] copyOf(U[] original, int newLength, Class<? extends T[]> newType) {
3212 @SuppressWarnings("unchecked")
3213 T[] copy = ((Object)newType == (Object)Object[].class)
3214 ? (T[]) new Object[newLength]
3215 : (T[]) Array.newInstance(newType.getComponentType(), newLength);
3216 System.arraycopy(original, 0, copy, 0,
3217 Math.min(original.length, newLength));
3218 return copy;
3219 }
3220
3221 /**
3222 * Copies the specified array, truncating or padding with zeros (if necessary)
3223 * so the copy has the specified length. For all indices that are
3224 * valid in both the original array and the copy, the two arrays will
3225 * contain identical values. For any indices that are valid in the
3226 * copy but not the original, the copy will contain <tt>(byte)0</tt>.
3227 * Such indices will exist if and only if the specified length
3228 * is greater than that of the original array.
3229 *
3230 * @param original the array to be copied
3231 * @param newLength the length of the copy to be returned
3232 * @return a copy of the original array, truncated or padded with zeros
3233 * to obtain the specified length
3234 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3235 * @throws NullPointerException if <tt>original</tt> is null
3236 * @since 1.6
3237 */
3238 public static byte[] copyOf(byte[] original, int newLength) {
3239 byte[] copy = new byte[newLength];
3240 System.arraycopy(original, 0, copy, 0,
3241 Math.min(original.length, newLength));
3242 return copy;
3243 }
3244
3245 /**
3246 * Copies the specified array, truncating or padding with zeros (if necessary)
3247 * so the copy has the specified length. For all indices that are
3248 * valid in both the original array and the copy, the two arrays will
3249 * contain identical values. For any indices that are valid in the
3250 * copy but not the original, the copy will contain <tt>(short)0</tt>.
3251 * Such indices will exist if and only if the specified length
3252 * is greater than that of the original array.
3253 *
3254 * @param original the array to be copied
3255 * @param newLength the length of the copy to be returned
3256 * @return a copy of the original array, truncated or padded with zeros
3257 * to obtain the specified length
3258 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3259 * @throws NullPointerException if <tt>original</tt> is null
3260 * @since 1.6
3261 */
3262 public static short[] copyOf(short[] original, int newLength) {
3263 short[] copy = new short[newLength];
3264 System.arraycopy(original, 0, copy, 0,
3265 Math.min(original.length, newLength));
3266 return copy;
3267 }
3268
3269 /**
3270 * Copies the specified array, truncating or padding with zeros (if necessary)
3271 * so the copy has the specified length. For all indices that are
3272 * valid in both the original array and the copy, the two arrays will
3273 * contain identical values. For any indices that are valid in the
3274 * copy but not the original, the copy will contain <tt>0</tt>.
3275 * Such indices will exist if and only if the specified length
3276 * is greater than that of the original array.
3277 *
3278 * @param original the array to be copied
3279 * @param newLength the length of the copy to be returned
3280 * @return a copy of the original array, truncated or padded with zeros
3281 * to obtain the specified length
3282 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3283 * @throws NullPointerException if <tt>original</tt> is null
3284 * @since 1.6
3285 */
3286 public static int[] copyOf(int[] original, int newLength) {
3287 int[] copy = new int[newLength];
3288 System.arraycopy(original, 0, copy, 0,
3289 Math.min(original.length, newLength));
3290 return copy;
3291 }
3292
3293 /**
3294 * Copies the specified array, truncating or padding with zeros (if necessary)
3295 * so the copy has the specified length. For all indices that are
3296 * valid in both the original array and the copy, the two arrays will
3297 * contain identical values. For any indices that are valid in the
3298 * copy but not the original, the copy will contain <tt>0L</tt>.
3299 * Such indices will exist if and only if the specified length
3300 * is greater than that of the original array.
3301 *
3302 * @param original the array to be copied
3303 * @param newLength the length of the copy to be returned
3304 * @return a copy of the original array, truncated or padded with zeros
3305 * to obtain the specified length
3306 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3307 * @throws NullPointerException if <tt>original</tt> is null
3308 * @since 1.6
3309 */
3310 public static long[] copyOf(long[] original, int newLength) {
3311 long[] copy = new long[newLength];
3312 System.arraycopy(original, 0, copy, 0,
3313 Math.min(original.length, newLength));
3314 return copy;
3315 }
3316
3317 /**
3318 * Copies the specified array, truncating or padding with null characters (if necessary)
3319 * so the copy has the specified length. For all indices that are valid
3320 * in both the original array and the copy, the two arrays will contain
3321 * identical values. For any indices that are valid in the copy but not
3322 * the original, the copy will contain <tt>'\\u000'</tt>. Such indices
3323 * will exist if and only if the specified length is greater than that of
3324 * the original array.
3325 *
3326 * @param original the array to be copied
3327 * @param newLength the length of the copy to be returned
3328 * @return a copy of the original array, truncated or padded with null characters
3329 * to obtain the specified length
3330 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3331 * @throws NullPointerException if <tt>original</tt> is null
3332 * @since 1.6
3333 */
3334 public static char[] copyOf(char[] original, int newLength) {
3335 char[] copy = new char[newLength];
3336 System.arraycopy(original, 0, copy, 0,
3337 Math.min(original.length, newLength));
3338 return copy;
3339 }
3340
3341 /**
3342 * Copies the specified array, truncating or padding with zeros (if necessary)
3343 * so the copy has the specified length. For all indices that are
3344 * valid in both the original array and the copy, the two arrays will
3345 * contain identical values. For any indices that are valid in the
3346 * copy but not the original, the copy will contain <tt>0f</tt>.
3347 * Such indices will exist if and only if the specified length
3348 * is greater than that of the original array.
3349 *
3350 * @param original the array to be copied
3351 * @param newLength the length of the copy to be returned
3352 * @return a copy of the original array, truncated or padded with zeros
3353 * to obtain the specified length
3354 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3355 * @throws NullPointerException if <tt>original</tt> is null
3356 * @since 1.6
3357 */
3358 public static float[] copyOf(float[] original, int newLength) {
3359 float[] copy = new float[newLength];
3360 System.arraycopy(original, 0, copy, 0,
3361 Math.min(original.length, newLength));
3362 return copy;
3363 }
3364
3365 /**
3366 * Copies the specified array, truncating or padding with zeros (if necessary)
3367 * so the copy has the specified length. For all indices that are
3368 * valid in both the original array and the copy, the two arrays will
3369 * contain identical values. For any indices that are valid in the
3370 * copy but not the original, the copy will contain <tt>0d</tt>.
3371 * Such indices will exist if and only if the specified length
3372 * is greater than that of the original array.
3373 *
3374 * @param original the array to be copied
3375 * @param newLength the length of the copy to be returned
3376 * @return a copy of the original array, truncated or padded with zeros
3377 * to obtain the specified length
3378 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3379 * @throws NullPointerException if <tt>original</tt> is null
3380 * @since 1.6
3381 */
3382 public static double[] copyOf(double[] original, int newLength) {
3383 double[] copy = new double[newLength];
3384 System.arraycopy(original, 0, copy, 0,
3385 Math.min(original.length, newLength));
3386 return copy;
3387 }
3388
3389 /**
3390 * Copies the specified array, truncating or padding with <tt>false</tt> (if necessary)
3391 * so the copy has the specified length. For all indices that are
3392 * valid in both the original array and the copy, the two arrays will
3393 * contain identical values. For any indices that are valid in the
3394 * copy but not the original, the copy will contain <tt>false</tt>.
3395 * Such indices will exist if and only if the specified length
3396 * is greater than that of the original array.
3397 *
3398 * @param original the array to be copied
3399 * @param newLength the length of the copy to be returned
3400 * @return a copy of the original array, truncated or padded with false elements
3401 * to obtain the specified length
3402 * @throws NegativeArraySizeException if <tt>newLength</tt> is negative
3403 * @throws NullPointerException if <tt>original</tt> is null
3404 * @since 1.6
3405 */
3406 public static boolean[] copyOf(boolean[] original, int newLength) {
3407 boolean[] copy = new boolean[newLength];
3408 System.arraycopy(original, 0, copy, 0,
3409 Math.min(original.length, newLength));
3410 return copy;
3411 }
3412
3413 /**
3414 * Copies the specified range of the specified array into a new array.
3415 * The initial index of the range (<tt>from</tt>) must lie between zero
3416 * and <tt>original.length</tt>, inclusive. The value at
3417 * <tt>original[from]</tt> is placed into the initial element of the copy
3418 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3419 * Values from subsequent elements in the original array are placed into
3420 * subsequent elements in the copy. The final index of the range
3421 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3422 * may be greater than <tt>original.length</tt>, in which case
3423 * <tt>null</tt> is placed in all elements of the copy whose index is
3424 * greater than or equal to <tt>original.length - from</tt>. The length
3425 * of the returned array will be <tt>to - from</tt>.
3426 * <p>
3427 * The resulting array is of exactly the same class as the original array.
3428 *
3429 * @param <T> the class of the objects in the array
3430 * @param original the array from which a range is to be copied
3431 * @param from the initial index of the range to be copied, inclusive
3432 * @param to the final index of the range to be copied, exclusive.
3433 * (This index may lie outside the array.)
3434 * @return a new array containing the specified range from the original array,
3435 * truncated or padded with nulls to obtain the required length
3436 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3437 * or {@code from > original.length}
3438 * @throws IllegalArgumentException if <tt>from > to</tt>
3439 * @throws NullPointerException if <tt>original</tt> is null
3440 * @since 1.6
3441 */
3442 @SuppressWarnings("unchecked")
3443 public static <T> T[] copyOfRange(T[] original, int from, int to) {
3444 return copyOfRange(original, from, to, (Class<? extends T[]>) original.getClass());
3445 }
3446
3447 /**
3448 * Copies the specified range of the specified array into a new array.
3449 * The initial index of the range (<tt>from</tt>) must lie between zero
3450 * and <tt>original.length</tt>, inclusive. The value at
3451 * <tt>original[from]</tt> is placed into the initial element of the copy
3452 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3453 * Values from subsequent elements in the original array are placed into
3454 * subsequent elements in the copy. The final index of the range
3455 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3456 * may be greater than <tt>original.length</tt>, in which case
3457 * <tt>null</tt> is placed in all elements of the copy whose index is
3458 * greater than or equal to <tt>original.length - from</tt>. The length
3459 * of the returned array will be <tt>to - from</tt>.
3460 * The resulting array is of the class <tt>newType</tt>.
3461 *
3462 * @param <U> the class of the objects in the original array
3463 * @param <T> the class of the objects in the returned array
3464 * @param original the array from which a range is to be copied
3465 * @param from the initial index of the range to be copied, inclusive
3466 * @param to the final index of the range to be copied, exclusive.
3467 * (This index may lie outside the array.)
3468 * @param newType the class of the copy to be returned
3469 * @return a new array containing the specified range from the original array,
3470 * truncated or padded with nulls to obtain the required length
3471 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3472 * or {@code from > original.length}
3473 * @throws IllegalArgumentException if <tt>from > to</tt>
3474 * @throws NullPointerException if <tt>original</tt> is null
3475 * @throws ArrayStoreException if an element copied from
3476 * <tt>original</tt> is not of a runtime type that can be stored in
3477 * an array of class <tt>newType</tt>.
3478 * @since 1.6
3479 */
3480 @HotSpotIntrinsicCandidate
3481 public static <T,U> T[] copyOfRange(U[] original, int from, int to, Class<? extends T[]> newType) {
3482 int newLength = to - from;
3483 if (newLength < 0)
3484 throw new IllegalArgumentException(from + " > " + to);
3485 @SuppressWarnings("unchecked")
3486 T[] copy = ((Object)newType == (Object)Object[].class)
3487 ? (T[]) new Object[newLength]
3488 : (T[]) Array.newInstance(newType.getComponentType(), newLength);
3489 System.arraycopy(original, from, copy, 0,
3490 Math.min(original.length - from, newLength));
3491 return copy;
3492 }
3493
3494 /**
3495 * Copies the specified range of the specified array into a new array.
3496 * The initial index of the range (<tt>from</tt>) must lie between zero
3497 * and <tt>original.length</tt>, inclusive. The value at
3498 * <tt>original[from]</tt> is placed into the initial element of the copy
3499 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3500 * Values from subsequent elements in the original array are placed into
3501 * subsequent elements in the copy. The final index of the range
3502 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3503 * may be greater than <tt>original.length</tt>, in which case
3504 * <tt>(byte)0</tt> is placed in all elements of the copy whose index is
3505 * greater than or equal to <tt>original.length - from</tt>. The length
3506 * of the returned array will be <tt>to - from</tt>.
3507 *
3508 * @param original the array from which a range is to be copied
3509 * @param from the initial index of the range to be copied, inclusive
3510 * @param to the final index of the range to be copied, exclusive.
3511 * (This index may lie outside the array.)
3512 * @return a new array containing the specified range from the original array,
3513 * truncated or padded with zeros to obtain the required length
3514 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3515 * or {@code from > original.length}
3516 * @throws IllegalArgumentException if <tt>from > to</tt>
3517 * @throws NullPointerException if <tt>original</tt> is null
3518 * @since 1.6
3519 */
3520 public static byte[] copyOfRange(byte[] original, int from, int to) {
3521 int newLength = to - from;
3522 if (newLength < 0)
3523 throw new IllegalArgumentException(from + " > " + to);
3524 byte[] copy = new byte[newLength];
3525 System.arraycopy(original, from, copy, 0,
3526 Math.min(original.length - from, newLength));
3527 return copy;
3528 }
3529
3530 /**
3531 * Copies the specified range of the specified array into a new array.
3532 * The initial index of the range (<tt>from</tt>) must lie between zero
3533 * and <tt>original.length</tt>, inclusive. The value at
3534 * <tt>original[from]</tt> is placed into the initial element of the copy
3535 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3536 * Values from subsequent elements in the original array are placed into
3537 * subsequent elements in the copy. The final index of the range
3538 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3539 * may be greater than <tt>original.length</tt>, in which case
3540 * <tt>(short)0</tt> is placed in all elements of the copy whose index is
3541 * greater than or equal to <tt>original.length - from</tt>. The length
3542 * of the returned array will be <tt>to - from</tt>.
3543 *
3544 * @param original the array from which a range is to be copied
3545 * @param from the initial index of the range to be copied, inclusive
3546 * @param to the final index of the range to be copied, exclusive.
3547 * (This index may lie outside the array.)
3548 * @return a new array containing the specified range from the original array,
3549 * truncated or padded with zeros to obtain the required length
3550 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3551 * or {@code from > original.length}
3552 * @throws IllegalArgumentException if <tt>from > to</tt>
3553 * @throws NullPointerException if <tt>original</tt> is null
3554 * @since 1.6
3555 */
3556 public static short[] copyOfRange(short[] original, int from, int to) {
3557 int newLength = to - from;
3558 if (newLength < 0)
3559 throw new IllegalArgumentException(from + " > " + to);
3560 short[] copy = new short[newLength];
3561 System.arraycopy(original, from, copy, 0,
3562 Math.min(original.length - from, newLength));
3563 return copy;
3564 }
3565
3566 /**
3567 * Copies the specified range of the specified array into a new array.
3568 * The initial index of the range (<tt>from</tt>) must lie between zero
3569 * and <tt>original.length</tt>, inclusive. The value at
3570 * <tt>original[from]</tt> is placed into the initial element of the copy
3571 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3572 * Values from subsequent elements in the original array are placed into
3573 * subsequent elements in the copy. The final index of the range
3574 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3575 * may be greater than <tt>original.length</tt>, in which case
3576 * <tt>0</tt> is placed in all elements of the copy whose index is
3577 * greater than or equal to <tt>original.length - from</tt>. The length
3578 * of the returned array will be <tt>to - from</tt>.
3579 *
3580 * @param original the array from which a range is to be copied
3581 * @param from the initial index of the range to be copied, inclusive
3582 * @param to the final index of the range to be copied, exclusive.
3583 * (This index may lie outside the array.)
3584 * @return a new array containing the specified range from the original array,
3585 * truncated or padded with zeros to obtain the required length
3586 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3587 * or {@code from > original.length}
3588 * @throws IllegalArgumentException if <tt>from > to</tt>
3589 * @throws NullPointerException if <tt>original</tt> is null
3590 * @since 1.6
3591 */
3592 public static int[] copyOfRange(int[] original, int from, int to) {
3593 int newLength = to - from;
3594 if (newLength < 0)
3595 throw new IllegalArgumentException(from + " > " + to);
3596 int[] copy = new int[newLength];
3597 System.arraycopy(original, from, copy, 0,
3598 Math.min(original.length - from, newLength));
3599 return copy;
3600 }
3601
3602 /**
3603 * Copies the specified range of the specified array into a new array.
3604 * The initial index of the range (<tt>from</tt>) must lie between zero
3605 * and <tt>original.length</tt>, inclusive. The value at
3606 * <tt>original[from]</tt> is placed into the initial element of the copy
3607 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3608 * Values from subsequent elements in the original array are placed into
3609 * subsequent elements in the copy. The final index of the range
3610 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3611 * may be greater than <tt>original.length</tt>, in which case
3612 * <tt>0L</tt> is placed in all elements of the copy whose index is
3613 * greater than or equal to <tt>original.length - from</tt>. The length
3614 * of the returned array will be <tt>to - from</tt>.
3615 *
3616 * @param original the array from which a range is to be copied
3617 * @param from the initial index of the range to be copied, inclusive
3618 * @param to the final index of the range to be copied, exclusive.
3619 * (This index may lie outside the array.)
3620 * @return a new array containing the specified range from the original array,
3621 * truncated or padded with zeros to obtain the required length
3622 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3623 * or {@code from > original.length}
3624 * @throws IllegalArgumentException if <tt>from > to</tt>
3625 * @throws NullPointerException if <tt>original</tt> is null
3626 * @since 1.6
3627 */
3628 public static long[] copyOfRange(long[] original, int from, int to) {
3629 int newLength = to - from;
3630 if (newLength < 0)
3631 throw new IllegalArgumentException(from + " > " + to);
3632 long[] copy = new long[newLength];
3633 System.arraycopy(original, from, copy, 0,
3634 Math.min(original.length - from, newLength));
3635 return copy;
3636 }
3637
3638 /**
3639 * Copies the specified range of the specified array into a new array.
3640 * The initial index of the range (<tt>from</tt>) must lie between zero
3641 * and <tt>original.length</tt>, inclusive. The value at
3642 * <tt>original[from]</tt> is placed into the initial element of the copy
3643 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3644 * Values from subsequent elements in the original array are placed into
3645 * subsequent elements in the copy. The final index of the range
3646 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3647 * may be greater than <tt>original.length</tt>, in which case
3648 * <tt>'\\u000'</tt> is placed in all elements of the copy whose index is
3649 * greater than or equal to <tt>original.length - from</tt>. The length
3650 * of the returned array will be <tt>to - from</tt>.
3651 *
3652 * @param original the array from which a range is to be copied
3653 * @param from the initial index of the range to be copied, inclusive
3654 * @param to the final index of the range to be copied, exclusive.
3655 * (This index may lie outside the array.)
3656 * @return a new array containing the specified range from the original array,
3657 * truncated or padded with null characters to obtain the required length
3658 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3659 * or {@code from > original.length}
3660 * @throws IllegalArgumentException if <tt>from > to</tt>
3661 * @throws NullPointerException if <tt>original</tt> is null
3662 * @since 1.6
3663 */
3664 public static char[] copyOfRange(char[] original, int from, int to) {
3665 int newLength = to - from;
3666 if (newLength < 0)
3667 throw new IllegalArgumentException(from + " > " + to);
3668 char[] copy = new char[newLength];
3669 System.arraycopy(original, from, copy, 0,
3670 Math.min(original.length - from, newLength));
3671 return copy;
3672 }
3673
3674 /**
3675 * Copies the specified range of the specified array into a new array.
3676 * The initial index of the range (<tt>from</tt>) must lie between zero
3677 * and <tt>original.length</tt>, inclusive. The value at
3678 * <tt>original[from]</tt> is placed into the initial element of the copy
3679 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3680 * Values from subsequent elements in the original array are placed into
3681 * subsequent elements in the copy. The final index of the range
3682 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3683 * may be greater than <tt>original.length</tt>, in which case
3684 * <tt>0f</tt> is placed in all elements of the copy whose index is
3685 * greater than or equal to <tt>original.length - from</tt>. The length
3686 * of the returned array will be <tt>to - from</tt>.
3687 *
3688 * @param original the array from which a range is to be copied
3689 * @param from the initial index of the range to be copied, inclusive
3690 * @param to the final index of the range to be copied, exclusive.
3691 * (This index may lie outside the array.)
3692 * @return a new array containing the specified range from the original array,
3693 * truncated or padded with zeros to obtain the required length
3694 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3695 * or {@code from > original.length}
3696 * @throws IllegalArgumentException if <tt>from > to</tt>
3697 * @throws NullPointerException if <tt>original</tt> is null
3698 * @since 1.6
3699 */
3700 public static float[] copyOfRange(float[] original, int from, int to) {
3701 int newLength = to - from;
3702 if (newLength < 0)
3703 throw new IllegalArgumentException(from + " > " + to);
3704 float[] copy = new float[newLength];
3705 System.arraycopy(original, from, copy, 0,
3706 Math.min(original.length - from, newLength));
3707 return copy;
3708 }
3709
3710 /**
3711 * Copies the specified range of the specified array into a new array.
3712 * The initial index of the range (<tt>from</tt>) must lie between zero
3713 * and <tt>original.length</tt>, inclusive. The value at
3714 * <tt>original[from]</tt> is placed into the initial element of the copy
3715 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3716 * Values from subsequent elements in the original array are placed into
3717 * subsequent elements in the copy. The final index of the range
3718 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3719 * may be greater than <tt>original.length</tt>, in which case
3720 * <tt>0d</tt> is placed in all elements of the copy whose index is
3721 * greater than or equal to <tt>original.length - from</tt>. The length
3722 * of the returned array will be <tt>to - from</tt>.
3723 *
3724 * @param original the array from which a range is to be copied
3725 * @param from the initial index of the range to be copied, inclusive
3726 * @param to the final index of the range to be copied, exclusive.
3727 * (This index may lie outside the array.)
3728 * @return a new array containing the specified range from the original array,
3729 * truncated or padded with zeros to obtain the required length
3730 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3731 * or {@code from > original.length}
3732 * @throws IllegalArgumentException if <tt>from > to</tt>
3733 * @throws NullPointerException if <tt>original</tt> is null
3734 * @since 1.6
3735 */
3736 public static double[] copyOfRange(double[] original, int from, int to) {
3737 int newLength = to - from;
3738 if (newLength < 0)
3739 throw new IllegalArgumentException(from + " > " + to);
3740 double[] copy = new double[newLength];
3741 System.arraycopy(original, from, copy, 0,
3742 Math.min(original.length - from, newLength));
3743 return copy;
3744 }
3745
3746 /**
3747 * Copies the specified range of the specified array into a new array.
3748 * The initial index of the range (<tt>from</tt>) must lie between zero
3749 * and <tt>original.length</tt>, inclusive. The value at
3750 * <tt>original[from]</tt> is placed into the initial element of the copy
3751 * (unless <tt>from == original.length</tt> or <tt>from == to</tt>).
3752 * Values from subsequent elements in the original array are placed into
3753 * subsequent elements in the copy. The final index of the range
3754 * (<tt>to</tt>), which must be greater than or equal to <tt>from</tt>,
3755 * may be greater than <tt>original.length</tt>, in which case
3756 * <tt>false</tt> is placed in all elements of the copy whose index is
3757 * greater than or equal to <tt>original.length - from</tt>. The length
3758 * of the returned array will be <tt>to - from</tt>.
3759 *
3760 * @param original the array from which a range is to be copied
3761 * @param from the initial index of the range to be copied, inclusive
3762 * @param to the final index of the range to be copied, exclusive.
3763 * (This index may lie outside the array.)
3764 * @return a new array containing the specified range from the original array,
3765 * truncated or padded with false elements to obtain the required length
3766 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3767 * or {@code from > original.length}
3768 * @throws IllegalArgumentException if <tt>from > to</tt>
3769 * @throws NullPointerException if <tt>original</tt> is null
3770 * @since 1.6
3771 */
3772 public static boolean[] copyOfRange(boolean[] original, int from, int to) {
3773 int newLength = to - from;
3774 if (newLength < 0)
3775 throw new IllegalArgumentException(from + " > " + to);
3776 boolean[] copy = new boolean[newLength];
3777 System.arraycopy(original, from, copy, 0,
3778 Math.min(original.length - from, newLength));
3779 return copy;
3780 }
3781
3782 // Misc
3783
3784 /**
3785 * Returns a fixed-size list backed by the specified array. (Changes to
3786 * the returned list "write through" to the array.) This method acts
3787 * as bridge between array-based and collection-based APIs, in
3788 * combination with {@link Collection#toArray}. The returned list is
3789 * serializable and implements {@link RandomAccess}.
3885 }
3886 }
3887
3888 @Override
3889 public void replaceAll(UnaryOperator<E> operator) {
3890 Objects.requireNonNull(operator);
3891 E[] a = this.a;
3892 for (int i = 0; i < a.length; i++) {
3893 a[i] = operator.apply(a[i]);
3894 }
3895 }
3896
3897 @Override
3898 public void sort(Comparator<? super E> c) {
3899 Arrays.sort(a, c);
3900 }
3901 }
3902
3903 /**
3904 * Returns a hash code based on the contents of the specified array.
3905 * For any two <tt>long</tt> arrays <tt>a</tt> and <tt>b</tt>
3906 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
3907 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
3908 *
3909 * <p>The value returned by this method is the same value that would be
3910 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
3911 * method on a {@link List} containing a sequence of {@link Long}
3912 * instances representing the elements of <tt>a</tt> in the same order.
3913 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
3914 *
3915 * @param a the array whose hash value to compute
3916 * @return a content-based hash code for <tt>a</tt>
3917 * @since 1.5
3918 */
3919 public static int hashCode(long a[]) {
3920 if (a == null)
3921 return 0;
3922
3923 int result = 1;
3924 for (long element : a) {
3925 int elementHash = (int)(element ^ (element >>> 32));
3926 result = 31 * result + elementHash;
3927 }
3928
3929 return result;
3930 }
3931
3932 /**
3933 * Returns a hash code based on the contents of the specified array.
3934 * For any two non-null <tt>int</tt> arrays <tt>a</tt> and <tt>b</tt>
3935 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
3936 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
3937 *
3938 * <p>The value returned by this method is the same value that would be
3939 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
3940 * method on a {@link List} containing a sequence of {@link Integer}
3941 * instances representing the elements of <tt>a</tt> in the same order.
3942 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
3943 *
3944 * @param a the array whose hash value to compute
3945 * @return a content-based hash code for <tt>a</tt>
3946 * @since 1.5
3947 */
3948 public static int hashCode(int a[]) {
3949 if (a == null)
3950 return 0;
3951
3952 int result = 1;
3953 for (int element : a)
3954 result = 31 * result + element;
3955
3956 return result;
3957 }
3958
3959 /**
3960 * Returns a hash code based on the contents of the specified array.
3961 * For any two <tt>short</tt> arrays <tt>a</tt> and <tt>b</tt>
3962 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
3963 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
3964 *
3965 * <p>The value returned by this method is the same value that would be
3966 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
3967 * method on a {@link List} containing a sequence of {@link Short}
3968 * instances representing the elements of <tt>a</tt> in the same order.
3969 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
3970 *
3971 * @param a the array whose hash value to compute
3972 * @return a content-based hash code for <tt>a</tt>
3973 * @since 1.5
3974 */
3975 public static int hashCode(short a[]) {
3976 if (a == null)
3977 return 0;
3978
3979 int result = 1;
3980 for (short element : a)
3981 result = 31 * result + element;
3982
3983 return result;
3984 }
3985
3986 /**
3987 * Returns a hash code based on the contents of the specified array.
3988 * For any two <tt>char</tt> arrays <tt>a</tt> and <tt>b</tt>
3989 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
3990 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
3991 *
3992 * <p>The value returned by this method is the same value that would be
3993 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
3994 * method on a {@link List} containing a sequence of {@link Character}
3995 * instances representing the elements of <tt>a</tt> in the same order.
3996 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
3997 *
3998 * @param a the array whose hash value to compute
3999 * @return a content-based hash code for <tt>a</tt>
4000 * @since 1.5
4001 */
4002 public static int hashCode(char a[]) {
4003 if (a == null)
4004 return 0;
4005
4006 int result = 1;
4007 for (char element : a)
4008 result = 31 * result + element;
4009
4010 return result;
4011 }
4012
4013 /**
4014 * Returns a hash code based on the contents of the specified array.
4015 * For any two <tt>byte</tt> arrays <tt>a</tt> and <tt>b</tt>
4016 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
4017 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
4018 *
4019 * <p>The value returned by this method is the same value that would be
4020 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
4021 * method on a {@link List} containing a sequence of {@link Byte}
4022 * instances representing the elements of <tt>a</tt> in the same order.
4023 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
4024 *
4025 * @param a the array whose hash value to compute
4026 * @return a content-based hash code for <tt>a</tt>
4027 * @since 1.5
4028 */
4029 public static int hashCode(byte a[]) {
4030 if (a == null)
4031 return 0;
4032
4033 int result = 1;
4034 for (byte element : a)
4035 result = 31 * result + element;
4036
4037 return result;
4038 }
4039
4040 /**
4041 * Returns a hash code based on the contents of the specified array.
4042 * For any two <tt>boolean</tt> arrays <tt>a</tt> and <tt>b</tt>
4043 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
4044 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
4045 *
4046 * <p>The value returned by this method is the same value that would be
4047 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
4048 * method on a {@link List} containing a sequence of {@link Boolean}
4049 * instances representing the elements of <tt>a</tt> in the same order.
4050 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
4051 *
4052 * @param a the array whose hash value to compute
4053 * @return a content-based hash code for <tt>a</tt>
4054 * @since 1.5
4055 */
4056 public static int hashCode(boolean a[]) {
4057 if (a == null)
4058 return 0;
4059
4060 int result = 1;
4061 for (boolean element : a)
4062 result = 31 * result + (element ? 1231 : 1237);
4063
4064 return result;
4065 }
4066
4067 /**
4068 * Returns a hash code based on the contents of the specified array.
4069 * For any two <tt>float</tt> arrays <tt>a</tt> and <tt>b</tt>
4070 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
4071 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
4072 *
4073 * <p>The value returned by this method is the same value that would be
4074 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
4075 * method on a {@link List} containing a sequence of {@link Float}
4076 * instances representing the elements of <tt>a</tt> in the same order.
4077 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
4078 *
4079 * @param a the array whose hash value to compute
4080 * @return a content-based hash code for <tt>a</tt>
4081 * @since 1.5
4082 */
4083 public static int hashCode(float a[]) {
4084 if (a == null)
4085 return 0;
4086
4087 int result = 1;
4088 for (float element : a)
4089 result = 31 * result + Float.floatToIntBits(element);
4090
4091 return result;
4092 }
4093
4094 /**
4095 * Returns a hash code based on the contents of the specified array.
4096 * For any two <tt>double</tt> arrays <tt>a</tt> and <tt>b</tt>
4097 * such that <tt>Arrays.equals(a, b)</tt>, it is also the case that
4098 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
4099 *
4100 * <p>The value returned by this method is the same value that would be
4101 * obtained by invoking the {@link List#hashCode() <tt>hashCode</tt>}
4102 * method on a {@link List} containing a sequence of {@link Double}
4103 * instances representing the elements of <tt>a</tt> in the same order.
4104 * If <tt>a</tt> is <tt>null</tt>, this method returns 0.
4105 *
4106 * @param a the array whose hash value to compute
4107 * @return a content-based hash code for <tt>a</tt>
4108 * @since 1.5
4109 */
4110 public static int hashCode(double a[]) {
4111 if (a == null)
4112 return 0;
4113
4114 int result = 1;
4115 for (double element : a) {
4116 long bits = Double.doubleToLongBits(element);
4117 result = 31 * result + (int)(bits ^ (bits >>> 32));
4118 }
4119 return result;
4120 }
4121
4122 /**
4123 * Returns a hash code based on the contents of the specified array. If
4124 * the array contains other arrays as elements, the hash code is based on
4125 * their identities rather than their contents. It is therefore
4126 * acceptable to invoke this method on an array that contains itself as an
4127 * element, either directly or indirectly through one or more levels of
4128 * arrays.
4129 *
4130 * <p>For any two arrays <tt>a</tt> and <tt>b</tt> such that
4131 * <tt>Arrays.equals(a, b)</tt>, it is also the case that
4132 * <tt>Arrays.hashCode(a) == Arrays.hashCode(b)</tt>.
4133 *
4134 * <p>The value returned by this method is equal to the value that would
4135 * be returned by <tt>Arrays.asList(a).hashCode()</tt>, unless <tt>a</tt>
4136 * is <tt>null</tt>, in which case <tt>0</tt> is returned.
4137 *
4138 * @param a the array whose content-based hash code to compute
4139 * @return a content-based hash code for <tt>a</tt>
4140 * @see #deepHashCode(Object[])
4141 * @since 1.5
4142 */
4143 public static int hashCode(Object a[]) {
4144 if (a == null)
4145 return 0;
4146
4147 int result = 1;
4148
4149 for (Object element : a)
4150 result = 31 * result + (element == null ? 0 : element.hashCode());
4151
4152 return result;
4153 }
4154
4155 /**
4156 * Returns a hash code based on the "deep contents" of the specified
4157 * array. If the array contains other arrays as elements, the
4158 * hash code is based on their contents and so on, ad infinitum.
4159 * It is therefore unacceptable to invoke this method on an array that
4160 * contains itself as an element, either directly or indirectly through
4161 * one or more levels of arrays. The behavior of such an invocation is
4162 * undefined.
4163 *
4164 * <p>For any two arrays <tt>a</tt> and <tt>b</tt> such that
4165 * <tt>Arrays.deepEquals(a, b)</tt>, it is also the case that
4166 * <tt>Arrays.deepHashCode(a) == Arrays.deepHashCode(b)</tt>.
4167 *
4168 * <p>The computation of the value returned by this method is similar to
4169 * that of the value returned by {@link List#hashCode()} on a list
4170 * containing the same elements as <tt>a</tt> in the same order, with one
4171 * difference: If an element <tt>e</tt> of <tt>a</tt> is itself an array,
4172 * its hash code is computed not by calling <tt>e.hashCode()</tt>, but as
4173 * by calling the appropriate overloading of <tt>Arrays.hashCode(e)</tt>
4174 * if <tt>e</tt> is an array of a primitive type, or as by calling
4175 * <tt>Arrays.deepHashCode(e)</tt> recursively if <tt>e</tt> is an array
4176 * of a reference type. If <tt>a</tt> is <tt>null</tt>, this method
4177 * returns 0.
4178 *
4179 * @param a the array whose deep-content-based hash code to compute
4180 * @return a deep-content-based hash code for <tt>a</tt>
4181 * @see #hashCode(Object[])
4182 * @since 1.5
4183 */
4184 public static int deepHashCode(Object a[]) {
4185 if (a == null)
4186 return 0;
4187
4188 int result = 1;
4189
4190 for (Object element : a) {
4191 int elementHash = 0;
4192 if (element instanceof Object[])
4193 elementHash = deepHashCode((Object[]) element);
4194 else if (element instanceof byte[])
4195 elementHash = hashCode((byte[]) element);
4196 else if (element instanceof short[])
4197 elementHash = hashCode((short[]) element);
4198 else if (element instanceof int[])
4199 elementHash = hashCode((int[]) element);
4200 else if (element instanceof long[])
4201 elementHash = hashCode((long[]) element);
4202 else if (element instanceof char[])
4203 elementHash = hashCode((char[]) element);
4204 else if (element instanceof float[])
4205 elementHash = hashCode((float[]) element);
4206 else if (element instanceof double[])
4207 elementHash = hashCode((double[]) element);
4208 else if (element instanceof boolean[])
4209 elementHash = hashCode((boolean[]) element);
4210 else if (element != null)
4211 elementHash = element.hashCode();
4212
4213 result = 31 * result + elementHash;
4214 }
4215
4216 return result;
4217 }
4218
4219 /**
4220 * Returns <tt>true</tt> if the two specified arrays are <i>deeply
4221 * equal</i> to one another. Unlike the {@link #equals(Object[],Object[])}
4222 * method, this method is appropriate for use with nested arrays of
4223 * arbitrary depth.
4224 *
4225 * <p>Two array references are considered deeply equal if both
4226 * are <tt>null</tt>, or if they refer to arrays that contain the same
4227 * number of elements and all corresponding pairs of elements in the two
4228 * arrays are deeply equal.
4229 *
4230 * <p>Two possibly <tt>null</tt> elements <tt>e1</tt> and <tt>e2</tt> are
4231 * deeply equal if any of the following conditions hold:
4232 * <ul>
4233 * <li> <tt>e1</tt> and <tt>e2</tt> are both arrays of object reference
4234 * types, and <tt>Arrays.deepEquals(e1, e2) would return true</tt>
4235 * <li> <tt>e1</tt> and <tt>e2</tt> are arrays of the same primitive
4236 * type, and the appropriate overloading of
4237 * <tt>Arrays.equals(e1, e2)</tt> would return true.
4238 * <li> <tt>e1 == e2</tt>
4239 * <li> <tt>e1.equals(e2)</tt> would return true.
4240 * </ul>
4241 * Note that this definition permits <tt>null</tt> elements at any depth.
4242 *
4243 * <p>If either of the specified arrays contain themselves as elements
4244 * either directly or indirectly through one or more levels of arrays,
4245 * the behavior of this method is undefined.
4246 *
4247 * @param a1 one array to be tested for equality
4248 * @param a2 the other array to be tested for equality
4249 * @return <tt>true</tt> if the two arrays are equal
4250 * @see #equals(Object[],Object[])
4251 * @see Objects#deepEquals(Object, Object)
4252 * @since 1.5
4253 */
4254 public static boolean deepEquals(Object[] a1, Object[] a2) {
4255 if (a1 == a2)
4256 return true;
4257 if (a1 == null || a2==null)
4258 return false;
4259 int length = a1.length;
4260 if (a2.length != length)
4261 return false;
4262
4263 for (int i = 0; i < length; i++) {
4264 Object e1 = a1[i];
4265 Object e2 = a2[i];
4266
4267 if (e1 == e2)
4268 continue;
4269 if (e1 == null)
4290 else if (e1 instanceof int[] && e2 instanceof int[])
4291 eq = equals((int[]) e1, (int[]) e2);
4292 else if (e1 instanceof long[] && e2 instanceof long[])
4293 eq = equals((long[]) e1, (long[]) e2);
4294 else if (e1 instanceof char[] && e2 instanceof char[])
4295 eq = equals((char[]) e1, (char[]) e2);
4296 else if (e1 instanceof float[] && e2 instanceof float[])
4297 eq = equals((float[]) e1, (float[]) e2);
4298 else if (e1 instanceof double[] && e2 instanceof double[])
4299 eq = equals((double[]) e1, (double[]) e2);
4300 else if (e1 instanceof boolean[] && e2 instanceof boolean[])
4301 eq = equals((boolean[]) e1, (boolean[]) e2);
4302 else
4303 eq = e1.equals(e2);
4304 return eq;
4305 }
4306
4307 /**
4308 * Returns a string representation of the contents of the specified array.
4309 * The string representation consists of a list of the array's elements,
4310 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements are
4311 * separated by the characters <tt>", "</tt> (a comma followed by a
4312 * space). Elements are converted to strings as by
4313 * <tt>String.valueOf(long)</tt>. Returns <tt>"null"</tt> if <tt>a</tt>
4314 * is <tt>null</tt>.
4315 *
4316 * @param a the array whose string representation to return
4317 * @return a string representation of <tt>a</tt>
4318 * @since 1.5
4319 */
4320 public static String toString(long[] a) {
4321 if (a == null)
4322 return "null";
4323 int iMax = a.length - 1;
4324 if (iMax == -1)
4325 return "[]";
4326
4327 StringBuilder b = new StringBuilder();
4328 b.append('[');
4329 for (int i = 0; ; i++) {
4330 b.append(a[i]);
4331 if (i == iMax)
4332 return b.append(']').toString();
4333 b.append(", ");
4334 }
4335 }
4336
4337 /**
4338 * Returns a string representation of the contents of the specified array.
4339 * The string representation consists of a list of the array's elements,
4340 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements are
4341 * separated by the characters <tt>", "</tt> (a comma followed by a
4342 * space). Elements are converted to strings as by
4343 * <tt>String.valueOf(int)</tt>. Returns <tt>"null"</tt> if <tt>a</tt> is
4344 * <tt>null</tt>.
4345 *
4346 * @param a the array whose string representation to return
4347 * @return a string representation of <tt>a</tt>
4348 * @since 1.5
4349 */
4350 public static String toString(int[] a) {
4351 if (a == null)
4352 return "null";
4353 int iMax = a.length - 1;
4354 if (iMax == -1)
4355 return "[]";
4356
4357 StringBuilder b = new StringBuilder();
4358 b.append('[');
4359 for (int i = 0; ; i++) {
4360 b.append(a[i]);
4361 if (i == iMax)
4362 return b.append(']').toString();
4363 b.append(", ");
4364 }
4365 }
4366
4367 /**
4368 * Returns a string representation of the contents of the specified array.
4369 * The string representation consists of a list of the array's elements,
4370 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements are
4371 * separated by the characters <tt>", "</tt> (a comma followed by a
4372 * space). Elements are converted to strings as by
4373 * <tt>String.valueOf(short)</tt>. Returns <tt>"null"</tt> if <tt>a</tt>
4374 * is <tt>null</tt>.
4375 *
4376 * @param a the array whose string representation to return
4377 * @return a string representation of <tt>a</tt>
4378 * @since 1.5
4379 */
4380 public static String toString(short[] a) {
4381 if (a == null)
4382 return "null";
4383 int iMax = a.length - 1;
4384 if (iMax == -1)
4385 return "[]";
4386
4387 StringBuilder b = new StringBuilder();
4388 b.append('[');
4389 for (int i = 0; ; i++) {
4390 b.append(a[i]);
4391 if (i == iMax)
4392 return b.append(']').toString();
4393 b.append(", ");
4394 }
4395 }
4396
4397 /**
4398 * Returns a string representation of the contents of the specified array.
4399 * The string representation consists of a list of the array's elements,
4400 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements are
4401 * separated by the characters <tt>", "</tt> (a comma followed by a
4402 * space). Elements are converted to strings as by
4403 * <tt>String.valueOf(char)</tt>. Returns <tt>"null"</tt> if <tt>a</tt>
4404 * is <tt>null</tt>.
4405 *
4406 * @param a the array whose string representation to return
4407 * @return a string representation of <tt>a</tt>
4408 * @since 1.5
4409 */
4410 public static String toString(char[] a) {
4411 if (a == null)
4412 return "null";
4413 int iMax = a.length - 1;
4414 if (iMax == -1)
4415 return "[]";
4416
4417 StringBuilder b = new StringBuilder();
4418 b.append('[');
4419 for (int i = 0; ; i++) {
4420 b.append(a[i]);
4421 if (i == iMax)
4422 return b.append(']').toString();
4423 b.append(", ");
4424 }
4425 }
4426
4427 /**
4428 * Returns a string representation of the contents of the specified array.
4429 * The string representation consists of a list of the array's elements,
4430 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements
4431 * are separated by the characters <tt>", "</tt> (a comma followed
4432 * by a space). Elements are converted to strings as by
4433 * <tt>String.valueOf(byte)</tt>. Returns <tt>"null"</tt> if
4434 * <tt>a</tt> is <tt>null</tt>.
4435 *
4436 * @param a the array whose string representation to return
4437 * @return a string representation of <tt>a</tt>
4438 * @since 1.5
4439 */
4440 public static String toString(byte[] a) {
4441 if (a == null)
4442 return "null";
4443 int iMax = a.length - 1;
4444 if (iMax == -1)
4445 return "[]";
4446
4447 StringBuilder b = new StringBuilder();
4448 b.append('[');
4449 for (int i = 0; ; i++) {
4450 b.append(a[i]);
4451 if (i == iMax)
4452 return b.append(']').toString();
4453 b.append(", ");
4454 }
4455 }
4456
4457 /**
4458 * Returns a string representation of the contents of the specified array.
4459 * The string representation consists of a list of the array's elements,
4460 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements are
4461 * separated by the characters <tt>", "</tt> (a comma followed by a
4462 * space). Elements are converted to strings as by
4463 * <tt>String.valueOf(boolean)</tt>. Returns <tt>"null"</tt> if
4464 * <tt>a</tt> is <tt>null</tt>.
4465 *
4466 * @param a the array whose string representation to return
4467 * @return a string representation of <tt>a</tt>
4468 * @since 1.5
4469 */
4470 public static String toString(boolean[] a) {
4471 if (a == null)
4472 return "null";
4473 int iMax = a.length - 1;
4474 if (iMax == -1)
4475 return "[]";
4476
4477 StringBuilder b = new StringBuilder();
4478 b.append('[');
4479 for (int i = 0; ; i++) {
4480 b.append(a[i]);
4481 if (i == iMax)
4482 return b.append(']').toString();
4483 b.append(", ");
4484 }
4485 }
4486
4487 /**
4488 * Returns a string representation of the contents of the specified array.
4489 * The string representation consists of a list of the array's elements,
4490 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements are
4491 * separated by the characters <tt>", "</tt> (a comma followed by a
4492 * space). Elements are converted to strings as by
4493 * <tt>String.valueOf(float)</tt>. Returns <tt>"null"</tt> if <tt>a</tt>
4494 * is <tt>null</tt>.
4495 *
4496 * @param a the array whose string representation to return
4497 * @return a string representation of <tt>a</tt>
4498 * @since 1.5
4499 */
4500 public static String toString(float[] a) {
4501 if (a == null)
4502 return "null";
4503
4504 int iMax = a.length - 1;
4505 if (iMax == -1)
4506 return "[]";
4507
4508 StringBuilder b = new StringBuilder();
4509 b.append('[');
4510 for (int i = 0; ; i++) {
4511 b.append(a[i]);
4512 if (i == iMax)
4513 return b.append(']').toString();
4514 b.append(", ");
4515 }
4516 }
4517
4518 /**
4519 * Returns a string representation of the contents of the specified array.
4520 * The string representation consists of a list of the array's elements,
4521 * enclosed in square brackets (<tt>"[]"</tt>). Adjacent elements are
4522 * separated by the characters <tt>", "</tt> (a comma followed by a
4523 * space). Elements are converted to strings as by
4524 * <tt>String.valueOf(double)</tt>. Returns <tt>"null"</tt> if <tt>a</tt>
4525 * is <tt>null</tt>.
4526 *
4527 * @param a the array whose string representation to return
4528 * @return a string representation of <tt>a</tt>
4529 * @since 1.5
4530 */
4531 public static String toString(double[] a) {
4532 if (a == null)
4533 return "null";
4534 int iMax = a.length - 1;
4535 if (iMax == -1)
4536 return "[]";
4537
4538 StringBuilder b = new StringBuilder();
4539 b.append('[');
4540 for (int i = 0; ; i++) {
4541 b.append(a[i]);
4542 if (i == iMax)
4543 return b.append(']').toString();
4544 b.append(", ");
4545 }
4546 }
4547
4548 /**
4549 * Returns a string representation of the contents of the specified array.
4550 * If the array contains other arrays as elements, they are converted to
4551 * strings by the {@link Object#toString} method inherited from
4552 * <tt>Object</tt>, which describes their <i>identities</i> rather than
4553 * their contents.
4554 *
4555 * <p>The value returned by this method is equal to the value that would
4556 * be returned by <tt>Arrays.asList(a).toString()</tt>, unless <tt>a</tt>
4557 * is <tt>null</tt>, in which case <tt>"null"</tt> is returned.
4558 *
4559 * @param a the array whose string representation to return
4560 * @return a string representation of <tt>a</tt>
4561 * @see #deepToString(Object[])
4562 * @since 1.5
4563 */
4564 public static String toString(Object[] a) {
4565 if (a == null)
4566 return "null";
4567
4568 int iMax = a.length - 1;
4569 if (iMax == -1)
4570 return "[]";
4571
4572 StringBuilder b = new StringBuilder();
4573 b.append('[');
4574 for (int i = 0; ; i++) {
4575 b.append(String.valueOf(a[i]));
4576 if (i == iMax)
4577 return b.append(']').toString();
4578 b.append(", ");
4579 }
4580 }
4581
4582 /**
4583 * Returns a string representation of the "deep contents" of the specified
4584 * array. If the array contains other arrays as elements, the string
4585 * representation contains their contents and so on. This method is
4586 * designed for converting multidimensional arrays to strings.
4587 *
4588 * <p>The string representation consists of a list of the array's
4589 * elements, enclosed in square brackets (<tt>"[]"</tt>). Adjacent
4590 * elements are separated by the characters <tt>", "</tt> (a comma
4591 * followed by a space). Elements are converted to strings as by
4592 * <tt>String.valueOf(Object)</tt>, unless they are themselves
4593 * arrays.
4594 *
4595 * <p>If an element <tt>e</tt> is an array of a primitive type, it is
4596 * converted to a string as by invoking the appropriate overloading of
4597 * <tt>Arrays.toString(e)</tt>. If an element <tt>e</tt> is an array of a
4598 * reference type, it is converted to a string as by invoking
4599 * this method recursively.
4600 *
4601 * <p>To avoid infinite recursion, if the specified array contains itself
4602 * as an element, or contains an indirect reference to itself through one
4603 * or more levels of arrays, the self-reference is converted to the string
4604 * <tt>"[...]"</tt>. For example, an array containing only a reference
4605 * to itself would be rendered as <tt>"[[...]]"</tt>.
4606 *
4607 * <p>This method returns <tt>"null"</tt> if the specified array
4608 * is <tt>null</tt>.
4609 *
4610 * @param a the array whose string representation to return
4611 * @return a string representation of <tt>a</tt>
4612 * @see #toString(Object[])
4613 * @since 1.5
4614 */
4615 public static String deepToString(Object[] a) {
4616 if (a == null)
4617 return "null";
4618
4619 int bufLen = 20 * a.length;
4620 if (a.length != 0 && bufLen <= 0)
4621 bufLen = Integer.MAX_VALUE;
4622 StringBuilder buf = new StringBuilder(bufLen);
4623 deepToString(a, buf, new HashSet<>());
4624 return buf.toString();
4625 }
4626
4627 private static void deepToString(Object[] a, StringBuilder buf,
4628 Set<Object[]> dejaVu) {
4629 if (a == null) {
4630 buf.append("null");
4631 return;
|
1755 Objects.requireNonNull(op);
1756 rangeCheck(array.length, fromIndex, toIndex);
1757 if (fromIndex < toIndex)
1758 new ArrayPrefixHelpers.IntCumulateTask
1759 (null, op, array, fromIndex, toIndex).invoke();
1760 }
1761
1762 // Searching
1763
1764 /**
1765 * Searches the specified array of longs for the specified value using the
1766 * binary search algorithm. The array must be sorted (as
1767 * by the {@link #sort(long[])} method) prior to making this call. If it
1768 * is not sorted, the results are undefined. If the array contains
1769 * multiple elements with the specified value, there is no guarantee which
1770 * one will be found.
1771 *
1772 * @param a the array to be searched
1773 * @param key the value to be searched for
1774 * @return index of the search key, if it is contained in the array;
1775 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
1776 * <i>insertion point</i> is defined as the point at which the
1777 * key would be inserted into the array: the index of the first
1778 * element greater than the key, or {@code a.length} if all
1779 * elements in the array are less than the specified key. Note
1780 * that this guarantees that the return value will be >= 0 if
1781 * and only if the key is found.
1782 */
1783 public static int binarySearch(long[] a, long key) {
1784 return binarySearch0(a, 0, a.length, key);
1785 }
1786
1787 /**
1788 * Searches a range of
1789 * the specified array of longs for the specified value using the
1790 * binary search algorithm.
1791 * The range must be sorted (as
1792 * by the {@link #sort(long[], int, int)} method)
1793 * prior to making this call. If it
1794 * is not sorted, the results are undefined. If the range contains
1795 * multiple elements with the specified value, there is no guarantee which
1796 * one will be found.
1797 *
1798 * @param a the array to be searched
1799 * @param fromIndex the index of the first element (inclusive) to be
1800 * searched
1801 * @param toIndex the index of the last element (exclusive) to be searched
1802 * @param key the value to be searched for
1803 * @return index of the search key, if it is contained in the array
1804 * within the specified range;
1805 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
1806 * <i>insertion point</i> is defined as the point at which the
1807 * key would be inserted into the array: the index of the first
1808 * element in the range greater than the key,
1809 * or {@code toIndex} if all
1810 * elements in the range are less than the specified key. Note
1811 * that this guarantees that the return value will be >= 0 if
1812 * and only if the key is found.
1813 * @throws IllegalArgumentException
1814 * if {@code fromIndex > toIndex}
1815 * @throws ArrayIndexOutOfBoundsException
1816 * if {@code fromIndex < 0 or toIndex > a.length}
1817 * @since 1.6
1818 */
1819 public static int binarySearch(long[] a, int fromIndex, int toIndex,
1820 long key) {
1821 rangeCheck(a.length, fromIndex, toIndex);
1822 return binarySearch0(a, fromIndex, toIndex, key);
1823 }
1824
1825 // Like public version, but without range checks.
1826 private static int binarySearch0(long[] a, int fromIndex, int toIndex,
1827 long key) {
1828 int low = fromIndex;
1829 int high = toIndex - 1;
1836 low = mid + 1;
1837 else if (midVal > key)
1838 high = mid - 1;
1839 else
1840 return mid; // key found
1841 }
1842 return -(low + 1); // key not found.
1843 }
1844
1845 /**
1846 * Searches the specified array of ints for the specified value using the
1847 * binary search algorithm. The array must be sorted (as
1848 * by the {@link #sort(int[])} method) prior to making this call. If it
1849 * is not sorted, the results are undefined. If the array contains
1850 * multiple elements with the specified value, there is no guarantee which
1851 * one will be found.
1852 *
1853 * @param a the array to be searched
1854 * @param key the value to be searched for
1855 * @return index of the search key, if it is contained in the array;
1856 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
1857 * <i>insertion point</i> is defined as the point at which the
1858 * key would be inserted into the array: the index of the first
1859 * element greater than the key, or {@code a.length} if all
1860 * elements in the array are less than the specified key. Note
1861 * that this guarantees that the return value will be >= 0 if
1862 * and only if the key is found.
1863 */
1864 public static int binarySearch(int[] a, int key) {
1865 return binarySearch0(a, 0, a.length, key);
1866 }
1867
1868 /**
1869 * Searches a range of
1870 * the specified array of ints for the specified value using the
1871 * binary search algorithm.
1872 * The range must be sorted (as
1873 * by the {@link #sort(int[], int, int)} method)
1874 * prior to making this call. If it
1875 * is not sorted, the results are undefined. If the range contains
1876 * multiple elements with the specified value, there is no guarantee which
1877 * one will be found.
1878 *
1879 * @param a the array to be searched
1880 * @param fromIndex the index of the first element (inclusive) to be
1881 * searched
1882 * @param toIndex the index of the last element (exclusive) to be searched
1883 * @param key the value to be searched for
1884 * @return index of the search key, if it is contained in the array
1885 * within the specified range;
1886 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
1887 * <i>insertion point</i> is defined as the point at which the
1888 * key would be inserted into the array: the index of the first
1889 * element in the range greater than the key,
1890 * or {@code toIndex} if all
1891 * elements in the range are less than the specified key. Note
1892 * that this guarantees that the return value will be >= 0 if
1893 * and only if the key is found.
1894 * @throws IllegalArgumentException
1895 * if {@code fromIndex > toIndex}
1896 * @throws ArrayIndexOutOfBoundsException
1897 * if {@code fromIndex < 0 or toIndex > a.length}
1898 * @since 1.6
1899 */
1900 public static int binarySearch(int[] a, int fromIndex, int toIndex,
1901 int key) {
1902 rangeCheck(a.length, fromIndex, toIndex);
1903 return binarySearch0(a, fromIndex, toIndex, key);
1904 }
1905
1906 // Like public version, but without range checks.
1907 private static int binarySearch0(int[] a, int fromIndex, int toIndex,
1908 int key) {
1909 int low = fromIndex;
1910 int high = toIndex - 1;
1917 low = mid + 1;
1918 else if (midVal > key)
1919 high = mid - 1;
1920 else
1921 return mid; // key found
1922 }
1923 return -(low + 1); // key not found.
1924 }
1925
1926 /**
1927 * Searches the specified array of shorts for the specified value using
1928 * the binary search algorithm. The array must be sorted
1929 * (as by the {@link #sort(short[])} method) prior to making this call. If
1930 * it is not sorted, the results are undefined. If the array contains
1931 * multiple elements with the specified value, there is no guarantee which
1932 * one will be found.
1933 *
1934 * @param a the array to be searched
1935 * @param key the value to be searched for
1936 * @return index of the search key, if it is contained in the array;
1937 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
1938 * <i>insertion point</i> is defined as the point at which the
1939 * key would be inserted into the array: the index of the first
1940 * element greater than the key, or {@code a.length} if all
1941 * elements in the array are less than the specified key. Note
1942 * that this guarantees that the return value will be >= 0 if
1943 * and only if the key is found.
1944 */
1945 public static int binarySearch(short[] a, short key) {
1946 return binarySearch0(a, 0, a.length, key);
1947 }
1948
1949 /**
1950 * Searches a range of
1951 * the specified array of shorts for the specified value using
1952 * the binary search algorithm.
1953 * The range must be sorted
1954 * (as by the {@link #sort(short[], int, int)} method)
1955 * prior to making this call. If
1956 * it is not sorted, the results are undefined. If the range contains
1957 * multiple elements with the specified value, there is no guarantee which
1958 * one will be found.
1959 *
1960 * @param a the array to be searched
1961 * @param fromIndex the index of the first element (inclusive) to be
1962 * searched
1963 * @param toIndex the index of the last element (exclusive) to be searched
1964 * @param key the value to be searched for
1965 * @return index of the search key, if it is contained in the array
1966 * within the specified range;
1967 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
1968 * <i>insertion point</i> is defined as the point at which the
1969 * key would be inserted into the array: the index of the first
1970 * element in the range greater than the key,
1971 * or {@code toIndex} if all
1972 * elements in the range are less than the specified key. Note
1973 * that this guarantees that the return value will be >= 0 if
1974 * and only if the key is found.
1975 * @throws IllegalArgumentException
1976 * if {@code fromIndex > toIndex}
1977 * @throws ArrayIndexOutOfBoundsException
1978 * if {@code fromIndex < 0 or toIndex > a.length}
1979 * @since 1.6
1980 */
1981 public static int binarySearch(short[] a, int fromIndex, int toIndex,
1982 short key) {
1983 rangeCheck(a.length, fromIndex, toIndex);
1984 return binarySearch0(a, fromIndex, toIndex, key);
1985 }
1986
1987 // Like public version, but without range checks.
1988 private static int binarySearch0(short[] a, int fromIndex, int toIndex,
1989 short key) {
1990 int low = fromIndex;
1991 int high = toIndex - 1;
1998 low = mid + 1;
1999 else if (midVal > key)
2000 high = mid - 1;
2001 else
2002 return mid; // key found
2003 }
2004 return -(low + 1); // key not found.
2005 }
2006
2007 /**
2008 * Searches the specified array of chars for the specified value using the
2009 * binary search algorithm. The array must be sorted (as
2010 * by the {@link #sort(char[])} method) prior to making this call. If it
2011 * is not sorted, the results are undefined. If the array contains
2012 * multiple elements with the specified value, there is no guarantee which
2013 * one will be found.
2014 *
2015 * @param a the array to be searched
2016 * @param key the value to be searched for
2017 * @return index of the search key, if it is contained in the array;
2018 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2019 * <i>insertion point</i> is defined as the point at which the
2020 * key would be inserted into the array: the index of the first
2021 * element greater than the key, or {@code a.length} if all
2022 * elements in the array are less than the specified key. Note
2023 * that this guarantees that the return value will be >= 0 if
2024 * and only if the key is found.
2025 */
2026 public static int binarySearch(char[] a, char key) {
2027 return binarySearch0(a, 0, a.length, key);
2028 }
2029
2030 /**
2031 * Searches a range of
2032 * the specified array of chars for the specified value using the
2033 * binary search algorithm.
2034 * The range must be sorted (as
2035 * by the {@link #sort(char[], int, int)} method)
2036 * prior to making this call. If it
2037 * is not sorted, the results are undefined. If the range contains
2038 * multiple elements with the specified value, there is no guarantee which
2039 * one will be found.
2040 *
2041 * @param a the array to be searched
2042 * @param fromIndex the index of the first element (inclusive) to be
2043 * searched
2044 * @param toIndex the index of the last element (exclusive) to be searched
2045 * @param key the value to be searched for
2046 * @return index of the search key, if it is contained in the array
2047 * within the specified range;
2048 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2049 * <i>insertion point</i> is defined as the point at which the
2050 * key would be inserted into the array: the index of the first
2051 * element in the range greater than the key,
2052 * or {@code toIndex} if all
2053 * elements in the range are less than the specified key. Note
2054 * that this guarantees that the return value will be >= 0 if
2055 * and only if the key is found.
2056 * @throws IllegalArgumentException
2057 * if {@code fromIndex > toIndex}
2058 * @throws ArrayIndexOutOfBoundsException
2059 * if {@code fromIndex < 0 or toIndex > a.length}
2060 * @since 1.6
2061 */
2062 public static int binarySearch(char[] a, int fromIndex, int toIndex,
2063 char key) {
2064 rangeCheck(a.length, fromIndex, toIndex);
2065 return binarySearch0(a, fromIndex, toIndex, key);
2066 }
2067
2068 // Like public version, but without range checks.
2069 private static int binarySearch0(char[] a, int fromIndex, int toIndex,
2070 char key) {
2071 int low = fromIndex;
2072 int high = toIndex - 1;
2079 low = mid + 1;
2080 else if (midVal > key)
2081 high = mid - 1;
2082 else
2083 return mid; // key found
2084 }
2085 return -(low + 1); // key not found.
2086 }
2087
2088 /**
2089 * Searches the specified array of bytes for the specified value using the
2090 * binary search algorithm. The array must be sorted (as
2091 * by the {@link #sort(byte[])} method) prior to making this call. If it
2092 * is not sorted, the results are undefined. If the array contains
2093 * multiple elements with the specified value, there is no guarantee which
2094 * one will be found.
2095 *
2096 * @param a the array to be searched
2097 * @param key the value to be searched for
2098 * @return index of the search key, if it is contained in the array;
2099 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2100 * <i>insertion point</i> is defined as the point at which the
2101 * key would be inserted into the array: the index of the first
2102 * element greater than the key, or {@code a.length} if all
2103 * elements in the array are less than the specified key. Note
2104 * that this guarantees that the return value will be >= 0 if
2105 * and only if the key is found.
2106 */
2107 public static int binarySearch(byte[] a, byte key) {
2108 return binarySearch0(a, 0, a.length, key);
2109 }
2110
2111 /**
2112 * Searches a range of
2113 * the specified array of bytes for the specified value using the
2114 * binary search algorithm.
2115 * The range must be sorted (as
2116 * by the {@link #sort(byte[], int, int)} method)
2117 * prior to making this call. If it
2118 * is not sorted, the results are undefined. If the range contains
2119 * multiple elements with the specified value, there is no guarantee which
2120 * one will be found.
2121 *
2122 * @param a the array to be searched
2123 * @param fromIndex the index of the first element (inclusive) to be
2124 * searched
2125 * @param toIndex the index of the last element (exclusive) to be searched
2126 * @param key the value to be searched for
2127 * @return index of the search key, if it is contained in the array
2128 * within the specified range;
2129 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2130 * <i>insertion point</i> is defined as the point at which the
2131 * key would be inserted into the array: the index of the first
2132 * element in the range greater than the key,
2133 * or {@code toIndex} if all
2134 * elements in the range are less than the specified key. Note
2135 * that this guarantees that the return value will be >= 0 if
2136 * and only if the key is found.
2137 * @throws IllegalArgumentException
2138 * if {@code fromIndex > toIndex}
2139 * @throws ArrayIndexOutOfBoundsException
2140 * if {@code fromIndex < 0 or toIndex > a.length}
2141 * @since 1.6
2142 */
2143 public static int binarySearch(byte[] a, int fromIndex, int toIndex,
2144 byte key) {
2145 rangeCheck(a.length, fromIndex, toIndex);
2146 return binarySearch0(a, fromIndex, toIndex, key);
2147 }
2148
2149 // Like public version, but without range checks.
2150 private static int binarySearch0(byte[] a, int fromIndex, int toIndex,
2151 byte key) {
2152 int low = fromIndex;
2153 int high = toIndex - 1;
2161 else if (midVal > key)
2162 high = mid - 1;
2163 else
2164 return mid; // key found
2165 }
2166 return -(low + 1); // key not found.
2167 }
2168
2169 /**
2170 * Searches the specified array of doubles for the specified value using
2171 * the binary search algorithm. The array must be sorted
2172 * (as by the {@link #sort(double[])} method) prior to making this call.
2173 * If it is not sorted, the results are undefined. If the array contains
2174 * multiple elements with the specified value, there is no guarantee which
2175 * one will be found. This method considers all NaN values to be
2176 * equivalent and equal.
2177 *
2178 * @param a the array to be searched
2179 * @param key the value to be searched for
2180 * @return index of the search key, if it is contained in the array;
2181 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2182 * <i>insertion point</i> is defined as the point at which the
2183 * key would be inserted into the array: the index of the first
2184 * element greater than the key, or {@code a.length} if all
2185 * elements in the array are less than the specified key. Note
2186 * that this guarantees that the return value will be >= 0 if
2187 * and only if the key is found.
2188 */
2189 public static int binarySearch(double[] a, double key) {
2190 return binarySearch0(a, 0, a.length, key);
2191 }
2192
2193 /**
2194 * Searches a range of
2195 * the specified array of doubles for the specified value using
2196 * the binary search algorithm.
2197 * The range must be sorted
2198 * (as by the {@link #sort(double[], int, int)} method)
2199 * prior to making this call.
2200 * If it is not sorted, the results are undefined. If the range contains
2201 * multiple elements with the specified value, there is no guarantee which
2202 * one will be found. This method considers all NaN values to be
2203 * equivalent and equal.
2204 *
2205 * @param a the array to be searched
2206 * @param fromIndex the index of the first element (inclusive) to be
2207 * searched
2208 * @param toIndex the index of the last element (exclusive) to be searched
2209 * @param key the value to be searched for
2210 * @return index of the search key, if it is contained in the array
2211 * within the specified range;
2212 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2213 * <i>insertion point</i> is defined as the point at which the
2214 * key would be inserted into the array: the index of the first
2215 * element in the range greater than the key,
2216 * or {@code toIndex} if all
2217 * elements in the range are less than the specified key. Note
2218 * that this guarantees that the return value will be >= 0 if
2219 * and only if the key is found.
2220 * @throws IllegalArgumentException
2221 * if {@code fromIndex > toIndex}
2222 * @throws ArrayIndexOutOfBoundsException
2223 * if {@code fromIndex < 0 or toIndex > a.length}
2224 * @since 1.6
2225 */
2226 public static int binarySearch(double[] a, int fromIndex, int toIndex,
2227 double key) {
2228 rangeCheck(a.length, fromIndex, toIndex);
2229 return binarySearch0(a, fromIndex, toIndex, key);
2230 }
2231
2232 // Like public version, but without range checks.
2233 private static int binarySearch0(double[] a, int fromIndex, int toIndex,
2234 double key) {
2235 int low = fromIndex;
2236 int high = toIndex - 1;
2252 low = mid + 1;
2253 else // (0.0, -0.0) or (NaN, !NaN)
2254 high = mid - 1;
2255 }
2256 }
2257 return -(low + 1); // key not found.
2258 }
2259
2260 /**
2261 * Searches the specified array of floats for the specified value using
2262 * the binary search algorithm. The array must be sorted
2263 * (as by the {@link #sort(float[])} method) prior to making this call. If
2264 * it is not sorted, the results are undefined. If the array contains
2265 * multiple elements with the specified value, there is no guarantee which
2266 * one will be found. This method considers all NaN values to be
2267 * equivalent and equal.
2268 *
2269 * @param a the array to be searched
2270 * @param key the value to be searched for
2271 * @return index of the search key, if it is contained in the array;
2272 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2273 * <i>insertion point</i> is defined as the point at which the
2274 * key would be inserted into the array: the index of the first
2275 * element greater than the key, or {@code a.length} if all
2276 * elements in the array are less than the specified key. Note
2277 * that this guarantees that the return value will be >= 0 if
2278 * and only if the key is found.
2279 */
2280 public static int binarySearch(float[] a, float key) {
2281 return binarySearch0(a, 0, a.length, key);
2282 }
2283
2284 /**
2285 * Searches a range of
2286 * the specified array of floats for the specified value using
2287 * the binary search algorithm.
2288 * The range must be sorted
2289 * (as by the {@link #sort(float[], int, int)} method)
2290 * prior to making this call. If
2291 * it is not sorted, the results are undefined. If the range contains
2292 * multiple elements with the specified value, there is no guarantee which
2293 * one will be found. This method considers all NaN values to be
2294 * equivalent and equal.
2295 *
2296 * @param a the array to be searched
2297 * @param fromIndex the index of the first element (inclusive) to be
2298 * searched
2299 * @param toIndex the index of the last element (exclusive) to be searched
2300 * @param key the value to be searched for
2301 * @return index of the search key, if it is contained in the array
2302 * within the specified range;
2303 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2304 * <i>insertion point</i> is defined as the point at which the
2305 * key would be inserted into the array: the index of the first
2306 * element in the range greater than the key,
2307 * or {@code toIndex} if all
2308 * elements in the range are less than the specified key. Note
2309 * that this guarantees that the return value will be >= 0 if
2310 * and only if the key is found.
2311 * @throws IllegalArgumentException
2312 * if {@code fromIndex > toIndex}
2313 * @throws ArrayIndexOutOfBoundsException
2314 * if {@code fromIndex < 0 or toIndex > a.length}
2315 * @since 1.6
2316 */
2317 public static int binarySearch(float[] a, int fromIndex, int toIndex,
2318 float key) {
2319 rangeCheck(a.length, fromIndex, toIndex);
2320 return binarySearch0(a, fromIndex, toIndex, key);
2321 }
2322
2323 // Like public version, but without range checks.
2324 private static int binarySearch0(float[] a, int fromIndex, int toIndex,
2325 float key) {
2326 int low = fromIndex;
2327 int high = toIndex - 1;
2349 }
2350
2351 /**
2352 * Searches the specified array for the specified object using the binary
2353 * search algorithm. The array must be sorted into ascending order
2354 * according to the
2355 * {@linkplain Comparable natural ordering}
2356 * of its elements (as by the
2357 * {@link #sort(Object[])} method) prior to making this call.
2358 * If it is not sorted, the results are undefined.
2359 * (If the array contains elements that are not mutually comparable (for
2360 * example, strings and integers), it <i>cannot</i> be sorted according
2361 * to the natural ordering of its elements, hence results are undefined.)
2362 * If the array contains multiple
2363 * elements equal to the specified object, there is no guarantee which
2364 * one will be found.
2365 *
2366 * @param a the array to be searched
2367 * @param key the value to be searched for
2368 * @return index of the search key, if it is contained in the array;
2369 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2370 * <i>insertion point</i> is defined as the point at which the
2371 * key would be inserted into the array: the index of the first
2372 * element greater than the key, or {@code a.length} if all
2373 * elements in the array are less than the specified key. Note
2374 * that this guarantees that the return value will be >= 0 if
2375 * and only if the key is found.
2376 * @throws ClassCastException if the search key is not comparable to the
2377 * elements of the array.
2378 */
2379 public static int binarySearch(Object[] a, Object key) {
2380 return binarySearch0(a, 0, a.length, key);
2381 }
2382
2383 /**
2384 * Searches a range of
2385 * the specified array for the specified object using the binary
2386 * search algorithm.
2387 * The range must be sorted into ascending order
2388 * according to the
2389 * {@linkplain Comparable natural ordering}
2390 * of its elements (as by the
2391 * {@link #sort(Object[], int, int)} method) prior to making this
2392 * call. If it is not sorted, the results are undefined.
2393 * (If the range contains elements that are not mutually comparable (for
2394 * example, strings and integers), it <i>cannot</i> be sorted according
2395 * to the natural ordering of its elements, hence results are undefined.)
2396 * If the range contains multiple
2397 * elements equal to the specified object, there is no guarantee which
2398 * one will be found.
2399 *
2400 * @param a the array to be searched
2401 * @param fromIndex the index of the first element (inclusive) to be
2402 * searched
2403 * @param toIndex the index of the last element (exclusive) to be searched
2404 * @param key the value to be searched for
2405 * @return index of the search key, if it is contained in the array
2406 * within the specified range;
2407 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2408 * <i>insertion point</i> is defined as the point at which the
2409 * key would be inserted into the array: the index of the first
2410 * element in the range greater than the key,
2411 * or {@code toIndex} if all
2412 * elements in the range are less than the specified key. Note
2413 * that this guarantees that the return value will be >= 0 if
2414 * and only if the key is found.
2415 * @throws ClassCastException if the search key is not comparable to the
2416 * elements of the array within the specified range.
2417 * @throws IllegalArgumentException
2418 * if {@code fromIndex > toIndex}
2419 * @throws ArrayIndexOutOfBoundsException
2420 * if {@code fromIndex < 0 or toIndex > a.length}
2421 * @since 1.6
2422 */
2423 public static int binarySearch(Object[] a, int fromIndex, int toIndex,
2424 Object key) {
2425 rangeCheck(a.length, fromIndex, toIndex);
2426 return binarySearch0(a, fromIndex, toIndex, key);
2427 }
2428
2429 // Like public version, but without range checks.
2430 private static int binarySearch0(Object[] a, int fromIndex, int toIndex,
2431 Object key) {
2447 return mid; // key found
2448 }
2449 return -(low + 1); // key not found.
2450 }
2451
2452 /**
2453 * Searches the specified array for the specified object using the binary
2454 * search algorithm. The array must be sorted into ascending order
2455 * according to the specified comparator (as by the
2456 * {@link #sort(Object[], Comparator) sort(T[], Comparator)}
2457 * method) prior to making this call. If it is
2458 * not sorted, the results are undefined.
2459 * If the array contains multiple
2460 * elements equal to the specified object, there is no guarantee which one
2461 * will be found.
2462 *
2463 * @param <T> the class of the objects in the array
2464 * @param a the array to be searched
2465 * @param key the value to be searched for
2466 * @param c the comparator by which the array is ordered. A
2467 * {@code null} value indicates that the elements'
2468 * {@linkplain Comparable natural ordering} should be used.
2469 * @return index of the search key, if it is contained in the array;
2470 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2471 * <i>insertion point</i> is defined as the point at which the
2472 * key would be inserted into the array: the index of the first
2473 * element greater than the key, or {@code a.length} if all
2474 * elements in the array are less than the specified key. Note
2475 * that this guarantees that the return value will be >= 0 if
2476 * and only if the key is found.
2477 * @throws ClassCastException if the array contains elements that are not
2478 * <i>mutually comparable</i> using the specified comparator,
2479 * or the search key is not comparable to the
2480 * elements of the array using this comparator.
2481 */
2482 public static <T> int binarySearch(T[] a, T key, Comparator<? super T> c) {
2483 return binarySearch0(a, 0, a.length, key, c);
2484 }
2485
2486 /**
2487 * Searches a range of
2488 * the specified array for the specified object using the binary
2489 * search algorithm.
2490 * The range must be sorted into ascending order
2491 * according to the specified comparator (as by the
2492 * {@link #sort(Object[], int, int, Comparator)
2493 * sort(T[], int, int, Comparator)}
2494 * method) prior to making this call.
2495 * If it is not sorted, the results are undefined.
2496 * If the range contains multiple elements equal to the specified object,
2497 * there is no guarantee which one will be found.
2498 *
2499 * @param <T> the class of the objects in the array
2500 * @param a the array to be searched
2501 * @param fromIndex the index of the first element (inclusive) to be
2502 * searched
2503 * @param toIndex the index of the last element (exclusive) to be searched
2504 * @param key the value to be searched for
2505 * @param c the comparator by which the array is ordered. A
2506 * {@code null} value indicates that the elements'
2507 * {@linkplain Comparable natural ordering} should be used.
2508 * @return index of the search key, if it is contained in the array
2509 * within the specified range;
2510 * otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2511 * <i>insertion point</i> is defined as the point at which the
2512 * key would be inserted into the array: the index of the first
2513 * element in the range greater than the key,
2514 * or {@code toIndex} if all
2515 * elements in the range are less than the specified key. Note
2516 * that this guarantees that the return value will be >= 0 if
2517 * and only if the key is found.
2518 * @throws ClassCastException if the range contains elements that are not
2519 * <i>mutually comparable</i> using the specified comparator,
2520 * or the search key is not comparable to the
2521 * elements in the range using this comparator.
2522 * @throws IllegalArgumentException
2523 * if {@code fromIndex > toIndex}
2524 * @throws ArrayIndexOutOfBoundsException
2525 * if {@code fromIndex < 0 or toIndex > a.length}
2526 * @since 1.6
2527 */
2528 public static <T> int binarySearch(T[] a, int fromIndex, int toIndex,
2529 T key, Comparator<? super T> c) {
2530 rangeCheck(a.length, fromIndex, toIndex);
2531 return binarySearch0(a, fromIndex, toIndex, key, c);
2532 }
2533
2534 // Like public version, but without range checks.
2540 int low = fromIndex;
2541 int high = toIndex - 1;
2542
2543 while (low <= high) {
2544 int mid = (low + high) >>> 1;
2545 T midVal = a[mid];
2546 int cmp = c.compare(midVal, key);
2547 if (cmp < 0)
2548 low = mid + 1;
2549 else if (cmp > 0)
2550 high = mid - 1;
2551 else
2552 return mid; // key found
2553 }
2554 return -(low + 1); // key not found.
2555 }
2556
2557 // Equality Testing
2558
2559 /**
2560 * Returns {@code true} if the two specified arrays of longs are
2561 * <i>equal</i> to one another. Two arrays are considered equal if both
2562 * arrays contain the same number of elements, and all corresponding pairs
2563 * of elements in the two arrays are equal. In other words, two arrays
2564 * are equal if they contain the same elements in the same order. Also,
2565 * two array references are considered equal if both are {@code null}.
2566 *
2567 * @param a one array to be tested for equality
2568 * @param a2 the other array to be tested for equality
2569 * @return {@code true} if the two arrays are equal
2570 */
2571 public static boolean equals(long[] a, long[] a2) {
2572 if (a==a2)
2573 return true;
2574 if (a==null || a2==null)
2575 return false;
2576
2577 int length = a.length;
2578 if (a2.length != length)
2579 return false;
2580
2581 for (int i=0; i<length; i++)
2582 if (a[i] != a2[i])
2583 return false;
2584
2585 return true;
2586 }
2587
2588 /**
2589 * Returns {@code true} if the two specified arrays of ints are
2590 * <i>equal</i> to one another. Two arrays are considered equal if both
2591 * arrays contain the same number of elements, and all corresponding pairs
2592 * of elements in the two arrays are equal. In other words, two arrays
2593 * are equal if they contain the same elements in the same order. Also,
2594 * two array references are considered equal if both are {@code null}.
2595 *
2596 * @param a one array to be tested for equality
2597 * @param a2 the other array to be tested for equality
2598 * @return {@code true} if the two arrays are equal
2599 */
2600 public static boolean equals(int[] a, int[] a2) {
2601 if (a==a2)
2602 return true;
2603 if (a==null || a2==null)
2604 return false;
2605
2606 int length = a.length;
2607 if (a2.length != length)
2608 return false;
2609
2610 for (int i=0; i<length; i++)
2611 if (a[i] != a2[i])
2612 return false;
2613
2614 return true;
2615 }
2616
2617 /**
2618 * Returns {@code true} if the two specified arrays of shorts are
2619 * <i>equal</i> to one another. Two arrays are considered equal if both
2620 * arrays contain the same number of elements, and all corresponding pairs
2621 * of elements in the two arrays are equal. In other words, two arrays
2622 * are equal if they contain the same elements in the same order. Also,
2623 * two array references are considered equal if both are {@code null}.
2624 *
2625 * @param a one array to be tested for equality
2626 * @param a2 the other array to be tested for equality
2627 * @return {@code true} if the two arrays are equal
2628 */
2629 public static boolean equals(short[] a, short a2[]) {
2630 if (a==a2)
2631 return true;
2632 if (a==null || a2==null)
2633 return false;
2634
2635 int length = a.length;
2636 if (a2.length != length)
2637 return false;
2638
2639 for (int i=0; i<length; i++)
2640 if (a[i] != a2[i])
2641 return false;
2642
2643 return true;
2644 }
2645
2646 /**
2647 * Returns {@code true} if the two specified arrays of chars are
2648 * <i>equal</i> to one another. Two arrays are considered equal if both
2649 * arrays contain the same number of elements, and all corresponding pairs
2650 * of elements in the two arrays are equal. In other words, two arrays
2651 * are equal if they contain the same elements in the same order. Also,
2652 * two array references are considered equal if both are {@code null}.
2653 *
2654 * @param a one array to be tested for equality
2655 * @param a2 the other array to be tested for equality
2656 * @return {@code true} if the two arrays are equal
2657 */
2658 @HotSpotIntrinsicCandidate
2659 public static boolean equals(char[] a, char[] a2) {
2660 if (a==a2)
2661 return true;
2662 if (a==null || a2==null)
2663 return false;
2664
2665 int length = a.length;
2666 if (a2.length != length)
2667 return false;
2668
2669 for (int i=0; i<length; i++)
2670 if (a[i] != a2[i])
2671 return false;
2672
2673 return true;
2674 }
2675
2676 /**
2677 * Returns {@code true} if the two specified arrays of bytes are
2678 * <i>equal</i> to one another. Two arrays are considered equal if both
2679 * arrays contain the same number of elements, and all corresponding pairs
2680 * of elements in the two arrays are equal. In other words, two arrays
2681 * are equal if they contain the same elements in the same order. Also,
2682 * two array references are considered equal if both are {@code null}.
2683 *
2684 * @param a one array to be tested for equality
2685 * @param a2 the other array to be tested for equality
2686 * @return {@code true} if the two arrays are equal
2687 */
2688 public static boolean equals(byte[] a, byte[] a2) {
2689 if (a==a2)
2690 return true;
2691 if (a==null || a2==null)
2692 return false;
2693
2694 int length = a.length;
2695 if (a2.length != length)
2696 return false;
2697
2698 for (int i=0; i<length; i++)
2699 if (a[i] != a2[i])
2700 return false;
2701
2702 return true;
2703 }
2704
2705 /**
2706 * Returns {@code true} if the two specified arrays of booleans are
2707 * <i>equal</i> to one another. Two arrays are considered equal if both
2708 * arrays contain the same number of elements, and all corresponding pairs
2709 * of elements in the two arrays are equal. In other words, two arrays
2710 * are equal if they contain the same elements in the same order. Also,
2711 * two array references are considered equal if both are {@code null}.
2712 *
2713 * @param a one array to be tested for equality
2714 * @param a2 the other array to be tested for equality
2715 * @return {@code true} if the two arrays are equal
2716 */
2717 public static boolean equals(boolean[] a, boolean[] a2) {
2718 if (a==a2)
2719 return true;
2720 if (a==null || a2==null)
2721 return false;
2722
2723 int length = a.length;
2724 if (a2.length != length)
2725 return false;
2726
2727 for (int i=0; i<length; i++)
2728 if (a[i] != a2[i])
2729 return false;
2730
2731 return true;
2732 }
2733
2734 /**
2735 * Returns {@code true} if the two specified arrays of doubles are
2736 * <i>equal</i> to one another. Two arrays are considered equal if both
2737 * arrays contain the same number of elements, and all corresponding pairs
2738 * of elements in the two arrays are equal. In other words, two arrays
2739 * are equal if they contain the same elements in the same order. Also,
2740 * two array references are considered equal if both are {@code null}.
2741 *
2742 * Two doubles {@code d1} and {@code d2} are considered equal if:
2743 * <pre> {@code new Double(d1).equals(new Double(d2))}</pre>
2744 * (Unlike the {@code ==} operator, this method considers
2745 * {@code NaN} equals to itself, and 0.0d unequal to -0.0d.)
2746 *
2747 * @param a one array to be tested for equality
2748 * @param a2 the other array to be tested for equality
2749 * @return {@code true} if the two arrays are equal
2750 * @see Double#equals(Object)
2751 */
2752 public static boolean equals(double[] a, double[] a2) {
2753 if (a==a2)
2754 return true;
2755 if (a==null || a2==null)
2756 return false;
2757
2758 int length = a.length;
2759 if (a2.length != length)
2760 return false;
2761
2762 for (int i=0; i<length; i++)
2763 if (Double.doubleToLongBits(a[i])!=Double.doubleToLongBits(a2[i]))
2764 return false;
2765
2766 return true;
2767 }
2768
2769 /**
2770 * Returns {@code true} if the two specified arrays of floats are
2771 * <i>equal</i> to one another. Two arrays are considered equal if both
2772 * arrays contain the same number of elements, and all corresponding pairs
2773 * of elements in the two arrays are equal. In other words, two arrays
2774 * are equal if they contain the same elements in the same order. Also,
2775 * two array references are considered equal if both are {@code null}.
2776 *
2777 * Two floats {@code f1} and {@code f2} are considered equal if:
2778 * <pre> {@code new Float(f1).equals(new Float(f2))}</pre>
2779 * (Unlike the {@code ==} operator, this method considers
2780 * {@code NaN} equals to itself, and 0.0f unequal to -0.0f.)
2781 *
2782 * @param a one array to be tested for equality
2783 * @param a2 the other array to be tested for equality
2784 * @return {@code true} if the two arrays are equal
2785 * @see Float#equals(Object)
2786 */
2787 public static boolean equals(float[] a, float[] a2) {
2788 if (a==a2)
2789 return true;
2790 if (a==null || a2==null)
2791 return false;
2792
2793 int length = a.length;
2794 if (a2.length != length)
2795 return false;
2796
2797 for (int i=0; i<length; i++)
2798 if (Float.floatToIntBits(a[i])!=Float.floatToIntBits(a2[i]))
2799 return false;
2800
2801 return true;
2802 }
2803
2804 /**
2805 * Returns {@code true} if the two specified arrays of Objects are
2806 * <i>equal</i> to one another. The two arrays are considered equal if
2807 * both arrays contain the same number of elements, and all corresponding
2808 * pairs of elements in the two arrays are equal. Two objects {@code e1}
2809 * and {@code e2} are considered <i>equal</i> if {@code (e1==null ? e2==null
2810 * : e1.equals(e2))}. In other words, the two arrays are equal if
2811 * they contain the same elements in the same order. Also, two array
2812 * references are considered equal if both are {@code null}.
2813 *
2814 * @param a one array to be tested for equality
2815 * @param a2 the other array to be tested for equality
2816 * @return {@code true} if the two arrays are equal
2817 */
2818 public static boolean equals(Object[] a, Object[] a2) {
2819 if (a==a2)
2820 return true;
2821 if (a==null || a2==null)
2822 return false;
2823
2824 int length = a.length;
2825 if (a2.length != length)
2826 return false;
2827
2828 for (int i=0; i<length; i++) {
2829 Object o1 = a[i];
2830 Object o2 = a2[i];
2831 if (!(o1==null ? o2==null : o1.equals(o2)))
2832 return false;
2833 }
2834
2835 return true;
2836 }
2837
2838 // Filling
2839
2840 /**
2841 * Assigns the specified long value to each element of the specified array
2842 * of longs.
2843 *
2844 * @param a the array to be filled
2845 * @param val the value to be stored in all elements of the array
2846 */
2847 public static void fill(long[] a, long val) {
2848 for (int i = 0, len = a.length; i < len; i++)
2849 a[i] = val;
2850 }
2851
2852 /**
2853 * Assigns the specified long value to each element of the specified
2854 * range of the specified array of longs. The range to be filled
2855 * extends from index {@code fromIndex}, inclusive, to index
2856 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
2857 * range to be filled is empty.)
2858 *
2859 * @param a the array to be filled
2860 * @param fromIndex the index of the first element (inclusive) to be
2861 * filled with the specified value
2862 * @param toIndex the index of the last element (exclusive) to be
2863 * filled with the specified value
2864 * @param val the value to be stored in all elements of the array
2865 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
2866 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
2867 * {@code toIndex > a.length}
2868 */
2869 public static void fill(long[] a, int fromIndex, int toIndex, long val) {
2870 rangeCheck(a.length, fromIndex, toIndex);
2871 for (int i = fromIndex; i < toIndex; i++)
2872 a[i] = val;
2873 }
2874
2875 /**
2876 * Assigns the specified int value to each element of the specified array
2877 * of ints.
2878 *
2879 * @param a the array to be filled
2880 * @param val the value to be stored in all elements of the array
2881 */
2882 public static void fill(int[] a, int val) {
2883 for (int i = 0, len = a.length; i < len; i++)
2884 a[i] = val;
2885 }
2886
2887 /**
2888 * Assigns the specified int value to each element of the specified
2889 * range of the specified array of ints. The range to be filled
2890 * extends from index {@code fromIndex}, inclusive, to index
2891 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
2892 * range to be filled is empty.)
2893 *
2894 * @param a the array to be filled
2895 * @param fromIndex the index of the first element (inclusive) to be
2896 * filled with the specified value
2897 * @param toIndex the index of the last element (exclusive) to be
2898 * filled with the specified value
2899 * @param val the value to be stored in all elements of the array
2900 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
2901 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
2902 * {@code toIndex > a.length}
2903 */
2904 public static void fill(int[] a, int fromIndex, int toIndex, int val) {
2905 rangeCheck(a.length, fromIndex, toIndex);
2906 for (int i = fromIndex; i < toIndex; i++)
2907 a[i] = val;
2908 }
2909
2910 /**
2911 * Assigns the specified short value to each element of the specified array
2912 * of shorts.
2913 *
2914 * @param a the array to be filled
2915 * @param val the value to be stored in all elements of the array
2916 */
2917 public static void fill(short[] a, short val) {
2918 for (int i = 0, len = a.length; i < len; i++)
2919 a[i] = val;
2920 }
2921
2922 /**
2923 * Assigns the specified short value to each element of the specified
2924 * range of the specified array of shorts. The range to be filled
2925 * extends from index {@code fromIndex}, inclusive, to index
2926 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
2927 * range to be filled is empty.)
2928 *
2929 * @param a the array to be filled
2930 * @param fromIndex the index of the first element (inclusive) to be
2931 * filled with the specified value
2932 * @param toIndex the index of the last element (exclusive) to be
2933 * filled with the specified value
2934 * @param val the value to be stored in all elements of the array
2935 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
2936 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
2937 * {@code toIndex > a.length}
2938 */
2939 public static void fill(short[] a, int fromIndex, int toIndex, short val) {
2940 rangeCheck(a.length, fromIndex, toIndex);
2941 for (int i = fromIndex; i < toIndex; i++)
2942 a[i] = val;
2943 }
2944
2945 /**
2946 * Assigns the specified char value to each element of the specified array
2947 * of chars.
2948 *
2949 * @param a the array to be filled
2950 * @param val the value to be stored in all elements of the array
2951 */
2952 public static void fill(char[] a, char val) {
2953 for (int i = 0, len = a.length; i < len; i++)
2954 a[i] = val;
2955 }
2956
2957 /**
2958 * Assigns the specified char value to each element of the specified
2959 * range of the specified array of chars. The range to be filled
2960 * extends from index {@code fromIndex}, inclusive, to index
2961 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
2962 * range to be filled is empty.)
2963 *
2964 * @param a the array to be filled
2965 * @param fromIndex the index of the first element (inclusive) to be
2966 * filled with the specified value
2967 * @param toIndex the index of the last element (exclusive) to be
2968 * filled with the specified value
2969 * @param val the value to be stored in all elements of the array
2970 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
2971 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
2972 * {@code toIndex > a.length}
2973 */
2974 public static void fill(char[] a, int fromIndex, int toIndex, char val) {
2975 rangeCheck(a.length, fromIndex, toIndex);
2976 for (int i = fromIndex; i < toIndex; i++)
2977 a[i] = val;
2978 }
2979
2980 /**
2981 * Assigns the specified byte value to each element of the specified array
2982 * of bytes.
2983 *
2984 * @param a the array to be filled
2985 * @param val the value to be stored in all elements of the array
2986 */
2987 public static void fill(byte[] a, byte val) {
2988 for (int i = 0, len = a.length; i < len; i++)
2989 a[i] = val;
2990 }
2991
2992 /**
2993 * Assigns the specified byte value to each element of the specified
2994 * range of the specified array of bytes. The range to be filled
2995 * extends from index {@code fromIndex}, inclusive, to index
2996 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
2997 * range to be filled is empty.)
2998 *
2999 * @param a the array to be filled
3000 * @param fromIndex the index of the first element (inclusive) to be
3001 * filled with the specified value
3002 * @param toIndex the index of the last element (exclusive) to be
3003 * filled with the specified value
3004 * @param val the value to be stored in all elements of the array
3005 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3006 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3007 * {@code toIndex > a.length}
3008 */
3009 public static void fill(byte[] a, int fromIndex, int toIndex, byte val) {
3010 rangeCheck(a.length, fromIndex, toIndex);
3011 for (int i = fromIndex; i < toIndex; i++)
3012 a[i] = val;
3013 }
3014
3015 /**
3016 * Assigns the specified boolean value to each element of the specified
3017 * array of booleans.
3018 *
3019 * @param a the array to be filled
3020 * @param val the value to be stored in all elements of the array
3021 */
3022 public static void fill(boolean[] a, boolean val) {
3023 for (int i = 0, len = a.length; i < len; i++)
3024 a[i] = val;
3025 }
3026
3027 /**
3028 * Assigns the specified boolean value to each element of the specified
3029 * range of the specified array of booleans. The range to be filled
3030 * extends from index {@code fromIndex}, inclusive, to index
3031 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
3032 * range to be filled is empty.)
3033 *
3034 * @param a the array to be filled
3035 * @param fromIndex the index of the first element (inclusive) to be
3036 * filled with the specified value
3037 * @param toIndex the index of the last element (exclusive) to be
3038 * filled with the specified value
3039 * @param val the value to be stored in all elements of the array
3040 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3041 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3042 * {@code toIndex > a.length}
3043 */
3044 public static void fill(boolean[] a, int fromIndex, int toIndex,
3045 boolean val) {
3046 rangeCheck(a.length, fromIndex, toIndex);
3047 for (int i = fromIndex; i < toIndex; i++)
3048 a[i] = val;
3049 }
3050
3051 /**
3052 * Assigns the specified double value to each element of the specified
3053 * array of doubles.
3054 *
3055 * @param a the array to be filled
3056 * @param val the value to be stored in all elements of the array
3057 */
3058 public static void fill(double[] a, double val) {
3059 for (int i = 0, len = a.length; i < len; i++)
3060 a[i] = val;
3061 }
3062
3063 /**
3064 * Assigns the specified double value to each element of the specified
3065 * range of the specified array of doubles. The range to be filled
3066 * extends from index {@code fromIndex}, inclusive, to index
3067 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
3068 * range to be filled is empty.)
3069 *
3070 * @param a the array to be filled
3071 * @param fromIndex the index of the first element (inclusive) to be
3072 * filled with the specified value
3073 * @param toIndex the index of the last element (exclusive) to be
3074 * filled with the specified value
3075 * @param val the value to be stored in all elements of the array
3076 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3077 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3078 * {@code toIndex > a.length}
3079 */
3080 public static void fill(double[] a, int fromIndex, int toIndex,double val){
3081 rangeCheck(a.length, fromIndex, toIndex);
3082 for (int i = fromIndex; i < toIndex; i++)
3083 a[i] = val;
3084 }
3085
3086 /**
3087 * Assigns the specified float value to each element of the specified array
3088 * of floats.
3089 *
3090 * @param a the array to be filled
3091 * @param val the value to be stored in all elements of the array
3092 */
3093 public static void fill(float[] a, float val) {
3094 for (int i = 0, len = a.length; i < len; i++)
3095 a[i] = val;
3096 }
3097
3098 /**
3099 * Assigns the specified float value to each element of the specified
3100 * range of the specified array of floats. The range to be filled
3101 * extends from index {@code fromIndex}, inclusive, to index
3102 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
3103 * range to be filled is empty.)
3104 *
3105 * @param a the array to be filled
3106 * @param fromIndex the index of the first element (inclusive) to be
3107 * filled with the specified value
3108 * @param toIndex the index of the last element (exclusive) to be
3109 * filled with the specified value
3110 * @param val the value to be stored in all elements of the array
3111 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3112 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3113 * {@code toIndex > a.length}
3114 */
3115 public static void fill(float[] a, int fromIndex, int toIndex, float val) {
3116 rangeCheck(a.length, fromIndex, toIndex);
3117 for (int i = fromIndex; i < toIndex; i++)
3118 a[i] = val;
3119 }
3120
3121 /**
3122 * Assigns the specified Object reference to each element of the specified
3123 * array of Objects.
3124 *
3125 * @param a the array to be filled
3126 * @param val the value to be stored in all elements of the array
3127 * @throws ArrayStoreException if the specified value is not of a
3128 * runtime type that can be stored in the specified array
3129 */
3130 public static void fill(Object[] a, Object val) {
3131 for (int i = 0, len = a.length; i < len; i++)
3132 a[i] = val;
3133 }
3134
3135 /**
3136 * Assigns the specified Object reference to each element of the specified
3137 * range of the specified array of Objects. The range to be filled
3138 * extends from index {@code fromIndex}, inclusive, to index
3139 * {@code toIndex}, exclusive. (If {@code fromIndex==toIndex}, the
3140 * range to be filled is empty.)
3141 *
3142 * @param a the array to be filled
3143 * @param fromIndex the index of the first element (inclusive) to be
3144 * filled with the specified value
3145 * @param toIndex the index of the last element (exclusive) to be
3146 * filled with the specified value
3147 * @param val the value to be stored in all elements of the array
3148 * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3149 * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3150 * {@code toIndex > a.length}
3151 * @throws ArrayStoreException if the specified value is not of a
3152 * runtime type that can be stored in the specified array
3153 */
3154 public static void fill(Object[] a, int fromIndex, int toIndex, Object val) {
3155 rangeCheck(a.length, fromIndex, toIndex);
3156 for (int i = fromIndex; i < toIndex; i++)
3157 a[i] = val;
3158 }
3159
3160 // Cloning
3161
3162 /**
3163 * Copies the specified array, truncating or padding with nulls (if necessary)
3164 * so the copy has the specified length. For all indices that are
3165 * valid in both the original array and the copy, the two arrays will
3166 * contain identical values. For any indices that are valid in the
3167 * copy but not the original, the copy will contain {@code null}.
3168 * Such indices will exist if and only if the specified length
3169 * is greater than that of the original array.
3170 * The resulting array is of exactly the same class as the original array.
3171 *
3172 * @param <T> the class of the objects in the array
3173 * @param original the array to be copied
3174 * @param newLength the length of the copy to be returned
3175 * @return a copy of the original array, truncated or padded with nulls
3176 * to obtain the specified length
3177 * @throws NegativeArraySizeException if {@code newLength} is negative
3178 * @throws NullPointerException if {@code original} is null
3179 * @since 1.6
3180 */
3181 @SuppressWarnings("unchecked")
3182 public static <T> T[] copyOf(T[] original, int newLength) {
3183 return (T[]) copyOf(original, newLength, original.getClass());
3184 }
3185
3186 /**
3187 * Copies the specified array, truncating or padding with nulls (if necessary)
3188 * so the copy has the specified length. For all indices that are
3189 * valid in both the original array and the copy, the two arrays will
3190 * contain identical values. For any indices that are valid in the
3191 * copy but not the original, the copy will contain {@code null}.
3192 * Such indices will exist if and only if the specified length
3193 * is greater than that of the original array.
3194 * The resulting array is of the class {@code newType}.
3195 *
3196 * @param <U> the class of the objects in the original array
3197 * @param <T> the class of the objects in the returned array
3198 * @param original the array to be copied
3199 * @param newLength the length of the copy to be returned
3200 * @param newType the class of the copy to be returned
3201 * @return a copy of the original array, truncated or padded with nulls
3202 * to obtain the specified length
3203 * @throws NegativeArraySizeException if {@code newLength} is negative
3204 * @throws NullPointerException if {@code original} is null
3205 * @throws ArrayStoreException if an element copied from
3206 * {@code original} is not of a runtime type that can be stored in
3207 * an array of class {@code newType}
3208 * @since 1.6
3209 */
3210 @HotSpotIntrinsicCandidate
3211 public static <T,U> T[] copyOf(U[] original, int newLength, Class<? extends T[]> newType) {
3212 @SuppressWarnings("unchecked")
3213 T[] copy = ((Object)newType == (Object)Object[].class)
3214 ? (T[]) new Object[newLength]
3215 : (T[]) Array.newInstance(newType.getComponentType(), newLength);
3216 System.arraycopy(original, 0, copy, 0,
3217 Math.min(original.length, newLength));
3218 return copy;
3219 }
3220
3221 /**
3222 * Copies the specified array, truncating or padding with zeros (if necessary)
3223 * so the copy has the specified length. For all indices that are
3224 * valid in both the original array and the copy, the two arrays will
3225 * contain identical values. For any indices that are valid in the
3226 * copy but not the original, the copy will contain {@code (byte)0}.
3227 * Such indices will exist if and only if the specified length
3228 * is greater than that of the original array.
3229 *
3230 * @param original the array to be copied
3231 * @param newLength the length of the copy to be returned
3232 * @return a copy of the original array, truncated or padded with zeros
3233 * to obtain the specified length
3234 * @throws NegativeArraySizeException if {@code newLength} is negative
3235 * @throws NullPointerException if {@code original} is null
3236 * @since 1.6
3237 */
3238 public static byte[] copyOf(byte[] original, int newLength) {
3239 byte[] copy = new byte[newLength];
3240 System.arraycopy(original, 0, copy, 0,
3241 Math.min(original.length, newLength));
3242 return copy;
3243 }
3244
3245 /**
3246 * Copies the specified array, truncating or padding with zeros (if necessary)
3247 * so the copy has the specified length. For all indices that are
3248 * valid in both the original array and the copy, the two arrays will
3249 * contain identical values. For any indices that are valid in the
3250 * copy but not the original, the copy will contain {@code (short)0}.
3251 * Such indices will exist if and only if the specified length
3252 * is greater than that of the original array.
3253 *
3254 * @param original the array to be copied
3255 * @param newLength the length of the copy to be returned
3256 * @return a copy of the original array, truncated or padded with zeros
3257 * to obtain the specified length
3258 * @throws NegativeArraySizeException if {@code newLength} is negative
3259 * @throws NullPointerException if {@code original} is null
3260 * @since 1.6
3261 */
3262 public static short[] copyOf(short[] original, int newLength) {
3263 short[] copy = new short[newLength];
3264 System.arraycopy(original, 0, copy, 0,
3265 Math.min(original.length, newLength));
3266 return copy;
3267 }
3268
3269 /**
3270 * Copies the specified array, truncating or padding with zeros (if necessary)
3271 * so the copy has the specified length. For all indices that are
3272 * valid in both the original array and the copy, the two arrays will
3273 * contain identical values. For any indices that are valid in the
3274 * copy but not the original, the copy will contain {@code 0}.
3275 * Such indices will exist if and only if the specified length
3276 * is greater than that of the original array.
3277 *
3278 * @param original the array to be copied
3279 * @param newLength the length of the copy to be returned
3280 * @return a copy of the original array, truncated or padded with zeros
3281 * to obtain the specified length
3282 * @throws NegativeArraySizeException if {@code newLength} is negative
3283 * @throws NullPointerException if {@code original} is null
3284 * @since 1.6
3285 */
3286 public static int[] copyOf(int[] original, int newLength) {
3287 int[] copy = new int[newLength];
3288 System.arraycopy(original, 0, copy, 0,
3289 Math.min(original.length, newLength));
3290 return copy;
3291 }
3292
3293 /**
3294 * Copies the specified array, truncating or padding with zeros (if necessary)
3295 * so the copy has the specified length. For all indices that are
3296 * valid in both the original array and the copy, the two arrays will
3297 * contain identical values. For any indices that are valid in the
3298 * copy but not the original, the copy will contain {@code 0L}.
3299 * Such indices will exist if and only if the specified length
3300 * is greater than that of the original array.
3301 *
3302 * @param original the array to be copied
3303 * @param newLength the length of the copy to be returned
3304 * @return a copy of the original array, truncated or padded with zeros
3305 * to obtain the specified length
3306 * @throws NegativeArraySizeException if {@code newLength} is negative
3307 * @throws NullPointerException if {@code original} is null
3308 * @since 1.6
3309 */
3310 public static long[] copyOf(long[] original, int newLength) {
3311 long[] copy = new long[newLength];
3312 System.arraycopy(original, 0, copy, 0,
3313 Math.min(original.length, newLength));
3314 return copy;
3315 }
3316
3317 /**
3318 * Copies the specified array, truncating or padding with null characters (if necessary)
3319 * so the copy has the specified length. For all indices that are valid
3320 * in both the original array and the copy, the two arrays will contain
3321 * identical values. For any indices that are valid in the copy but not
3322 * the original, the copy will contain {@code '\\u000'}. Such indices
3323 * will exist if and only if the specified length is greater than that of
3324 * the original array.
3325 *
3326 * @param original the array to be copied
3327 * @param newLength the length of the copy to be returned
3328 * @return a copy of the original array, truncated or padded with null characters
3329 * to obtain the specified length
3330 * @throws NegativeArraySizeException if {@code newLength} is negative
3331 * @throws NullPointerException if {@code original} is null
3332 * @since 1.6
3333 */
3334 public static char[] copyOf(char[] original, int newLength) {
3335 char[] copy = new char[newLength];
3336 System.arraycopy(original, 0, copy, 0,
3337 Math.min(original.length, newLength));
3338 return copy;
3339 }
3340
3341 /**
3342 * Copies the specified array, truncating or padding with zeros (if necessary)
3343 * so the copy has the specified length. For all indices that are
3344 * valid in both the original array and the copy, the two arrays will
3345 * contain identical values. For any indices that are valid in the
3346 * copy but not the original, the copy will contain {@code 0f}.
3347 * Such indices will exist if and only if the specified length
3348 * is greater than that of the original array.
3349 *
3350 * @param original the array to be copied
3351 * @param newLength the length of the copy to be returned
3352 * @return a copy of the original array, truncated or padded with zeros
3353 * to obtain the specified length
3354 * @throws NegativeArraySizeException if {@code newLength} is negative
3355 * @throws NullPointerException if {@code original} is null
3356 * @since 1.6
3357 */
3358 public static float[] copyOf(float[] original, int newLength) {
3359 float[] copy = new float[newLength];
3360 System.arraycopy(original, 0, copy, 0,
3361 Math.min(original.length, newLength));
3362 return copy;
3363 }
3364
3365 /**
3366 * Copies the specified array, truncating or padding with zeros (if necessary)
3367 * so the copy has the specified length. For all indices that are
3368 * valid in both the original array and the copy, the two arrays will
3369 * contain identical values. For any indices that are valid in the
3370 * copy but not the original, the copy will contain {@code 0d}.
3371 * Such indices will exist if and only if the specified length
3372 * is greater than that of the original array.
3373 *
3374 * @param original the array to be copied
3375 * @param newLength the length of the copy to be returned
3376 * @return a copy of the original array, truncated or padded with zeros
3377 * to obtain the specified length
3378 * @throws NegativeArraySizeException if {@code newLength} is negative
3379 * @throws NullPointerException if {@code original} is null
3380 * @since 1.6
3381 */
3382 public static double[] copyOf(double[] original, int newLength) {
3383 double[] copy = new double[newLength];
3384 System.arraycopy(original, 0, copy, 0,
3385 Math.min(original.length, newLength));
3386 return copy;
3387 }
3388
3389 /**
3390 * Copies the specified array, truncating or padding with {@code false} (if necessary)
3391 * so the copy has the specified length. For all indices that are
3392 * valid in both the original array and the copy, the two arrays will
3393 * contain identical values. For any indices that are valid in the
3394 * copy but not the original, the copy will contain {@code false}.
3395 * Such indices will exist if and only if the specified length
3396 * is greater than that of the original array.
3397 *
3398 * @param original the array to be copied
3399 * @param newLength the length of the copy to be returned
3400 * @return a copy of the original array, truncated or padded with false elements
3401 * to obtain the specified length
3402 * @throws NegativeArraySizeException if {@code newLength} is negative
3403 * @throws NullPointerException if {@code original} is null
3404 * @since 1.6
3405 */
3406 public static boolean[] copyOf(boolean[] original, int newLength) {
3407 boolean[] copy = new boolean[newLength];
3408 System.arraycopy(original, 0, copy, 0,
3409 Math.min(original.length, newLength));
3410 return copy;
3411 }
3412
3413 /**
3414 * Copies the specified range of the specified array into a new array.
3415 * The initial index of the range ({@code from}) must lie between zero
3416 * and {@code original.length}, inclusive. The value at
3417 * {@code original[from]} is placed into the initial element of the copy
3418 * (unless {@code from == original.length} or {@code from == to}).
3419 * Values from subsequent elements in the original array are placed into
3420 * subsequent elements in the copy. The final index of the range
3421 * ({@code to}), which must be greater than or equal to {@code from},
3422 * may be greater than {@code original.length}, in which case
3423 * {@code null} is placed in all elements of the copy whose index is
3424 * greater than or equal to {@code original.length - from}. The length
3425 * of the returned array will be {@code to - from}.
3426 * <p>
3427 * The resulting array is of exactly the same class as the original array.
3428 *
3429 * @param <T> the class of the objects in the array
3430 * @param original the array from which a range is to be copied
3431 * @param from the initial index of the range to be copied, inclusive
3432 * @param to the final index of the range to be copied, exclusive.
3433 * (This index may lie outside the array.)
3434 * @return a new array containing the specified range from the original array,
3435 * truncated or padded with nulls to obtain the required length
3436 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3437 * or {@code from > original.length}
3438 * @throws IllegalArgumentException if {@code from > to}
3439 * @throws NullPointerException if {@code original} is null
3440 * @since 1.6
3441 */
3442 @SuppressWarnings("unchecked")
3443 public static <T> T[] copyOfRange(T[] original, int from, int to) {
3444 return copyOfRange(original, from, to, (Class<? extends T[]>) original.getClass());
3445 }
3446
3447 /**
3448 * Copies the specified range of the specified array into a new array.
3449 * The initial index of the range ({@code from}) must lie between zero
3450 * and {@code original.length}, inclusive. The value at
3451 * {@code original[from]} is placed into the initial element of the copy
3452 * (unless {@code from == original.length} or {@code from == to}).
3453 * Values from subsequent elements in the original array are placed into
3454 * subsequent elements in the copy. The final index of the range
3455 * ({@code to}), which must be greater than or equal to {@code from},
3456 * may be greater than {@code original.length}, in which case
3457 * {@code null} is placed in all elements of the copy whose index is
3458 * greater than or equal to {@code original.length - from}. The length
3459 * of the returned array will be {@code to - from}.
3460 * The resulting array is of the class {@code newType}.
3461 *
3462 * @param <U> the class of the objects in the original array
3463 * @param <T> the class of the objects in the returned array
3464 * @param original the array from which a range is to be copied
3465 * @param from the initial index of the range to be copied, inclusive
3466 * @param to the final index of the range to be copied, exclusive.
3467 * (This index may lie outside the array.)
3468 * @param newType the class of the copy to be returned
3469 * @return a new array containing the specified range from the original array,
3470 * truncated or padded with nulls to obtain the required length
3471 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3472 * or {@code from > original.length}
3473 * @throws IllegalArgumentException if {@code from > to}
3474 * @throws NullPointerException if {@code original} is null
3475 * @throws ArrayStoreException if an element copied from
3476 * {@code original} is not of a runtime type that can be stored in
3477 * an array of class {@code newType}.
3478 * @since 1.6
3479 */
3480 @HotSpotIntrinsicCandidate
3481 public static <T,U> T[] copyOfRange(U[] original, int from, int to, Class<? extends T[]> newType) {
3482 int newLength = to - from;
3483 if (newLength < 0)
3484 throw new IllegalArgumentException(from + " > " + to);
3485 @SuppressWarnings("unchecked")
3486 T[] copy = ((Object)newType == (Object)Object[].class)
3487 ? (T[]) new Object[newLength]
3488 : (T[]) Array.newInstance(newType.getComponentType(), newLength);
3489 System.arraycopy(original, from, copy, 0,
3490 Math.min(original.length - from, newLength));
3491 return copy;
3492 }
3493
3494 /**
3495 * Copies the specified range of the specified array into a new array.
3496 * The initial index of the range ({@code from}) must lie between zero
3497 * and {@code original.length}, inclusive. The value at
3498 * {@code original[from]} is placed into the initial element of the copy
3499 * (unless {@code from == original.length} or {@code from == to}).
3500 * Values from subsequent elements in the original array are placed into
3501 * subsequent elements in the copy. The final index of the range
3502 * ({@code to}), which must be greater than or equal to {@code from},
3503 * may be greater than {@code original.length}, in which case
3504 * {@code (byte)0} is placed in all elements of the copy whose index is
3505 * greater than or equal to {@code original.length - from}. The length
3506 * of the returned array will be {@code to - from}.
3507 *
3508 * @param original the array from which a range is to be copied
3509 * @param from the initial index of the range to be copied, inclusive
3510 * @param to the final index of the range to be copied, exclusive.
3511 * (This index may lie outside the array.)
3512 * @return a new array containing the specified range from the original array,
3513 * truncated or padded with zeros to obtain the required length
3514 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3515 * or {@code from > original.length}
3516 * @throws IllegalArgumentException if {@code from > to}
3517 * @throws NullPointerException if {@code original} is null
3518 * @since 1.6
3519 */
3520 public static byte[] copyOfRange(byte[] original, int from, int to) {
3521 int newLength = to - from;
3522 if (newLength < 0)
3523 throw new IllegalArgumentException(from + " > " + to);
3524 byte[] copy = new byte[newLength];
3525 System.arraycopy(original, from, copy, 0,
3526 Math.min(original.length - from, newLength));
3527 return copy;
3528 }
3529
3530 /**
3531 * Copies the specified range of the specified array into a new array.
3532 * The initial index of the range ({@code from}) must lie between zero
3533 * and {@code original.length}, inclusive. The value at
3534 * {@code original[from]} is placed into the initial element of the copy
3535 * (unless {@code from == original.length} or {@code from == to}).
3536 * Values from subsequent elements in the original array are placed into
3537 * subsequent elements in the copy. The final index of the range
3538 * ({@code to}), which must be greater than or equal to {@code from},
3539 * may be greater than {@code original.length}, in which case
3540 * {@code (short)0} is placed in all elements of the copy whose index is
3541 * greater than or equal to {@code original.length - from}. The length
3542 * of the returned array will be {@code to - from}.
3543 *
3544 * @param original the array from which a range is to be copied
3545 * @param from the initial index of the range to be copied, inclusive
3546 * @param to the final index of the range to be copied, exclusive.
3547 * (This index may lie outside the array.)
3548 * @return a new array containing the specified range from the original array,
3549 * truncated or padded with zeros to obtain the required length
3550 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3551 * or {@code from > original.length}
3552 * @throws IllegalArgumentException if {@code from > to}
3553 * @throws NullPointerException if {@code original} is null
3554 * @since 1.6
3555 */
3556 public static short[] copyOfRange(short[] original, int from, int to) {
3557 int newLength = to - from;
3558 if (newLength < 0)
3559 throw new IllegalArgumentException(from + " > " + to);
3560 short[] copy = new short[newLength];
3561 System.arraycopy(original, from, copy, 0,
3562 Math.min(original.length - from, newLength));
3563 return copy;
3564 }
3565
3566 /**
3567 * Copies the specified range of the specified array into a new array.
3568 * The initial index of the range ({@code from}) must lie between zero
3569 * and {@code original.length}, inclusive. The value at
3570 * {@code original[from]} is placed into the initial element of the copy
3571 * (unless {@code from == original.length} or {@code from == to}).
3572 * Values from subsequent elements in the original array are placed into
3573 * subsequent elements in the copy. The final index of the range
3574 * ({@code to}), which must be greater than or equal to {@code from},
3575 * may be greater than {@code original.length}, in which case
3576 * {@code 0} is placed in all elements of the copy whose index is
3577 * greater than or equal to {@code original.length - from}. The length
3578 * of the returned array will be {@code to - from}.
3579 *
3580 * @param original the array from which a range is to be copied
3581 * @param from the initial index of the range to be copied, inclusive
3582 * @param to the final index of the range to be copied, exclusive.
3583 * (This index may lie outside the array.)
3584 * @return a new array containing the specified range from the original array,
3585 * truncated or padded with zeros to obtain the required length
3586 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3587 * or {@code from > original.length}
3588 * @throws IllegalArgumentException if {@code from > to}
3589 * @throws NullPointerException if {@code original} is null
3590 * @since 1.6
3591 */
3592 public static int[] copyOfRange(int[] original, int from, int to) {
3593 int newLength = to - from;
3594 if (newLength < 0)
3595 throw new IllegalArgumentException(from + " > " + to);
3596 int[] copy = new int[newLength];
3597 System.arraycopy(original, from, copy, 0,
3598 Math.min(original.length - from, newLength));
3599 return copy;
3600 }
3601
3602 /**
3603 * Copies the specified range of the specified array into a new array.
3604 * The initial index of the range ({@code from}) must lie between zero
3605 * and {@code original.length}, inclusive. The value at
3606 * {@code original[from]} is placed into the initial element of the copy
3607 * (unless {@code from == original.length} or {@code from == to}).
3608 * Values from subsequent elements in the original array are placed into
3609 * subsequent elements in the copy. The final index of the range
3610 * ({@code to}), which must be greater than or equal to {@code from},
3611 * may be greater than {@code original.length}, in which case
3612 * {@code 0L} is placed in all elements of the copy whose index is
3613 * greater than or equal to {@code original.length - from}. The length
3614 * of the returned array will be {@code to - from}.
3615 *
3616 * @param original the array from which a range is to be copied
3617 * @param from the initial index of the range to be copied, inclusive
3618 * @param to the final index of the range to be copied, exclusive.
3619 * (This index may lie outside the array.)
3620 * @return a new array containing the specified range from the original array,
3621 * truncated or padded with zeros to obtain the required length
3622 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3623 * or {@code from > original.length}
3624 * @throws IllegalArgumentException if {@code from > to}
3625 * @throws NullPointerException if {@code original} is null
3626 * @since 1.6
3627 */
3628 public static long[] copyOfRange(long[] original, int from, int to) {
3629 int newLength = to - from;
3630 if (newLength < 0)
3631 throw new IllegalArgumentException(from + " > " + to);
3632 long[] copy = new long[newLength];
3633 System.arraycopy(original, from, copy, 0,
3634 Math.min(original.length - from, newLength));
3635 return copy;
3636 }
3637
3638 /**
3639 * Copies the specified range of the specified array into a new array.
3640 * The initial index of the range ({@code from}) must lie between zero
3641 * and {@code original.length}, inclusive. The value at
3642 * {@code original[from]} is placed into the initial element of the copy
3643 * (unless {@code from == original.length} or {@code from == to}).
3644 * Values from subsequent elements in the original array are placed into
3645 * subsequent elements in the copy. The final index of the range
3646 * ({@code to}), which must be greater than or equal to {@code from},
3647 * may be greater than {@code original.length}, in which case
3648 * {@code '\\u000'} is placed in all elements of the copy whose index is
3649 * greater than or equal to {@code original.length - from}. The length
3650 * of the returned array will be {@code to - from}.
3651 *
3652 * @param original the array from which a range is to be copied
3653 * @param from the initial index of the range to be copied, inclusive
3654 * @param to the final index of the range to be copied, exclusive.
3655 * (This index may lie outside the array.)
3656 * @return a new array containing the specified range from the original array,
3657 * truncated or padded with null characters to obtain the required length
3658 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3659 * or {@code from > original.length}
3660 * @throws IllegalArgumentException if {@code from > to}
3661 * @throws NullPointerException if {@code original} is null
3662 * @since 1.6
3663 */
3664 public static char[] copyOfRange(char[] original, int from, int to) {
3665 int newLength = to - from;
3666 if (newLength < 0)
3667 throw new IllegalArgumentException(from + " > " + to);
3668 char[] copy = new char[newLength];
3669 System.arraycopy(original, from, copy, 0,
3670 Math.min(original.length - from, newLength));
3671 return copy;
3672 }
3673
3674 /**
3675 * Copies the specified range of the specified array into a new array.
3676 * The initial index of the range ({@code from}) must lie between zero
3677 * and {@code original.length}, inclusive. The value at
3678 * {@code original[from]} is placed into the initial element of the copy
3679 * (unless {@code from == original.length} or {@code from == to}).
3680 * Values from subsequent elements in the original array are placed into
3681 * subsequent elements in the copy. The final index of the range
3682 * ({@code to}), which must be greater than or equal to {@code from},
3683 * may be greater than {@code original.length}, in which case
3684 * {@code 0f} is placed in all elements of the copy whose index is
3685 * greater than or equal to {@code original.length - from}. The length
3686 * of the returned array will be {@code to - from}.
3687 *
3688 * @param original the array from which a range is to be copied
3689 * @param from the initial index of the range to be copied, inclusive
3690 * @param to the final index of the range to be copied, exclusive.
3691 * (This index may lie outside the array.)
3692 * @return a new array containing the specified range from the original array,
3693 * truncated or padded with zeros to obtain the required length
3694 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3695 * or {@code from > original.length}
3696 * @throws IllegalArgumentException if {@code from > to}
3697 * @throws NullPointerException if {@code original} is null
3698 * @since 1.6
3699 */
3700 public static float[] copyOfRange(float[] original, int from, int to) {
3701 int newLength = to - from;
3702 if (newLength < 0)
3703 throw new IllegalArgumentException(from + " > " + to);
3704 float[] copy = new float[newLength];
3705 System.arraycopy(original, from, copy, 0,
3706 Math.min(original.length - from, newLength));
3707 return copy;
3708 }
3709
3710 /**
3711 * Copies the specified range of the specified array into a new array.
3712 * The initial index of the range ({@code from}) must lie between zero
3713 * and {@code original.length}, inclusive. The value at
3714 * {@code original[from]} is placed into the initial element of the copy
3715 * (unless {@code from == original.length} or {@code from == to}).
3716 * Values from subsequent elements in the original array are placed into
3717 * subsequent elements in the copy. The final index of the range
3718 * ({@code to}), which must be greater than or equal to {@code from},
3719 * may be greater than {@code original.length}, in which case
3720 * {@code 0d} is placed in all elements of the copy whose index is
3721 * greater than or equal to {@code original.length - from}. The length
3722 * of the returned array will be {@code to - from}.
3723 *
3724 * @param original the array from which a range is to be copied
3725 * @param from the initial index of the range to be copied, inclusive
3726 * @param to the final index of the range to be copied, exclusive.
3727 * (This index may lie outside the array.)
3728 * @return a new array containing the specified range from the original array,
3729 * truncated or padded with zeros to obtain the required length
3730 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3731 * or {@code from > original.length}
3732 * @throws IllegalArgumentException if {@code from > to}
3733 * @throws NullPointerException if {@code original} is null
3734 * @since 1.6
3735 */
3736 public static double[] copyOfRange(double[] original, int from, int to) {
3737 int newLength = to - from;
3738 if (newLength < 0)
3739 throw new IllegalArgumentException(from + " > " + to);
3740 double[] copy = new double[newLength];
3741 System.arraycopy(original, from, copy, 0,
3742 Math.min(original.length - from, newLength));
3743 return copy;
3744 }
3745
3746 /**
3747 * Copies the specified range of the specified array into a new array.
3748 * The initial index of the range ({@code from}) must lie between zero
3749 * and {@code original.length}, inclusive. The value at
3750 * {@code original[from]} is placed into the initial element of the copy
3751 * (unless {@code from == original.length} or {@code from == to}).
3752 * Values from subsequent elements in the original array are placed into
3753 * subsequent elements in the copy. The final index of the range
3754 * ({@code to}), which must be greater than or equal to {@code from},
3755 * may be greater than {@code original.length}, in which case
3756 * {@code false} is placed in all elements of the copy whose index is
3757 * greater than or equal to {@code original.length - from}. The length
3758 * of the returned array will be {@code to - from}.
3759 *
3760 * @param original the array from which a range is to be copied
3761 * @param from the initial index of the range to be copied, inclusive
3762 * @param to the final index of the range to be copied, exclusive.
3763 * (This index may lie outside the array.)
3764 * @return a new array containing the specified range from the original array,
3765 * truncated or padded with false elements to obtain the required length
3766 * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3767 * or {@code from > original.length}
3768 * @throws IllegalArgumentException if {@code from > to}
3769 * @throws NullPointerException if {@code original} is null
3770 * @since 1.6
3771 */
3772 public static boolean[] copyOfRange(boolean[] original, int from, int to) {
3773 int newLength = to - from;
3774 if (newLength < 0)
3775 throw new IllegalArgumentException(from + " > " + to);
3776 boolean[] copy = new boolean[newLength];
3777 System.arraycopy(original, from, copy, 0,
3778 Math.min(original.length - from, newLength));
3779 return copy;
3780 }
3781
3782 // Misc
3783
3784 /**
3785 * Returns a fixed-size list backed by the specified array. (Changes to
3786 * the returned list "write through" to the array.) This method acts
3787 * as bridge between array-based and collection-based APIs, in
3788 * combination with {@link Collection#toArray}. The returned list is
3789 * serializable and implements {@link RandomAccess}.
3885 }
3886 }
3887
3888 @Override
3889 public void replaceAll(UnaryOperator<E> operator) {
3890 Objects.requireNonNull(operator);
3891 E[] a = this.a;
3892 for (int i = 0; i < a.length; i++) {
3893 a[i] = operator.apply(a[i]);
3894 }
3895 }
3896
3897 @Override
3898 public void sort(Comparator<? super E> c) {
3899 Arrays.sort(a, c);
3900 }
3901 }
3902
3903 /**
3904 * Returns a hash code based on the contents of the specified array.
3905 * For any two {@code long} arrays {@code a} and {@code b}
3906 * such that {@code Arrays.equals(a, b)}, it is also the case that
3907 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
3908 *
3909 * <p>The value returned by this method is the same value that would be
3910 * obtained by invoking the {@link List#hashCode() hashCode}
3911 * method on a {@link List} containing a sequence of {@link Long}
3912 * instances representing the elements of {@code a} in the same order.
3913 * If {@code a} is {@code null}, this method returns 0.
3914 *
3915 * @param a the array whose hash value to compute
3916 * @return a content-based hash code for {@code a}
3917 * @since 1.5
3918 */
3919 public static int hashCode(long a[]) {
3920 if (a == null)
3921 return 0;
3922
3923 int result = 1;
3924 for (long element : a) {
3925 int elementHash = (int)(element ^ (element >>> 32));
3926 result = 31 * result + elementHash;
3927 }
3928
3929 return result;
3930 }
3931
3932 /**
3933 * Returns a hash code based on the contents of the specified array.
3934 * For any two non-null {@code int} arrays {@code a} and {@code b}
3935 * such that {@code Arrays.equals(a, b)}, it is also the case that
3936 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
3937 *
3938 * <p>The value returned by this method is the same value that would be
3939 * obtained by invoking the {@link List#hashCode() hashCode}
3940 * method on a {@link List} containing a sequence of {@link Integer}
3941 * instances representing the elements of {@code a} in the same order.
3942 * If {@code a} is {@code null}, this method returns 0.
3943 *
3944 * @param a the array whose hash value to compute
3945 * @return a content-based hash code for {@code a}
3946 * @since 1.5
3947 */
3948 public static int hashCode(int a[]) {
3949 if (a == null)
3950 return 0;
3951
3952 int result = 1;
3953 for (int element : a)
3954 result = 31 * result + element;
3955
3956 return result;
3957 }
3958
3959 /**
3960 * Returns a hash code based on the contents of the specified array.
3961 * For any two {@code short} arrays {@code a} and {@code b}
3962 * such that {@code Arrays.equals(a, b)}, it is also the case that
3963 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
3964 *
3965 * <p>The value returned by this method is the same value that would be
3966 * obtained by invoking the {@link List#hashCode() hashCode}
3967 * method on a {@link List} containing a sequence of {@link Short}
3968 * instances representing the elements of {@code a} in the same order.
3969 * If {@code a} is {@code null}, this method returns 0.
3970 *
3971 * @param a the array whose hash value to compute
3972 * @return a content-based hash code for {@code a}
3973 * @since 1.5
3974 */
3975 public static int hashCode(short a[]) {
3976 if (a == null)
3977 return 0;
3978
3979 int result = 1;
3980 for (short element : a)
3981 result = 31 * result + element;
3982
3983 return result;
3984 }
3985
3986 /**
3987 * Returns a hash code based on the contents of the specified array.
3988 * For any two {@code char} arrays {@code a} and {@code b}
3989 * such that {@code Arrays.equals(a, b)}, it is also the case that
3990 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
3991 *
3992 * <p>The value returned by this method is the same value that would be
3993 * obtained by invoking the {@link List#hashCode() hashCode}
3994 * method on a {@link List} containing a sequence of {@link Character}
3995 * instances representing the elements of {@code a} in the same order.
3996 * If {@code a} is {@code null}, this method returns 0.
3997 *
3998 * @param a the array whose hash value to compute
3999 * @return a content-based hash code for {@code a}
4000 * @since 1.5
4001 */
4002 public static int hashCode(char a[]) {
4003 if (a == null)
4004 return 0;
4005
4006 int result = 1;
4007 for (char element : a)
4008 result = 31 * result + element;
4009
4010 return result;
4011 }
4012
4013 /**
4014 * Returns a hash code based on the contents of the specified array.
4015 * For any two {@code byte} arrays {@code a} and {@code b}
4016 * such that {@code Arrays.equals(a, b)}, it is also the case that
4017 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4018 *
4019 * <p>The value returned by this method is the same value that would be
4020 * obtained by invoking the {@link List#hashCode() hashCode}
4021 * method on a {@link List} containing a sequence of {@link Byte}
4022 * instances representing the elements of {@code a} in the same order.
4023 * If {@code a} is {@code null}, this method returns 0.
4024 *
4025 * @param a the array whose hash value to compute
4026 * @return a content-based hash code for {@code a}
4027 * @since 1.5
4028 */
4029 public static int hashCode(byte a[]) {
4030 if (a == null)
4031 return 0;
4032
4033 int result = 1;
4034 for (byte element : a)
4035 result = 31 * result + element;
4036
4037 return result;
4038 }
4039
4040 /**
4041 * Returns a hash code based on the contents of the specified array.
4042 * For any two {@code boolean} arrays {@code a} and {@code b}
4043 * such that {@code Arrays.equals(a, b)}, it is also the case that
4044 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4045 *
4046 * <p>The value returned by this method is the same value that would be
4047 * obtained by invoking the {@link List#hashCode() hashCode}
4048 * method on a {@link List} containing a sequence of {@link Boolean}
4049 * instances representing the elements of {@code a} in the same order.
4050 * If {@code a} is {@code null}, this method returns 0.
4051 *
4052 * @param a the array whose hash value to compute
4053 * @return a content-based hash code for {@code a}
4054 * @since 1.5
4055 */
4056 public static int hashCode(boolean a[]) {
4057 if (a == null)
4058 return 0;
4059
4060 int result = 1;
4061 for (boolean element : a)
4062 result = 31 * result + (element ? 1231 : 1237);
4063
4064 return result;
4065 }
4066
4067 /**
4068 * Returns a hash code based on the contents of the specified array.
4069 * For any two {@code float} arrays {@code a} and {@code b}
4070 * such that {@code Arrays.equals(a, b)}, it is also the case that
4071 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4072 *
4073 * <p>The value returned by this method is the same value that would be
4074 * obtained by invoking the {@link List#hashCode() hashCode}
4075 * method on a {@link List} containing a sequence of {@link Float}
4076 * instances representing the elements of {@code a} in the same order.
4077 * If {@code a} is {@code null}, this method returns 0.
4078 *
4079 * @param a the array whose hash value to compute
4080 * @return a content-based hash code for {@code a}
4081 * @since 1.5
4082 */
4083 public static int hashCode(float a[]) {
4084 if (a == null)
4085 return 0;
4086
4087 int result = 1;
4088 for (float element : a)
4089 result = 31 * result + Float.floatToIntBits(element);
4090
4091 return result;
4092 }
4093
4094 /**
4095 * Returns a hash code based on the contents of the specified array.
4096 * For any two {@code double} arrays {@code a} and {@code b}
4097 * such that {@code Arrays.equals(a, b)}, it is also the case that
4098 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4099 *
4100 * <p>The value returned by this method is the same value that would be
4101 * obtained by invoking the {@link List#hashCode() hashCode}
4102 * method on a {@link List} containing a sequence of {@link Double}
4103 * instances representing the elements of {@code a} in the same order.
4104 * If {@code a} is {@code null}, this method returns 0.
4105 *
4106 * @param a the array whose hash value to compute
4107 * @return a content-based hash code for {@code a}
4108 * @since 1.5
4109 */
4110 public static int hashCode(double a[]) {
4111 if (a == null)
4112 return 0;
4113
4114 int result = 1;
4115 for (double element : a) {
4116 long bits = Double.doubleToLongBits(element);
4117 result = 31 * result + (int)(bits ^ (bits >>> 32));
4118 }
4119 return result;
4120 }
4121
4122 /**
4123 * Returns a hash code based on the contents of the specified array. If
4124 * the array contains other arrays as elements, the hash code is based on
4125 * their identities rather than their contents. It is therefore
4126 * acceptable to invoke this method on an array that contains itself as an
4127 * element, either directly or indirectly through one or more levels of
4128 * arrays.
4129 *
4130 * <p>For any two arrays {@code a} and {@code b} such that
4131 * {@code Arrays.equals(a, b)}, it is also the case that
4132 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4133 *
4134 * <p>The value returned by this method is equal to the value that would
4135 * be returned by {@code Arrays.asList(a).hashCode()}, unless {@code a}
4136 * is {@code null}, in which case {@code 0} is returned.
4137 *
4138 * @param a the array whose content-based hash code to compute
4139 * @return a content-based hash code for {@code a}
4140 * @see #deepHashCode(Object[])
4141 * @since 1.5
4142 */
4143 public static int hashCode(Object a[]) {
4144 if (a == null)
4145 return 0;
4146
4147 int result = 1;
4148
4149 for (Object element : a)
4150 result = 31 * result + (element == null ? 0 : element.hashCode());
4151
4152 return result;
4153 }
4154
4155 /**
4156 * Returns a hash code based on the "deep contents" of the specified
4157 * array. If the array contains other arrays as elements, the
4158 * hash code is based on their contents and so on, ad infinitum.
4159 * It is therefore unacceptable to invoke this method on an array that
4160 * contains itself as an element, either directly or indirectly through
4161 * one or more levels of arrays. The behavior of such an invocation is
4162 * undefined.
4163 *
4164 * <p>For any two arrays {@code a} and {@code b} such that
4165 * {@code Arrays.deepEquals(a, b)}, it is also the case that
4166 * {@code Arrays.deepHashCode(a) == Arrays.deepHashCode(b)}.
4167 *
4168 * <p>The computation of the value returned by this method is similar to
4169 * that of the value returned by {@link List#hashCode()} on a list
4170 * containing the same elements as {@code a} in the same order, with one
4171 * difference: If an element {@code e} of {@code a} is itself an array,
4172 * its hash code is computed not by calling {@code e.hashCode()}, but as
4173 * by calling the appropriate overloading of {@code Arrays.hashCode(e)}
4174 * if {@code e} is an array of a primitive type, or as by calling
4175 * {@code Arrays.deepHashCode(e)} recursively if {@code e} is an array
4176 * of a reference type. If {@code a} is {@code null}, this method
4177 * returns 0.
4178 *
4179 * @param a the array whose deep-content-based hash code to compute
4180 * @return a deep-content-based hash code for {@code a}
4181 * @see #hashCode(Object[])
4182 * @since 1.5
4183 */
4184 public static int deepHashCode(Object a[]) {
4185 if (a == null)
4186 return 0;
4187
4188 int result = 1;
4189
4190 for (Object element : a) {
4191 int elementHash = 0;
4192 if (element instanceof Object[])
4193 elementHash = deepHashCode((Object[]) element);
4194 else if (element instanceof byte[])
4195 elementHash = hashCode((byte[]) element);
4196 else if (element instanceof short[])
4197 elementHash = hashCode((short[]) element);
4198 else if (element instanceof int[])
4199 elementHash = hashCode((int[]) element);
4200 else if (element instanceof long[])
4201 elementHash = hashCode((long[]) element);
4202 else if (element instanceof char[])
4203 elementHash = hashCode((char[]) element);
4204 else if (element instanceof float[])
4205 elementHash = hashCode((float[]) element);
4206 else if (element instanceof double[])
4207 elementHash = hashCode((double[]) element);
4208 else if (element instanceof boolean[])
4209 elementHash = hashCode((boolean[]) element);
4210 else if (element != null)
4211 elementHash = element.hashCode();
4212
4213 result = 31 * result + elementHash;
4214 }
4215
4216 return result;
4217 }
4218
4219 /**
4220 * Returns {@code true} if the two specified arrays are <i>deeply
4221 * equal</i> to one another. Unlike the {@link #equals(Object[],Object[])}
4222 * method, this method is appropriate for use with nested arrays of
4223 * arbitrary depth.
4224 *
4225 * <p>Two array references are considered deeply equal if both
4226 * are {@code null}, or if they refer to arrays that contain the same
4227 * number of elements and all corresponding pairs of elements in the two
4228 * arrays are deeply equal.
4229 *
4230 * <p>Two possibly {@code null} elements {@code e1} and {@code e2} are
4231 * deeply equal if any of the following conditions hold:
4232 * <ul>
4233 * <li> {@code e1} and {@code e2} are both arrays of object reference
4234 * types, and {@code Arrays.deepEquals(e1, e2) would return true}
4235 * <li> {@code e1} and {@code e2} are arrays of the same primitive
4236 * type, and the appropriate overloading of
4237 * {@code Arrays.equals(e1, e2)} would return true.
4238 * <li> {@code e1 == e2}
4239 * <li> {@code e1.equals(e2)} would return true.
4240 * </ul>
4241 * Note that this definition permits {@code null} elements at any depth.
4242 *
4243 * <p>If either of the specified arrays contain themselves as elements
4244 * either directly or indirectly through one or more levels of arrays,
4245 * the behavior of this method is undefined.
4246 *
4247 * @param a1 one array to be tested for equality
4248 * @param a2 the other array to be tested for equality
4249 * @return {@code true} if the two arrays are equal
4250 * @see #equals(Object[],Object[])
4251 * @see Objects#deepEquals(Object, Object)
4252 * @since 1.5
4253 */
4254 public static boolean deepEquals(Object[] a1, Object[] a2) {
4255 if (a1 == a2)
4256 return true;
4257 if (a1 == null || a2==null)
4258 return false;
4259 int length = a1.length;
4260 if (a2.length != length)
4261 return false;
4262
4263 for (int i = 0; i < length; i++) {
4264 Object e1 = a1[i];
4265 Object e2 = a2[i];
4266
4267 if (e1 == e2)
4268 continue;
4269 if (e1 == null)
4290 else if (e1 instanceof int[] && e2 instanceof int[])
4291 eq = equals((int[]) e1, (int[]) e2);
4292 else if (e1 instanceof long[] && e2 instanceof long[])
4293 eq = equals((long[]) e1, (long[]) e2);
4294 else if (e1 instanceof char[] && e2 instanceof char[])
4295 eq = equals((char[]) e1, (char[]) e2);
4296 else if (e1 instanceof float[] && e2 instanceof float[])
4297 eq = equals((float[]) e1, (float[]) e2);
4298 else if (e1 instanceof double[] && e2 instanceof double[])
4299 eq = equals((double[]) e1, (double[]) e2);
4300 else if (e1 instanceof boolean[] && e2 instanceof boolean[])
4301 eq = equals((boolean[]) e1, (boolean[]) e2);
4302 else
4303 eq = e1.equals(e2);
4304 return eq;
4305 }
4306
4307 /**
4308 * Returns a string representation of the contents of the specified array.
4309 * The string representation consists of a list of the array's elements,
4310 * enclosed in square brackets ({@code "[]"}). Adjacent elements are
4311 * separated by the characters {@code ", "} (a comma followed by a
4312 * space). Elements are converted to strings as by
4313 * {@code String.valueOf(long)}. Returns {@code "null"} if {@code a}
4314 * is {@code null}.
4315 *
4316 * @param a the array whose string representation to return
4317 * @return a string representation of {@code a}
4318 * @since 1.5
4319 */
4320 public static String toString(long[] a) {
4321 if (a == null)
4322 return "null";
4323 int iMax = a.length - 1;
4324 if (iMax == -1)
4325 return "[]";
4326
4327 StringBuilder b = new StringBuilder();
4328 b.append('[');
4329 for (int i = 0; ; i++) {
4330 b.append(a[i]);
4331 if (i == iMax)
4332 return b.append(']').toString();
4333 b.append(", ");
4334 }
4335 }
4336
4337 /**
4338 * Returns a string representation of the contents of the specified array.
4339 * The string representation consists of a list of the array's elements,
4340 * enclosed in square brackets ({@code "[]"}). Adjacent elements are
4341 * separated by the characters {@code ", "} (a comma followed by a
4342 * space). Elements are converted to strings as by
4343 * {@code String.valueOf(int)}. Returns {@code "null"} if {@code a} is
4344 * {@code null}.
4345 *
4346 * @param a the array whose string representation to return
4347 * @return a string representation of {@code a}
4348 * @since 1.5
4349 */
4350 public static String toString(int[] a) {
4351 if (a == null)
4352 return "null";
4353 int iMax = a.length - 1;
4354 if (iMax == -1)
4355 return "[]";
4356
4357 StringBuilder b = new StringBuilder();
4358 b.append('[');
4359 for (int i = 0; ; i++) {
4360 b.append(a[i]);
4361 if (i == iMax)
4362 return b.append(']').toString();
4363 b.append(", ");
4364 }
4365 }
4366
4367 /**
4368 * Returns a string representation of the contents of the specified array.
4369 * The string representation consists of a list of the array's elements,
4370 * enclosed in square brackets ({@code "[]"}). Adjacent elements are
4371 * separated by the characters {@code ", "} (a comma followed by a
4372 * space). Elements are converted to strings as by
4373 * {@code String.valueOf(short)}. Returns {@code "null"} if {@code a}
4374 * is {@code null}.
4375 *
4376 * @param a the array whose string representation to return
4377 * @return a string representation of {@code a}
4378 * @since 1.5
4379 */
4380 public static String toString(short[] a) {
4381 if (a == null)
4382 return "null";
4383 int iMax = a.length - 1;
4384 if (iMax == -1)
4385 return "[]";
4386
4387 StringBuilder b = new StringBuilder();
4388 b.append('[');
4389 for (int i = 0; ; i++) {
4390 b.append(a[i]);
4391 if (i == iMax)
4392 return b.append(']').toString();
4393 b.append(", ");
4394 }
4395 }
4396
4397 /**
4398 * Returns a string representation of the contents of the specified array.
4399 * The string representation consists of a list of the array's elements,
4400 * enclosed in square brackets ({@code "[]"}). Adjacent elements are
4401 * separated by the characters {@code ", "} (a comma followed by a
4402 * space). Elements are converted to strings as by
4403 * {@code String.valueOf(char)}. Returns {@code "null"} if {@code a}
4404 * is {@code null}.
4405 *
4406 * @param a the array whose string representation to return
4407 * @return a string representation of {@code a}
4408 * @since 1.5
4409 */
4410 public static String toString(char[] a) {
4411 if (a == null)
4412 return "null";
4413 int iMax = a.length - 1;
4414 if (iMax == -1)
4415 return "[]";
4416
4417 StringBuilder b = new StringBuilder();
4418 b.append('[');
4419 for (int i = 0; ; i++) {
4420 b.append(a[i]);
4421 if (i == iMax)
4422 return b.append(']').toString();
4423 b.append(", ");
4424 }
4425 }
4426
4427 /**
4428 * Returns a string representation of the contents of the specified array.
4429 * The string representation consists of a list of the array's elements,
4430 * enclosed in square brackets ({@code "[]"}). Adjacent elements
4431 * are separated by the characters {@code ", "} (a comma followed
4432 * by a space). Elements are converted to strings as by
4433 * {@code String.valueOf(byte)}. Returns {@code "null"} if
4434 * {@code a} is {@code null}.
4435 *
4436 * @param a the array whose string representation to return
4437 * @return a string representation of {@code a}
4438 * @since 1.5
4439 */
4440 public static String toString(byte[] a) {
4441 if (a == null)
4442 return "null";
4443 int iMax = a.length - 1;
4444 if (iMax == -1)
4445 return "[]";
4446
4447 StringBuilder b = new StringBuilder();
4448 b.append('[');
4449 for (int i = 0; ; i++) {
4450 b.append(a[i]);
4451 if (i == iMax)
4452 return b.append(']').toString();
4453 b.append(", ");
4454 }
4455 }
4456
4457 /**
4458 * Returns a string representation of the contents of the specified array.
4459 * The string representation consists of a list of the array's elements,
4460 * enclosed in square brackets ({@code "[]"}). Adjacent elements are
4461 * separated by the characters {@code ", "} (a comma followed by a
4462 * space). Elements are converted to strings as by
4463 * {@code String.valueOf(boolean)}. Returns {@code "null"} if
4464 * {@code a} is {@code null}.
4465 *
4466 * @param a the array whose string representation to return
4467 * @return a string representation of {@code a}
4468 * @since 1.5
4469 */
4470 public static String toString(boolean[] a) {
4471 if (a == null)
4472 return "null";
4473 int iMax = a.length - 1;
4474 if (iMax == -1)
4475 return "[]";
4476
4477 StringBuilder b = new StringBuilder();
4478 b.append('[');
4479 for (int i = 0; ; i++) {
4480 b.append(a[i]);
4481 if (i == iMax)
4482 return b.append(']').toString();
4483 b.append(", ");
4484 }
4485 }
4486
4487 /**
4488 * Returns a string representation of the contents of the specified array.
4489 * The string representation consists of a list of the array's elements,
4490 * enclosed in square brackets ({@code "[]"}). Adjacent elements are
4491 * separated by the characters {@code ", "} (a comma followed by a
4492 * space). Elements are converted to strings as by
4493 * {@code String.valueOf(float)}. Returns {@code "null"} if {@code a}
4494 * is {@code null}.
4495 *
4496 * @param a the array whose string representation to return
4497 * @return a string representation of {@code a}
4498 * @since 1.5
4499 */
4500 public static String toString(float[] a) {
4501 if (a == null)
4502 return "null";
4503
4504 int iMax = a.length - 1;
4505 if (iMax == -1)
4506 return "[]";
4507
4508 StringBuilder b = new StringBuilder();
4509 b.append('[');
4510 for (int i = 0; ; i++) {
4511 b.append(a[i]);
4512 if (i == iMax)
4513 return b.append(']').toString();
4514 b.append(", ");
4515 }
4516 }
4517
4518 /**
4519 * Returns a string representation of the contents of the specified array.
4520 * The string representation consists of a list of the array's elements,
4521 * enclosed in square brackets ({@code "[]"}). Adjacent elements are
4522 * separated by the characters {@code ", "} (a comma followed by a
4523 * space). Elements are converted to strings as by
4524 * {@code String.valueOf(double)}. Returns {@code "null"} if {@code a}
4525 * is {@code null}.
4526 *
4527 * @param a the array whose string representation to return
4528 * @return a string representation of {@code a}
4529 * @since 1.5
4530 */
4531 public static String toString(double[] a) {
4532 if (a == null)
4533 return "null";
4534 int iMax = a.length - 1;
4535 if (iMax == -1)
4536 return "[]";
4537
4538 StringBuilder b = new StringBuilder();
4539 b.append('[');
4540 for (int i = 0; ; i++) {
4541 b.append(a[i]);
4542 if (i == iMax)
4543 return b.append(']').toString();
4544 b.append(", ");
4545 }
4546 }
4547
4548 /**
4549 * Returns a string representation of the contents of the specified array.
4550 * If the array contains other arrays as elements, they are converted to
4551 * strings by the {@link Object#toString} method inherited from
4552 * {@code Object}, which describes their <i>identities</i> rather than
4553 * their contents.
4554 *
4555 * <p>The value returned by this method is equal to the value that would
4556 * be returned by {@code Arrays.asList(a).toString()}, unless {@code a}
4557 * is {@code null}, in which case {@code "null"} is returned.
4558 *
4559 * @param a the array whose string representation to return
4560 * @return a string representation of {@code a}
4561 * @see #deepToString(Object[])
4562 * @since 1.5
4563 */
4564 public static String toString(Object[] a) {
4565 if (a == null)
4566 return "null";
4567
4568 int iMax = a.length - 1;
4569 if (iMax == -1)
4570 return "[]";
4571
4572 StringBuilder b = new StringBuilder();
4573 b.append('[');
4574 for (int i = 0; ; i++) {
4575 b.append(String.valueOf(a[i]));
4576 if (i == iMax)
4577 return b.append(']').toString();
4578 b.append(", ");
4579 }
4580 }
4581
4582 /**
4583 * Returns a string representation of the "deep contents" of the specified
4584 * array. If the array contains other arrays as elements, the string
4585 * representation contains their contents and so on. This method is
4586 * designed for converting multidimensional arrays to strings.
4587 *
4588 * <p>The string representation consists of a list of the array's
4589 * elements, enclosed in square brackets ({@code "[]"}). Adjacent
4590 * elements are separated by the characters {@code ", "} (a comma
4591 * followed by a space). Elements are converted to strings as by
4592 * {@code String.valueOf(Object)}, unless they are themselves
4593 * arrays.
4594 *
4595 * <p>If an element {@code e} is an array of a primitive type, it is
4596 * converted to a string as by invoking the appropriate overloading of
4597 * {@code Arrays.toString(e)}. If an element {@code e} is an array of a
4598 * reference type, it is converted to a string as by invoking
4599 * this method recursively.
4600 *
4601 * <p>To avoid infinite recursion, if the specified array contains itself
4602 * as an element, or contains an indirect reference to itself through one
4603 * or more levels of arrays, the self-reference is converted to the string
4604 * {@code "[...]"}. For example, an array containing only a reference
4605 * to itself would be rendered as {@code "[[...]]"}.
4606 *
4607 * <p>This method returns {@code "null"} if the specified array
4608 * is {@code null}.
4609 *
4610 * @param a the array whose string representation to return
4611 * @return a string representation of {@code a}
4612 * @see #toString(Object[])
4613 * @since 1.5
4614 */
4615 public static String deepToString(Object[] a) {
4616 if (a == null)
4617 return "null";
4618
4619 int bufLen = 20 * a.length;
4620 if (a.length != 0 && bufLen <= 0)
4621 bufLen = Integer.MAX_VALUE;
4622 StringBuilder buf = new StringBuilder(bufLen);
4623 deepToString(a, buf, new HashSet<>());
4624 return buf.toString();
4625 }
4626
4627 private static void deepToString(Object[] a, StringBuilder buf,
4628 Set<Object[]> dejaVu) {
4629 if (a == null) {
4630 buf.append("null");
4631 return;
|