001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect; 018 019import static com.google.common.base.Preconditions.checkPositionIndexes; 020 021import com.google.common.annotations.GwtCompatible; 022import com.google.common.annotations.GwtIncompatible; 023import com.google.errorprone.annotations.CanIgnoreReturnValue; 024import java.lang.reflect.Array; 025import java.util.Arrays; 026import java.util.Collection; 027import javax.annotation.Nullable; 028 029/** 030 * Static utility methods pertaining to object arrays. 031 * 032 * @author Kevin Bourrillion 033 * @since 2.0 034 */ 035@GwtCompatible(emulated = true) 036public final class ObjectArrays { 037 038 private ObjectArrays() {} 039 040 /** 041 * Returns a new array of the given length with the specified component type. 042 * 043 * @param type the component type 044 * @param length the length of the new array 045 */ 046 @GwtIncompatible // Array.newInstance(Class, int) 047 @SuppressWarnings("unchecked") 048 public static <T> T[] newArray(Class<T> type, int length) { 049 return (T[]) Array.newInstance(type, length); 050 } 051 052 /** 053 * Returns a new array of the given length with the same type as a reference 054 * array. 055 * 056 * @param reference any array of the desired type 057 * @param length the length of the new array 058 */ 059 public static <T> T[] newArray(T[] reference, int length) { 060 return Platform.newArray(reference, length); 061 } 062 063 /** 064 * Returns a new array that contains the concatenated contents of two arrays. 065 * 066 * @param first the first array of elements to concatenate 067 * @param second the second array of elements to concatenate 068 * @param type the component type of the returned array 069 */ 070 @GwtIncompatible // Array.newInstance(Class, int) 071 public static <T> T[] concat(T[] first, T[] second, Class<T> type) { 072 T[] result = newArray(type, first.length + second.length); 073 System.arraycopy(first, 0, result, 0, first.length); 074 System.arraycopy(second, 0, result, first.length, second.length); 075 return result; 076 } 077 078 /** 079 * Returns a new array that prepends {@code element} to {@code array}. 080 * 081 * @param element the element to prepend to the front of {@code array} 082 * @param array the array of elements to append 083 * @return an array whose size is one larger than {@code array}, with 084 * {@code element} occupying the first position, and the 085 * elements of {@code array} occupying the remaining elements. 086 */ 087 public static <T> T[] concat(@Nullable T element, T[] array) { 088 T[] result = newArray(array, array.length + 1); 089 result[0] = element; 090 System.arraycopy(array, 0, result, 1, array.length); 091 return result; 092 } 093 094 /** 095 * Returns a new array that appends {@code element} to {@code array}. 096 * 097 * @param array the array of elements to prepend 098 * @param element the element to append to the end 099 * @return an array whose size is one larger than {@code array}, with 100 * the same contents as {@code array}, plus {@code element} occupying the 101 * last position. 102 */ 103 public static <T> T[] concat(T[] array, @Nullable T element) { 104 T[] result = Arrays.copyOf(array, array.length + 1); 105 result[array.length] = element; 106 return result; 107 } 108 109 /** 110 * Returns an array containing all of the elements in the specified 111 * collection; the runtime type of the returned array is that of the specified 112 * array. If the collection fits in the specified array, it is returned 113 * therein. Otherwise, a new array is allocated with the runtime type of the 114 * specified array and the size of the specified collection. 115 * 116 * <p>If the collection fits in the specified array with room to spare (i.e., 117 * the array has more elements than the collection), the element in the array 118 * immediately following the end of the collection is set to {@code null}. 119 * This is useful in determining the length of the collection <i>only</i> if 120 * the caller knows that the collection does not contain any null elements. 121 * 122 * <p>This method returns the elements in the order they are returned by the 123 * collection's iterator. 124 * 125 * <p>TODO(kevinb): support concurrently modified collections? 126 * 127 * @param c the collection for which to return an array of elements 128 * @param array the array in which to place the collection elements 129 * @throws ArrayStoreException if the runtime type of the specified array is 130 * not a supertype of the runtime type of every element in the specified 131 * collection 132 */ 133 static <T> T[] toArrayImpl(Collection<?> c, T[] array) { 134 int size = c.size(); 135 if (array.length < size) { 136 array = newArray(array, size); 137 } 138 fillArray(c, array); 139 if (array.length > size) { 140 array[size] = null; 141 } 142 return array; 143 } 144 145 /** 146 * Implementation of {@link Collection#toArray(Object[])} for collections backed by an object 147 * array. the runtime type of the returned array is that of the specified array. If the collection 148 * fits in the specified array, it is returned therein. Otherwise, a new array is allocated with 149 * the runtime type of the specified array and the size of the specified collection. 150 * 151 * <p>If the collection fits in the specified array with room to spare (i.e., the array has more 152 * elements than the collection), the element in the array immediately following the end of the 153 * collection is set to {@code null}. This is useful in determining the length of the collection 154 * <i>only</i> if the caller knows that the collection does not contain any null elements. 155 */ 156 static <T> T[] toArrayImpl(Object[] src, int offset, int len, T[] dst) { 157 checkPositionIndexes(offset, offset + len, src.length); 158 if (dst.length < len) { 159 dst = newArray(dst, len); 160 } else if (dst.length > len) { 161 dst[len] = null; 162 } 163 System.arraycopy(src, offset, dst, 0, len); 164 return dst; 165 } 166 167 /** 168 * Returns an array containing all of the elements in the specified 169 * collection. This method returns the elements in the order they are returned 170 * by the collection's iterator. The returned array is "safe" in that no 171 * references to it are maintained by the collection. The caller is thus free 172 * to modify the returned array. 173 * 174 * <p>This method assumes that the collection size doesn't change while the 175 * method is running. 176 * 177 * <p>TODO(kevinb): support concurrently modified collections? 178 * 179 * @param c the collection for which to return an array of elements 180 */ 181 static Object[] toArrayImpl(Collection<?> c) { 182 return fillArray(c, new Object[c.size()]); 183 } 184 185 /** 186 * Returns a copy of the specified subrange of the specified array that is literally an Object[], 187 * and not e.g. a {@code String[]}. 188 */ 189 static Object[] copyAsObjectArray(Object[] elements, int offset, int length) { 190 checkPositionIndexes(offset, offset + length, elements.length); 191 if (length == 0) { 192 return new Object[0]; 193 } 194 Object[] result = new Object[length]; 195 System.arraycopy(elements, offset, result, 0, length); 196 return result; 197 } 198 199 @CanIgnoreReturnValue 200 private static Object[] fillArray(Iterable<?> elements, Object[] array) { 201 int i = 0; 202 for (Object element : elements) { 203 array[i++] = element; 204 } 205 return array; 206 } 207 208 /** 209 * Swaps {@code array[i]} with {@code array[j]}. 210 */ 211 static void swap(Object[] array, int i, int j) { 212 Object temp = array[i]; 213 array[i] = array[j]; 214 array[j] = temp; 215 } 216 217 @CanIgnoreReturnValue 218 static Object[] checkElementsNotNull(Object... array) { 219 return checkElementsNotNull(array, array.length); 220 } 221 222 @CanIgnoreReturnValue 223 static Object[] checkElementsNotNull(Object[] array, int length) { 224 for (int i = 0; i < length; i++) { 225 checkElementNotNull(array[i], i); 226 } 227 return array; 228 } 229 230 // We do this instead of Preconditions.checkNotNull to save boxing and array 231 // creation cost. 232 @CanIgnoreReturnValue 233 static Object checkElementNotNull(Object element, int index) { 234 if (element == null) { 235 throw new NullPointerException("at index " + index); 236 } 237 return element; 238 } 239}