1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus.util;
23
24 import org.hipparchus.exception.LocalizedCoreFormats;
25 import org.hipparchus.exception.MathIllegalArgumentException;
26 import org.hipparchus.exception.MathIllegalStateException;
27 import org.hipparchus.exception.NullArgumentException;
28
29 /**
30 * Utility that increments a counter until a maximum is reached, at
31 * which point, the instance will by default throw a
32 * {@link MathIllegalStateException}.
33 * However, the user is able to override this behaviour by defining a
34 * custom {@link MaxCountExceededCallback callback}, in order to e.g.
35 * select which exception must be thrown.
36 */
37 public class Incrementor {
38 /** Default callback. */
39 private static final MaxCountExceededCallback DEFAULT_CALLBACK =
40 (int max) -> {
41 throw new MathIllegalStateException(LocalizedCoreFormats.MAX_COUNT_EXCEEDED, max);
42 };
43
44 /** Upper limit for the counter. */
45 private final int maximalCount;
46 /** Function called at counter exhaustion. */
47 private final MaxCountExceededCallback maxCountCallback;
48 /** Current count. */
49 private int count;
50
51 /**
52 * Defines a method to be called at counter exhaustion.
53 * The {@link #trigger(int) trigger} method should usually throw an exception.
54 */
55 @FunctionalInterface
56 public interface MaxCountExceededCallback {
57 /**
58 * Function called when the maximal count has been reached.
59 *
60 * @param maximalCount Maximal count.
61 * @throws MathIllegalStateException at counter exhaustion
62 */
63 void trigger(int maximalCount) throws MathIllegalStateException;
64 }
65
66 /**
67 * Creates an Incrementor.
68 * <p>
69 * The maximal value will be set to {@code Integer.MAX_VALUE}.
70 */
71 public Incrementor() {
72 this(Integer.MAX_VALUE);
73 }
74
75 /**
76 * Creates an Incrementor.
77 *
78 * @param max Maximal count.
79 * @throws MathIllegalArgumentException if {@code max} is negative.
80 */
81 public Incrementor(int max) {
82 this(max, DEFAULT_CALLBACK);
83 }
84
85 /**
86 * Creates an Incrementor.
87 *
88 * @param max Maximal count.
89 * @param cb Function to be called when the maximal count has been reached.
90 * @throws NullArgumentException if {@code cb} is {@code null}.
91 * @throws MathIllegalArgumentException if {@code max} is negative.
92 */
93 public Incrementor(int max,
94 MaxCountExceededCallback cb)
95 throws NullArgumentException {
96 this(0, max, cb);
97 }
98
99 /**
100 * Creates an Incrementor.
101 *
102 * @param count Initial counter value.
103 * @param max Maximal count.
104 * @param cb Function to be called when the maximal count has been reached.
105 * @throws NullArgumentException if {@code cb} is {@code null}.
106 * @throws MathIllegalArgumentException if {@code max} is negative.
107 */
108 private Incrementor(int count,
109 int max,
110 MaxCountExceededCallback cb)
111 throws NullArgumentException {
112 if (cb == null) {
113 throw new NullArgumentException();
114 }
115 if (max < 0) {
116 throw new MathIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL, max, 0);
117 }
118 this.maximalCount = max;
119 this.maxCountCallback = cb;
120 this.count = count;
121 }
122
123 /**
124 * Creates a new instance and set the counter to the given value.
125 *
126 * @param value Value of the counter.
127 * @return a new instance.
128 */
129 public Incrementor withCount(int value) {
130 return new Incrementor(value,
131 this.maximalCount,
132 this.maxCountCallback);
133 }
134
135 /**
136 * Creates a new instance with a given maximal count.
137 * The counter is reset to 0.
138 *
139 * @param max Maximal count.
140 * @return a new instance.
141 * @throws MathIllegalArgumentException if {@code max} is negative.
142 */
143 public Incrementor withMaximalCount(int max) {
144 return new Incrementor(0,
145 max,
146 this.maxCountCallback);
147 }
148
149 /**
150 * Creates a new instance with a given callback.
151 * The counter is reset to 0.
152 *
153 * @param cb Callback to be called at counter exhaustion.
154 * @return a new instance.
155 */
156 public Incrementor withCallback(MaxCountExceededCallback cb) {
157 return new Incrementor(0,
158 this.maximalCount,
159 cb);
160 }
161
162 /**
163 * Gets the upper limit of the counter.
164 *
165 * @return the counter upper limit.
166 */
167 public int getMaximalCount() {
168 return maximalCount;
169 }
170
171 /**
172 * Gets the current count.
173 *
174 * @return the current count.
175 */
176 public int getCount() {
177 return count;
178 }
179
180 /**
181 * Checks whether incrementing the counter {@code nTimes} is allowed.
182 *
183 * @return {@code false} if calling {@link #increment()}
184 * will trigger a {@code MathIllegalStateException},
185 * {@code true} otherwise.
186 */
187 public boolean canIncrement() {
188 return canIncrement(1);
189 }
190
191 /**
192 * Checks whether incrementing the counter several times is allowed.
193 *
194 * @param nTimes Number of increments.
195 * @return {@code false} if calling {@link #increment(int)
196 * increment(nTimes)} would call the {@link MaxCountExceededCallback callback}
197 * {@code true} otherwise.
198 * @throws MathIllegalArgumentException if {@code nTimes} is negative.
199 */
200 public boolean canIncrement(int nTimes) {
201 if (nTimes < 0) {
202 throw new MathIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL,
203 nTimes, 0);
204 }
205 return count <= maximalCount - nTimes;
206 }
207
208 /**
209 * Performs multiple increments.
210 *
211 * @param nTimes Number of increments.
212 * @throws MathIllegalArgumentException if {@code nTimes} is negative.
213 *
214 * @see #increment()
215 */
216 public void increment(int nTimes) {
217 if (nTimes < 0) {
218 throw new MathIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL,
219 nTimes, 0);
220 }
221
222 for (int i = 0; i < nTimes; i++) {
223 increment();
224 }
225 }
226
227 /**
228 * Adds the increment value to the current iteration count.
229 * At counter exhaustion, this method will call the
230 * {@link MaxCountExceededCallback#trigger(int) trigger} method of the
231 * callback object passed to the
232 * {@link #withCallback(MaxCountExceededCallback)} method.
233 *
234 * @see #increment(int)
235 */
236 public void increment() {
237 if (count > maximalCount - 1) {
238 maxCountCallback.trigger(maximalCount);
239 }
240 ++count;
241 }
242
243 /**
244 * Resets the counter to 0.
245 */
246 public void reset() {
247 count = 0;
248 }
249 }