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    *      http://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
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      */
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 }