Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      https://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.mutable;
018
019import java.util.concurrent.atomic.AtomicInteger;
020
021/**
022 * A mutable {@code int} wrapper.
023 * <p>
024 * This class was created before the introduction of the the {@link java.util.concurrent.atomic} package and the {@link AtomicInteger} class.
025 * </p>
026 * <p>
027 * Note that as MutableInt does not extend {@link Integer}, it is not treated by {@link String#format(String, Object...)} as an Integer parameter.
028 * </p>
029 *
030 * @see Integer
031 * @see AtomicInteger
032 * @since 2.1
033 */
034public class MutableInt extends Number implements Comparable<MutableInt>, Mutable<Number> {
035
036    /**
037     * Required for serialization support.
038     *
039     * @see java.io.Serializable
040     */
041    private static final long serialVersionUID = 512176391864L;
042
043    /** The mutable value. */
044    private int value;
045
046    /**
047     * Constructs a new MutableInt with the default value of zero.
048     */
049    public MutableInt() {
050    }
051
052    /**
053     * Constructs a new MutableInt with the specified value.
054     *
055     * @param value  the initial value to store.
056     */
057    public MutableInt(final int value) {
058        this.value = value;
059    }
060
061    /**
062     * Constructs a new MutableInt with the specified value.
063     *
064     * @param value  the initial value to store, not null.
065     * @throws NullPointerException if the object is null.
066     */
067    public MutableInt(final Number value) {
068        this.value = value.intValue();
069    }
070
071    /**
072     * Constructs a new MutableInt parsing the given string.
073     *
074     * @param value  the string to parse, not null.
075     * @throws NumberFormatException if the string cannot be parsed into an int, see {@link Integer#parseInt(String)}.
076     * @since 2.5
077     */
078    public MutableInt(final String value) {
079        this.value = Integer.parseInt(value);
080    }
081
082    /**
083     * Adds a value to the value of this instance.
084     *
085     * @param operand  the value to add, not null.
086     * @since 2.2
087     */
088    public void add(final int operand) {
089        this.value += operand;
090    }
091
092    /**
093     * Adds a value to the value of this instance.
094     *
095     * @param operand  the value to add, not null.
096     * @throws NullPointerException if the object is null.
097     * @since 2.2
098     */
099    public void add(final Number operand) {
100        this.value += operand.intValue();
101    }
102
103    /**
104     * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
105     * immediately after the addition operation. This method is not thread safe.
106     *
107     * @param operand the quantity to add, not null.
108     * @return the value associated with this instance after adding the operand.
109     * @since 3.5
110     */
111    public int addAndGet(final int operand) {
112        this.value += operand;
113        return value;
114    }
115
116    /**
117     * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
118     * immediately after the addition operation. This method is not thread safe.
119     *
120     * @param operand the quantity to add, not null.
121     * @throws NullPointerException if {@code operand} is null.
122     * @return the value associated with this instance after adding the operand.
123     * @since 3.5
124     */
125    public int addAndGet(final Number operand) {
126        this.value += operand.intValue();
127        return value;
128    }
129
130    /**
131     * Compares this mutable to another in ascending order.
132     *
133     * @param other  the other mutable to compare to, not null.
134     * @return negative if this is less, zero if equal, positive if greater.
135     */
136    @Override
137    public int compareTo(final MutableInt other) {
138        return Integer.compare(this.value, other.value);
139    }
140
141    /**
142     * Decrements the value.
143     *
144     * @since 2.2
145     */
146    public void decrement() {
147        value--;
148    }
149
150    /**
151     * Decrements this instance's value by 1; this method returns the value associated with the instance
152     * immediately after the decrement operation. This method is not thread safe.
153     *
154     * @return the value associated with the instance after it is decremented.
155     * @since 3.5
156     */
157    public int decrementAndGet() {
158        value--;
159        return value;
160    }
161
162    /**
163     * Returns the value of this MutableInt as a double.
164     *
165     * @return the numeric value represented by this object after conversion to type double.
166     */
167    @Override
168    public double doubleValue() {
169        return value;
170    }
171
172    /**
173     * Compares this object to the specified object. The result is {@code true} if and only if the argument is
174     * not {@code null} and is a {@link MutableInt} object that contains the same {@code int} value
175     * as this object.
176     *
177     * @param obj  the object to compare with, null returns false.
178     * @return {@code true} if the objects are the same; {@code false} otherwise.
179     */
180    @Override
181    public boolean equals(final Object obj) {
182        if (obj instanceof MutableInt) {
183            return value == ((MutableInt) obj).intValue();
184        }
185        return false;
186    }
187
188    /**
189     * Returns the value of this MutableInt as a float.
190     *
191     * @return the numeric value represented by this object after conversion to type float.
192     */
193    @Override
194    public float floatValue() {
195        return value;
196    }
197
198    /**
199     * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
200     * immediately prior to the addition operation. This method is not thread safe.
201     *
202     * @param operand the quantity to add, not null.
203     * @return the value associated with this instance immediately before the operand was added.
204     * @since 3.5
205     */
206    public int getAndAdd(final int operand) {
207        final int last = value;
208        this.value += operand;
209        return last;
210    }
211
212    /**
213     * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
214     * immediately prior to the addition operation. This method is not thread safe.
215     *
216     * @param operand the quantity to add, not null.
217     * @throws NullPointerException if {@code operand} is null.
218     * @return the value associated with this instance immediately before the operand was added.
219     * @since 3.5
220     */
221    public int getAndAdd(final Number operand) {
222        final int last = value;
223        this.value += operand.intValue();
224        return last;
225    }
226
227    /**
228     * Decrements this instance's value by 1; this method returns the value associated with the instance
229     * immediately prior to the decrement operation. This method is not thread safe.
230     *
231     * @return the value associated with the instance before it was decremented.
232     * @since 3.5
233     */
234    public int getAndDecrement() {
235        final int last = value;
236        value--;
237        return last;
238    }
239
240    /**
241     * Increments this instance's value by 1; this method returns the value associated with the instance
242     * immediately prior to the increment operation. This method is not thread safe.
243     *
244     * @return the value associated with the instance before it was incremented.
245     * @since 3.5
246     */
247    public int getAndIncrement() {
248        final int last = value;
249        value++;
250        return last;
251    }
252
253    /**
254     * Gets the value as a Integer instance.
255     *
256     * @return the value as a Integer, never null.
257     * @deprecated Use {@link #get()}.
258     */
259    @Deprecated
260    @Override
261    public Integer getValue() {
262        return Integer.valueOf(this.value);
263    }
264
265    /**
266     * Returns a suitable hash code for this mutable.
267     *
268     * @return a suitable hash code.
269     */
270    @Override
271    public int hashCode() {
272        return value;
273    }
274
275    /**
276     * Increments the value.
277     *
278     * @since 2.2
279     */
280    public void increment() {
281        value++;
282    }
283
284    /**
285     * Increments this instance's value by 1; this method returns the value associated with the instance
286     * immediately after the increment operation. This method is not thread safe.
287     *
288     * @return the value associated with the instance after it is incremented.
289     * @since 3.5
290     */
291    public int incrementAndGet() {
292        value++;
293        return value;
294    }
295
296    // shortValue and byteValue rely on Number implementation
297    /**
298     * Returns the value of this MutableInt as an int.
299     *
300     * @return the numeric value represented by this object after conversion to type int.
301     */
302    @Override
303    public int intValue() {
304        return value;
305    }
306
307    /**
308     * Returns the value of this MutableInt as a long.
309     *
310     * @return the numeric value represented by this object after conversion to type long.
311     */
312    @Override
313    public long longValue() {
314        return value;
315    }
316
317    /**
318     * Sets the value.
319     *
320     * @param value  the value to set.
321     */
322    public void setValue(final int value) {
323        this.value = value;
324    }
325
326    /**
327     * Sets the value from any Number instance.
328     *
329     * @param value  the value to set, not null.
330     * @throws NullPointerException if the object is null.
331     */
332    @Override
333    public void setValue(final Number value) {
334        this.value = value.intValue();
335    }
336
337    /**
338     * Subtracts a value from the value of this instance.
339     *
340     * @param operand  the value to subtract, not null.
341     * @since 2.2
342     */
343    public void subtract(final int operand) {
344        this.value -= operand;
345    }
346
347    /**
348     * Subtracts a value from the value of this instance.
349     *
350     * @param operand  the value to subtract, not null.
351     * @throws NullPointerException if the object is null.
352     * @since 2.2
353     */
354    public void subtract(final Number operand) {
355        this.value -= operand.intValue();
356    }
357
358    /**
359     * Gets this mutable as an instance of Integer.
360     *
361     * @return an Integer instance containing the value from this mutable, never null.
362     */
363    public Integer toInteger() {
364        return Integer.valueOf(intValue());
365    }
366
367    /**
368     * Returns the String value of this mutable.
369     *
370     * @return the mutable value as a string.
371     */
372    @Override
373    public String toString() {
374        return String.valueOf(value);
375    }
376
377}