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;
021
022 import static java.lang.String.format;
023 import static io.jenetics.internal.util.Hashes.hash;
024
025 import java.io.Serial;
026 import java.io.Serializable;
027 import java.util.Objects;
028
029 import io.jenetics.util.ISeq;
030 import io.jenetics.util.RandomRegistry;
031
032 /**
033 * <p>
034 * Gene which holds enumerable (countable) genes. Will be used for combinatorial
035 * problems in combination with the {@link PermutationChromosome}.
036 * </p>
037 * The following code shows how to create a combinatorial genotype factory which
038 * can be used when creating an {@link io.jenetics.engine.Engine} instance.
039 * {@snippet lang="java":
040 * final ISeq<Integer> alleles = ISeq.of(1, 2, 3, 4, 5, 6, 7, 8);
041 * final Factory<Genotype<EnumGene<Integer>>> gtf = Genotype.of(
042 * PermutationChromosome.of(alleles)
043 * );
044 * }
045 *
046 * The following code shows the assurances of the {@code EnumGene}.
047 * {@snippet lang="java":
048 * final ISeq<Integer> alleles = ISeq.of(1, 2, 3, 4, 5, 6, 7, 8);
049 * final EnumGene<Integer> gene = new EnumGene<>(5, alleles);
050 *
051 * assert(gene.alleleIndex() == 5);
052 * assert(gene.allele() == gene.validAlleles().get(5));
053 * assert(gene.validAlleles() == alleles);
054 * }
055 *
056 * @see PermutationChromosome
057 * @see PartiallyMatchedCrossover
058 *
059 * @implNote
060 * This class is immutable and thread-safe.
061 *
062 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
063 * @since 1.0
064 * @version 5.2
065 */
066 public final class EnumGene<A>
067 implements
068 Gene<A, EnumGene<A>>,
069 Comparable<EnumGene<A>>,
070 Serializable
071 {
072
073 @Serial
074 private static final long serialVersionUID = 2L;
075
076 private final ISeq<A> _validAlleles;
077 private final int _alleleIndex;
078
079 /**
080 * Create a new enum gene from the given valid genes and the chosen allele
081 * index.
082 *
083 * @param alleleIndex the index of the allele for this gene.
084 * @param validAlleles the sequence of valid alleles.
085 * @throws IllegalArgumentException if the give valid alleles sequence is
086 * empty
087 * @throws NullPointerException if the valid alleles seq is {@code null}.
088 */
089 EnumGene(final int alleleIndex, final ISeq<? extends A> validAlleles) {
090 if (validAlleles.isEmpty()) {
091 throw new IllegalArgumentException(
092 "Array of valid alleles must be greater than zero."
093 );
094 }
095
096 if (alleleIndex < 0 || alleleIndex >= validAlleles.length()) {
097 throw new IndexOutOfBoundsException(format(
098 "Allele index is not in range [0, %d): %d.",
099 validAlleles.length(),
100 alleleIndex
101 ));
102 }
103
104 _validAlleles = ISeq.upcast(validAlleles);
105 _alleleIndex = alleleIndex;
106 }
107
108 /**
109 * Return sequence of the valid alleles where this gene is a part of.
110 *
111 * @return the sequence of the valid alleles.
112 */
113 public ISeq<A> validAlleles() {
114 return _validAlleles;
115 }
116
117 /**
118 * Return the index of the allele this gene is representing.
119 *
120 * @return the index of the allele this gene is representing.
121 */
122 public int alleleIndex() {
123 return _alleleIndex;
124 }
125
126 @Override
127 public A allele() {
128 return _validAlleles.get(_alleleIndex);
129 }
130
131 @Override
132 public boolean isValid() {
133 return _alleleIndex >= 0 && _alleleIndex < _validAlleles.length();
134 }
135
136 @Override
137 public EnumGene<A> newInstance() {
138 return new EnumGene<>(
139 RandomRegistry.random().nextInt(_validAlleles.length()),
140 _validAlleles
141 );
142 }
143
144 /**
145 * Create a new gene from the given {@code value} and the gene context.
146 *
147 * @since 1.6
148 *
149 * @param value the value of the new gene.
150 * @return a new gene with the given value.
151 */
152 public EnumGene<A> newInstance(final A value) {
153 return new EnumGene<>(
154 _validAlleles.indexOf(value),
155 _validAlleles
156 );
157 }
158
159 @Override
160 public int compareTo(final EnumGene<A> gene) {
161 int result = 0;
162 if (_alleleIndex > gene._alleleIndex) {
163 result = 1;
164 } else if (_alleleIndex < gene._alleleIndex) {
165 result = -1;
166 }
167
168 return result;
169 }
170
171 @Override
172 public int hashCode() {
173 return hash(_alleleIndex, hash(_validAlleles));
174 }
175
176 @Override
177 public boolean equals(final Object obj) {
178 return obj instanceof EnumGene<?> other &&
179 _alleleIndex == other._alleleIndex &&
180 Objects.equals(_validAlleles, other._validAlleles);
181 }
182
183 @Override
184 public String toString() {
185 return Objects.toString(allele());
186 }
187
188
189 /* *************************************************************************
190 * Static object creation methods
191 * ************************************************************************/
192
193 /**
194 * Create a new enum gene from the given valid genes and the chosen allele
195 * index.
196 *
197 * @since 3.4
198 *
199 * @param <A> the allele type
200 * @param alleleIndex the index of the allele for this gene.
201 * @param validAlleles the sequence of valid alleles.
202 * @return a new {@code EnumGene} with the given with the allele
203 * {@code validAlleles.get(alleleIndex)}
204 * @throws IllegalArgumentException if the give valid alleles sequence is
205 * empty
206 * @throws NullPointerException if the valid alleles seq is {@code null}.
207 */
208 public static <A> EnumGene<A> of(
209 final int alleleIndex,
210 final ISeq<? extends A> validAlleles
211 ) {
212 return new EnumGene<>(alleleIndex, validAlleles);
213 }
214
215 /**
216 * Return a new enum gene with an allele randomly chosen from the given
217 * valid alleles.
218 *
219 * @param <A> the allele type
220 * @param validAlleles the sequence of valid alleles.
221 * @return a new {@code EnumGene} with a randomly chosen allele from the
222 * sequence of valid alleles
223 * @throws java.lang.IllegalArgumentException if the give valid alleles
224 * sequence is empty
225 * @throws NullPointerException if the valid alleles seq is {@code null}.
226 */
227 public static <A> EnumGene<A> of(final ISeq<? extends A> validAlleles) {
228 return new EnumGene<>(
229 RandomRegistry.random().nextInt(validAlleles.length()),
230 validAlleles
231 );
232 }
233
234 /**
235 * Create a new enum gene from the given valid genes and the chosen allele
236 * index.
237 *
238 * @param <A> the allele type
239 * @param alleleIndex the index of the allele for this gene.
240 * @param validAlleles the array of valid alleles.
241 * @return a new {@code EnumGene} with the given with the allele
242 * {@code validAlleles[alleleIndex]}
243 * @throws java.lang.IllegalArgumentException if the give valid alleles
244 * array is empty of the allele index is out of range.
245 */
246 @SafeVarargs
247 public static <A> EnumGene<A> of(
248 final int alleleIndex,
249 final A... validAlleles
250 ) {
251 return new EnumGene<>(alleleIndex, ISeq.of(validAlleles));
252 }
253
254 /**
255 * Return a new enum gene with an allele randomly chosen from the given
256 * valid alleles.
257 *
258 * @param <A> the allele type
259 * @param validAlleles the array of valid alleles.
260 * @return a new {@code EnumGene} with a randomly chosen allele from the
261 * sequence of valid alleles
262 * @throws IllegalArgumentException if the give valid alleles array is empty
263 */
264 @SafeVarargs
265 public static <A> EnumGene<A> of(final A... validAlleles) {
266 return EnumGene.of(ISeq.of(validAlleles));
267 }
268
269 }
|