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