Source code

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 {@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 Thrown 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 Thrown 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 Thrown 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 Thrown 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     * Gets this instance's current value, then adds {@code operand}. This method is not thread-safe.
211     *
212     * @param operand The quantity to add, not null.
213     * @return The value associated with this instance immediately before the operand was added.
214     * @since 3.5
215     */
216    public byte getAndAdd(final byte operand) {
217        final byte last = value;
218        this.value += operand;
219        return last;
220    }
221
222    /**
223     * Gets this instance's current value, then adds {@code operand}. This method is not thread-safe.
224     *
225     * @param operand The quantity to add, not null.
226     * @throws NullPointerException Thrown if {@code operand} is null.
227     * @return The value associated with this instance immediately before the operand was added.
228     * @since 3.5
229     */
230    public byte getAndAdd(final Number operand) {
231        final byte last = value;
232        this.value += operand.byteValue();
233        return last;
234    }
235
236    /**
237     * Gets this instance's current value, then decrements it by 1. This method is not thread-safe.
238     *
239     * @return The value associated with the instance before it was decremented.
240     * @since 3.5
241     */
242    public byte getAndDecrement() {
243        final byte last = value;
244        value--;
245        return last;
246    }
247
248    /**
249     * Gets this instance's current value, then increments it by 1. 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     * @deprecated Use {@link #get()}.
265     */
266    @Deprecated
267    @Override
268    public Byte getValue() {
269        return Byte.valueOf(this.value);
270    }
271
272    /**
273     * Returns a suitable hash code for this mutable.
274     *
275     * @return A suitable hash code.
276     */
277    @Override
278    public int hashCode() {
279        return value;
280    }
281
282    /**
283     * Increments the value.
284     *
285     * @since 2.2
286     */
287    public void increment() {
288        value++;
289    }
290
291    /**
292     * Increments this instance's value by 1; this method returns the value associated with the instance
293     * immediately after the increment operation. This method is not thread safe.
294     *
295     * @return The value associated with the instance after it is incremented.
296     * @since 3.5
297     */
298    public byte incrementAndGet() {
299        value++;
300        return value;
301    }
302
303    /**
304     * Returns the value of this MutableByte as an int.
305     *
306     * @return The numeric value represented by this object after conversion to type int.
307     */
308    @Override
309    public int intValue() {
310        return value;
311    }
312
313    /**
314     * Returns the value of this MutableByte as a long.
315     *
316     * @return The numeric value represented by this object after conversion to type long.
317     */
318    @Override
319    public long longValue() {
320        return value;
321    }
322
323    /**
324     * Sets the value.
325     *
326     * @param value  The value to set.
327     */
328    public void setValue(final byte value) {
329        this.value = value;
330    }
331
332    /**
333     * Sets the value from any Number instance.
334     *
335     * @param value  The value to set, not null.
336     * @throws NullPointerException Thrown if the object is null.
337     */
338    @Override
339    public void setValue(final Number value) {
340        this.value = value.byteValue();
341    }
342
343    /**
344     * Subtracts a value from the value of this instance.
345     *
346     * @param operand  The value to subtract, not null.
347     * @since 2.2
348     */
349    public void subtract(final byte operand) {
350        this.value -= operand;
351    }
352
353    /**
354     * Subtracts a value from the value of this instance.
355     *
356     * @param operand  The value to subtract, not null.
357     * @throws NullPointerException Thrown if the object is null.
358     * @since 2.2
359     */
360    public void subtract(final Number operand) {
361        this.value -= operand.byteValue();
362    }
363
364    /**
365     * Gets this mutable as an instance of Byte.
366     *
367     * @return A Byte instance containing the value from this mutable.
368     */
369    public Byte toByte() {
370        return Byte.valueOf(byteValue());
371    }
372
373    /**
374     * Returns the String value of this mutable.
375     *
376     * @return The mutable value as a string.
377     */
378    @Override
379    public String toString() {
380        return String.valueOf(value);
381    }
382
383}