001 /*
002 * Java Genetic Algorithm Library (jenetics-4.3.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;
021
022 import java.util.stream.IntStream;
023 import java.util.stream.Stream;
024
025 import io.jenetics.util.Factory;
026 import io.jenetics.util.ISeq;
027 import io.jenetics.util.Verifiable;
028
029 /**
030 * A chromosome consists of one or more genes. It also provides a factory
031 * method for creating new, random chromosome instances of the same type and the
032 * same constraint.
033 *
034 * @implSpec
035 * Implementations of the {@code Chromosome} interface must be <em>immutable</em>
036 * and guarantee an efficient random access ({@code O(1)}) to the genes. A
037 * {@code Chromosome} must contains at least one {@code Gene}.
038 *
039 * @see <a href="http://en.wikipedia.org/wiki/Chromosome">Wikipdida: Chromosome</a>
040 * @see Genotype
041 * @see Gene
042 *
043 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
044 * @since 1.0
045 * @version 3.7
046 */
047 public interface Chromosome<G extends Gene<?, G>>
048 extends
049 Verifiable,
050 Iterable<G>,
051 Factory<Chromosome<G>>
052 {
053 /**
054 * A factory method which creates a new {@link Chromosome} of specific type
055 * and the given {@code genes}.
056 *
057 * @param genes the genes of the new chromosome. The given genes array is
058 * not copied.
059 * @return A new {@link Chromosome} of the same type with the given genes.
060 * @throws NullPointerException if the given {@code gene}s are {@code null}.
061 * @throws IllegalArgumentException if the length of the given gene sequence
062 * is smaller than one.
063 */
064 public Chromosome<G> newInstance(final ISeq<G> genes);
065
066 /**
067 * Return the first gene of this chromosome. Each chromosome must contain
068 * at least one gene.
069 *
070 * @return the first gene of this chromosome.
071 */
072 public default G getGene() {
073 return getGene(0);
074 }
075
076 /**
077 * Return the gene on the specified index.
078 *
079 * @param index The gene index.
080 * @return the wanted gene.
081 * @throws IndexOutOfBoundsException if the index is out of range
082 * (index < 1 || index >= length()).
083 */
084 public G getGene(final int index);
085
086 /**
087 * Returns the length of the Chromosome. The minimal length of a
088 * chromosome is one.
089 *
090 * @return Length of the Chromosome
091 */
092 public int length();
093
094 /**
095 * Return an unmodifiable sequence of the genes of this chromosome.
096 *
097 * @return an immutable gene sequence.
098 */
099 public ISeq<G> toSeq();
100
101 /**
102 * Casts this {@code Chromosome} to an instance of type {@code C}.
103 * This is a convenient method for an ordinary cast and allows seamless
104 * method-chaining. Instead of
105 * <pre>{@code
106 * final Genotype<BitGene> gt = ...
107 * final int count = ((BitChromosome)gt.getChromosome()).bitCount()
108 * }</pre>
109 * you can write
110 * <pre>{@code
111 * final Genotype<BitGene> gt = ...
112 * final int count = gt.getChromosome()
113 * .as(BitChromosome.class)
114 * .bitCount()
115 * }</pre>
116 * This may lead to a more elegant programming style in some cases.
117 *
118 * @since 3.7
119 *
120 * @param type the target type class
121 * @param <C> the target chromosome type
122 * @return this chromosome casted as {@code C}
123 * @throws NullPointerException if the target type class is {@code null}
124 * @throws ClassCastException if this chromosome can't be casted to a
125 * chromosome of type {@code C}
126 */
127 public default <C extends Chromosome<G>> C as(final Class<C> type) {
128 return type.cast(this);
129 }
130
131 /**
132 * Returns a sequential {@code Stream} of genes with this chromosome as
133 * its source.
134 *
135 * @since 3.3
136 *
137 * @return a sequential {@code Stream} of genes
138 */
139 public default Stream<G> stream() {
140 return IntStream.range(0, length()).mapToObj(this::getGene);
141 }
142
143 }
|