ReductionSettings.java

1 
/*******************************************************************************
2 
 * Copyright (C) 2026, Leo Galambos
3 
 * All rights reserved.
4 
 *
5 
 * Redistribution and use in source and binary forms, with or without
6 
 * modification, are permitted provided that the following conditions are met:
7 
 *
8 
 * 1. Redistributions of source code must retain the above copyright notice,
9 
 *    this list of conditions and the following disclaimer.
10 
 *
11 
 * 2. Redistributions in binary form must reproduce the above copyright notice,
12 
 *    this list of conditions and the following disclaimer in the documentation
13 
 *    and/or other materials provided with the distribution.
14 
 *
15 
 * 3. Neither the name of the copyright holder nor the names of its contributors
16 
 *    may be used to endorse or promote products derived from this software
17 
 *    without specific prior written permission.
18 
 *
19 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
23 
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 
 * POSSIBILITY OF SUCH DAMAGE.
30 
 ******************************************************************************/
31 
package org.egothor.stemmer;
32
33 
import java.util.Objects;
34
35 
/**
36 
 * Immutable reduction configuration used by {@link FrequencyTrie.Builder}.
37 
 *
38 
 * <p>
39 
 * The settings influence how mutable trie nodes are merged into canonical
40 
 * read-only nodes during compilation.
41 
 *
42 
 * @param reductionMode                 reduction mode
43 
 * @param dominantWinnerMinPercent      minimum dominant winner percentage
44 
 * @param dominantWinnerOverSecondRatio minimum winner-over-second ratio
45 
 * @param contractUniformSubtrees       whether compilation may contract a subtree
46 
 *                                      whose reachable terminal values all contain
47 
 *                                      the same single value
48 
 */
49 
@SuppressWarnings("PMD.LongVariable")
50 
public record ReductionSettings(ReductionMode reductionMode, int dominantWinnerMinPercent,
51 
        int dominantWinnerOverSecondRatio, boolean contractUniformSubtrees) {
52
53 
    /**
54 
     * Default minimum dominant winner percentage.
55 
     */
56 
    public static final int DEFAULT_DOMINANT_WINNER_MIN_PERCENT = 75;
57
58 
    /**
59 
     * Default minimum winner-over-second ratio.
60 
     */
61 
    public static final int DEFAULT_DOMINANT_WINNER_OVER_SECOND_RATIO = 3;
62
63 
    /**
64 
     * Creates a new instance.
65 
     *
66 
     * @param reductionMode                 reduction mode
67 
     * @param dominantWinnerMinPercent      minimum dominant winner percentage in
68 
     *                                      the inclusive range {@code 1..100}
69 
     * @param dominantWinnerOverSecondRatio minimum winner-over-second ratio, must
70 
     *                                      be at least {@code 1}
71 
     * @param contractUniformSubtrees       whether uniform subtrees may be
72 
     *                                      contracted into accepting leaves
73 
     * @throws NullPointerException     if {@code reductionMode} is {@code null}
74 
     * @throws IllegalArgumentException if any numeric value is outside the valid
75 
     *                                  range
76 
     */
77 
    public ReductionSettings(final ReductionMode reductionMode, final int dominantWinnerMinPercent,
78 
            final int dominantWinnerOverSecondRatio, final boolean contractUniformSubtrees) {
79 
        this.reductionMode = Objects.requireNonNull(reductionMode, "reductionMode");
80 
        if (dominantWinnerMinPercent < 1 || dominantWinnerMinPercent > 100) {
81 
            throw new IllegalArgumentException("dominantWinnerMinPercent must be in range 1..100.");
82 
        }
83 
        if (dominantWinnerOverSecondRatio < 1) { // NOPMD
84 
            throw new IllegalArgumentException("dominantWinnerOverSecondRatio must be at least 1.");
85 
        }
86 
        this.dominantWinnerMinPercent = dominantWinnerMinPercent;
87 
        this.dominantWinnerOverSecondRatio = dominantWinnerOverSecondRatio;
88 
        this.contractUniformSubtrees = contractUniformSubtrees;
89 
    }
90
91 
    /**
92 
     * Creates a new instance without uniform-subtree contraction.
93 
     *
94 
     * @param reductionMode                 reduction mode
95 
     * @param dominantWinnerMinPercent      minimum dominant winner percentage
96 
     * @param dominantWinnerOverSecondRatio minimum winner-over-second ratio
97 
     */
98 
    public ReductionSettings(final ReductionMode reductionMode, final int dominantWinnerMinPercent,
99 
            final int dominantWinnerOverSecondRatio) {
100 
        this(reductionMode, dominantWinnerMinPercent, dominantWinnerOverSecondRatio, false);
101 
    }
102
103 
    /**
104 
     * Creates settings with default dominance thresholds.
105 
     *
106 
     * @param reductionMode reduction mode
107 
     * @return new settings instance
108 
     * @throws NullPointerException if {@code reductionMode} is {@code null}
109 
     */
110 
    public static ReductionSettings withDefaults(final ReductionMode reductionMode) {
111 1 1. withDefaults : replaced return value with null for org/egothor/stemmer/ReductionSettings::withDefaults → KILLED
 
        return new ReductionSettings(reductionMode, DEFAULT_DOMINANT_WINNER_MIN_PERCENT,
112 
                DEFAULT_DOMINANT_WINNER_OVER_SECOND_RATIO);
113 
    }
114
115 
    /**
116 
     * Returns settings that run uniform-subtree contraction before the configured
117 
     * subtree-merging mode.
118 
     *
119 
     * <p>
120 
     * This is intended for Radixor patch-command tries, where a contracted accepting
121 
     * leaf can safely represent a subtree whose reachable entries all use the same
122 
     * patch command.
123 
     * </p>
124 
     *
125 
     * @param settings base settings
126 
     * @return equivalent settings with uniform-subtree contraction enabled
127 
     */
128 
    /* default */ static ReductionSettings withUniformSubtreeContraction(final ReductionSettings settings) {
129 
        Objects.requireNonNull(settings, "settings");
130 1 1. withUniformSubtreeContraction : replaced return value with null for org/egothor/stemmer/ReductionSettings::withUniformSubtreeContraction → KILLED
 
        return new ReductionSettings(settings.reductionMode(), settings.dominantWinnerMinPercent(),
131 
                settings.dominantWinnerOverSecondRatio(), true);
132 
    }
133 
}

Mutations

111

1.1
Location : withDefaults
Killed by : org.egothor.stemmer.FrequencyTrieTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.FrequencyTrieTest]/[method:fallbackDiacriticModeIsNotSupportedYet()] replaced return value with null for org/egothor/stemmer/ReductionSettings::withDefaults → KILLED

130

1.1
Location : withUniformSubtreeContraction
Killed by : org.egothor.stemmer.FrequencyTrieTest.[engine:junit-jupiter]/[class:org.egothor.stemmer.FrequencyTrieTest]/[method:shouldPreserveUniformSubtreeContractionWhenMappingValues()] replaced return value with null for org/egothor/stemmer/ReductionSettings::withUniformSubtreeContraction → KILLED

Active mutators

Tests examined


Report generated by PIT 1.22.1