View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.mutable;
18  
19  import org.apache.commons.lang3.math.NumberUtils;
20  
21  /**
22   * A mutable {@code byte} wrapper.
23   * <p>
24   * Note that as MutableByte does not extend Byte, it is not treated by String.format as a Byte parameter.
25   * </p>
26   *
27   * @see Byte
28   * @since 2.1
29   */
30  public class MutableByte extends Number implements Comparable<MutableByte>, Mutable<Number> {
31  
32      /**
33       * Required for serialization support.
34       *
35       * @see java.io.Serializable
36       */
37      private static final long serialVersionUID = -1585823265L;
38  
39      /** The mutable value. */
40      private byte value;
41  
42      /**
43       * Constructs a new MutableByte with the default value of zero.
44       */
45      public MutableByte() {
46      }
47  
48      /**
49       * Constructs a new MutableByte with the specified value.
50       *
51       * @param value  the initial value to store
52       */
53      public MutableByte(final byte value) {
54          this.value = value;
55      }
56  
57      /**
58       * Constructs a new MutableByte with the specified value.
59       *
60       * @param value  the initial value to store, not null
61       * @throws NullPointerException if the object is null
62       */
63      public MutableByte(final Number value) {
64          this.value = value.byteValue();
65      }
66  
67      /**
68       * Constructs a new MutableByte parsing the given string.
69       *
70       * @param value  the string to parse, not null
71       * @throws NumberFormatException if the string cannot be parsed into a byte, see {@link Byte#parseByte(String)}.
72       * @since 2.5
73       */
74      public MutableByte(final String value) {
75          this.value = Byte.parseByte(value);
76      }
77  
78      /**
79       * Adds a value to the value of this instance.
80       *
81       * @param operand  the value to add, not null
82       * @since 2.2
83       */
84      public void add(final byte operand) {
85          this.value += operand;
86      }
87  
88      /**
89       * Adds a value to the value of this instance.
90       *
91       * @param operand  the value to add, not null
92       * @throws NullPointerException if the object is null
93       * @since 2.2
94       */
95      public void add(final Number operand) {
96          this.value += operand.byteValue();
97      }
98  
99      /**
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      * @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 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 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 }