public interface ReferenceList<K> extends java.util.List<K>, ReferenceCollection<K>
List
; provides some additional methods that use polymorphism to avoid (un)boxing.
Additionally, this interface strengthens iterator()
, listIterator()
,
listIterator(int)
and subList(int,int)
. The former had been already
strengthened upstream, but unfortunately List
re-specifies it.
This interface specifies reference equality semantics (members will be compared equal with
==
instead of equals
), which may result in breaks in contract
if attempted to be used with non reference-equality semantics based List
s. For example, a
aReferenceList.equals(aObjectList)
may return different a different result then
aObjectList.equals(aReferenceList)
, in violation of equals
's contract
requiring it being symmetric.
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.
List
Modifier and Type | Method and Description |
---|---|
default boolean |
addAll(int index,
ReferenceList<? extends K> l)
Inserts all of the elements in the specified type-specific list into this type-specific list at the specified position (optional operation).
|
default boolean |
addAll(ReferenceList<? extends K> l)
Appends all of the elements in the specified type-specific list to the end of this type-specific list (optional operation).
|
void |
addElements(int index,
K[] a)
Add (hopefully quickly) elements to this type-specific list.
|
void |
addElements(int index,
K[] a,
int offset,
int length)
Add (hopefully quickly) elements to this type-specific list.
|
void |
getElements(int from,
java.lang.Object[] a,
int offset,
int length)
Copies (hopefully quickly) elements of this type-specific list into the given array.
|
ObjectListIterator<K> |
iterator()
Returns a type-specific iterator on the elements of this list.
|
ObjectListIterator<K> |
listIterator()
Returns a type-specific list iterator on the list.
|
ObjectListIterator<K> |
listIterator(int index)
Returns a type-specific list iterator on the list starting at a given index.
|
static <K> ReferenceList<K> |
of()
Returns an immutable empty list.
|
static <K> ReferenceList<K> |
of(K... a)
Returns an immutable list with the elements given.
|
static <K> ReferenceList<K> |
of(K e)
Returns an immutable list with the element given.
|
static <K> ReferenceList<K> |
of(K e0,
K e1)
Returns an immutable list with the elements given.
|
static <K> ReferenceList<K> |
of(K e0,
K e1,
K e2)
Returns an immutable list with the elements given.
|
void |
removeElements(int from,
int to)
Removes (hopefully quickly) elements of this type-specific list.
|
default void |
setElements(int index,
K[] a)
Set (hopefully quickly) elements to match the array given.
|
default void |
setElements(int index,
K[] a,
int offset,
int length)
Set (hopefully quickly) elements to match the array given.
|
default void |
setElements(K[] a)
Set (hopefully quickly) elements to match the array given.
|
void |
size(int size)
Sets the size of this list.
|
default void |
sort(java.util.Comparator<? super K> comparator)
Sorts this list using a sort assured to be stable.
|
default ObjectSpliterator<K> |
spliterator()
Returns a type-specific spliterator on the elements of this list.
|
ReferenceList<K> |
subList(int from,
int to)
Returns a type-specific view of the portion of this list from the index
from , inclusive, to the index to , exclusive. |
default void |
unstableSort(java.util.Comparator<? super K> comparator)
Sorts this list using a sort not assured to be stable.
|
ObjectListIterator<K> iterator()
iterator
in interface java.util.Collection<K>
iterator
in interface java.lang.Iterable<K>
iterator
in interface java.util.List<K>
iterator
in interface ObjectIterable<K>
iterator
in interface ReferenceCollection<K>
Iterable.iterator()
List.iterator()
.
It would not be normally necessary, but Iterable.iterator()
is bizarrily re-specified
in List
.
Also, this is generally the only iterator
method subclasses should override.
default ObjectSpliterator<K> spliterator()
List spliterators must report at least Spliterator.SIZED
and Spliterator.ORDERED
.
See List.spliterator()
for more documentation on the requirements
of the returned spliterator.
spliterator
in interface java.util.Collection<K>
spliterator
in interface java.lang.Iterable<K>
spliterator
in interface java.util.List<K>
spliterator
in interface ObjectIterable<K>
spliterator
in interface ReferenceCollection<K>
Collection.spliterator()
, which was already
strengthened in the corresponding type-specific class,
but was weakened by the fact that this interface extends List
.
Also, this is generally the only spliterator
method subclasses should override.
Spliterator
for documentation on what binding policies mean).
RandomAccess
lists, this will return a spliterator
that calls the type-specific List.get(int)
method on the appropriate indexes.iterator()
.In either case, the spliterator reports Spliterator.SIZED
,
Spliterator.SUBSIZED
, and Spliterator.ORDERED
.
Iterator
is an inherently linear API, the returned
spliterator will yield limited performance gains when run in parallel contexts, as the
returned spliterator's trySplit()
will have linear runtime.
For RandomAccess
lists, the parallel performance should
be reasonable assuming List.get(int)
is truly constant time like RandomAccess
suggests.
ObjectListIterator<K> listIterator()
listIterator
in interface java.util.List<K>
List.listIterator()
ObjectListIterator<K> listIterator(int index)
listIterator
in interface java.util.List<K>
List.listIterator(int)
ReferenceList<K> subList(int from, int to)
from
, inclusive, to the index to
, exclusive.subList
in interface java.util.List<K>
List.subList(int,int)
List.subList(int,int)
.void size(int size)
If the specified size is smaller than the current size, the last elements are
discarded. Otherwise, they are filled with 0/null
/false
.
size
- the new size.void getElements(int from, java.lang.Object[] a, int offset, int length)
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.void removeElements(int from, int to)
from
- the start index (inclusive).to
- the end index (exclusive).void addElements(int index, K[] a)
index
- the index at which to add elements.a
- the array containing the elements.void addElements(int index, K[] a, int offset, int length)
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.default void setElements(K[] a)
a
- the array containing the elements.default void setElements(int index, K[] a)
index
- the index at which to start setting elements.a
- the array containing the elements.default void setElements(int index, K[] a, int offset, int length)
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.index
- the index at which to start setting elements.a
- the array containing the elementsoffset
- the offset of the first element to add.length
- the number of elements to add.default boolean addAll(int index, ReferenceList<? extends K> l)
List.addAll(int,Collection)
getElements(int, java.lang.Object[], int, int)
/addElements(int, K[])
.default boolean addAll(ReferenceList<? extends K> l)
List.addAll(Collection)
List.size()
as first argument.static <K> ReferenceList<K> of()
static <K> ReferenceList<K> of(K e)
e
- the element that the returned list will contain.e
.static <K> ReferenceList<K> of(K e0, K e1)
e0
- the first element.e1
- the second element.e0
and e1
.static <K> ReferenceList<K> of(K e0, K e1, K e2)
e0
- the first element.e1
- the second element.e2
- the third element.e0
, e1
, and e2
.@SafeVarargs static <K> ReferenceList<K> of(K... a)
Note that this method does not perform a defensive copy.
a
- a list of elements that will be used to initialize the immutable list.a
.default void sort(java.util.Comparator<? super K> comparator)
Pass null
to sort using natural ordering.
Unless a subclass specifies otherwise, the results of the method if the list is concurrently modified during the sort are unspecified.
sort
in interface java.util.List<K>
List.toArray()
, sorts the array, then replaces all elements using the
setElements(K[])
function.default void unstableSort(java.util.Comparator<? super K> comparator)
List.sort(java.util.Comparator)
in that the results are
not assured to be stable, but may be a bit faster.
Pass null
to sort using natural ordering.
Unless a subclass specifies otherwise, the results of the method if the list is concurrently modified during the sort are unspecified.
List.toArray()
, sorts the array, then replaces all elements using the
setElements(K[])
function.