http://fastutil.di.unimi.it/: fastutil extends the Java Collections Framework by providing type-specific maps, sets, lists and priority queues with a small memory footprint and fast access and insertion; provides also big (64-bit) arrays, sets and lists, and fast, practical I/O classes for binary and text files.
  • Sebastiano Vigna 
/*
	* Copyright (C) 2002-2019 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 it.unimi.dsi.fastutil.longs;
import java.util.List;

A type-specific List; provides some additional methods that use polymorphism to avoid (un)boxing. 
 Note that this type-specific interface extends Comparable: it is expected that implementing classes perform a lexicographical comparison using the standard operator "less then" for primitive types, and the usual compareTo() method for objects. 
 Additionally, this interface strengthens listIterator(), listIterator(int) and 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 Also:
/**
 * A type-specific {@link List}; provides some additional methods that use
 * polymorphism to avoid (un)boxing.
 *
 * <p>
 * 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.
 *
 * <p>
 * Additionally, this interface strengthens {@link #listIterator()},
 * {@link #listIterator(int)} and {@link #subList(int,int)}.
 *
 * <p>
 * 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 LongList extends List<Long>, Comparable<List<? extends Long>>, LongCollection {
	
Returns a type-specific iterator on the elements of this list.

 Note that this specification strengthens the one given in List.iterator(). It would not be normally necessary, but Iterable.iterator() is bizarrily re-specified in List. 
Returns:an iterator on the elements of this list.
/**
	 * Returns a type-specific iterator on the elements of this list.
	 *
	 * <p>
	 * 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
	LongListIterator iterator();
	
Returns a type-specific list iterator on the list.

See Also:
  • listIterator.listIterator()
/**
	 * Returns a type-specific list iterator on the list.
	 *
	 * @see List#listIterator()
	 */
	@Override
	LongListIterator listIterator();
	
Returns a type-specific list iterator on the list starting at a given index.

See Also:
  • listIterator.listIterator(int)
/**
	 * Returns a type-specific list iterator on the list starting at a given index.
	 *
	 * @see List#listIterator(int)
	 */
	@Override
	LongListIterator listIterator(int index);
	
Returns a type-specific view of the portion of this list from the index from, inclusive, to the index to, exclusive. 
 Note that this specification strengthens the one given in List.subList(int, int). 
See Also:
/**
	 * Returns a type-specific view of the portion of this list from the index
	 * {@code from}, inclusive, to the index {@code to}, exclusive.
	 *
	 * <p>
	 * Note that this specification strengthens the one given in
	 * {@link List#subList(int,int)}.
	 *
	 * @see List#subList(int,int)
	 */
	@Override
	LongList 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/null/false. 
Params:
  • size – 
           the new size.
/**
	 * Sets the size of this list.
	 *
	 * <p>
	 * 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.

Params:
  • from – 
           the start index (inclusive).
  • a – 
           the destination array.
  • offset – 
           the offset into the destination array where to store the first
           element copied.
  • length – 
           the number of elements to be copied.
/**
	 * 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, long a[], int offset, int length);
	
Removes (hopefully quickly) elements of this type-specific list.

Params:
  • from – 
           the start index (inclusive).
  • to – 
           the end index (exclusive).
/**
	 * 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.

Params:
  • index – 
           the index at which to add elements.
  • a – 
           the array containing the elements.
/**
	 * 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, long a[]);
	
Add (hopefully quickly) elements to this type-specific list.

Params:
  • index – 
           the index at which to add elements.
  • a – 
           the array containing the elements.
  • offset – 
           the offset of the first element to add.
  • length – 
           the number of elements to add.
/**
	 * 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, long a[], int offset, int length);
	
Set (hopefully quickly) elements to match the array given.

Params:
  • a – 
           the array containing the elements.
Since:8.3.0
/**
	 * Set (hopefully quickly) elements to match the array given.
	 * 
	 * @param a
	 *            the array containing the elements.
	 * @since 8.3.0
	 */
	default void setElements(long a[]) {
		setElements(0, a);
	}
	
Set (hopefully quickly) elements to match the array given.

Params:
  • index – 
           the index at which to start setting elements.
  • a – 
           the array containing the elements.
Since:8.3.0
/**
	 * 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, long 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.

Params:
  • index – 
           the index at which to start setting elements.
  • a – 
           the array containing the elements
  • offset – 
           the offset of the first element to add.
  • length – 
           the number of elements to add.
Since:8.3.0
/**
	 * Set (hopefully quickly) elements to match the array given.
	 *
	 * Sets each in this list to the corresponding elements in the array, as if by
	 * 
	 * <pre>
	 * <code>
	 * ListIterator iter = listIterator(index);
	 * int i = 0;
	 * while (i < length) {
	 *   iter.next();
	 *   iter.set(a[offset + i++]);
	 * }
	 * </code>
	 * </pre>
	 * 
	 * 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, long 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()) + ")");
		LongArrays.ensureOffsetLength(a, offset, length);
		if (index + length > size())
			throw new IndexOutOfBoundsException(
					"End index (" + (index + length) + ") is greater than list size (" + size() + ")");
		LongListIterator iter = listIterator(index);
		int i = 0;
		while (i < length) {
			iter.nextLong();
			iter.set(a[offset + i++]);
		}
	}
	
Appends the specified element to the end of this list (optional operation).

See Also:
  • add.add(Object)
/**
	 * Appends the specified element to the end of this list (optional operation).
	 * 
	 * @see List#add(Object)
	 */
	@Override
	boolean add(long key);
	
Inserts the specified element at the specified position in this list
(optional operation).

See Also:
  • add.add(int, Object)
/**
	 * Inserts the specified element at the specified position in this list
	 * (optional operation).
	 * 
	 * @see List#add(int,Object)
	 */
	void add(int index, long key);
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default void add(int index, Long key) {
		add(index, (key).longValue());
	}
	
Inserts all of the elements in the specified type-specific collection into
this type-specific list at the specified position (optional operation).

See Also:
  • addAll.addAll(int, Collection)
/**
	 * 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, LongCollection c);
	
Inserts all of the elements in the specified type-specific list into this
type-specific list at the specified position (optional operation).

See Also:
  • add.add(int, Object)
/**
	 * 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, LongList c);
	
Appends all of the elements in the specified type-specific list to the end of
this type-specific list (optional operation).

See Also:
  • add.add(int, Object)
/**
	 * 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(LongList c);
	
Replaces the element at the specified position in this list with the
specified element (optional operation).

See Also:
  • set.set(int, Object)
/**
	 * Replaces the element at the specified position in this list with the
	 * specified element (optional operation).
	 * 
	 * @see List#set(int,Object)
	 */
	long set(int index, long k);
	
Returns the element at the specified position in this list.

See Also:
  • get.get(int)
/**
	 * Returns the element at the specified position in this list.
	 * 
	 * @see List#get(int)
	 */
	long getLong(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 Also:
  • indexOf.indexOf(Object)
/**
	 * 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(long 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 Also:
  • lastIndexOf.lastIndexOf(Object)
/**
	 * 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(long k);
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default boolean contains(final Object key) {
		return LongCollection.super.contains(key);
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default Long get(int index) {
		return Long.valueOf(getLong(index));
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default int indexOf(Object o) {
		return indexOf(((Long) (o)).longValue());
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default int lastIndexOf(Object o) {
		return lastIndexOf(((Long) (o)).longValue());
	}
	
{@inheritDoc}


This method specification is a workaround for
bug
8177440.

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * <p>
	 * This method specification is a workaround for
	 * <a href="http://bugs.java.com/bugdatabase/view_bug.do?bug_id=JDK-8177440">bug
	 * 8177440</a>.
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default boolean add(Long k) {
		return add((k).longValue());
	}
	
Removes the element at the specified position in this list (optional
operation).

See Also:
  • remove.remove(int)
/**
	 * Removes the element at the specified position in this list (optional
	 * operation).
	 * 
	 * @see List#remove(int)
	 */
	long removeLong(int index);
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default boolean remove(final Object key) {
		return LongCollection.super.remove(key);
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default Long remove(int index) {
		return Long.valueOf(removeLong(index));
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default Long set(int index, Long k) {
		return Long.valueOf(set(index, (k).longValue()));
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default void sort(final java.util.Comparator<? super Long> comparator) {
		sort(LongComparators.asLongComparator(comparator));
	}
	
Sort a list using a type-specific comparator.

 Pass null to sort using natural ordering. 
See Also:
Implementation Requirements:The default implementation dumps the elements into an array using List<Long>.toArray(), sorts the array, then replaces all elements using the setElements function.
Implementation Note:It is possible for this method to call unstableSort if it can determine that the results of a stable and unstable sort are completely equivalent. This means if you override unstableSort, it should not call this method
          unless you override this method as well.
Since:8.3.0
/**
	 * Sort a list using a type-specific comparator.
	 *
	 * <p>
	 * 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.
	 *
	 * @implNote 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 <em>not</em> call this method
	 *           unless you override this method as well.
	 *
	 * @since 8.3.0
	 */
	default void sort(final LongComparator comparator) {
		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 {
			long[] elements = toLongArray();
			LongArrays.stableSort(elements, comparator);
			setElements(elements);
		}
	}
	
Sorts this list using a sort not assured to be stable.

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * 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<? super Long> comparator) {
		unstableSort(LongComparators.asLongComparator(comparator));
	}
	
Sorts this list using a sort not assured to be stable.

 Pass null to sort using natural ordering. 
 This differs from List.sort(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.

Implementation Requirements:The default implementation dumps the elements into an array using List<Long>.toArray(), sorts the array, then replaces all elements using the setElements function.
Since:8.3.0
/**
	 * Sorts this list using a sort not assured to be stable.
	 *
	 * <p>
	 * Pass {@code null} to sort using natural ordering.
	 *
	 * <p>
	 * 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.
	 *
	 * <p>
	 * 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 LongComparator comparator) {
		long[] elements = toLongArray();
		if (comparator == null) {
			LongArrays.unstableSort(elements);
		} else {
			LongArrays.unstableSort(elements, comparator);
		}
		setElements(elements);
	}
}