ObjectArrays.java revision 1d580d0f6ee4f21eb309ba7b509d2c6d671c4044
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; 20 21import java.util.Collection; 22 23import javax.annotation.Nullable; 24 25/** 26 * Static utility methods pertaining to object arrays. 27 * 28 * @author Kevin Bourrillion 29 * @since 2.0 (imported from Google Collections Library) 30 */ 31@GwtCompatible(emulated = true) 32public final class ObjectArrays { 33 private ObjectArrays() {} 34 35 /** 36 * Returns a new array of the given length with the same type as a reference 37 * array. 38 * 39 * @param reference any array of the desired type 40 * @param length the length of the new array 41 */ 42 public static <T> T[] newArray(T[] reference, int length) { 43 return Platform.newArray(reference, length); 44 } 45 46 /** 47 * Returns a new array that prepends {@code element} to {@code array}. 48 * 49 * @param element the element to prepend to the front of {@code array} 50 * @param array the array of elements to append 51 * @return an array whose size is one larger than {@code array}, with 52 * {@code element} occupying the first position, and the 53 * elements of {@code array} occupying the remaining elements. 54 */ 55 public static <T> T[] concat(@Nullable T element, T[] array) { 56 T[] result = newArray(array, array.length + 1); 57 result[0] = element; 58 Platform.unsafeArrayCopy(array, 0, result, 1, array.length); 59 return result; 60 } 61 62 /** 63 * Returns a new array that appends {@code element} to {@code array}. 64 * 65 * @param array the array of elements to prepend 66 * @param element the element to append to the end 67 * @return an array whose size is one larger than {@code array}, with 68 * the same contents as {@code array}, plus {@code element} occupying the 69 * last position. 70 */ 71 public static <T> T[] concat(T[] array, @Nullable T element) { 72 T[] result = arraysCopyOf(array, array.length + 1); 73 result[array.length] = element; 74 return result; 75 } 76 77 /** GWT safe version of Arrays.copyOf. */ 78 static <T> T[] arraysCopyOf(T[] original, int newLength) { 79 T[] copy = newArray(original, newLength); 80 Platform.unsafeArrayCopy( 81 original, 0, copy, 0, Math.min(original.length, newLength)); 82 return copy; 83 } 84 85 /** 86 * Returns an array containing all of the elements in the specified 87 * collection; the runtime type of the returned array is that of the specified 88 * array. If the collection fits in the specified array, it is returned 89 * therein. Otherwise, a new array is allocated with the runtime type of the 90 * specified array and the size of the specified collection. 91 * 92 * <p>If the collection fits in the specified array with room to spare (i.e., 93 * the array has more elements than the collection), the element in the array 94 * immediately following the end of the collection is set to {@code null}. 95 * This is useful in determining the length of the collection <i>only</i> if 96 * the caller knows that the collection does not contain any null elements. 97 * 98 * <p>This method returns the elements in the order they are returned by the 99 * collection's iterator. 100 * 101 * <p>TODO(kevinb): support concurrently modified collections? 102 * 103 * @param c the collection for which to return an array of elements 104 * @param array the array in which to place the collection elements 105 * @throws ArrayStoreException if the runtime type of the specified array is 106 * not a supertype of the runtime type of every element in the specified 107 * collection 108 */ 109 static <T> T[] toArrayImpl(Collection<?> c, T[] array) { 110 int size = c.size(); 111 if (array.length < size) { 112 array = newArray(array, size); 113 } 114 fillArray(c, array); 115 if (array.length > size) { 116 array[size] = null; 117 } 118 return array; 119 } 120 121 /** 122 * Returns an array containing all of the elements in the specified 123 * collection. This method returns the elements in the order they are returned 124 * by the collection's iterator. The returned array is "safe" in that no 125 * references to it are maintained by the collection. The caller is thus free 126 * to modify the returned array. 127 * 128 * <p>This method assumes that the collection size doesn't change while the 129 * method is running. 130 * 131 * <p>TODO(kevinb): support concurrently modified collections? 132 * 133 * @param c the collection for which to return an array of elements 134 */ 135 static Object[] toArrayImpl(Collection<?> c) { 136 return fillArray(c, new Object[c.size()]); 137 } 138 139 private static Object[] fillArray(Iterable<?> elements, Object[] array) { 140 int i = 0; 141 for (Object element : elements) { 142 array[i++] = element; 143 } 144 return array; 145 } 146 147 /** 148 * Swaps {@code array[i]} with {@code array[j]}. 149 */ 150 static void swap(Object[] array, int i, int j) { 151 Object temp = array[i]; 152 array[i] = array[j]; 153 array[j] = temp; 154 } 155} 156 157