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