BaseSeq.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-8.0.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  */
020 package io.jenetics.util;
021 
022 import java.util.Iterator;
023 import java.util.ListIterator;
024 import java.util.Objects;
025 import java.util.RandomAccess;
026 import java.util.Spliterator;
027 import java.util.function.Consumer;
028 import java.util.stream.Stream;
029 import java.util.stream.StreamSupport;
030 
031 import io.jenetics.internal.collection.BaseSeqIterator;
032 import 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  */
041 public 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 }