001 /*
002 * Java Genetic Algorithm Library (jenetics-4.2.0).
003 * Copyright (c) 2007-2018 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 static java.util.Objects.requireNonNull;
023
024 import java.util.ArrayList;
025 import java.util.List;
026 import java.util.function.Function;
027 import java.util.function.Supplier;
028 import java.util.stream.Collector;
029
030 import io.jenetics.internal.collection.Empty;
031 import io.jenetics.internal.collection.Empty.EmptyISeq;
032 import io.jenetics.internal.util.require;
033
034 /**
035 * Immutable, ordered, fixed sized sequence.
036 *
037 * @see MSeq
038 *
039 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
040 * @since 1.0
041 * @version 4.2
042 */
043 public interface ISeq<T>
044 extends
045 Seq<T>,
046 Copyable<MSeq<T>>
047 {
048
049 @Override
050 public ISeq<T> subSeq(final int start, final int end);
051
052 @Override
053 public ISeq<T> subSeq(final int start);
054
055 @Override
056 public <B> ISeq<B> map(final Function<? super T, ? extends B> mapper);
057
058 @SuppressWarnings("unchecked")
059 @Override
060 public default ISeq<T> append(final T... values) {
061 return append(ISeq.of(values));
062 }
063
064 @Override
065 public ISeq<T> append(final Iterable<? extends T> values);
066
067 @SuppressWarnings("unchecked")
068 @Override
069 public default ISeq<T> prepend(final T... values) {
070 return prepend(ISeq.of(values));
071 }
072
073 @Override
074 public ISeq<T> prepend(final Iterable<? extends T> values);
075
076 /**
077 * Return a shallow copy of this sequence. The sequence elements are not
078 * cloned.
079 *
080 * @return a shallow copy of this sequence.
081 */
082 @Override
083 public MSeq<T> copy();
084
085
086 /* *************************************************************************
087 * Some static factory methods.
088 * ************************************************************************/
089
090 /**
091 * Single instance of an empty {@code ISeq}.
092 *
093 * @since 3.3
094 */
095 public static final ISeq<?> EMPTY = EmptyISeq.INSTANCE;
096
097 /**
098 * Return an empty {@code ISeq}.
099 *
100 * @since 3.3
101 *
102 * @param <T> the element type of the returned {@code ISeq}.
103 * @return an empty {@code ISeq}.
104 */
105 public static <T> ISeq<T> empty() {
106 return Empty.iseq();
107 }
108
109 /**
110 * Returns a {@code Collector} that accumulates the input elements into a
111 * new {@code ISeq}.
112 *
113 * @param <T> the type of the input elements
114 * @return a {@code Collector} which collects all the input elements into an
115 * {@code ISeq}, in encounter order
116 */
117 public static <T> Collector<T, ?, ISeq<T>> toISeq() {
118 return Collector.of(
119 (Supplier<List<T>>)ArrayList::new,
120 List::add,
121 (left, right) -> { left.addAll(right); return left; },
122 ISeq::of
123 );
124 }
125
126 /**
127 * Create a new {@code ISeq} from the given values.
128 *
129 * @param <T> the element type
130 * @param values the array values.
131 * @return a new {@code ISeq} with the given values.
132 * @throws NullPointerException if the {@code values} array is {@code null}.
133 */
134 @SafeVarargs
135 public static <T> ISeq<T> of(final T... values) {
136 return values.length == 0
137 ? empty()
138 : MSeq.of(values).toISeq();
139 }
140
141 /**
142 * Create a new {@code ISeq} from the given values.
143 *
144 * @param <T> the element type
145 * @param values the array values.
146 * @return a new {@code ISeq} with the given values.
147 * @throws NullPointerException if the {@code values} array is {@code null}.
148 */
149 @SuppressWarnings("unchecked")
150 public static <T> ISeq<T> of(final Iterable<? extends T> values) {
151 requireNonNull(values);
152
153 return values instanceof ISeq
154 ? (ISeq<T>)values
155 : values instanceof MSeq
156 ? ((MSeq<T>)values).toISeq()
157 : MSeq.<T>of(values).toISeq();
158 }
159
160 // /**
161 // * Create a new {@code ISeq} instance from the remaining elements of the
162 // * given iterator.
163 // *
164 // * @since 3.3
165 // *
166 // * @param <T> the element type.
167 // * @return a new {@code ISeq} with the given remaining values.
168 // * @throws NullPointerException if the {@code values} object is
169 // * {@code null}.
170 // */
171 // public static <T> ISeq<T> of(final Iterator<? extends T> values) {
172 // final MSeq<T> seq = MSeq.of(values);
173 // return seq.isEmpty() ? empty() : seq.toISeq();
174 // }
175
176 /**
177 * Creates a new sequence, which is filled with objects created be the given
178 * {@code supplier}.
179 *
180 * @since 3.2
181 *
182 * @param <T> the element type of the sequence
183 * @param supplier the {@code Supplier} which creates the elements, the
184 * returned sequence is filled with
185 * @param length the length of the returned sequence
186 * @return a new sequence filled with elements given by the {@code supplier}
187 * @throws NegativeArraySizeException if the given {@code length} is
188 * negative
189 * @throws NullPointerException if the given {@code supplier} is
190 * {@code null}
191 */
192 public static <T> ISeq<T> of(
193 final Supplier<? extends T> supplier,
194 final int length
195 ) {
196 requireNonNull(supplier);
197 require.nonNegative(length);
198
199 return length == 0
200 ? empty()
201 : MSeq.<T>ofLength(length).fill(supplier).toISeq();
202 }
203
204 /**
205 * Allows a safe (without compile warning) upcast from {@code B} to
206 * {@code A}. Since {@code ISeq} instances are immutable, an <i>upcast</i>
207 * will be always safe.
208 *
209 * <pre>{@code
210 * // The sequence which we want to case.
211 * final ISeq<? extends Number> ints = ISeq.of(1, 2, 3, 4, 5);
212 *
213 * // This casts are possible without warning.
214 * final ISeq<Object> objects = ISeq.upcast(ints);
215 * final ISeq<Number> numbers = ISeq.upcast(ints);
216 *
217 * // This cast will, of course, still fail.
218 * final ISeq<String> strings = ISeq.upcast(ints);
219 * final ISeq<Integer> integers = ISeq.upcast(ints);
220 * }</pre>
221 *
222 * @since 3.6
223 *
224 * @param seq the sequence to cast safely
225 * @param <A> the <i>super</i>-object type
226 * @param <B> the <i>sub</i>-object type
227 * @return the casted instance of the given {@code seq}
228 */
229 @SuppressWarnings("unchecked")
230 public static <A, B extends A> ISeq<A> upcast(final ISeq<B> seq) {
231 return (ISeq<A>)seq;
232 }
233
234 }
|