com.google.common.primitives.UnsignedInteger Maven / Gradle / Ivy
/*
* Copyright (C) 2011 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the
* License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.primitives;
import static com.google.common.base.Preconditions.checkArgument;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.primitives.UnsignedInts.INT_MASK;
import static com.google.common.primitives.UnsignedInts.compare;
import static com.google.common.primitives.UnsignedInts.toLong;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.GwtIncompatible;
import java.math.BigInteger;
import javax.annotation.CheckReturnValue;
import javax.annotation.Nullable;
/**
* A wrapper class for unsigned {@code int} values, supporting arithmetic operations.
*
* In some cases, when speed is more important than code readability, it may be faster simply to
* treat primitive {@code int} values as unsigned, using the methods from {@link UnsignedInts}.
*
*
See the Guava User Guide article on
* unsigned primitive utilities.
*
* @author Louis Wasserman
* @since 11.0
*/
@GwtCompatible(emulated = true)
public final class UnsignedInteger extends Number implements Comparable {
public static final UnsignedInteger ZERO = asUnsigned(0);
public static final UnsignedInteger ONE = asUnsigned(1);
public static final UnsignedInteger MAX_VALUE = asUnsigned(-1);
private final int value;
private UnsignedInteger(int value) {
// GWT doesn't consistently overflow values to make them 32-bit, so we need to force it.
this.value = value & 0xffffffff;
}
/**
* Returns an {@code UnsignedInteger} that, when treated as signed, is
* equal to {@code value}.
*
* @deprecated Use {@link #fromIntBits(int)}. This method is scheduled to be removed in Guava
* release 15.0.
*/
@Deprecated
@Beta
public static UnsignedInteger asUnsigned(int value) {
return fromIntBits(value);
}
/**
* Returns an {@code UnsignedInteger} corresponding to a given bit representation.
* The argument is interpreted as an unsigned 32-bit value. Specifically, the sign bit
* of {@code bits} is interpreted as a normal bit, and all other bits are treated as usual.
*
* If the argument is nonnegative, the returned result will be equal to {@code bits},
* otherwise, the result will be equal to {@code 2^32 + bits}.
*
*
To represent unsigned decimal constants, consider {@link #valueOf(long)} instead.
*
* @since 14.0
*/
public static UnsignedInteger fromIntBits(int bits) {
return new UnsignedInteger(bits);
}
/**
* Returns an {@code UnsignedInteger} that is equal to {@code value},
* if possible. The inverse operation of {@link #longValue()}.
*/
public static UnsignedInteger valueOf(long value) {
checkArgument((value & INT_MASK) == value,
"value (%s) is outside the range for an unsigned integer value", value);
return fromIntBits((int) value);
}
/**
* Returns a {@code UnsignedInteger} representing the same value as the specified
* {@link BigInteger}. This is the inverse operation of {@link #bigIntegerValue()}.
*
* @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^32}
*/
public static UnsignedInteger valueOf(BigInteger value) {
checkNotNull(value);
checkArgument(value.signum() >= 0 && value.bitLength() <= Integer.SIZE,
"value (%s) is outside the range for an unsigned integer value", value);
return fromIntBits(value.intValue());
}
/**
* Returns an {@code UnsignedInteger} holding the value of the specified {@code String}, parsed
* as an unsigned {@code int} value.
*
* @throws NumberFormatException if the string does not contain a parsable unsigned {@code int}
* value
*/
public static UnsignedInteger valueOf(String string) {
return valueOf(string, 10);
}
/**
* Returns an {@code UnsignedInteger} holding the value of the specified {@code String}, parsed
* as an unsigned {@code int} value in the specified radix.
*
* @throws NumberFormatException if the string does not contain a parsable unsigned {@code int}
* value
*/
public static UnsignedInteger valueOf(String string, int radix) {
return fromIntBits(UnsignedInts.parseUnsignedInt(string, radix));
}
/**
* Returns the result of adding this and {@code val}. If the result would have more than 32 bits,
* returns the low 32 bits of the result.
*
* @deprecated Use {@link #plus(UnsignedInteger)}. This method is scheduled to be removed in Guava
* release 15.0.
*/
@Deprecated
@Beta
public UnsignedInteger add(UnsignedInteger val) {
return plus(val);
}
/**
* Returns the result of adding this and {@code val}. If the result would have more than 32 bits,
* returns the low 32 bits of the result.
*
* @since 14.0
*/
@CheckReturnValue
public UnsignedInteger plus(UnsignedInteger val) {
return fromIntBits(this.value + checkNotNull(val).value);
}
/**
* Returns the result of subtracting this and {@code val}. If the result would be negative,
* returns the low 32 bits of the result.
*
* @deprecated Use {@link #minus(UnsignedInteger)}. This method is scheduled to be removed in
* Guava release 15.0.
*/
@Deprecated
@Beta
public UnsignedInteger subtract(UnsignedInteger val) {
return minus(val);
}
/**
* Returns the result of subtracting this and {@code val}. If the result would be negative,
* returns the low 32 bits of the result.
*
* @since 14.0
*/
@CheckReturnValue
public UnsignedInteger minus(UnsignedInteger val) {
return fromIntBits(value - checkNotNull(val).value);
}
/**
* Returns the result of multiplying this and {@code val}. If the result would have more than 32
* bits, returns the low 32 bits of the result.
*
* @deprecated Use {@link #times(UnsignedInteger)}. This method is scheduled to be removed in
* Guava release 15.0.
*/
@Deprecated
@Beta
@GwtIncompatible("Does not truncate correctly")
public UnsignedInteger multiply(UnsignedInteger val) {
return times(val);
}
/**
* Returns the result of multiplying this and {@code val}. If the result would have more than 32
* bits, returns the low 32 bits of the result.
*
* @since 14.0
*/
@CheckReturnValue
@GwtIncompatible("Does not truncate correctly")
public UnsignedInteger times(UnsignedInteger val) {
// TODO(user): make this GWT-compatible
return fromIntBits(value * checkNotNull(val).value);
}
/**
* Returns the result of dividing this by {@code val}.
*
* @deprecated Use {@link #dividedBy(UnsignedInteger)}. This method is scheduled to be removed in
* Guava release 15.0.
*/
@Deprecated
@Beta
public UnsignedInteger divide(UnsignedInteger val) {
return dividedBy(val);
}
/**
* Returns the result of dividing this by {@code val}.
*
* @throws ArithmeticException if {@code val} is zero
* @since 14.0
*/
@CheckReturnValue
public UnsignedInteger dividedBy(UnsignedInteger val) {
return fromIntBits(UnsignedInts.divide(value, checkNotNull(val).value));
}
/**
* Returns the remainder of dividing this by {@code val}.
*
* @deprecated Use {@link #mod(UnsignedInteger)}. This method is scheduled to be removed in Guava
* release 15.0.
*/
@Deprecated
@Beta
public UnsignedInteger remainder(UnsignedInteger val) {
return mod(val);
}
/**
* Returns this mod {@code val}.
*
* @throws ArithmeticException if {@code val} is zero
* @since 14.0
*/
@CheckReturnValue
public UnsignedInteger mod(UnsignedInteger val) {
return fromIntBits(UnsignedInts.remainder(value, checkNotNull(val).value));
}
/**
* Returns the value of this {@code UnsignedInteger} as an {@code int}. This is an inverse
* operation to {@link #fromIntBits}.
*
*
Note that if this {@code UnsignedInteger} holds a value {@code >= 2^31}, the returned value
* will be equal to {@code this - 2^32}.
*/
@Override
public int intValue() {
return value;
}
/**
* Returns the value of this {@code UnsignedInteger} as a {@code long}.
*/
@Override
public long longValue() {
return toLong(value);
}
/**
* Returns the value of this {@code UnsignedInteger} as a {@code float}, analogous to a widening
* primitive conversion from {@code int} to {@code float}, and correctly rounded.
*/
@Override
public float floatValue() {
return longValue();
}
/**
* Returns the value of this {@code UnsignedInteger} as a {@code float}, analogous to a widening
* primitive conversion from {@code int} to {@code double}, and correctly rounded.
*/
@Override
public double doubleValue() {
return longValue();
}
/**
* Returns the value of this {@code UnsignedInteger} as a {@link BigInteger}.
*/
public BigInteger bigIntegerValue() {
return BigInteger.valueOf(longValue());
}
/**
* Compares this unsigned integer to another unsigned integer.
* Returns {@code 0} if they are equal, a negative number if {@code this < other},
* and a positive number if {@code this > other}.
*/
@Override
public int compareTo(UnsignedInteger other) {
checkNotNull(other);
return compare(value, other.value);
}
@Override
public int hashCode() {
return value;
}
@Override
public boolean equals(@Nullable Object obj) {
if (obj instanceof UnsignedInteger) {
UnsignedInteger other = (UnsignedInteger) obj;
return value == other.value;
}
return false;
}
/**
* Returns a string representation of the {@code UnsignedInteger} value, in base 10.
*/
@Override
public String toString() {
return toString(10);
}
/**
* Returns a string representation of the {@code UnsignedInteger} value, in base {@code radix}.
* If {@code radix < Character.MIN_RADIX} or {@code radix > Character.MAX_RADIX}, the radix
* {@code 10} is used.
*/
public String toString(int radix) {
return UnsignedInts.toString(value, radix);
}
}