Added in API level 35

SequencedCollection

interface SequencedCollection<E : Any!> : MutableCollection<E>
java.util.SequencedCollection

A collection that has a well-defined encounter order, that supports operations at both ends, and that is reversible. The elements of a sequenced collection have an encounter order, where conceptually the elements have a linear arrangement from the first element to the last element. Given any two elements, one element is either before (closer to the first element) or after (closer to the last element) the other element.

(Note that this definition does not imply anything about physical positioning of elements, such as their locations in a computer's memory.)

Several methods inherited from the Collection interface are required to operate on elements according to this collection's encounter order. For instance, the iterator method provides elements starting from the first element, proceeding through successive elements, until the last element. Other methods that are required to operate on elements in encounter order include the following: forEach, parallelStream, spliterator, stream, and all overloads of the java.util.Collection#toArray method.

This interface provides methods to add, retrieve, and remove elements at either end of the collection.

This interface also defines the reversed method, which provides a reverse-ordered view of this collection. In the reverse-ordered view, the concepts of first and last are inverted, as are the concepts of successor and predecessor. The first element of this collection is the last element of the reverse-ordered view, and vice-versa. The successor of some element in this collection is its predecessor in the reversed view, and vice-versa. All methods that respect the encounter order of the collection operate as if the encounter order is inverted. For instance, the iterator method of the reversed view reports the elements in order from the last element of this collection to the first. The availability of the reversed method, and its impact on the ordering semantics of all applicable methods, allow convenient iteration, searching, copying, and streaming of the elements of this collection in either forward order or reverse order.

This class is a member of the Java Collections Framework.

Summary

Public methods
open Unit
addFirst(e: E)

Adds an element as the first element of this collection (optional operation).

open Unit
addLast(e: E)

Adds an element as the last element of this collection (optional operation).

open E

Gets the first element of this collection.

open E

Gets the last element of this collection.

open E

Removes and returns the first element of this collection (optional operation).

open E

Removes and returns the last element of this collection (optional operation).

abstract SequencedCollection<E>!

Returns a reverse-ordered view of this collection.

Public methods

addFirst

Added in API level 35
open fun addFirst(e: E): Unit

Adds an element as the first element of this collection (optional operation). After this operation completes normally, the given element will be a member of this collection, and it will be the first element in encounter order.

Parameters
e E: the element to be added
Exceptions
java.lang.NullPointerException if the specified element is null and this collection does not permit null elements
java.lang.UnsupportedOperationException if this collection implementation does not support this operation

addLast

Added in API level 35
open fun addLast(e: E): Unit

Adds an element as the last element of this collection (optional operation). After this operation completes normally, the given element will be a member of this collection, and it will be the last element in encounter order.

Parameters
e E: the element to be added.
Exceptions
java.lang.NullPointerException if the specified element is null and this collection does not permit null elements
java.lang.UnsupportedOperationException if this collection implementation does not support this operation

getFirst

Added in API level 35
open fun getFirst(): E

Gets the first element of this collection.

Return
E the retrieved element
Exceptions
java.util.NoSuchElementException if this collection is empty

getLast

Added in API level 35
open fun getLast(): E

Gets the last element of this collection.

Return
E the retrieved element
Exceptions
java.util.NoSuchElementException if this collection is empty

removeFirst

Added in API level 35
open fun removeFirst(): E

Removes and returns the first element of this collection (optional operation).

Return
E the removed element
Exceptions
java.util.NoSuchElementException if this collection is empty
java.lang.UnsupportedOperationException if this collection implementation does not support this operation

removeLast

Added in API level 35
open fun removeLast(): E

Removes and returns the last element of this collection (optional operation).

Return
E the removed element
Exceptions
java.util.NoSuchElementException if this collection is empty
java.lang.UnsupportedOperationException if this collection implementation does not support this operation

reversed

Added in API level 35
abstract fun reversed(): SequencedCollection<E>!

Returns a reverse-ordered view of this collection. The encounter order of elements in the returned view is the inverse of the encounter order of elements in this collection. The reverse ordering affects all order-sensitive operations, including those on the view collections of the returned view. If the collection implementation permits modifications to this view, the modifications "write through" to the underlying collection. Changes to the underlying collection might or might not be visible in this reversed view, depending upon the implementation.

Return
SequencedCollection<E>! a reverse-ordered view of this collection