001/*
002 * Copyright (C) 2011 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.primitives;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static com.google.common.primitives.UnsignedInts.INT_MASK;
020import static com.google.common.primitives.UnsignedInts.compare;
021import static com.google.common.primitives.UnsignedInts.toLong;
022
023import com.google.common.annotations.GwtCompatible;
024import com.google.common.annotations.GwtIncompatible;
025import java.math.BigInteger;
026import javax.annotation.CheckForNull;
027
028/**
029 * A wrapper class for unsigned {@code int} values, supporting arithmetic operations.
030 *
031 * <p>In some cases, when speed is more important than code readability, it may be faster simply to
032 * treat primitive {@code int} values as unsigned, using the methods from {@link UnsignedInts}.
033 *
034 * <p>See the Guava User Guide article on <a
035 * href="https://github.com/google/guava/wiki/PrimitivesExplained#unsigned-support">unsigned
036 * primitive utilities</a>.
037 *
038 * @author Louis Wasserman
039 * @since 11.0
040 */
041@GwtCompatible(emulated = true)
042@ElementTypesAreNonnullByDefault
043public final class UnsignedInteger extends Number implements Comparable<UnsignedInteger> {
044  public static final UnsignedInteger ZERO = fromIntBits(0);
045  public static final UnsignedInteger ONE = fromIntBits(1);
046  public static final UnsignedInteger MAX_VALUE = fromIntBits(-1);
047
048  private final int value;
049
050  private UnsignedInteger(int value) {
051    // GWT doesn't consistently overflow values to make them 32-bit, so we need to force it.
052    this.value = value & 0xffffffff;
053  }
054
055  /**
056   * Returns an {@code UnsignedInteger} corresponding to a given bit representation. The argument is
057   * interpreted as an unsigned 32-bit value. Specifically, the sign bit of {@code bits} is
058   * interpreted as a normal bit, and all other bits are treated as usual.
059   *
060   * <p>If the argument is nonnegative, the returned result will be equal to {@code bits},
061   * otherwise, the result will be equal to {@code 2^32 + bits}.
062   *
063   * <p>To represent unsigned decimal constants, consider {@link #valueOf(long)} instead.
064   *
065   * @since 14.0
066   */
067  public static UnsignedInteger fromIntBits(int bits) {
068    return new UnsignedInteger(bits);
069  }
070
071  /**
072   * Returns an {@code UnsignedInteger} that is equal to {@code value}, if possible. The inverse
073   * operation of {@link #longValue()}.
074   */
075  public static UnsignedInteger valueOf(long value) {
076    checkArgument(
077        (value & INT_MASK) == value,
078        "value (%s) is outside the range for an unsigned integer value",
079        value);
080    return fromIntBits((int) value);
081  }
082
083  /**
084   * Returns a {@code UnsignedInteger} representing the same value as the specified {@link
085   * BigInteger}. This is the inverse operation of {@link #bigIntegerValue()}.
086   *
087   * @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^32}
088   */
089  public static UnsignedInteger valueOf(BigInteger value) {
090    checkNotNull(value);
091    checkArgument(
092        value.signum() >= 0 && value.bitLength() <= Integer.SIZE,
093        "value (%s) is outside the range for an unsigned integer value",
094        value);
095    return fromIntBits(value.intValue());
096  }
097
098  /**
099   * Returns an {@code UnsignedInteger} holding the value of the specified {@code String}, parsed as
100   * an unsigned {@code int} value.
101   *
102   * @throws NumberFormatException if the string does not contain a parsable unsigned {@code int}
103   *     value
104   */
105  public static UnsignedInteger valueOf(String string) {
106    return valueOf(string, 10);
107  }
108
109  /**
110   * Returns an {@code UnsignedInteger} holding the value of the specified {@code String}, parsed as
111   * an unsigned {@code int} value in the specified radix.
112   *
113   * @throws NumberFormatException if the string does not contain a parsable unsigned {@code int}
114   *     value
115   */
116  public static UnsignedInteger valueOf(String string, int radix) {
117    return fromIntBits(UnsignedInts.parseUnsignedInt(string, radix));
118  }
119
120  /**
121   * Returns the result of adding this and {@code val}. If the result would have more than 32 bits,
122   * returns the low 32 bits of the result.
123   *
124   * @since 14.0
125   */
126  public UnsignedInteger plus(UnsignedInteger val) {
127    return fromIntBits(this.value + checkNotNull(val).value);
128  }
129
130  /**
131   * Returns the result of subtracting this and {@code val}. If the result would be negative,
132   * returns the low 32 bits of the result.
133   *
134   * @since 14.0
135   */
136  public UnsignedInteger minus(UnsignedInteger val) {
137    return fromIntBits(value - checkNotNull(val).value);
138  }
139
140  /**
141   * Returns the result of multiplying this and {@code val}. If the result would have more than 32
142   * bits, returns the low 32 bits of the result.
143   *
144   * @since 14.0
145   */
146  @GwtIncompatible // Does not truncate correctly
147  public UnsignedInteger times(UnsignedInteger val) {
148    // TODO(lowasser): make this GWT-compatible
149    return fromIntBits(value * checkNotNull(val).value);
150  }
151
152  /**
153   * Returns the result of dividing this by {@code val}.
154   *
155   * @throws ArithmeticException if {@code val} is zero
156   * @since 14.0
157   */
158  public UnsignedInteger dividedBy(UnsignedInteger val) {
159    return fromIntBits(UnsignedInts.divide(value, checkNotNull(val).value));
160  }
161
162  /**
163   * Returns this mod {@code val}.
164   *
165   * @throws ArithmeticException if {@code val} is zero
166   * @since 14.0
167   */
168  public UnsignedInteger mod(UnsignedInteger val) {
169    return fromIntBits(UnsignedInts.remainder(value, checkNotNull(val).value));
170  }
171
172  /**
173   * Returns the value of this {@code UnsignedInteger} as an {@code int}. This is an inverse
174   * operation to {@link #fromIntBits}.
175   *
176   * <p>Note that if this {@code UnsignedInteger} holds a value {@code >= 2^31}, the returned value
177   * will be equal to {@code this - 2^32}.
178   */
179  @Override
180  public int intValue() {
181    return value;
182  }
183
184  /** Returns the value of this {@code UnsignedInteger} as a {@code long}. */
185  @Override
186  public long longValue() {
187    return toLong(value);
188  }
189
190  /**
191   * Returns the value of this {@code UnsignedInteger} as a {@code float}, analogous to a widening
192   * primitive conversion from {@code int} to {@code float}, and correctly rounded.
193   */
194  @Override
195  public float floatValue() {
196    return longValue();
197  }
198
199  /**
200   * Returns the value of this {@code UnsignedInteger} as a {@code float}, analogous to a widening
201   * primitive conversion from {@code int} to {@code double}, and correctly rounded.
202   */
203  @Override
204  public double doubleValue() {
205    return longValue();
206  }
207
208  /** Returns the value of this {@code UnsignedInteger} as a {@link BigInteger}. */
209  public BigInteger bigIntegerValue() {
210    return BigInteger.valueOf(longValue());
211  }
212
213  /**
214   * Compares this unsigned integer to another unsigned integer. Returns {@code 0} if they are
215   * equal, a negative number if {@code this < other}, and a positive number if {@code this >
216   * other}.
217   */
218  @Override
219  public int compareTo(UnsignedInteger other) {
220    checkNotNull(other);
221    return compare(value, other.value);
222  }
223
224  @Override
225  public int hashCode() {
226    return value;
227  }
228
229  @Override
230  public boolean equals(@CheckForNull Object obj) {
231    if (obj instanceof UnsignedInteger) {
232      UnsignedInteger other = (UnsignedInteger) obj;
233      return value == other.value;
234    }
235    return false;
236  }
237
238  /** Returns a string representation of the {@code UnsignedInteger} value, in base 10. */
239  @Override
240  public String toString() {
241    return toString(10);
242  }
243
244  /**
245   * Returns a string representation of the {@code UnsignedInteger} value, in base {@code radix}. If
246   * {@code radix < Character.MIN_RADIX} or {@code radix > Character.MAX_RADIX}, the radix {@code
247   * 10} is used.
248   */
249  public String toString(int radix) {
250    return UnsignedInts.toString(value, radix);
251  }
252}