001/*
002 * Java Genetic Algorithm Library (jenetics-8.1.0).
003 * Copyright (c) 2007-2024 Franz Wilhelmstötter
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 * Author:
018 *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
019 */
020package io.jenetics.util;
021
022import java.util.Iterator;
023import java.util.ListIterator;
024import java.util.Objects;
025import java.util.RandomAccess;
026import java.util.Spliterator;
027import java.util.function.Consumer;
028import java.util.stream.Stream;
029import java.util.stream.StreamSupport;
030
031import io.jenetics.internal.collection.BaseSeqIterator;
032import io.jenetics.internal.collection.BaseSeqSpliterator;
033
034/**
035 * General base interface for an ordered, fixed sized, object sequence.
036 *
037 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
038 * @since 5.2
039 * @version 5.2
040 */
041public interface BaseSeq<T> extends Iterable<T>, RandomAccess {
042
043        /**
044         * Return the value at the given {@code index}.
045         *
046         * @param index index of the element to return.
047         * @return the value at the given {@code index}.
048         * @throws IndexOutOfBoundsException if the index is out of range
049         *         (index &lt; 0 || index &gt;= size()).
050         */
051        T get(final int index);
052
053        /**
054         * Return the length of this sequence. Once the sequence is created, the
055         * length can't be changed.
056         *
057         * @return the length of this sequence.
058         */
059        int length();
060
061        /**
062         * Returns {@code true} if this sequence contains no elements.
063         *
064         * @since 6.0
065         *
066         * @return {@code true} if this sequence contains no elements
067         */
068        default boolean isEmpty() {
069                return length() == 0;
070        }
071
072        /**
073         * Returns {@code true} if this sequence contains at least one element.
074         *
075         * @since 6.0
076         *
077         * @return {@code true} if this sequence contains at least one element
078         */
079        default boolean nonEmpty() {
080                return !isEmpty();
081        }
082
083        @Override
084        default void forEach(final Consumer<? super T> action) {
085                Objects.requireNonNull(action);
086                for (int i = 0, n = length(); i < n; ++i) {
087                        action.accept(get(i));
088                }
089        }
090
091        @Override
092        default Iterator<T> iterator() {
093                return listIterator();
094        }
095
096        /**
097         * Returns a list iterator over the elements in this sequence (in proper
098         * order).
099         *
100         * @return a list iterator over the elements in this sequence (in proper
101         *         order)
102         */
103        default ListIterator<T> listIterator() {
104                return new BaseSeqIterator<>(this);
105        }
106
107        /**
108         * Returns a sequential Stream with this sequence as its source.
109         *
110         * @return a sequential Stream over the elements in this sequence
111         */
112        default Stream<T> stream() {
113                return StreamSupport.stream(spliterator(), false);
114        }
115
116        @Override
117        default Spliterator<T> spliterator() {
118                return new BaseSeqSpliterator<>(this);
119        }
120
121}