drv.List.drv Maven / Gradle / Ivy
Show all versions of fastutil Show documentation
/*
* Copyright (C) 2002-2020 Sebastiano Vigna
*
* 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 PACKAGE;
import java.util.List;
#if ! KEY_CLASS_Reference
/** A type-specific {@link List}; provides some additional methods that use polymorphism to avoid (un)boxing.
*
* Note that this type-specific interface extends {@link Comparable}: it is expected that implementing
* classes perform a lexicographical comparison using the standard operator "less then" for primitive types,
* and the usual {@link Comparable#compareTo(Object) compareTo()} method for objects.
*
*
Additionally, this interface strengthens {@link #listIterator()},
* {@link #listIterator(int)} and {@link #subList(int,int)}.
*
*
Besides polymorphic methods, this interfaces specifies methods to copy into an array or remove contiguous
* sublists. Although the abstract implementation of this interface provides simple, one-by-one implementations
* of these methods, it is expected that concrete implementation override them with optimized versions.
*
* @see List
*/
public interface LIST KEY_GENERIC extends List, Comparable>, COLLECTION KEY_GENERIC {
#else
/** A type-specific {@link List}; provides some additional methods that use polymorphism to avoid (un)boxing.
*
* Additionally, this interface strengthens {@link #iterator()}, {@link #listIterator()},
* {@link #listIterator(int)} and {@link #subList(int,int)}. The former had been already
* strengthened upstream, but unfortunately {@link List} re-specifies it.
*
*
Besides polymorphic methods, this interfaces specifies methods to copy into an array or remove contiguous
* sublists. Although the abstract implementation of this interface provides simple, one-by-one implementations
* of these methods, it is expected that concrete implementation override them with optimized versions.
*
* @see List
*/
public interface LIST KEY_GENERIC extends List, COLLECTION KEY_GENERIC {
#endif
/** Returns a type-specific iterator on the elements of this list.
*
* Note that this specification strengthens the one given in {@link List#iterator()}.
* It would not be normally necessary, but {@link java.lang.Iterable#iterator()} is bizarrily re-specified
* in {@link List}.
*
* @return an iterator on the elements of this list.
*/
@Override
KEY_LIST_ITERATOR KEY_GENERIC iterator();
/** Returns a type-specific list iterator on the list.
*
* @see List#listIterator()
*/
@Override
KEY_LIST_ITERATOR KEY_GENERIC listIterator();
/** Returns a type-specific list iterator on the list starting at a given index.
*
* @see List#listIterator(int)
*/
@Override
KEY_LIST_ITERATOR KEY_GENERIC listIterator(int index);
/** Returns a type-specific view of the portion of this list from the index {@code from}, inclusive, to the index {@code to}, exclusive.
*
*
Note that this specification strengthens the one given in {@link List#subList(int,int)}.
*
* @see List#subList(int,int)
*/
@Override
LIST KEY_GENERIC subList(int from, int to);
/** Sets the size of this list.
*
*
If the specified size is smaller than the current size, the last elements are
* discarded. Otherwise, they are filled with 0/{@code null}/{@code false}.
*
* @param size the new size.
*/
void size(int size);
/** Copies (hopefully quickly) elements of this type-specific list into the given array.
*
* @param from the start index (inclusive).
* @param a the destination array.
* @param offset the offset into the destination array where to store the first element copied.
* @param length the number of elements to be copied.
*/
void getElements(int from, KEY_TYPE a[], int offset, int length);
/** Removes (hopefully quickly) elements of this type-specific list.
*
* @param from the start index (inclusive).
* @param to the end index (exclusive).
*/
void removeElements(int from, int to);
/** Add (hopefully quickly) elements to this type-specific list.
*
* @param index the index at which to add elements.
* @param a the array containing the elements.
*/
void addElements(int index, KEY_GENERIC_TYPE a[]);
/** Add (hopefully quickly) elements to this type-specific list.
*
* @param index the index at which to add elements.
* @param a the array containing the elements.
* @param offset the offset of the first element to add.
* @param length the number of elements to add.
*/
void addElements(int index, KEY_GENERIC_TYPE a[], int offset, int length);
/** Set (hopefully quickly) elements to match the array given.
* @param a the array containing the elements.
* @since 8.3.0
*/
default void setElements(KEY_GENERIC_TYPE a[]) {
setElements(0, a);
}
/** Set (hopefully quickly) elements to match the array given.
* @param index the index at which to start setting elements.
* @param a the array containing the elements.
* @since 8.3.0
*/
default void setElements(int index, KEY_GENERIC_TYPE a[]) {
setElements(index, a, 0, a.length);
}
/** Set (hopefully quickly) elements to match the array given.
*
* Sets each in this list to the corresponding elements in the array, as if by
*
* ListIterator iter = listIterator(index);
* int i = 0;
* while (i < length) {
* iter.next();
* iter.set(a[offset + i++]);
* }
*
* However, the exact implementation may be more efficient, taking into account
* whether random access is faster or not, or at the discretion of subclasses,
* abuse internals.
*
* @param index the index at which to start setting elements.
* @param a the array containing the elements
* @param offset the offset of the first element to add.
* @param length the number of elements to add.
* @since 8.3.0
*/
default void setElements(int index, KEY_GENERIC_TYPE a[], int offset, int length) {
// We can't use AbstractList#ensureIndex, sadly.
if (index < 0) throw new IndexOutOfBoundsException("Index (" + index + ") is negative");
if (index > size()) throw new IndexOutOfBoundsException("Index (" + index + ") is greater than list size (" + (size()) + ")");
ARRAYS.ensureOffsetLength(a, offset, length);
if (index + length > size()) throw new IndexOutOfBoundsException("End index (" + (index + length) + ") is greater than list size (" + size() + ")");
KEY_LIST_ITERATOR KEY_GENERIC iter = listIterator(index);
int i = 0;
while (i < length) {
iter.NEXT_KEY();
iter.set(a[offset + i++]);
}
}
#if KEYS_PRIMITIVE
/** Appends the specified element to the end of this list (optional operation).
* @see List#add(Object)
*/
@Override
boolean add(KEY_TYPE key);
/** Inserts the specified element at the specified position in this list (optional operation).
* @see List#add(int,Object)
*/
void add(int index, KEY_TYPE key);
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default void add(int index, KEY_CLASS key) {
add(index, KEY_CLASS2TYPE(key));
}
/** Inserts all of the elements in the specified type-specific collection into this type-specific list at the specified position (optional operation).
* @see List#addAll(int,java.util.Collection)
*/
boolean addAll(int index, COLLECTION c);
/** Inserts all of the elements in the specified type-specific list into this type-specific list at the specified position (optional operation).
* @see List#add(int,Object)
*/
boolean addAll(int index, LIST c);
/** Appends all of the elements in the specified type-specific list to the end of this type-specific list (optional operation).
* @see List#add(int,Object)
*/
boolean addAll(LIST c);
/** Replaces the element at the specified position in this list with the specified element (optional operation).
* @see List#set(int,Object)
*/
KEY_TYPE set(int index, KEY_TYPE k);
/** Returns the element at the specified position in this list.
* @see List#get(int)
*/
KEY_TYPE GET_KEY(int index);
/** Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.
* @see List#indexOf(Object)
*/
int indexOf(KEY_TYPE k);
/** Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.
* @see List#lastIndexOf(Object)
*/
int lastIndexOf(KEY_TYPE k);
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead.
*/
@Deprecated
@Override
default boolean contains(final Object key) {
return COLLECTION.super.contains(key);
}
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default KEY_GENERIC_CLASS get(int index) {
return KEY2OBJ(GET_KEY(index));
}
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default int indexOf(Object o) {
return indexOf(KEY_OBJ2TYPE(o));
}
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default int lastIndexOf(Object o) {
return lastIndexOf(KEY_OBJ2TYPE(o));
}
/** {@inheritDoc}
* This method specification is a workaround for
* bug 8177440.
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default boolean add(KEY_CLASS k) {
return add(KEY_CLASS2TYPE(k));
}
/** Removes the element at the specified position in this list (optional operation).
* @see List#remove(int)
*/
KEY_TYPE REMOVE_KEY(int index);
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead.
*/
@Deprecated
@Override
default boolean remove(final Object key) {
return COLLECTION.super.remove(key);
}
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default KEY_GENERIC_CLASS remove(int index) {
return KEY2OBJ(REMOVE_KEY(index));
}
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead. */
@Deprecated
@Override
default KEY_GENERIC_CLASS set(int index, KEY_CLASS k) {
return KEY2OBJ(set(index, KEY_CLASS2TYPE(k)));
}
#endif
#if defined KEY_COMPARATOR && KEYS_PRIMITIVE
/** {@inheritDoc}
* @deprecated Please use the corresponding type-specific method instead.
*/
@Deprecated
@Override
default void sort(final java.util.Comparator comparator) {
sort(COMPARATORS.AS_KEY_COMPARATOR(comparator));
}
/** Sort a list using a type-specific comparator.
*
*
Pass {@code null} to sort using natural ordering.
* @see List#sort(java.util.Comparator)
*
* @implSpec The default implementation dumps the elements into an array using
* {@link #toArray()}, sorts the array, then replaces all elements using the
* {@link #setElements} function.
*
* @implneNote It is possible for this method to call {@link #unstableSort} if it can
* determine that the results of a stable and unstable sort are completely equivalent.
* This means if you override {@link #unstableSort}, it should not call this
* method unless you override this method as well.
*
* @since 8.3.0
*/
default void sort(final KEY_COMPARATOR comparator) {
#if !(KEY_CLASS_Float || KEY_CLASS_Double)
if (comparator == null) {
// For non-floating point primitive types, when comparing naturally,
// it is impossible to tell the difference between a stable and not-stable sort.
// So just use the probably faster unstable sort.
unstableSort(comparator);
} else {
KEY_TYPE[] elements = TO_KEY_ARRAY();
ARRAYS.stableSort(elements, comparator);
setElements(elements);
}
#else
KEY_TYPE[] elements = TO_KEY_ARRAY();
if (comparator == null) {
ARRAYS.stableSort(elements);
} else {
ARRAYS.stableSort(elements, comparator);
}
setElements(elements);
#endif
}
/** Sorts this list using a sort not assured to be stable.
* @deprecated Please use the corresponding type-specific method instead.
*/
@Deprecated
default void unstableSort(final java.util.Comparator comparator) {
unstableSort(COMPARATORS.AS_KEY_COMPARATOR(comparator));
}
/** Sorts this list using a sort not assured to be stable.
*
*
Pass {@code null} to sort using natural ordering.
*
*
This differs from {@link List#sort(java.util.Comparator)} in that the results are
* not assured to be stable, but may be a bit faster.
*
*
Unless a subclass specifies otherwise, the results of the method if the list is
* concurrently modified during the sort are unspecified.
*
* @implSpec The default implementation dumps the elements into an array using
* {@link #toArray()}, sorts the array, then replaces all elements using the
* {@link #setElements} function.
*
* @since 8.3.0
*/
default void unstableSort(final KEY_COMPARATOR comparator) {
KEY_TYPE[] elements = TO_KEY_ARRAY();
if (comparator == null) {
ARRAYS.unstableSort(elements);
} else {
ARRAYS.unstableSort(elements, comparator);
}
setElements(elements);
}
#else
#if !KEYS_REFERENCE
#error Assertion error: No KEY_COMPARATOR defined, but not a reference type.
#endif
/** Sorts this list using a sort not assured to be stable.
* This differs from {@link List#sort(java.util.Comparator)} in that the results are
* not assured to be stable, but may be a bit faster.
*
*
Unless a subclass specifies otherwise, the results of the method if the list is
* concurrently modified during the sort are unspecified.
*
* @implSpec The default implementation dumps the elements into an array using
* {@link #toArray()}, sorts the array, then replaces all elements using the
* {@link #setElements} function.
*
* @since 8.3.0
*/
SUPPRESS_WARNINGS_KEY_UNCHECKED
default void unstableSort(final java.util.Comparator comparator) {
KEY_GENERIC_TYPE[] elements = (KEY_GENERIC_TYPE[])toArray();
if (comparator == null) {
ARRAYS.unstableSort(elements);
} else {
ARRAYS.unstableSort(elements, comparator);
}
setElements(elements);
}
#endif
}