Java tutorial
/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.collect; import static com.google.common.base.Preconditions.checkPositionIndexes; import com.google.common.annotations.GwtCompatible; import com.google.common.annotations.GwtIncompatible; import java.lang.reflect.Array; import java.util.Collection; import javax.annotation.Nullable; /** * Static utility methods pertaining to object arrays. * * @author Kevin Bourrillion * @since 2.0 */ @GwtCompatible(emulated = true) public final class ObjectArrays { static final Object[] EMPTY_ARRAY = new Object[0]; private ObjectArrays() { } /** * Returns a new array of the given length with the specified component type. * * @param type the component type * @param length the length of the new array */ @GwtIncompatible("Array.newInstance(Class, int)") @SuppressWarnings("unchecked") public static <T> T[] newArray(Class<T> type, int length) { return (T[]) Array.newInstance(type, length); } /** * Returns a new array of the given length with the same type as a reference * array. * * @param reference any array of the desired type * @param length the length of the new array */ public static <T> T[] newArray(T[] reference, int length) { return Platform.newArray(reference, length); } /** * Returns a new array that contains the concatenated contents of two arrays. * * @param first the first array of elements to concatenate * @param second the second array of elements to concatenate * @param type the component type of the returned array */ @GwtIncompatible("Array.newInstance(Class, int)") public static <T> T[] concat(T[] first, T[] second, Class<T> type) { T[] result = newArray(type, first.length + second.length); System.arraycopy(first, 0, result, 0, first.length); System.arraycopy(second, 0, result, first.length, second.length); return result; } /** * Returns a new array that prepends {@code element} to {@code array}. * * @param element the element to prepend to the front of {@code array} * @param array the array of elements to append * @return an array whose size is one larger than {@code array}, with * {@code element} occupying the first position, and the * elements of {@code array} occupying the remaining elements. */ public static <T> T[] concat(@Nullable T element, T[] array) { T[] result = newArray(array, array.length + 1); result[0] = element; System.arraycopy(array, 0, result, 1, array.length); return result; } /** * Returns a new array that appends {@code element} to {@code array}. * * @param array the array of elements to prepend * @param element the element to append to the end * @return an array whose size is one larger than {@code array}, with * the same contents as {@code array}, plus {@code element} occupying the * last position. */ public static <T> T[] concat(T[] array, @Nullable T element) { T[] result = arraysCopyOf(array, array.length + 1); result[array.length] = element; return result; } /** GWT safe version of Arrays.copyOf. */ static <T> T[] arraysCopyOf(T[] original, int newLength) { T[] copy = newArray(original, newLength); System.arraycopy(original, 0, copy, 0, Math.min(original.length, newLength)); return copy; } /** * Returns an array containing all of the elements in the specified * collection; the runtime type of the returned array is that of the specified * array. If the collection fits in the specified array, it is returned * therein. Otherwise, a new array is allocated with the runtime type of the * specified array and the size of the specified collection. * * <p>If the collection fits in the specified array with room to spare (i.e., * the array has more elements than the collection), the element in the array * immediately following the end of the collection is set to {@code null}. * This is useful in determining the length of the collection <i>only</i> if * the caller knows that the collection does not contain any null elements. * * <p>This method returns the elements in the order they are returned by the * collection's iterator. * * <p>TODO(kevinb): support concurrently modified collections? * * @param c the collection for which to return an array of elements * @param array the array in which to place the collection elements * @throws ArrayStoreException if the runtime type of the specified array is * not a supertype of the runtime type of every element in the specified * collection */ static <T> T[] toArrayImpl(Collection<?> c, T[] array) { int size = c.size(); if (array.length < size) { array = newArray(array, size); } fillArray(c, array); if (array.length > size) { array[size] = null; } return array; } /** * Implementation of {@link Collection#toArray(Object[])} for collections backed by an object * array. the runtime type of the returned array is that of the specified array. If the collection * fits in the specified array, it is returned therein. Otherwise, a new array is allocated with * the runtime type of the specified array and the size of the specified collection. * * <p>If the collection fits in the specified array with room to spare (i.e., the array has more * elements than the collection), the element in the array immediately following the end of the * collection is set to {@code null}. This is useful in determining the length of the collection * <i>only</i> if the caller knows that the collection does not contain any null elements. */ static <T> T[] toArrayImpl(Object[] src, int offset, int len, T[] dst) { checkPositionIndexes(offset, offset + len, src.length); if (dst.length < len) { dst = newArray(dst, len); } else if (dst.length > len) { dst[len] = null; } System.arraycopy(src, offset, dst, 0, len); return dst; } /** * Returns an array containing all of the elements in the specified * collection. This method returns the elements in the order they are returned * by the collection's iterator. The returned array is "safe" in that no * references to it are maintained by the collection. The caller is thus free * to modify the returned array. * * <p>This method assumes that the collection size doesn't change while the * method is running. * * <p>TODO(kevinb): support concurrently modified collections? * * @param c the collection for which to return an array of elements */ static Object[] toArrayImpl(Collection<?> c) { return fillArray(c, new Object[c.size()]); } /** * Returns a copy of the specified subrange of the specified array that is literally an Object[], * and not e.g. a {@code String[]}. */ static Object[] copyAsObjectArray(Object[] elements, int offset, int length) { checkPositionIndexes(offset, offset + length, elements.length); if (length == 0) { return EMPTY_ARRAY; } Object[] result = new Object[length]; System.arraycopy(elements, offset, result, 0, length); return result; } private static Object[] fillArray(Iterable<?> elements, Object[] array) { int i = 0; for (Object element : elements) { array[i++] = element; } return array; } /** * Swaps {@code array[i]} with {@code array[j]}. */ static void swap(Object[] array, int i, int j) { Object temp = array[i]; array[i] = array[j]; array[j] = temp; } static Object[] checkElementsNotNull(Object... array) { return checkElementsNotNull(array, array.length); } static Object[] checkElementsNotNull(Object[] array, int length) { for (int i = 0; i < length; i++) { checkElementNotNull(array[i], i); } return array; } // We do this instead of Preconditions.checkNotNull to save boxing and array // creation cost. static Object checkElementNotNull(Object element, int index) { if (element == null) { throw new NullPointerException("at index " + index); } return element; } }