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