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; 019 020import com.google.common.annotations.GwtCompatible; 021import com.google.errorprone.annotations.CanIgnoreReturnValue; 022import java.io.Serializable; 023import java.math.BigInteger; 024import javax.annotation.CheckForNull; 025 026/** 027 * A wrapper class for unsigned {@code long} values, supporting arithmetic operations. 028 * 029 * <p>In some cases, when speed is more important than code readability, it may be faster simply to 030 * treat primitive {@code long} values as unsigned, using the methods from {@link UnsignedLongs}. 031 * 032 * <p>See the Guava User Guide article on <a 033 * href="https://github.com/google/guava/wiki/PrimitivesExplained#unsigned-support">unsigned 034 * primitive utilities</a>. 035 * 036 * @author Louis Wasserman 037 * @author Colin Evans 038 * @since 11.0 039 */ 040@GwtCompatible(serializable = true) 041@ElementTypesAreNonnullByDefault 042public final class UnsignedLong extends Number implements Comparable<UnsignedLong>, Serializable { 043 044 private static final long UNSIGNED_MASK = 0x7fffffffffffffffL; 045 046 public static final UnsignedLong ZERO = new UnsignedLong(0); 047 public static final UnsignedLong ONE = new UnsignedLong(1); 048 public static final UnsignedLong MAX_VALUE = new UnsignedLong(-1L); 049 050 private final long value; 051 052 private UnsignedLong(long value) { 053 this.value = value; 054 } 055 056 /** 057 * Returns an {@code UnsignedLong} corresponding to a given bit representation. The argument is 058 * interpreted as an unsigned 64-bit value. Specifically, the sign bit of {@code bits} is 059 * interpreted as a normal bit, and all other bits are treated as usual. 060 * 061 * <p>If the argument is nonnegative, the returned result will be equal to {@code bits}, 062 * otherwise, the result will be equal to {@code 2^64 + bits}. 063 * 064 * <p>To represent decimal constants less than {@code 2^63}, consider {@link #valueOf(long)} 065 * instead. 066 * 067 * @since 14.0 068 */ 069 public static UnsignedLong fromLongBits(long bits) { 070 // TODO(lowasser): consider caching small values, like Long.valueOf 071 return new UnsignedLong(bits); 072 } 073 074 /** 075 * Returns an {@code UnsignedLong} representing the same value as the specified {@code long}. 076 * 077 * @throws IllegalArgumentException if {@code value} is negative 078 * @since 14.0 079 */ 080 @CanIgnoreReturnValue 081 public static UnsignedLong valueOf(long value) { 082 checkArgument(value >= 0, "value (%s) is outside the range for an unsigned long value", value); 083 return fromLongBits(value); 084 } 085 086 /** 087 * Returns a {@code UnsignedLong} representing the same value as the specified {@code BigInteger}. 088 * This is the inverse operation of {@link #bigIntegerValue()}. 089 * 090 * @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^64} 091 */ 092 @CanIgnoreReturnValue 093 public static UnsignedLong valueOf(BigInteger value) { 094 checkNotNull(value); 095 checkArgument( 096 value.signum() >= 0 && value.bitLength() <= Long.SIZE, 097 "value (%s) is outside the range for an unsigned long value", 098 value); 099 return fromLongBits(value.longValue()); 100 } 101 102 /** 103 * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as an 104 * unsigned {@code long} value. 105 * 106 * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long} 107 * value 108 */ 109 @CanIgnoreReturnValue 110 public static UnsignedLong valueOf(String string) { 111 return valueOf(string, 10); 112 } 113 114 /** 115 * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as an 116 * unsigned {@code long} value in the specified radix. 117 * 118 * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long} 119 * value, or {@code radix} is not between {@link Character#MIN_RADIX} and {@link 120 * Character#MAX_RADIX} 121 */ 122 @CanIgnoreReturnValue 123 public static UnsignedLong valueOf(String string, int radix) { 124 return fromLongBits(UnsignedLongs.parseUnsignedLong(string, radix)); 125 } 126 127 /** 128 * Returns the result of adding this and {@code val}. If the result would have more than 64 bits, 129 * returns the low 64 bits of the result. 130 * 131 * @since 14.0 132 */ 133 public UnsignedLong plus(UnsignedLong val) { 134 return fromLongBits(this.value + checkNotNull(val).value); 135 } 136 137 /** 138 * Returns the result of subtracting this and {@code val}. If the result would have more than 64 139 * bits, returns the low 64 bits of the result. 140 * 141 * @since 14.0 142 */ 143 public UnsignedLong minus(UnsignedLong val) { 144 return fromLongBits(this.value - checkNotNull(val).value); 145 } 146 147 /** 148 * Returns the result of multiplying this and {@code val}. If the result would have more than 64 149 * bits, returns the low 64 bits of the result. 150 * 151 * @since 14.0 152 */ 153 public UnsignedLong times(UnsignedLong val) { 154 return fromLongBits(value * checkNotNull(val).value); 155 } 156 157 /** 158 * Returns the result of dividing this by {@code val}. 159 * 160 * @since 14.0 161 */ 162 public UnsignedLong dividedBy(UnsignedLong val) { 163 return fromLongBits(UnsignedLongs.divide(value, checkNotNull(val).value)); 164 } 165 166 /** 167 * Returns this modulo {@code val}. 168 * 169 * @since 14.0 170 */ 171 public UnsignedLong mod(UnsignedLong val) { 172 return fromLongBits(UnsignedLongs.remainder(value, checkNotNull(val).value)); 173 } 174 175 /** Returns the value of this {@code UnsignedLong} as an {@code int}. */ 176 @Override 177 public int intValue() { 178 return (int) value; 179 } 180 181 /** 182 * Returns the value of this {@code UnsignedLong} as a {@code long}. This is an inverse operation 183 * to {@link #fromLongBits}. 184 * 185 * <p>Note that if this {@code UnsignedLong} holds a value {@code >= 2^63}, the returned value 186 * will be equal to {@code this - 2^64}. 187 */ 188 @Override 189 public long longValue() { 190 return value; 191 } 192 193 /** 194 * Returns the value of this {@code UnsignedLong} as a {@code float}, analogous to a widening 195 * primitive conversion from {@code long} to {@code float}, and correctly rounded. 196 */ 197 @Override 198 public float floatValue() { 199 if (value >= 0) { 200 return (float) value; 201 } 202 // The top bit is set, which means that the float value is going to come from the top 24 bits. 203 // So we can ignore the bottom 8, except for rounding. See doubleValue() for more. 204 return (float) ((value >>> 1) | (value & 1)) * 2f; 205 } 206 207 /** 208 * Returns the value of this {@code UnsignedLong} as a {@code double}, analogous to a widening 209 * primitive conversion from {@code long} to {@code double}, and correctly rounded. 210 */ 211 @Override 212 public double doubleValue() { 213 if (value >= 0) { 214 return (double) value; 215 } 216 // The top bit is set, which means that the double value is going to come from the top 53 bits. 217 // So we can ignore the bottom 11, except for rounding. We can unsigned-shift right 1, aka 218 // unsigned-divide by 2, and convert that. Then we'll get exactly half of the desired double 219 // value. But in the specific case where the bottom two bits of the original number are 01, we 220 // want to replace that with 1 in the shifted value for correct rounding. 221 return (double) ((value >>> 1) | (value & 1)) * 2.0; 222 } 223 224 /** Returns the value of this {@code UnsignedLong} as a {@link BigInteger}. */ 225 public BigInteger bigIntegerValue() { 226 BigInteger bigInt = BigInteger.valueOf(value & UNSIGNED_MASK); 227 if (value < 0) { 228 bigInt = bigInt.setBit(Long.SIZE - 1); 229 } 230 return bigInt; 231 } 232 233 @Override 234 public int compareTo(UnsignedLong o) { 235 checkNotNull(o); 236 return UnsignedLongs.compare(value, o.value); 237 } 238 239 @Override 240 public int hashCode() { 241 return Longs.hashCode(value); 242 } 243 244 @Override 245 public boolean equals(@CheckForNull Object obj) { 246 if (obj instanceof UnsignedLong) { 247 UnsignedLong other = (UnsignedLong) obj; 248 return value == other.value; 249 } 250 return false; 251 } 252 253 /** Returns a string representation of the {@code UnsignedLong} value, in base 10. */ 254 @Override 255 public String toString() { 256 return UnsignedLongs.toString(value); 257 } 258 259 /** 260 * Returns a string representation of the {@code UnsignedLong} value, in base {@code radix}. If 261 * {@code radix < Character.MIN_RADIX} or {@code radix > Character.MAX_RADIX}, the radix {@code 262 * 10} is used. 263 */ 264 public String toString(int radix) { 265 return UnsignedLongs.toString(value, radix); 266 } 267}