001 /*
002 * Java Genetic Algorithm Library (jenetics-1.6.0).
003 * Copyright (c) 2007-2014 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@gmx.at)
019 */
020 package org.jenetics.util;
021
022 import java.util.Iterator;
023 import java.util.ListIterator;
024
025 /**
026 * Mutable, ordered, fixed sized sequence.
027 *
028 * @see ISeq
029 *
030 * @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
031 * @since 1.0
032 * @version 1.2 — <em>$Date: 2014-02-15 $</em>
033 */
034 public interface MSeq<T> extends Seq<T>, Copyable<MSeq<T>> {
035
036 /**
037 * Set the {@code value} at the given {@code index}.
038 *
039 * @param index the index of the new value.
040 * @param value the new value.
041 * @throws IndexOutOfBoundsException if the index is out of range
042 * {@code (index < 0 || index >= size())}.
043 */
044 public void set(final int index, final T value);
045
046 /**
047 * Set all sequence elements to the given {@code value}.
048 *
049 * @param value {@code value} to fill this sequence with.
050 * @return {@code this} array.
051 */
052 public MSeq<T> setAll(final T value);
053
054 /**
055 * Fills the sequence with values of the given iterator.
056 *
057 * @param it the iterator of the values to fill this sequence.
058 * @return {@code this} sequence.
059 */
060 public MSeq<T> setAll(final Iterator<? extends T> it);
061
062 /**
063 * Fills the sequence with values of the given iterable.
064 *
065 * @param values the values to fill this sequence.
066 * @return {@code this} sequence.
067 */
068 public MSeq<T> setAll(final Iterable<? extends T> values);
069
070 /**
071 * Fill the sequence with the given values.
072 *
073 * @param values the first initial values of this sequence
074 * @return {@code this} sequence.
075 */
076 public MSeq<T> setAll(final T[] values);
077
078 /**
079 * Fill the sequence with values generated by the given factory.
080 *
081 * @param factory the value factory.
082 * @return {@code this} sequence.
083 * @throws NullPointerException if the given {@code factory} is {@code null}.
084 */
085 public MSeq<T> fill(final Factory<? extends T> factory);
086
087 /**
088 * Swap the elements at the two positions.
089 *
090 * @param i the index of the first element.
091 * @param j the index of the second element.
092 * @throws IndexOutOfBoundsException if {@code i < 0 || j >= length()}.
093 */
094 public void swap(final int i, final int j);
095
096 /**
097 * Swap a given range with a range of the same size with another array.
098 *
099 * <pre>
100 * start end
101 * | |
102 * this: +---+---+---+---+---+---+---+---+---+---+---+---+
103 * +---------------+
104 * +---------------+
105 * other: +---+---+---+---+---+---+---+---+---+---+---+---+
106 * |
107 * otherStart
108 * </pre>
109 *
110 * @param start the start index of {@code this} range, inclusively.
111 * @param end the end index of {@code this} range, exclusively.
112 * @param other the other array to swap the elements with.
113 * @param otherStart the start index of the {@code other} array.
114 * @throws IndexOutOfBoundsException if {@code start > end} or
115 * if {@code start < 0 || end >= this.length() || otherStart < 0 ||
116 * otherStart + (end - start) >= other.length()}
117 */
118 public void swap(
119 final int start, final int end,
120 final MSeq<T> other, final int otherStart
121 );
122
123 /**
124 * Returns a list iterator over the elements in this sequence (in proper
125 * sequence).
126 *
127 * @return a list iterator over the elements in this list (in proper
128 * sequence)
129 */
130 public ListIterator<T> listIterator();
131
132 @Override
133 public MSeq<T> subSeq(final int start, final int end);
134
135 @Override
136 public MSeq<T> subSeq(final int start);
137
138 @Override
139 public <B> MSeq<B> map(final Function<? super T, ? extends B> mapper);
140
141 /**
142 * Return a read-only projection of this sequence. Changes to the original
143 * sequence will not influence the returned {@code ISeq}.
144 *
145 * @return a read-only projection of this sequence
146 */
147 public ISeq<T> toISeq();
148
149
150 }
|