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 java.util.concurrent.atomic.AtomicLong;
20
21 import org.apache.commons.lang3.math.NumberUtils;
22
23 /**
24 * A mutable {@code long} wrapper.
25 * <p>
26 * This class was created before the introduction of {@link AtomicLong}.
27 * </p>
28 * <p>
29 * Note that as MutableLong does not extend {@link Long}, it is not treated by {@link String#format(String, Object...)} as a Long parameter.
30 * </p>
31 *
32 * @see Long
33 * @see AtomicLong
34 * @since 2.1
35 */
36 public class MutableLong extends Number implements Comparable<MutableLong>, Mutable<Number> {
37
38 /**
39 * Required for serialization support.
40 *
41 * @see java.io.Serializable
42 */
43 private static final long serialVersionUID = 62986528375L;
44
45 /** The mutable value. */
46 private long value;
47
48 /**
49 * Constructs a new MutableLong with the default value of zero.
50 */
51 public MutableLong() {
52 }
53
54 /**
55 * Constructs a new MutableLong with the specified value.
56 *
57 * @param value the initial value to store
58 */
59 public MutableLong(final long value) {
60 this.value = value;
61 }
62
63 /**
64 * Constructs a new MutableLong with the specified value.
65 *
66 * @param value the initial value to store, not null
67 * @throws NullPointerException if the object is null
68 */
69 public MutableLong(final Number value) {
70 this.value = value.longValue();
71 }
72
73 /**
74 * Constructs a new MutableLong parsing the given string.
75 *
76 * @param value the string to parse, not null
77 * @throws NumberFormatException if the string cannot be parsed into a long, see {@link Long#parseLong(String)}.
78 * @since 2.5
79 */
80 public MutableLong(final String value) {
81 this.value = Long.parseLong(value);
82 }
83
84 /**
85 * Adds a value to the value of this instance.
86 *
87 * @param operand the value to add, not null
88 * @since 2.2
89 */
90 public void add(final long operand) {
91 this.value += operand;
92 }
93
94 /**
95 * Adds a value to the value of this instance.
96 *
97 * @param operand the value to add, not null
98 * @throws NullPointerException if the object is null
99 * @since 2.2
100 */
101 public void add(final Number operand) {
102 this.value += operand.longValue();
103 }
104
105 /**
106 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
107 * immediately after the addition operation. This method is not thread safe.
108 *
109 * @param operand the quantity to add, not null
110 * @return the value associated with this instance after adding the operand
111 * @since 3.5
112 */
113 public long addAndGet(final long operand) {
114 this.value += operand;
115 return value;
116 }
117
118 /**
119 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
120 * immediately after the addition operation. This method is not thread safe.
121 *
122 * @param operand the quantity to add, not null
123 * @throws NullPointerException if {@code operand} is null
124 * @return the value associated with this instance after adding the operand
125 * @since 3.5
126 */
127 public long addAndGet(final Number operand) {
128 this.value += operand.longValue();
129 return value;
130 }
131
132 /**
133 * Compares this mutable to another in ascending order.
134 *
135 * @param other the other mutable to compare to, not null
136 * @return negative if this is less, zero if equal, positive if greater
137 */
138 @Override
139 public int compareTo(final MutableLong other) {
140 return NumberUtils.compare(this.value, other.value);
141 }
142
143 /**
144 * Decrements the value.
145 *
146 * @since 2.2
147 */
148 public void decrement() {
149 value--;
150 }
151
152 /**
153 * Decrements this instance's value by 1; this method returns the value associated with the instance
154 * immediately after the decrement operation. This method is not thread safe.
155 *
156 * @return the value associated with the instance after it is decremented
157 * @since 3.5
158 */
159 public long decrementAndGet() {
160 value--;
161 return value;
162 }
163
164 /**
165 * Returns the value of this MutableLong as a double.
166 *
167 * @return the numeric value represented by this object after conversion to type double.
168 */
169 @Override
170 public double doubleValue() {
171 return value;
172 }
173
174 /**
175 * Compares this object to the specified object. The result is {@code true} if and only if the argument
176 * is not {@code null} and is a {@link MutableLong} object that contains the same {@code long}
177 * value as this object.
178 *
179 * @param obj the object to compare with, null returns false
180 * @return {@code true} if the objects are the same; {@code false} otherwise.
181 */
182 @Override
183 public boolean equals(final Object obj) {
184 if (obj instanceof MutableLong) {
185 return value == ((MutableLong) obj).longValue();
186 }
187 return false;
188 }
189
190 /**
191 * Returns the value of this MutableLong as a float.
192 *
193 * @return the numeric value represented by this object after conversion to type float.
194 */
195 @Override
196 public float floatValue() {
197 return value;
198 }
199
200 /**
201 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
202 * immediately prior to the addition operation. This method is not thread safe.
203 *
204 * @param operand the quantity to add, not null
205 * @return the value associated with this instance immediately before the operand was added
206 * @since 3.5
207 */
208 public long getAndAdd(final long operand) {
209 final long last = value;
210 this.value += operand;
211 return last;
212 }
213
214 /**
215 * Increments this instance's value by {@code operand}; this method returns the value associated with the instance
216 * immediately prior to the addition operation. This method is not thread safe.
217 *
218 * @param operand the quantity to add, not null
219 * @throws NullPointerException if {@code operand} is null
220 * @return the value associated with this instance immediately before the operand was added
221 * @since 3.5
222 */
223 public long getAndAdd(final Number operand) {
224 final long last = value;
225 this.value += operand.longValue();
226 return last;
227 }
228
229 /**
230 * Decrements this instance's value by 1; this method returns the value associated with the instance
231 * immediately prior to the decrement operation. This method is not thread safe.
232 *
233 * @return the value associated with the instance before it was decremented
234 * @since 3.5
235 */
236 public long getAndDecrement() {
237 final long last = value;
238 value--;
239 return last;
240 }
241
242 /**
243 * Increments this instance's value by 1; this method returns the value associated with the instance
244 * immediately prior to the increment operation. This method is not thread safe.
245 *
246 * @return the value associated with the instance before it was incremented
247 * @since 3.5
248 */
249 public long getAndIncrement() {
250 final long last = value;
251 value++;
252 return last;
253 }
254
255 /**
256 * Gets the value as a Long instance.
257 *
258 * @return the value as a Long, never null.
259 * @deprecated Use {@link #get()}.
260 */
261 @Deprecated
262 @Override
263 public Long getValue() {
264 return Long.valueOf(this.value);
265 }
266
267 /**
268 * Returns a suitable hash code for this mutable.
269 *
270 * @return a suitable hash code
271 */
272 @Override
273 public int hashCode() {
274 return (int) (value ^ value >>> 32);
275 }
276
277 /**
278 * Increments the value.
279 *
280 * @since 2.2
281 */
282 public void increment() {
283 value++;
284 }
285
286 /**
287 * Increments this instance's value by 1; this method returns the value associated with the instance
288 * immediately after the increment operation. This method is not thread safe.
289 *
290 * @return the value associated with the instance after it is incremented
291 * @since 3.5
292 */
293 public long incrementAndGet() {
294 value++;
295 return value;
296 }
297
298 // shortValue and byteValue rely on Number implementation
299 /**
300 * Returns the value of this MutableLong as an int.
301 *
302 * @return the numeric value represented by this object after conversion to type int.
303 */
304 @Override
305 public int intValue() {
306 return (int) value;
307 }
308
309 /**
310 * Returns the value of this MutableLong as a long.
311 *
312 * @return the numeric value represented by this object after conversion to type long.
313 */
314 @Override
315 public long longValue() {
316 return value;
317 }
318
319 /**
320 * Sets the value.
321 *
322 * @param value the value to set
323 */
324 public void setValue(final long value) {
325 this.value = value;
326 }
327
328 /**
329 * Sets the value from any Number instance.
330 *
331 * @param value the value to set, not null
332 * @throws NullPointerException if the object is null
333 */
334 @Override
335 public void setValue(final Number value) {
336 this.value = value.longValue();
337 }
338
339 /**
340 * Subtracts a value from the value of this instance.
341 *
342 * @param operand the value to subtract, not null
343 * @since 2.2
344 */
345 public void subtract(final long operand) {
346 this.value -= operand;
347 }
348
349 /**
350 * Subtracts a value from the value of this instance.
351 *
352 * @param operand the value to subtract, not null
353 * @throws NullPointerException if the object is null
354 * @since 2.2
355 */
356 public void subtract(final Number operand) {
357 this.value -= operand.longValue();
358 }
359
360 /**
361 * Gets this mutable as an instance of Long.
362 *
363 * @return a Long instance containing the value from this mutable, never null
364 */
365 public Long toLong() {
366 return Long.valueOf(longValue());
367 }
368
369 /**
370 * Returns the String value of this mutable.
371 *
372 * @return the mutable value as a string
373 */
374 @Override
375 public String toString() {
376 return String.valueOf(value);
377 }
378
379 }