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.Nullable; 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 033 * <a 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) 041public final class UnsignedLong extends Number implements Comparable<UnsignedLong>, Serializable { 042 043 private static final long UNSIGNED_MASK = 0x7fffffffffffffffL; 044 045 public static final UnsignedLong ZERO = new UnsignedLong(0); 046 public static final UnsignedLong ONE = new UnsignedLong(1); 047 public static final UnsignedLong MAX_VALUE = new UnsignedLong(-1L); 048 049 private final long value; 050 051 private UnsignedLong(long value) { 052 this.value = value; 053 } 054 055 /** 056 * Returns an {@code UnsignedLong} corresponding to a given bit representation. The argument is 057 * interpreted as an unsigned 64-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^64 + bits}. 062 * 063 * <p>To represent decimal constants less than {@code 2^63}, consider {@link #valueOf(long)} 064 * instead. 065 * 066 * @since 14.0 067 */ 068 public static UnsignedLong fromLongBits(long bits) { 069 // TODO(lowasser): consider caching small values, like Long.valueOf 070 return new UnsignedLong(bits); 071 } 072 073 /** 074 * Returns an {@code UnsignedLong} representing the same value as the specified {@code long}. 075 * 076 * @throws IllegalArgumentException if {@code value} is negative 077 * @since 14.0 078 */ 079 @CanIgnoreReturnValue 080 public static UnsignedLong valueOf(long value) { 081 checkArgument(value >= 0, "value (%s) is outside the range for an unsigned long value", value); 082 return fromLongBits(value); 083 } 084 085 /** 086 * Returns a {@code UnsignedLong} representing the same value as the specified {@code BigInteger}. 087 * This is the inverse operation of {@link #bigIntegerValue()}. 088 * 089 * @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^64} 090 */ 091 @CanIgnoreReturnValue 092 public static UnsignedLong valueOf(BigInteger value) { 093 checkNotNull(value); 094 checkArgument( 095 value.signum() >= 0 && value.bitLength() <= Long.SIZE, 096 "value (%s) is outside the range for an unsigned long value", 097 value); 098 return fromLongBits(value.longValue()); 099 } 100 101 /** 102 * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as an 103 * unsigned {@code long} value. 104 * 105 * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long} 106 * value 107 */ 108 @CanIgnoreReturnValue 109 public static UnsignedLong valueOf(String string) { 110 return valueOf(string, 10); 111 } 112 113 /** 114 * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as an 115 * unsigned {@code long} value in the specified radix. 116 * 117 * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long} 118 * value, or {@code radix} is not between {@link Character#MIN_RADIX} and 119 * {@link Character#MAX_RADIX} 120 */ 121 @CanIgnoreReturnValue 122 public static UnsignedLong valueOf(String string, int radix) { 123 return fromLongBits(UnsignedLongs.parseUnsignedLong(string, radix)); 124 } 125 126 /** 127 * Returns the result of adding this and {@code val}. If the result would have more than 64 bits, 128 * returns the low 64 bits of the result. 129 * 130 * @since 14.0 131 */ 132 public UnsignedLong plus(UnsignedLong val) { 133 return fromLongBits(this.value + checkNotNull(val).value); 134 } 135 136 /** 137 * Returns the result of subtracting this and {@code val}. If the result would have more than 64 138 * bits, returns the low 64 bits of the result. 139 * 140 * @since 14.0 141 */ 142 public UnsignedLong minus(UnsignedLong val) { 143 return fromLongBits(this.value - checkNotNull(val).value); 144 } 145 146 /** 147 * Returns the result of multiplying this and {@code val}. If the result would have more than 64 148 * bits, returns the low 64 bits of the result. 149 * 150 * @since 14.0 151 */ 152 public UnsignedLong times(UnsignedLong val) { 153 return fromLongBits(value * checkNotNull(val).value); 154 } 155 156 /** 157 * Returns the result of dividing this by {@code val}. 158 * 159 * @since 14.0 160 */ 161 public UnsignedLong dividedBy(UnsignedLong val) { 162 return fromLongBits(UnsignedLongs.divide(value, checkNotNull(val).value)); 163 } 164 165 /** 166 * Returns this modulo {@code val}. 167 * 168 * @since 14.0 169 */ 170 public UnsignedLong mod(UnsignedLong val) { 171 return fromLongBits(UnsignedLongs.remainder(value, checkNotNull(val).value)); 172 } 173 174 /** 175 * Returns the value of this {@code UnsignedLong} as an {@code int}. 176 */ 177 @Override 178 public int intValue() { 179 return (int) value; 180 } 181 182 /** 183 * Returns the value of this {@code UnsignedLong} as a {@code long}. This is an inverse operation 184 * to {@link #fromLongBits}. 185 * 186 * <p>Note that if this {@code UnsignedLong} holds a value {@code >= 2^63}, the returned value 187 * will be equal to {@code this - 2^64}. 188 */ 189 @Override 190 public long longValue() { 191 return value; 192 } 193 194 /** 195 * Returns the value of this {@code UnsignedLong} as a {@code float}, analogous to a widening 196 * primitive conversion from {@code long} to {@code float}, and correctly rounded. 197 */ 198 @Override 199 public float floatValue() { 200 @SuppressWarnings("cast") 201 float fValue = (float) (value & UNSIGNED_MASK); 202 if (value < 0) { 203 fValue += 0x1.0p63f; 204 } 205 return fValue; 206 } 207 208 /** 209 * Returns the value of this {@code UnsignedLong} as a {@code double}, analogous to a widening 210 * primitive conversion from {@code long} to {@code double}, and correctly rounded. 211 */ 212 @Override 213 public double doubleValue() { 214 @SuppressWarnings("cast") 215 double dValue = (double) (value & UNSIGNED_MASK); 216 if (value < 0) { 217 dValue += 0x1.0p63; 218 } 219 return dValue; 220 } 221 222 /** 223 * Returns the value of this {@code UnsignedLong} as a {@link BigInteger}. 224 */ 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(@Nullable Object obj) { 246 if (obj instanceof UnsignedLong) { 247 UnsignedLong other = (UnsignedLong) obj; 248 return value == other.value; 249 } 250 return false; 251 } 252 253 /** 254 * Returns a string representation of the {@code UnsignedLong} value, in base 10. 255 */ 256 @Override 257 public String toString() { 258 return UnsignedLongs.toString(value); 259 } 260 261 /** 262 * Returns a string representation of the {@code UnsignedLong} value, in base {@code radix}. If 263 * {@code radix < Character.MIN_RADIX} or {@code radix > Character.MAX_RADIX}, the radix 264 * {@code 10} is used. 265 */ 266 public String toString(int radix) { 267 return UnsignedLongs.toString(value, radix); 268 } 269}