001/*
002 * Java Genetic Algorithm Library (jenetics-9.1.0).
003 * Copyright (c) 2007-2026 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 */
020package io.jenetics;
021
022import static java.util.Objects.requireNonNull;
023import static io.jenetics.util.RandomRegistry.random;
024
025import java.util.Objects;
026import java.util.function.Predicate;
027import java.util.function.Supplier;
028
029import io.jenetics.util.ISeq;
030import io.jenetics.util.IntRange;
031import io.jenetics.util.MSeq;
032
033/**
034 * {@code Gene} implementation, which allows creating genes without explicit
035 * implementing the {@code Gene} interface.
036 * {@snippet lang="java":
037 * class Main {
038 *     // First Monday of 2015.
039 *     private static final LocalDate MIN_MONDAY = LocalDate.of(2015, 1, 5);
040 *
041 *     // Supplier of random 'LocalDate' objects. The implementation is responsible
042 *     // for guaranteeing the desired allele restriction. In this case, we will
043 *     // generate only mondays.
044 *     static LocalDate nextRandomMonday() {
045 *         return MIN_MONDAY.plusWeeks(RandomRegistry.getRandom().nextInt(1000));
046 *     }
047 *
048 *     // Create a new 'LocalDate' gene. All other genes, created with
049 *     // gene.newInstance(), are calling the 'newRandomMonday' method.
050 *     final AnyGene<LocalDate> gene = AnyGene.of(Main::nextRandomMonday);
051 * }
052 * }
053 * The example above shows how to create {@code LocalDate} genes from a random
054 * {@code LocalDate} supplier. It also shows how to implement a restriction on
055 * the created dates. The usage of the {@code AnyGene} class is useful for
056 * supporting custom allele types without explicit implementation of the
057 * {@code Gene} interface. But the {@code AnyGene} can only be used for a subset
058 * of the existing alterers.
059 *
060 * @see AnyChromosome
061 *
062 * @implNote
063 * This class is immutable and thread-safe.
064 *
065 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
066 * @version 6.0
067 * @since 3.3
068 */
069public final class AnyGene<A> implements Gene<A, AnyGene<A>> {
070
071        private final A _allele;
072        private final Supplier<? extends A> _supplier;
073        private final Predicate<? super A> _validator;
074
075        private AnyGene(
076                final A allele,
077                final Supplier<? extends A> supplier,
078                final Predicate<? super A> validator
079        ) {
080                _allele = allele;
081                _supplier = requireNonNull(supplier);
082                _validator = requireNonNull(validator);
083        }
084
085        @Override
086        public A allele() {
087                return _allele;
088        }
089
090        @Override
091        public AnyGene<A> newInstance() {
092                return new AnyGene<>(_supplier.get(), _supplier, _validator);
093        }
094
095        @Override
096        public AnyGene<A> newInstance(final A value) {
097                return new AnyGene<>(value, _supplier, _validator);
098        }
099
100        @Override
101        public boolean isValid() {
102                return _validator.test(_allele);
103        }
104
105        @Override
106        public int hashCode() {
107                return _allele.hashCode();
108        }
109
110        @Override
111        public boolean equals(final Object obj) {
112                return obj instanceof AnyGene<?> other &&
113                        Objects.equals(other._allele, _allele);
114        }
115
116        @Override
117        public String toString() {
118                return Objects.toString(_allele);
119        }
120
121
122        /* *************************************************************************
123         *  Static factory methods.
124         * ************************************************************************/
125
126        /**
127         * Create a new {@code AnyGene} instance with the given parameters. New
128         * (random) genes are created with the given allele {@code supplier}.
129         *
130         * @param <A> the allele type
131         * @param allele the actual allele instance the created gene represents.
132         *        {@code null} values are allowed.
133         * @param supplier the allele-supplier which is used for creating new,
134         *        random alleles
135         * @param validator the validator used for validating the created gene. This
136         *        predicate is used in the {@link #isValid()} method.
137         * @return a new {@code AnyGene} with the given parameters
138         * @throws NullPointerException if the {@code supplier} or {@code validator}
139         *         is {@code null}
140         */
141        public static <A> AnyGene<A> of(
142                final A allele,
143                final Supplier<? extends A> supplier,
144                final Predicate<? super A> validator
145        ) {
146                return new AnyGene<>(allele, supplier, validator);
147        }
148
149        /**
150         * Create a new {@code AnyGene} instance with the given parameters. New
151         * (random) genes are created with the given allele {@code supplier}. The
152         * {@code validator} predicate of the generated gene will always return
153         * {@code true}.
154         *
155         * @param <A> the allele type
156         * @param allele the actual allele instance the created gene represents.
157         *        {@code null} values are allowed.
158         * @param supplier the allele-supplier which is used for creating new,
159         *        random alleles
160         * @return a new {@code AnyGene} with the given parameters
161         * @throws NullPointerException if the {@code suppler} is {@code null}
162         */
163        public static <A> AnyGene<A> of(
164                final A allele,
165                final Supplier<? extends A> supplier
166        ) {
167                return new AnyGene<>(allele, supplier, _ -> true);
168        }
169
170        /**
171         * Create a new {@code AnyGene} instance with the given allele
172         * {@code supplier}. The {@code validator} predicate of the generated gene
173         * will always return {@code true}.
174         *
175         * @param <A> the allele type
176         * @param supplier the allele-supplier which is used for creating new,
177         *        random alleles
178         * @return a new {@code AnyGene} with the given parameters
179         * @throws NullPointerException if one of the parameters is {@code null}
180         */
181        public static <A> AnyGene<A> of(final Supplier<? extends A> supplier) {
182                return new AnyGene<>(supplier.get(), supplier, _ -> true);
183        }
184
185        /**
186         * Create a new {@code AnyGene} instance with the given parameters. New
187         * (random) genes are created with the given allele {@code supplier}.
188         *
189         * @param <A> the allele type
190         * @param supplier the allele-supplier which is used for creating new,
191         *        random alleles
192         * @param validator the validator used for validating the created gene. This
193         *        predicate is used in the {@link #isValid()} method.
194         * @return a new {@code AnyGene} with the given parameters
195         * @throws NullPointerException if one of the parameters is {@code null}
196         */
197        public static <A> AnyGene<A> of(
198                final Supplier<? extends A> supplier,
199                final Predicate<? super A> validator
200        ) {
201                return new AnyGene<>(supplier.get(), supplier, validator);
202        }
203
204        // Create gene sequence.
205        static <A> ISeq<AnyGene<A>> seq(
206                final IntRange lengthRange,
207                final Supplier<? extends A> supplier,
208                final Predicate<? super A> validator
209        ) {
210                final var random = random();
211                final var length = random.nextInt(lengthRange.min(), lengthRange.max());
212
213                return MSeq.<AnyGene<A>>ofLength(length)
214                        .fill(() -> of(supplier.get(), supplier, validator))
215                        .toISeq();
216        }
217
218}