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