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