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