1 /* 2 * Copyright (C) 2007 Google Inc. 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 17 package com.google.common.collect; 18 19 import com.google.common.annotations.GwtCompatible; 20 import com.google.common.annotations.GwtIncompatible; 21 22 import java.util.Collection; 23 24 import javax.annotation.Nullable; 25 26 /** 27 * Static utility methods pertaining to object arrays. 28 * 29 * @author Kevin Bourrillion 30 * @since 2010.01.04 <b>stable</b> (imported from Google Collections Library) 31 */ 32 @GwtCompatible 33 public 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 @SuppressWarnings("unchecked") 44 public static <T> T[] newArray(Class<T> type, int length) { 45 return Platform.newArray(type, length); 46 } 47 48 /** 49 * Returns a new array of the given length with the same type as a reference 50 * array. 51 * 52 * @param reference any array of the desired type 53 * @param length the length of the new array 54 */ 55 public static <T> T[] newArray(T[] reference, int length) { 56 return Platform.newArray(reference, length); 57 } 58 59 /** 60 * Returns a new array that contains the concatenated contents of two arrays. 61 * 62 * @param first the first array of elements to concatenate 63 * @param second the second array of elements to concatenate 64 * @param type the component type of the returned array 65 */ 66 @GwtIncompatible("Array.newInstance(Class, int)") 67 public static <T> T[] concat(T[] first, T[] second, Class<T> type) { 68 T[] result = newArray(type, first.length + second.length); 69 Platform.unsafeArrayCopy(first, 0, result, 0, first.length); 70 Platform.unsafeArrayCopy(second, 0, result, first.length, second.length); 71 return result; 72 } 73 74 /** 75 * Returns a new array that prepends {@code element} to {@code array}. 76 * 77 * @param element the element to prepend to the front of {@code array} 78 * @param array the array of elements to append 79 * @return an array whose size is one larger than {@code array}, with 80 * {@code element} occupying the first position, and the 81 * elements of {@code array} occupying the remaining elements. 82 */ 83 public static <T> T[] concat(@Nullable T element, T[] array) { 84 T[] result = newArray(array, array.length + 1); 85 result[0] = element; 86 Platform.unsafeArrayCopy(array, 0, result, 1, array.length); 87 return result; 88 } 89 90 /** 91 * Returns a new array that appends {@code element} to {@code array}. 92 * 93 * @param array the array of elements to prepend 94 * @param element the element to append to the end 95 * @return an array whose size is one larger than {@code array}, with 96 * the same contents as {@code array}, plus {@code element} occupying the 97 * last position. 98 */ 99 public static <T> T[] concat(T[] array, @Nullable T element) { 100 T[] result = arraysCopyOf(array, array.length + 1); 101 result[array.length] = element; 102 return result; 103 } 104 105 /** GWT safe version of Arrays.copyOf. */ 106 private static <T> T[] arraysCopyOf(T[] original, int newLength) { 107 T[] copy = newArray(original, newLength); 108 Platform.unsafeArrayCopy( 109 original, 0, copy, 0, Math.min(original.length, newLength)); 110 return copy; 111 } 112 113 /** 114 * Returns an array containing all of the elements in the specified 115 * collection; the runtime type of the returned array is that of the specified 116 * array. If the collection fits in the specified array, it is returned 117 * therein. Otherwise, a new array is allocated with the runtime type of the 118 * specified array and the size of the specified collection. 119 * 120 * <p>If the collection fits in the specified array with room to spare (i.e., 121 * the array has more elements than the collection), the element in the array 122 * immediately following the end of the collection is set to null. This is 123 * useful in determining the length of the collection <i>only</i> if the 124 * caller knows that the collection does not contain any null elements. 125 * 126 * <p>This method returns the elements in the order they are returned by the 127 * collection's iterator. 128 * 129 * <p>TODO: Support concurrent collections whose size can change while the 130 * method is running. 131 * 132 * @param c the collection for which to return an array of elements 133 * @param array the array in which to place the collection elements 134 * @throws ArrayStoreException if the runtime type of the specified array is 135 * not a supertype of the runtime type of every element in the specified 136 * collection 137 */ 138 static <T> T[] toArrayImpl(Collection<?> c, T[] array) { 139 int size = c.size(); 140 if (array.length < size) { 141 array = newArray(array, size); 142 } 143 fillArray(c, array); 144 if (array.length > size) { 145 array[size] = null; 146 } 147 return array; 148 } 149 150 /** 151 * Returns an array containing all of the elements in the specified 152 * collection. This method returns the elements in the order they are returned 153 * by the collection's iterator. The returned array is "safe" in that no 154 * references to it are maintained by the collection. The caller is thus free 155 * to modify the returned array. 156 * 157 * <p>This method assumes that the collection size doesn't change while the 158 * method is running. 159 * 160 * <p>TODO: Support concurrent collections whose size can change while the 161 * method is running. 162 * 163 * @param c the collection for which to return an array of elements 164 */ 165 static Object[] toArrayImpl(Collection<?> c) { 166 return fillArray(c, new Object[c.size()]); 167 } 168 169 private static Object[] fillArray(Iterable<?> elements, Object[] array) { 170 int i = 0; 171 for (Object element : elements) { 172 array[i++] = element; 173 } 174 return array; 175 } 176 } 177
