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