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