archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 07:14:30 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8266571: Sequenced Collections

Browse source 
Reviewed-by: alanb
This commit is contained in:
Stuart Marks 2023-04-25 15:19:08 +00:00
parent bad6aa68e4
commit 17ce0976e4
42 changed files with 7060 additions and 150 deletions
Download patch file Download diff file Expand all files Collapse all files

203
src/java.base/share/classes/java/util/SequencedCollection.java Normal file
View file

@ -0,0 +1,203 @@
/*
* Copyright (c) 2021, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.util;
/**
* 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 <a id="encounter">
* <i>encounter order</i></a>, 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.
* <p>
* (Note that this definition does not imply anything about physical positioning
* of elements, such as their locations in a computer's memory.)
* <p>
* Several methods inherited from the {@link Collection} interface are required to operate
* on elements according to this collection's encounter order. For instance, the
* {@link Collection#iterator 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:
* {@link Iterable#forEach forEach}, {@link Collection#parallelStream parallelStream},
* {@link Collection#spliterator spliterator}, {@link Collection#stream stream},
* and all overloads of the {@link Collection#toArray toArray} method.
* <p>
* This interface provides methods to add, retrieve, and remove elements at either end
* of the collection.
* <p>
* This interface also defines the {@link #reversed reversed} method, which provides
* a reverse-ordered <a href="Collection.html#view">view</a> 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 {@link #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 {@code 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.
* <p>
* This class is a member of the
* <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
* Java Collections Framework</a>.
*
* @apiNote
* This interface does not impose any requirements on the {@code equals} and {@code hashCode}
* methods, because requirements imposed by sub-interfaces {@link List} and {@link SequencedSet}
* (which inherits requirements from {@link Set}) would be in conflict. See the specifications for
* {@link Collection#equals Collection.equals} and {@link Collection#hashCode Collection.hashCode}
* for further information.
*
* @param <E> the type of elements in this collection
* @since 21
*/
public interface SequencedCollection<E> extends Collection<E> {
/**
* Returns a reverse-ordered <a href="Collection.html#view">view</a> 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 a reverse-ordered view of this collection
*/
SequencedCollection<E> reversed();
/**
* 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.
*
* @implSpec
* The implementation in this interface always throws {@code UnsupportedOperationException}.
*
* @param e the element to be added
* @throws NullPointerException if the specified element is null and this
* collection does not permit null elements
* @throws UnsupportedOperationException if this collection implementation
* does not support this operation
*/
default void addFirst(E e) {
throw new UnsupportedOperationException();
}
/**
* 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.
*
* @implSpec
* The implementation in this interface always throws {@code UnsupportedOperationException}.
*
* @param e the element to be added.
* @throws NullPointerException if the specified element is null and this
* collection does not permit null elements
* @throws UnsupportedOperationException if this collection implementation
* does not support this operation
*/
default void addLast(E e) {
throw new UnsupportedOperationException();
}
/**
* Gets the first element of this collection.
*
* @implSpec
* The implementation in this interface obtains an iterator of this collection, and
* then it obtains an element by calling the iterator's {@code next} method. Any
* {@code NoSuchElementException} thrown is propagated. Otherwise, it returns
* the element.
*
* @return the retrieved element
* @throws NoSuchElementException if this collection is empty
*/
default E getFirst() {
return this.iterator().next();
}
/**
* Gets the last element of this collection.
*
* @implSpec
* The implementation in this interface obtains an iterator of the reversed view
* of this collection, and then it obtains an element by calling the iterator's
* {@code next} method. Any {@code NoSuchElementException} thrown is propagated.
* Otherwise, it returns the element.
*
* @return the retrieved element
* @throws NoSuchElementException if this collection is empty
*/
default E getLast() {
return this.reversed().iterator().next();
}
/**
* Removes and returns the first element of this collection (optional operation).
*
* @implSpec
* The implementation in this interface obtains an iterator of this collection, and then
* it obtains an element by calling the iterator's {@code next} method. Any
* {@code NoSuchElementException} thrown is propagated. It then calls the iterator's
* {@code remove} method. Any {@code UnsupportedOperationException} thrown is propagated.
* Then, it returns the element.
*
* @return the removed element
* @throws NoSuchElementException if this collection is empty
* @throws UnsupportedOperationException if this collection implementation
* does not support this operation
*/
default E removeFirst() {
var it = this.iterator();
E e = it.next();
it.remove();
return e;
}
/**
* Removes and returns the last element of this collection (optional operation).
*
* @implSpec
* The implementation in this interface obtains an iterator of the reversed view of this
* collection, and then it obtains an element by calling the iterator's {@code next} method.
* Any {@code NoSuchElementException} thrown is propagated. It then calls the iterator's
* {@code remove} method. Any {@code UnsupportedOperationException} thrown is propagated.
* Then, it returns the element.
*
* @return the removed element
* @throws NoSuchElementException if this collection is empty
* @throws UnsupportedOperationException if this collection implementation
* does not support this operation
*/
default E removeLast() {
var it = this.reversed().iterator();
E e = it.next();
it.remove();
return e;
}
}