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}