1 /*
2 * Copyright (C) 2011 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.primitives;
16
17 import static com.google.common.base.Preconditions.checkArgument;
18 import static com.google.common.base.Preconditions.checkNotNull;
19 import static com.google.common.primitives.UnsignedInts.INT_MASK;
20 import static com.google.common.primitives.UnsignedInts.compare;
21 import static com.google.common.primitives.UnsignedInts.toLong;
22
23 import com.google.common.annotations.GwtCompatible;
24 import com.google.common.annotations.GwtIncompatible;
25 import java.math.BigInteger;
26 import javax.annotation.CheckForNull;
27
28 /**
29 * A wrapper class for unsigned {@code int} values, supporting arithmetic operations.
30 *
31 * <p>In some cases, when speed is more important than code readability, it may be faster simply to
32 * treat primitive {@code int} values as unsigned, using the methods from {@link UnsignedInts}.
33 *
34 * <p>See the Guava User Guide article on <a
35 * href="https://github.com/google/guava/wiki/PrimitivesExplained#unsigned-support">unsigned
36 * primitive utilities</a>.
37 *
38 * @author Louis Wasserman
39 * @since 11.0
40 */
41 @GwtCompatible(emulated = true)
42 @ElementTypesAreNonnullByDefault
43 public final class UnsignedInteger extends Number implements Comparable<UnsignedInteger> {
44 public static final UnsignedInteger ZERO = fromIntBits(0);
45 public static final UnsignedInteger ONE = fromIntBits(1);
46 public static final UnsignedInteger MAX_VALUE = fromIntBits(-1);
47
48 private final int value;
49
50 private UnsignedInteger(int value) {
51 // GWT doesn't consistently overflow values to make them 32-bit, so we need to force it.
52 this.value = value & 0xffffffff;
53 }
54
55 /**
56 * Returns an {@code UnsignedInteger} corresponding to a given bit representation. The argument is
57 * interpreted as an unsigned 32-bit value. Specifically, the sign bit of {@code bits} is
58 * interpreted as a normal bit, and all other bits are treated as usual.
59 *
60 * <p>If the argument is nonnegative, the returned result will be equal to {@code bits},
61 * otherwise, the result will be equal to {@code 2^32 + bits}.
62 *
63 * <p>To represent unsigned decimal constants, consider {@link #valueOf(long)} instead.
64 *
65 * @since 14.0
66 */
67 public static UnsignedInteger fromIntBits(int bits) {
68 return new UnsignedInteger(bits);
69 }
70
71 /**
72 * Returns an {@code UnsignedInteger} that is equal to {@code value}, if possible. The inverse
73 * operation of {@link #longValue()}.
74 */
75 public static UnsignedInteger valueOf(long value) {
76 checkArgument(
77 (value & INT_MASK) == value,
78 "value (%s) is outside the range for an unsigned integer value",
79 value);
80 return fromIntBits((int) value);
81 }
82
83 /**
84 * Returns a {@code UnsignedInteger} representing the same value as the specified {@link
85 * BigInteger}. This is the inverse operation of {@link #bigIntegerValue()}.
86 *
87 * @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^32}
88 */
89 public static UnsignedInteger valueOf(BigInteger value) {
90 checkNotNull(value);
91 checkArgument(
92 value.signum() >= 0 && value.bitLength() <= Integer.SIZE,
93 "value (%s) is outside the range for an unsigned integer value",
94 value);
95 return fromIntBits(value.intValue());
96 }
97
98 /**
99 * 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 }