org.jhotdraw8.icollection.immutable.ImmutableSequencedCollection Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.jhotdraw8.icollection Show documentation
JHotDraw8 Immutable Collections
The newest version!
/*
 * @(#)ImmutableSequencedSet.java
 * Copyright © 2023 The authors and contributors of JHotDraw. MIT License.
 */

package org.jhotdraw8.icollection.immutable;

import org.jspecify.annotations.Nullable;
import org.jhotdraw8.icollection.readonly.ReadOnlySequencedCollection;

import java.util.NoSuchElementException;

/**
 * An interface to an immutable collection with a well-defined iteration order;
 * the implementation guarantees that the state of the collection does not
 * change.
 * 
 * An interface to an immutable sequenced collection provides methods for creating a new
 * immutable sequenced collection with added or removed elements, without
 * changing the original immutable sequenced collection.
 *
 * @param  the element type
 */
public interface ImmutableSequencedCollection extends ImmutableCollection, ReadOnlySequencedCollection {
    @Override
    ImmutableSequencedCollection add(E element);

    @Override
    ImmutableSequencedCollection addAll(Iterable c);

    /**
     * Returns a copy of this collection that contains all elements
     * of this collection and also the specified element as the first
     * element in the iteration order.
     * 

     * A collection may prevent that the same element can be
     * added more than once.
     * 

     * If the iteration order is based on an ordering relation of
     * the elements, then the element is only the first in a sequence of elements
     * with the same ordering relation; which is not necessarily the first in
     * the total iteration order.
     *
     * @param element an element
     * @return this collection instance if it already contains the element
     * as the first in the iteration order, or
     * a different collection instance with the element added as the first
     * in the iteration order
     */
    ImmutableSequencedCollection addFirst(final @Nullable E element);

    /**
     * Returns a copy of this collection that contains all elements
     * of this collection and also the specified element as the last
     * element in the iteration order.
     * 

     * A collection may prevent that the same element can be
     * added more than once.
     * 
     * If the iteration order is based on an ordering relation of
     * the elements, then the element is only the last in a sequence of elements
     * with the same ordering relation; which is not necessarily the last in
     * the total iteration order.
     *
     * @param element an element
     * @return this collection instance if it already contains the element
     * as the last in the iteration order, or
     * a different collection instance with the element added as the last
     * in the iteration order
     */
    ImmutableSequencedCollection addLast(final @Nullable E element);

    @Override
     ImmutableSequencedCollection empty();

    @Override
    ImmutableSequencedCollection remove(E element);

    @Override
    ImmutableSequencedCollection removeAll(Iterable c);

    /**
     * Returns a copy of this set that contains all elements
     * of this set except the first.
     *
     * @return a new set instance with the first element removed
     * @throws NoSuchElementException if this set is empty
     */
    default ImmutableSequencedCollection removeFirst() {
        return remove(getFirst());
    }

    /**
     * Returns a copy of this set that contains all elements
     * of this set except the last.
     *
     * @return a new set instance with the last element removed
     * @throws NoSuchElementException if this set is empty
     */
    default ImmutableSequencedCollection removeLast() {
        return remove(getLast());
    }

    @Override
    ImmutableSequencedCollection retainAll(Iterable c);

}