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