    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}