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