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.CheckForNull; 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 <a 035 * 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) 042@ElementTypesAreNonnullByDefault 043public final class UnsignedInteger extends Number implements Comparable<UnsignedInteger> { 044 public static final UnsignedInteger ZERO = fromIntBits(0); 045 public static final UnsignedInteger ONE = fromIntBits(1); 046 public static final UnsignedInteger MAX_VALUE = fromIntBits(-1); 047 048 private final int value; 049 050 private UnsignedInteger(int value) { 051 // GWT doesn't consistently overflow values to make them 32-bit, so we need to force it. 052 this.value = value & 0xffffffff; 053 } 054 055 /** 056 * Returns an {@code UnsignedInteger} corresponding to a given bit representation. The argument is 057 * interpreted as an unsigned 32-bit value. Specifically, the sign bit of {@code bits} is 058 * interpreted as a normal bit, and all other bits are treated as usual. 059 * 060 * <p>If the argument is nonnegative, the returned result will be equal to {@code bits}, 061 * otherwise, the result will be equal to {@code 2^32 + bits}. 062 * 063 * <p>To represent unsigned decimal constants, consider {@link #valueOf(long)} instead. 064 * 065 * @since 14.0 066 */ 067 public static UnsignedInteger fromIntBits(int bits) { 068 return new UnsignedInteger(bits); 069 } 070 071 /** 072 * Returns an {@code UnsignedInteger} that is equal to {@code value}, if possible. The inverse 073 * operation of {@link #longValue()}. 074 */ 075 public static UnsignedInteger valueOf(long value) { 076 checkArgument( 077 (value & INT_MASK) == value, 078 "value (%s) is outside the range for an unsigned integer value", 079 value); 080 return fromIntBits((int) value); 081 } 082 083 /** 084 * Returns a {@code UnsignedInteger} representing the same value as the specified {@link 085 * BigInteger}. This is the inverse operation of {@link #bigIntegerValue()}. 086 * 087 * @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^32} 088 */ 089 public static UnsignedInteger valueOf(BigInteger value) { 090 checkNotNull(value); 091 checkArgument( 092 value.signum() >= 0 && value.bitLength() <= Integer.SIZE, 093 "value (%s) is outside the range for an unsigned integer value", 094 value); 095 return fromIntBits(value.intValue()); 096 } 097 098 /** 099 * 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}