    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 byte} wrapper.
    023 * <p>
    024 * Note that as MutableByte does not extend Byte, it is not treated by String.format as a Byte parameter.
    025 *
    026 * @see Byte
    027 * @since 2.1
    028 */
    029public class MutableByte extends Number implements Comparable<MutableByte>, Mutable<Number> {
    030
    031    /**
    032     * Required for serialization support.
    033     *
    034     * @see java.io.Serializable
    035     */
    036    private static final long serialVersionUID = -1585823265L;
    037
    038    /** The mutable value. */
    039    private byte value;
    040
    041    /**
    042     * Constructs a new MutableByte with the default value of zero.
    043     */
    044    public MutableByte() {
    045        super();
    046    }
    047
    048    /**
    049     * Constructs a new MutableByte with the specified value.
    050     *
    051     * @param value  the initial value to store
    052     */
    053    public MutableByte(final byte value) {
    054        super();
    055        this.value = value;
    056    }
    057
    058    /**
    059     * Constructs a new MutableByte 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 MutableByte(final Number value) {
    065        super();
    066        this.value = value.byteValue();
    067    }
    068
    069    /**
    070     * Constructs a new MutableByte parsing the given string.
    071     *
    072     * @param value  the string to parse, not null
    073     * @throws NumberFormatException if the string cannot be parsed into a byte
    074     * @since 2.5
    075     */
    076    public MutableByte(final String value) {
    077        super();
    078        this.value = Byte.parseByte(value);
    079    }
    080
    081    //-----------------------------------------------------------------------
    082    /**
    083     * Gets the value as a Byte instance.
    084     *
    085     * @return the value as a Byte, never null
    086     */
    087    @Override
    088    public Byte getValue() {
    089        return Byte.valueOf(this.value);
    090    }
    091
    092    /**
    093     * Sets the value.
    094     *
    095     * @param value  the value to set
    096     */
    097    public void setValue(final byte 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.byteValue();
    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 byte getAndIncrement() {
    130        final byte 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 byte 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 byte getAndDecrement() {
    164        final byte 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 byte 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 byte 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.byteValue();
    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 byte 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.byteValue();
    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 byte addAndGet(final byte 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 byte addAndGet(final Number operand) {
    247        this.value += operand.byteValue();
    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 byte getAndAdd(final byte operand) {
    260        final byte 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 byte getAndAdd(final Number operand) {
    275        final byte last = value;
    276        this.value += operand.byteValue();
    277        return last;
    278    }
    279
    280    //-----------------------------------------------------------------------
    281    // shortValue relies on Number implementation
    282    /**
    283     * Returns the value of this MutableByte as a byte.
    284     *
    285     * @return the numeric value represented by this object after conversion to type byte.
    286     */
    287    @Override
    288    public byte byteValue() {
    289        return value;
    290    }
    291
    292    /**
    293     * Returns the value of this MutableByte as an int.
    294     *
    295     * @return the numeric value represented by this object after conversion to type int.
    296     */
    297    @Override
    298    public int intValue() {
    299        return value;
    300    }
    301
    302    /**
    303     * Returns the value of this MutableByte as a long.
    304     *
    305     * @return the numeric value represented by this object after conversion to type long.
    306     */
    307    @Override
    308    public long longValue() {
    309        return value;
    310    }
    311
    312    /**
    313     * Returns the value of this MutableByte as a float.
    314     *
    315     * @return the numeric value represented by this object after conversion to type float.
    316     */
    317    @Override
    318    public float floatValue() {
    319        return value;
    320    }
    321
    322    /**
    323     * Returns the value of this MutableByte as a double.
    324     *
    325     * @return the numeric value represented by this object after conversion to type double.
    326     */
    327    @Override
    328    public double doubleValue() {
    329        return value;
    330    }
    331
    332    //-----------------------------------------------------------------------
    333    /**
    334     * Gets this mutable as an instance of Byte.
    335     *
    336     * @return a Byte instance containing the value from this mutable
    337     */
    338    public Byte toByte() {
    339        return Byte.valueOf(byteValue());
    340    }
    341
    342    //-----------------------------------------------------------------------
    343    /**
    344     * Compares this object to the specified object. The result is {@code true} if and only if the argument is
    345     * not {@code null} and is a {@code MutableByte} object that contains the same {@code byte} value
    346     * as this object.
    347     *
    348     * @param obj  the object to compare with, null returns false
    349     * @return {@code true} if the objects are the same; {@code false} otherwise.
    350     */
    351    @Override
    352    public boolean equals(final Object obj) {
    353        if (obj instanceof MutableByte) {
    354            return value == ((MutableByte) obj).byteValue();
    355        }
    356        return false;
    357    }
    358
    359    /**
    360     * Returns a suitable hash code for this mutable.
    361     *
    362     * @return a suitable hash code
    363     */
    364    @Override
    365    public int hashCode() {
    366        return value;
    367    }
    368
    369    //-----------------------------------------------------------------------
    370    /**
    371     * Compares this mutable to another in ascending order.
    372     *
    373     * @param other  the other mutable to compare to, not null
    374     * @return negative if this is less, zero if equal, positive if greater
    375     */
    376    @Override
    377    public int compareTo(final MutableByte other) {
    378        return NumberUtils.compare(this.value, other.value);
    379    }
    380
    381    //-----------------------------------------------------------------------
    382    /**
    383     * Returns the String value of this mutable.
    384     *
    385     * @return the mutable value as a string
    386     */
    387    @Override
    388    public String toString() {
    389        return String.valueOf(value);
    390    }
    391
    392}