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