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