/*
* Copyright (C) 2007 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.collect;
import static com.google.common.base.
Preconditions.checkPositionIndexes;
import com.google.common.annotations.
GwtCompatible;
import com.google.common.annotations.
GwtIncompatible;
import java.lang.reflect.
Array;
import java.util.
Collection;
import javax.annotation.
Nullable;
/**
* Static utility methods pertaining to object arrays.
*
* @author Kevin Bourrillion
* @since 2.0 (imported from Google Collections Library)
*/
@
GwtCompatible(emulated = true)
public final class
ObjectArrays {
static final
Object[]
EMPTY_ARRAY = new
Object[0];
private
ObjectArrays() {}
/**
* Returns a new array of the given length with the specified component type.
*
* @param type the component type
* @param length the length of the new array
*/
@
GwtIncompatible("Array.newInstance(Class, int)")
@
SuppressWarnings("unchecked")
public static <T> T[]
newArray(
Class<T>
type, int
length) {
return (T[])
Array.
newInstance(
type,
length);
}
/**
* Returns a new array of the given length with the same type as a reference
* array.
*
* @param reference any array of the desired type
* @param length the length of the new array
*/
public static <T> T[]
newArray(T[]
reference, int
length) {
return
Platform.
newArray(
reference,
length);
}
/**
* Returns a new array that contains the concatenated contents of two arrays.
*
* @param first the first array of elements to concatenate
* @param second the second array of elements to concatenate
* @param type the component type of the returned array
*/
@
GwtIncompatible("Array.newInstance(Class, int)")
public static <T> T[]
concat(T[]
first, T[]
second,
Class<T>
type) {
T[]
result =
newArray(
type,
first.length +
second.length);
System.
arraycopy(
first, 0,
result, 0,
first.length);
System.
arraycopy(
second, 0,
result,
first.length,
second.length);
return
result;
}
/**
* Returns a new array that prepends {@code element} to {@code array}.
*
* @param element the element to prepend to the front of {@code array}
* @param array the array of elements to append
* @return an array whose size is one larger than {@code array}, with
* {@code element} occupying the first position, and the
* elements of {@code array} occupying the remaining elements.
*/
public static <T> T[]
concat(@
Nullable T
element, T[]
array) {
T[]
result =
newArray(
array,
array.length + 1);
result[0] =
element;
System.
arraycopy(
array, 0,
result, 1,
array.length);
return
result;
}
/**
* Returns a new array that appends {@code element} to {@code array}.
*
* @param array the array of elements to prepend
* @param element the element to append to the end
* @return an array whose size is one larger than {@code array}, with
* the same contents as {@code array}, plus {@code element} occupying the
* last position.
*/
public static <T> T[]
concat(T[]
array, @
Nullable T
element) {
T[]
result =
arraysCopyOf(
array,
array.length + 1);
result[
array.length] =
element;
return
result;
}
/** GWT safe version of Arrays.copyOf. */
static <T> T[]
arraysCopyOf(T[]
original, int
newLength) {
T[]
copy =
newArray(
original,
newLength);
System.
arraycopy(
original, 0,
copy, 0,
Math.
min(
original.length,
newLength));
return
copy;
}
/**
* Returns an array containing all of the elements in the specified
* collection; the runtime type of the returned array is that of the specified
* array. If the collection fits in the specified array, it is returned
* therein. Otherwise, a new array is allocated with the runtime type of the
* specified array and the size of the specified collection.
*
* <p>If the collection fits in the specified array with room to spare (i.e.,
* the array has more elements than the collection), the element in the array
* immediately following the end of the collection is set to {@code null}.
* This is useful in determining the length of the collection <i>only</i> if
* the caller knows that the collection does not contain any null elements.
*
* <p>This method returns the elements in the order they are returned by the
* collection's iterator.
*
* <p>TODO(kevinb): support concurrently modified collections?
*
* @param c the collection for which to return an array of elements
* @param array the array in which to place the collection elements
* @throws ArrayStoreException if the runtime type of the specified array is
* not a supertype of the runtime type of every element in the specified
* collection
*/
static <T> T[]
toArrayImpl(
Collection<?>
c, T[]
array) {
int
size =
c.
size();
if (
array.length <
size) {
array =
newArray(
array,
size);
}
fillArray(
c,
array);
if (
array.length >
size) {
array[
size] = null;
}
return
array;
}
/**
* Implementation of {@link Collection#toArray(Object[])} for collections backed by an object
* array. the runtime type of the returned array is that of the specified array. If the collection
* fits in the specified array, it is returned therein. Otherwise, a new array is allocated with
* the runtime type of the specified array and the size of the specified collection.
*
* <p>If the collection fits in the specified array with room to spare (i.e., the array has more
* elements than the collection), the element in the array immediately following the end of the
* collection is set to {@code null}. This is useful in determining the length of the collection
* <i>only</i> if the caller knows that the collection does not contain any null elements.
*/
static <T> T[]
toArrayImpl(
Object[]
src, int
offset, int
len, T[]
dst) {
checkPositionIndexes(
offset,
offset +
len,
src.length);
if (
dst.length <
len) {
dst =
newArray(
dst,
len);
} else if (
dst.length >
len) {
dst[
len] = null;
}
System.
arraycopy(
src,
offset,
dst, 0,
len);
return
dst;
}
/**
* Returns an array containing all of the elements in the specified
* collection. This method returns the elements in the order they are returned
* by the collection's iterator. The returned array is "safe" in that no
* references to it are maintained by the collection. The caller is thus free
* to modify the returned array.
*
* <p>This method assumes that the collection size doesn't change while the
* method is running.
*
* <p>TODO(kevinb): support concurrently modified collections?
*
* @param c the collection for which to return an array of elements
*/
static
Object[]
toArrayImpl(
Collection<?>
c) {
return
fillArray(
c, new
Object[
c.
size()]);
}
/**
* Returns a copy of the specified subrange of the specified array that is literally an Object[],
* and not e.g. a {@code String[]}.
*/
static
Object[]
copyAsObjectArray(
Object[]
elements, int
offset, int
length) {
checkPositionIndexes(
offset,
offset +
length,
elements.length);
if (
length == 0) {
return
EMPTY_ARRAY;
}
Object[]
result = new
Object[
length];
System.
arraycopy(
elements,
offset,
result, 0,
length);
return
result;
}
private static
Object[]
fillArray(
Iterable<?>
elements,
Object[]
array) {
int
i = 0;
for (
Object element :
elements) {
array[
i++] =
element;
}
return
array;
}
/**
* Swaps {@code array[i]} with {@code array[j]}.
*/
static void
swap(
Object[]
array, int
i, int
j) {
Object temp =
array[
i];
array[
i] =
array[
j];
array[
j] =
temp;
}
static
Object[]
checkElementsNotNull(
Object...
array) {
return
checkElementsNotNull(
array,
array.length);
}
static
Object[]
checkElementsNotNull(
Object[]
array, int
length) {
for (int
i = 0;
i <
length;
i++) {
checkElementNotNull(
array[
i],
i);
}
return
array;
}
// We do this instead of Preconditions.checkNotNull to save boxing and array
// creation cost.
static
Object checkElementNotNull(
Object element, int
index) {
if (
element == null) {
throw new
NullPointerException("at index " +
index);
}
return
element;
}
}