MSeq.java
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 &mdash; <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 }