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
10 * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
11 * express or implied. See the License for the specific language governing permissions and
12 * limitations under the License.
13 */
14
15package com.google.common.primitives;
16
17import static com.google.common.base.Preconditions.checkArgument;
18import static com.google.common.base.Preconditions.checkNotNull;
19
20import java.io.Serializable;
21import java.math.BigInteger;
22
23import javax.annotation.Nullable;
24
25import com.google.common.annotations.Beta;
26import com.google.common.annotations.GwtCompatible;
27
28/**
29 * A wrapper class for unsigned {@code long} 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 long} values as unsigned, using the methods from {@link UnsignedLongs}.
33 *
34 * <p><b>Please do not extend this class; it will be made final in the near future.</b>
35 *
36 * @author Louis Wasserman
37 * @author Colin Evans
38 * @since 11.0
39 */
40@Beta
41@GwtCompatible(serializable = true)
42public class UnsignedLong extends Number implements Comparable<UnsignedLong>, Serializable {
43  // TODO(user): make final as soon as util.UnsignedLong is migrated over
44
45  private static final long UNSIGNED_MASK = 0x7fffffffffffffffL;
46
47  public static final UnsignedLong ZERO = new UnsignedLong(0);
48  public static final UnsignedLong ONE = new UnsignedLong(1);
49  public static final UnsignedLong MAX_VALUE = new UnsignedLong(-1L);
50
51  private final long value;
52
53  protected UnsignedLong(long value) {
54    this.value = value;
55  }
56
57  /**
58   * Returns an {@code UnsignedLong} that, when treated as signed, is equal to {@code value}. The
59   * inverse operation is {@link #longValue()}.
60   *
61   * <p>Put another way, if {@code value} is negative, the returned result will be equal to
62   * {@code 2^64 + value}; otherwise, the returned result will be equal to {@code value}.
63   */
64  public static UnsignedLong asUnsigned(long value) {
65    return new UnsignedLong(value);
66  }
67
68  /**
69   * Returns a {@code UnsignedLong} representing the same value as the specified {@code BigInteger}
70   * . This is the inverse operation of {@link #bigIntegerValue()}.
71   *
72   * @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^64}
73   */
74  public static UnsignedLong valueOf(BigInteger value) {
75    checkNotNull(value);
76    checkArgument(value.signum() >= 0 && value.bitLength() <= Long.SIZE,
77        "value (%s) is outside the range for an unsigned long value", value);
78    return asUnsigned(value.longValue());
79  }
80
81  /**
82   * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as
83   * an unsigned {@code long} value.
84   *
85   * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long}
86   *         value
87   */
88  public static UnsignedLong valueOf(String string) {
89    return valueOf(string, 10);
90  }
91
92  /**
93   * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as
94   * an unsigned {@code long} value in the specified radix.
95   *
96   * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long}
97   *         value, or {@code radix} is not between {@link Character#MIN_RADIX} and
98   *         {@link Character#MAX_RADIX}
99   */
100  public static UnsignedLong valueOf(String string, int radix) {
101    return asUnsigned(UnsignedLongs.parseUnsignedLong(string, radix));
102  }
103
104  /**
105   * Returns the result of adding this and {@code val}. If the result would have more than 64 bits,
106   * returns the low 64 bits of the result.
107   */
108  public UnsignedLong add(UnsignedLong val) {
109    checkNotNull(val);
110    return asUnsigned(this.value + val.value);
111  }
112
113  /**
114   * Returns the result of subtracting this and {@code val}. If the result would be negative,
115   * returns the low 64 bits of the result.
116   */
117  public UnsignedLong subtract(UnsignedLong val) {
118    checkNotNull(val);
119    return asUnsigned(this.value - val.value);
120  }
121
122  /**
123   * Returns the result of multiplying this and {@code val}. If the result would have more than 64
124   * bits, returns the low 64 bits of the result.
125   */
126  public UnsignedLong multiply(UnsignedLong val) {
127    checkNotNull(val);
128    return asUnsigned(value * val.value);
129  }
130
131  /**
132   * Returns the result of dividing this by {@code val}.
133   */
134  public UnsignedLong divide(UnsignedLong val) {
135    checkNotNull(val);
136    return asUnsigned(UnsignedLongs.divide(value, val.value));
137  }
138
139  /**
140   * Returns the remainder of dividing this by {@code val}.
141   */
142  public UnsignedLong remainder(UnsignedLong val) {
143    checkNotNull(val);
144    return asUnsigned(UnsignedLongs.remainder(value, val.value));
145  }
146
147  /**
148   * Returns the value of this {@code UnsignedLong} as an {@code int}.
149   */
150  @Override
151  public int intValue() {
152    return (int) value;
153  }
154
155  /**
156   * Returns the value of this {@code UnsignedLong} as a {@code long}. This is an inverse operation
157   * to {@link #asUnsigned}.
158   *
159   * <p>Note that if this {@code UnsignedLong} holds a value {@code >= 2^63}, the returned value
160   * will be equal to {@code this - 2^64}.
161   */
162  @Override
163  public long longValue() {
164    return value;
165  }
166
167  /**
168   * Returns the value of this {@code UnsignedLong} as a {@code float}, analogous to a widening
169   * primitive conversion from {@code long} to {@code float}, and correctly rounded.
170   */
171  @Override
172  public float floatValue() {
173    @SuppressWarnings("cast")
174    float fValue = (float) (value & UNSIGNED_MASK);
175    if (value < 0) {
176      fValue += 0x1.0p63f;
177    }
178    return fValue;
179  }
180
181  /**
182   * Returns the value of this {@code UnsignedLong} as a {@code double}, analogous to a widening
183   * primitive conversion from {@code long} to {@code double}, and correctly rounded.
184   */
185  @Override
186  public double doubleValue() {
187    @SuppressWarnings("cast")
188    double dValue = (double) (value & UNSIGNED_MASK);
189    if (value < 0) {
190      dValue += 0x1.0p63;
191    }
192    return dValue;
193  }
194
195  /**
196   * Returns the value of this {@code UnsignedLong} as a {@link BigInteger}.
197   */
198  public BigInteger bigIntegerValue() {
199    BigInteger bigInt = BigInteger.valueOf(value & UNSIGNED_MASK);
200    if (value < 0) {
201      bigInt = bigInt.setBit(Long.SIZE - 1);
202    }
203    return bigInt;
204  }
205
206  @Override
207  public int compareTo(UnsignedLong o) {
208    checkNotNull(o);
209    return UnsignedLongs.compare(value, o.value);
210  }
211
212  @Override
213  public int hashCode() {
214    return Longs.hashCode(value);
215  }
216
217  @Override
218  public boolean equals(@Nullable Object obj) {
219    if (obj instanceof UnsignedLong) {
220      UnsignedLong other = (UnsignedLong) obj;
221      return value == other.value;
222    }
223    return false;
224  }
225
226  /**
227   * Returns a string representation of the {@code UnsignedLong} value, in base 10.
228   */
229  @Override
230  public String toString() {
231    return UnsignedLongs.toString(value);
232  }
233
234  /**
235   * Returns a string representation of the {@code UnsignedLong} value, in base {@code radix}. If
236   * {@code radix < Character.MIN_RADIX} or {@code radix > Character.MAX_RADIX}, the radix
237   * {@code 10} is used.
238   */
239  public String toString(int radix) {
240    return UnsignedLongs.toString(value, radix);
241  }
242}
243