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 */
020package io.jenetics;
021
022import static java.util.Objects.requireNonNull;
023
024import java.io.Serial;
025import java.io.Serializable;
026import java.util.function.Function;
027import java.util.random.RandomGenerator;
028
029import io.jenetics.internal.util.Requires;
030
031/**
032 * Represents the result pair of one of the four {@code Mutator.mutate} calls.
033 *
034 * @see Mutator#mutate(Phenotype, long, double, RandomGenerator)
035 * @see Mutator#mutate(Genotype, double, RandomGenerator)
036 * @see Mutator#mutate(Chromosome, double, RandomGenerator)
037 * @see Mutator#mutate(Gene, RandomGenerator)
038 *
039 * @param <T> the mutation result type
040 * @param result the mutation result
041 * @param mutations the number of mutations applied while creating the mutation
042 *        result
043 *
044 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
045 * @version 7.0
046 * @since 4.0
047 */
048public record MutatorResult<T>(T result, int mutations)
049        implements Serializable
050{
051
052        @Serial
053        private static final long serialVersionUID = 2L;
054
055        /**
056         * Create a new mutation result with the given values.
057         *
058         * @param result the mutation result
059         * @param mutations the number of mutations
060         * @throws IllegalArgumentException if the given {@code mutations} is
061         *         negative
062         * @throws NullPointerException if the given mutation result is {@code null}
063         */
064        public MutatorResult {
065                requireNonNull(result);
066                Requires.nonNegative(mutations);
067        }
068
069        /**
070         * Maps this mutation result to type {@code B} using the given {@code mapper}.
071         *
072         * @param mapper the mutation result mapper
073         * @param <B> the new mutation result type
074         * @return a new mapped mutation result
075         * @throws NullPointerException if the given {@code mapper} is {@code null}
076         */
077        <B> MutatorResult<B> map(final Function<? super T, ? extends B> mapper) {
078                requireNonNull(mapper);
079                return new MutatorResult<>(mapper.apply(result), mutations);
080        }
081
082}