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 package org.apache.commons.lang3.mutable;
18
19 /**
20 * A mutable {@code float} wrapper.
21 * <p>
22 * Note that as MutableFloat does not extend Float, it is not treated by String.format as a Float parameter.
23 * </p>
24 *
25 * @see Float
26 * @since 2.1
27 */
28 public class MutableFloat extends Number implements Comparable<MutableFloat>, Mutable<Number> {
29
30 /**
31 * Required for serialization support.
32 *
33 * @see java.io.Serializable
34 */
35 private static final long serialVersionUID = 5787169186L;
36
37 /** The mutable value. */
38 private float value;
39
40 /**
41 * Constructs a new MutableFloat with the default value of zero.
42 */
43 public MutableFloat() {
44 }
45
46 /**
47 * Constructs a new MutableFloat with the specified value.
48 *
49 * @param value the initial value to store
50 */
51 public MutableFloat(final float value) {
52 this.value = value;
53 }
54
55 /**
56 * Constructs a new MutableFloat with the specified value.
57 *
58 * @param value the initial value to store, not null
59 * @throws NullPointerException if the object is null
60 */
61 public MutableFloat(final Number value) {
62 this.value = value.floatValue();
63 }
64
65 /**
66 * Constructs a new MutableFloat parsing the given string.
67 *
68 * @param value the string to parse, not null
69 * @throws NumberFormatException if the string cannot be parsed into a float, see {@link Float#parseFloat(String)}.
70 * @since 2.5
71 */
72 public MutableFloat(final String value) {
73 this.value = Float.parseFloat(value);
74 }
75
76 /**
77 * Adds a value to the value of this instance.
78 *
79 * @param operand the value to add, not null
80 * @since 2.2
81 */
82 public void add(final float operand) {
83 this.value += operand;
84 }
85
86 /**
87 * Adds a value to the value of this instance.
88 *
89 * @param operand the value to add, not null
90 * @throws NullPointerException if the object is null
91 * @since 2.2
92 */
93 public void add(final Number operand) {
94 this.value += operand.floatValue();
95 }
96
97 /**
98 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
99 * immediately after the addition operation. This method is not thread safe.
100 *
101 * @param operand the quantity to add, not null
102 * @return the value associated with this instance after adding the operand
103 * @since 3.5
104 */
105 public float addAndGet(final float operand) {
106 this.value += operand;
107 return value;
108 }
109
110 /**
111 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
112 * immediately after the addition operation. This method is not thread safe.
113 *
114 * @param operand the quantity to add, not null
115 * @throws NullPointerException if {@code operand} is null
116 * @return the value associated with this instance after adding the operand
117 * @since 3.5
118 */
119 public float addAndGet(final Number operand) {
120 this.value += operand.floatValue();
121 return value;
122 }
123
124 /**
125 * Compares this mutable to another in ascending order.
126 *
127 * @param other the other mutable to compare to, not null
128 * @return negative if this is less, zero if equal, positive if greater
129 */
130 @Override
131 public int compareTo(final MutableFloat other) {
132 return Float.compare(this.value, other.value);
133 }
134
135 /**
136 * Decrements the value.
137 *
138 * @since 2.2
139 */
140 public void decrement() {
141 value--;
142 }
143
144 /**
145 * Decrements this instance's value by 1; this method returns the value associated with the instance
146 * immediately after the decrement operation. This method is not thread safe.
147 *
148 * @return the value associated with the instance after it is decremented
149 * @since 3.5
150 */
151 public float decrementAndGet() {
152 value--;
153 return value;
154 }
155
156 /**
157 * Returns the value of this MutableFloat as a double.
158 *
159 * @return the numeric value represented by this object after conversion to type double.
160 */
161 @Override
162 public double doubleValue() {
163 return value;
164 }
165
166 /**
167 * Compares this object against some other object. The result is {@code true} if and only if the argument is
168 * not {@code null} and is a {@link Float} object that represents a {@code float} that has the
169 * identical bit pattern to the bit pattern of the {@code float} represented by this object. For this
170 * purpose, two float values are considered to be the same if and only if the method
171 * {@link Float#floatToIntBits(float)}returns the same int value when applied to each.
172 * <p>
173 * Note that in most cases, for two instances of class {@link Float},{@code f1} and {@code f2},
174 * the value of {@code f1.equals(f2)} is {@code true} if and only if <blockquote>
175 *
176 * <pre>
177 * f1.floatValue() == f2.floatValue()
178 * </pre>
179 *
180 * </blockquote>
181 * <p>
182 * also has the value {@code true}. However, there are two exceptions:
183 * <ul>
184 * <li>If {@code f1} and {@code f2} both represent {@code Float.NaN}, then the
185 * {@code equals} method returns {@code true}, even though {@code Float.NaN == Float.NaN} has
186 * the value {@code false}.
187 * <li>If {@code f1} represents {@code +0.0f} while {@code f2} represents {@code -0.0f},
188 * or vice versa, the {@code equal} test has the value {@code false}, even though
189 * {@code 0.0f == -0.0f} has the value {@code true}.
190 * </ul>
191 * This definition allows hashtables to operate properly.
192 *
193 * @param obj the object to compare with, null returns false
194 * @return {@code true} if the objects are the same; {@code false} otherwise.
195 * @see Float#floatToIntBits(float)
196 */
197 @Override
198 public boolean equals(final Object obj) {
199 return obj instanceof MutableFloat
200 && Float.floatToIntBits(((MutableFloat) obj).value) == Float.floatToIntBits(value);
201 }
202
203 /**
204 * Returns the value of this MutableFloat as a float.
205 *
206 * @return the numeric value represented by this object after conversion to type float.
207 */
208 @Override
209 public float floatValue() {
210 return value;
211 }
212
213 /**
214 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
215 * immediately prior to the addition operation. This method is not thread safe.
216 *
217 * @param operand the quantity to add, not null
218 * @return the value associated with this instance immediately before the operand was added
219 * @since 3.5
220 */
221 public float getAndAdd(final float operand) {
222 final float last = value;
223 this.value += operand;
224 return last;
225 }
226
227 /**
228 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
229 * immediately prior to the addition operation. This method is not thread safe.
230 *
231 * @param operand the quantity to add, not null
232 * @throws NullPointerException if {@code operand} is null
233 * @return the value associated with this instance immediately before the operand was added
234 * @since 3.5
235 */
236 public float getAndAdd(final Number operand) {
237 final float last = value;
238 this.value += operand.floatValue();
239 return last;
240 }
241
242 /**
243 * Decrements this instance's value by 1; this method returns the value associated with the instance
244 * immediately prior to the decrement operation. This method is not thread safe.
245 *
246 * @return the value associated with the instance before it was decremented
247 * @since 3.5
248 */
249 public float getAndDecrement() {
250 final float last = value;
251 value--;
252 return last;
253 }
254
255 /**
256 * Increments this instance's value by 1; this method returns the value associated with the instance
257 * immediately prior to the increment operation. This method is not thread safe.
258 *
259 * @return the value associated with the instance before it was incremented
260 * @since 3.5
261 */
262 public float getAndIncrement() {
263 final float last = value;
264 value++;
265 return last;
266 }
267
268 /**
269 * Gets the value as a Float instance.
270 *
271 * @return the value as a Float, never null.
272 * @deprecated Use {@link #get()}.
273 */
274 @Deprecated
275 @Override
276 public Float getValue() {
277 return Float.valueOf(this.value);
278 }
279
280 /**
281 * Returns a suitable hash code for this mutable.
282 *
283 * @return a suitable hash code
284 */
285 @Override
286 public int hashCode() {
287 return Float.floatToIntBits(value);
288 }
289
290 /**
291 * Increments the value.
292 *
293 * @since 2.2
294 */
295 public void increment() {
296 value++;
297 }
298
299 /**
300 * Increments this instance's value by 1; this method returns the value associated with the instance
301 * immediately after the increment operation. This method is not thread safe.
302 *
303 * @return the value associated with the instance after it is incremented
304 * @since 3.5
305 */
306 public float incrementAndGet() {
307 value++;
308 return value;
309 }
310
311 // shortValue and byteValue rely on Number implementation
312 /**
313 * Returns the value of this MutableFloat as an int.
314 *
315 * @return the numeric value represented by this object after conversion to type int.
316 */
317 @Override
318 public int intValue() {
319 return (int) value;
320 }
321
322 /**
323 * Checks whether the float value is infinite.
324 *
325 * @return true if infinite
326 */
327 public boolean isInfinite() {
328 return Float.isInfinite(value);
329 }
330
331 /**
332 * Checks whether the float value is the special NaN value.
333 *
334 * @return true if NaN
335 */
336 public boolean isNaN() {
337 return Float.isNaN(value);
338 }
339
340 /**
341 * Returns the value of this MutableFloat as a long.
342 *
343 * @return the numeric value represented by this object after conversion to type long.
344 */
345 @Override
346 public long longValue() {
347 return (long) value;
348 }
349
350 /**
351 * Sets the value.
352 *
353 * @param value the value to set
354 */
355 public void setValue(final float value) {
356 this.value = value;
357 }
358
359 /**
360 * Sets the value from any Number instance.
361 *
362 * @param value the value to set, not null
363 * @throws NullPointerException if the object is null
364 */
365 @Override
366 public void setValue(final Number value) {
367 this.value = value.floatValue();
368 }
369
370 /**
371 * Subtracts a value from the value of this instance.
372 *
373 * @param operand the value to subtract
374 * @since 2.2
375 */
376 public void subtract(final float operand) {
377 this.value -= operand;
378 }
379
380 /**
381 * Subtracts a value from the value of this instance.
382 *
383 * @param operand the value to subtract, not null
384 * @throws NullPointerException if the object is null
385 * @since 2.2
386 */
387 public void subtract(final Number operand) {
388 this.value -= operand.floatValue();
389 }
390
391 /**
392 * Gets this mutable as an instance of Float.
393 *
394 * @return a Float instance containing the value from this mutable, never null
395 */
396 public Float toFloat() {
397 return Float.valueOf(floatValue());
398 }
399
400 /**
401 * Returns the String value of this mutable.
402 *
403 * @return the mutable value as a string
404 */
405 @Override
406 public String toString() {
407 return String.valueOf(value);
408 }
409
410 }