1/* 2 * Copyright (C) 2007 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package com.google.common.collect; 18 19import com.google.common.annotations.GwtCompatible; 20import com.google.common.annotations.GwtIncompatible; 21 22import java.util.Collection; 23 24import javax.annotation.Nullable; 25 26/** 27 * Static utility methods pertaining to object arrays. 28 * 29 * @author Kevin Bourrillion 30 * @since 2.0 (imported from Google Collections Library) 31 */ 32@GwtCompatible(emulated = true) 33public final class ObjectArrays { 34 private ObjectArrays() {} 35 36 /** 37 * Returns a new array of the given length with the specified component type. 38 * 39 * @param type the component type 40 * @param length the length of the new array 41 */ 42 @GwtIncompatible("Array.newInstance(Class, int)") 43 public static <T> T[] newArray(Class<T> type, int length) { 44 return Platform.newArray(type, length); 45 } 46 47 /** 48 * Returns a new array of the given length with the same type as a reference 49 * array. 50 * 51 * @param reference any array of the desired type 52 * @param length the length of the new array 53 */ 54 public static <T> T[] newArray(T[] reference, int length) { 55 return Platform.newArray(reference, length); 56 } 57 58 /** 59 * Returns a new array that contains the concatenated contents of two arrays. 60 * 61 * @param first the first array of elements to concatenate 62 * @param second the second array of elements to concatenate 63 * @param type the component type of the returned array 64 */ 65 @GwtIncompatible("Array.newInstance(Class, int)") 66 public static <T> T[] concat(T[] first, T[] second, Class<T> type) { 67 T[] result = newArray(type, first.length + second.length); 68 Platform.unsafeArrayCopy(first, 0, result, 0, first.length); 69 Platform.unsafeArrayCopy(second, 0, result, first.length, second.length); 70 return result; 71 } 72 73 /** 74 * Returns a new array that prepends {@code element} to {@code array}. 75 * 76 * @param element the element to prepend to the front of {@code array} 77 * @param array the array of elements to append 78 * @return an array whose size is one larger than {@code array}, with 79 * {@code element} occupying the first position, and the 80 * elements of {@code array} occupying the remaining elements. 81 */ 82 public static <T> T[] concat(@Nullable T element, T[] array) { 83 T[] result = newArray(array, array.length + 1); 84 result[0] = element; 85 Platform.unsafeArrayCopy(array, 0, result, 1, array.length); 86 return result; 87 } 88 89 /** 90 * Returns a new array that appends {@code element} to {@code array}. 91 * 92 * @param array the array of elements to prepend 93 * @param element the element to append to the end 94 * @return an array whose size is one larger than {@code array}, with 95 * the same contents as {@code array}, plus {@code element} occupying the 96 * last position. 97 */ 98 public static <T> T[] concat(T[] array, @Nullable T element) { 99 T[] result = arraysCopyOf(array, array.length + 1); 100 result[array.length] = element; 101 return result; 102 } 103 104 /** GWT safe version of Arrays.copyOf. */ 105 static <T> T[] arraysCopyOf(T[] original, int newLength) { 106 T[] copy = newArray(original, newLength); 107 Platform.unsafeArrayCopy( 108 original, 0, copy, 0, Math.min(original.length, newLength)); 109 return copy; 110 } 111 112 /** 113 * Returns an array containing all of the elements in the specified 114 * collection; the runtime type of the returned array is that of the specified 115 * array. If the collection fits in the specified array, it is returned 116 * therein. Otherwise, a new array is allocated with the runtime type of the 117 * specified array and the size of the specified collection. 118 * 119 * <p>If the collection fits in the specified array with room to spare (i.e., 120 * the array has more elements than the collection), the element in the array 121 * immediately following the end of the collection is set to {@code null}. 122 * This is useful in determining the length of the collection <i>only</i> if 123 * the caller knows that the collection does not contain any null elements. 124 * 125 * <p>This method returns the elements in the order they are returned by the 126 * collection's iterator. 127 * 128 * <p>TODO(kevinb): support concurrently modified collections? 129 * 130 * @param c the collection for which to return an array of elements 131 * @param array the array in which to place the collection elements 132 * @throws ArrayStoreException if the runtime type of the specified array is 133 * not a supertype of the runtime type of every element in the specified 134 * collection 135 */ 136 static <T> T[] toArrayImpl(Collection<?> c, T[] array) { 137 int size = c.size(); 138 if (array.length < size) { 139 array = newArray(array, size); 140 } 141 fillArray(c, array); 142 if (array.length > size) { 143 array[size] = null; 144 } 145 return array; 146 } 147 148 /** 149 * Returns an array containing all of the elements in the specified 150 * collection. This method returns the elements in the order they are returned 151 * by the collection's iterator. The returned array is "safe" in that no 152 * references to it are maintained by the collection. The caller is thus free 153 * to modify the returned array. 154 * 155 * <p>This method assumes that the collection size doesn't change while the 156 * method is running. 157 * 158 * <p>TODO(kevinb): support concurrently modified collections? 159 * 160 * @param c the collection for which to return an array of elements 161 */ 162 static Object[] toArrayImpl(Collection<?> c) { 163 return fillArray(c, new Object[c.size()]); 164 } 165 166 private static Object[] fillArray(Iterable<?> elements, Object[] array) { 167 int i = 0; 168 for (Object element : elements) { 169 array[i++] = element; 170 } 171 return array; 172 } 173 174 /** 175 * Swaps {@code array[i]} with {@code array[j]}. 176 */ 177 static void swap(Object[] array, int i, int j) { 178 Object temp = array[i]; 179 array[i] = array[j]; 180 array[j] = temp; 181 } 182} 183