/*
 * 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 com.google.common.annotations.GwtCompatible;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.io.Serializable;
import java.math.BigInteger;
import org.checkerframework.checker.nullness.qual.Nullable;

A wrapper class for unsigned long values, supporting arithmetic operations. 
In some cases, when speed is more important than code readability, it may be faster simply to treat primitive long values as unsigned, using the methods from UnsignedLongs. 
See the Guava User Guide article on unsigned
primitive utilities.
Author:
Louis Wasserman, Colin Evans
Since:
11.0/**
 * A wrapper class for unsigned {@code long} values, supporting arithmetic operations.
 *
 * <p>In some cases, when speed is more important than code readability, it may be faster simply to
 * treat primitive {@code long} values as unsigned, using the methods from {@link UnsignedLongs}.
 *
 * <p>See the Guava User Guide article on <a
 * href="https://github.com/google/guava/wiki/PrimitivesExplained#unsigned-support">unsigned
 * primitive utilities</a>.
 *
 * @author Louis Wasserman
 * @author Colin Evans
 * @since 11.0
 */
@GwtCompatible(serializable = true)
public final class UnsignedLong extends Number implements Comparable<UnsignedLong>, Serializable {

  private static final long UNSIGNED_MASK = 0x7fffffffffffffffL;

  public static final UnsignedLong ZERO = new UnsignedLong(0);
  public static final UnsignedLong ONE = new UnsignedLong(1);
  public static final UnsignedLong MAX_VALUE = new UnsignedLong(-1L);

  private final long value;

  private UnsignedLong(long value) {
    this.value = value;
  }

  
Returns an UnsignedLong corresponding to a given bit representation. The argument is interpreted as an unsigned 64-bit value. Specifically, the sign bit of 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 bits, otherwise, the result will be equal to 2^64 + bits. 
To represent decimal constants less than 2^63, consider valueOf(long) instead. 
Since:
14.0/**
   * Returns an {@code UnsignedLong} corresponding to a given bit representation. The argument is
   * interpreted as an unsigned 64-bit value. Specifically, the sign bit of {@code bits} is
   * interpreted as a normal bit, and all other bits are treated as usual.
   *
   * <p>If the argument is nonnegative, the returned result will be equal to {@code bits},
   * otherwise, the result will be equal to {@code 2^64 + bits}.
   *
   * <p>To represent decimal constants less than {@code 2^63}, consider {@link #valueOf(long)}
   * instead.
   *
   * @since 14.0
   */
  public static UnsignedLong fromLongBits(long bits) {
    // TODO(lowasser): consider caching small values, like Long.valueOf
    return new UnsignedLong(bits);
  }

  
Returns an UnsignedLong representing the same value as the specified long. 
Throws:
IllegalArgumentException – if value is negative
Since:
14.0/**
   * Returns an {@code UnsignedLong} representing the same value as the specified {@code long}.
   *
   * @throws IllegalArgumentException if {@code value} is negative
   * @since 14.0
   */
  @CanIgnoreReturnValue
  public static UnsignedLong valueOf(long value) {
    checkArgument(value >= 0, "value (%s) is outside the range for an unsigned long value", value);
    return fromLongBits(value);
  }

  
Returns a UnsignedLong representing the same value as the specified BigInteger. This is the inverse operation of bigIntegerValue(). 
Throws:
IllegalArgumentException – if value is negative or value >= 2^64/**
   * Returns a {@code UnsignedLong} representing the same value as the specified {@code BigInteger}.
   * This is the inverse operation of {@link #bigIntegerValue()}.
   *
   * @throws IllegalArgumentException if {@code value} is negative or {@code value >= 2^64}
   */
  @CanIgnoreReturnValue
  public static UnsignedLong valueOf(BigInteger value) {
    checkNotNull(value);
    checkArgument(
        value.signum() >= 0 && value.bitLength() <= Long.SIZE,
        "value (%s) is outside the range for an unsigned long value",
        value);
    return fromLongBits(value.longValue());
  }

  
Returns an UnsignedLong holding the value of the specified String, parsed as an unsigned long value. 
Throws:
NumberFormatException – if the string does not contain a parsable unsigned long value/**
   * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as an
   * unsigned {@code long} value.
   *
   * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long}
   *     value
   */
  @CanIgnoreReturnValue
  public static UnsignedLong valueOf(String string) {
    return valueOf(string, 10);
  }

  
Returns an UnsignedLong holding the value of the specified String, parsed as an unsigned long value in the specified radix. 
Throws:
NumberFormatException – if the string does not contain a parsable unsigned long value, or radix is not between Character.MIN_RADIX and Character.MAX_RADIX/**
   * Returns an {@code UnsignedLong} holding the value of the specified {@code String}, parsed as an
   * unsigned {@code long} value in the specified radix.
   *
   * @throws NumberFormatException if the string does not contain a parsable unsigned {@code long}
   *     value, or {@code radix} is not between {@link Character#MIN_RADIX} and {@link
   *     Character#MAX_RADIX}
   */
  @CanIgnoreReturnValue
  public static UnsignedLong valueOf(String string, int radix) {
    return fromLongBits(UnsignedLongs.parseUnsignedLong(string, radix));
  }

  
Returns the result of adding this and val. If the result would have more than 64 bits, returns the low 64 bits of the result. 
Since:
14.0/**
   * Returns the result of adding this and {@code val}. If the result would have more than 64 bits,
   * returns the low 64 bits of the result.
   *
   * @since 14.0
   */
  public UnsignedLong plus(UnsignedLong val) {
    return fromLongBits(this.value + checkNotNull(val).value);
  }

  
Returns the result of subtracting this and val. If the result would have more than 64 bits, returns the low 64 bits of the result. 
Since:
14.0/**
   * Returns the result of subtracting this and {@code val}. If the result would have more than 64
   * bits, returns the low 64 bits of the result.
   *
   * @since 14.0
   */
  public UnsignedLong minus(UnsignedLong val) {
    return fromLongBits(this.value - checkNotNull(val).value);
  }

  
Returns the result of multiplying this and val. If the result would have more than 64 bits, returns the low 64 bits of the result. 
Since:
14.0/**
   * Returns the result of multiplying this and {@code val}. If the result would have more than 64
   * bits, returns the low 64 bits of the result.
   *
   * @since 14.0
   */
  public UnsignedLong times(UnsignedLong val) {
    return fromLongBits(value * checkNotNull(val).value);
  }

  
Returns the result of dividing this by val. 
Since:
14.0/**
   * Returns the result of dividing this by {@code val}.
   *
   * @since 14.0
   */
  public UnsignedLong dividedBy(UnsignedLong val) {
    return fromLongBits(UnsignedLongs.divide(value, checkNotNull(val).value));
  }

  
Returns this modulo val. 
Since:
14.0/**
   * Returns this modulo {@code val}.
   *
   * @since 14.0
   */
  public UnsignedLong mod(UnsignedLong val) {
    return fromLongBits(UnsignedLongs.remainder(value, checkNotNull(val).value));
  }

  
Returns the value of this UnsignedLong as an int. /** Returns the value of this {@code UnsignedLong} as an {@code int}. */
  @Override
  public int intValue() {
    return (int) value;
  }

  
Returns the value of this UnsignedLong as a long. This is an inverse operation to fromLongBits. 
Note that if this UnsignedLong holds a value >= 2^63, the returned value will be equal to this - 2^64. /**
   * Returns the value of this {@code UnsignedLong} as a {@code long}. This is an inverse operation
   * to {@link #fromLongBits}.
   *
   * <p>Note that if this {@code UnsignedLong} holds a value {@code >= 2^63}, the returned value
   * will be equal to {@code this - 2^64}.
   */
  @Override
  public long longValue() {
    return value;
  }

  
Returns the value of this UnsignedLong as a float, analogous to a widening primitive conversion from long to float, and correctly rounded. /**
   * Returns the value of this {@code UnsignedLong} as a {@code float}, analogous to a widening
   * primitive conversion from {@code long} to {@code float}, and correctly rounded.
   */
  @Override
  public float floatValue() {
    @SuppressWarnings("cast")
    float fValue = (float) (value & UNSIGNED_MASK);
    if (value < 0) {
      fValue += 0x1.0p63f;
    }
    return fValue;
  }

  
Returns the value of this UnsignedLong as a double, analogous to a widening primitive conversion from long to double, and correctly rounded. /**
   * Returns the value of this {@code UnsignedLong} as a {@code double}, analogous to a widening
   * primitive conversion from {@code long} to {@code double}, and correctly rounded.
   */
  @Override
  public double doubleValue() {
    @SuppressWarnings("cast")
    double dValue = (double) (value & UNSIGNED_MASK);
    if (value < 0) {
      dValue += 0x1.0p63;
    }
    return dValue;
  }

  
Returns the value of this UnsignedLong as a BigInteger. /** Returns the value of this {@code UnsignedLong} as a {@link BigInteger}. */
  public BigInteger bigIntegerValue() {
    BigInteger bigInt = BigInteger.valueOf(value & UNSIGNED_MASK);
    if (value < 0) {
      bigInt = bigInt.setBit(Long.SIZE - 1);
    }
    return bigInt;
  }

  @Override
  public int compareTo(UnsignedLong o) {
    checkNotNull(o);
    return UnsignedLongs.compare(value, o.value);
  }

  @Override
  public int hashCode() {
    return Longs.hashCode(value);
  }

  @Override
  public boolean equals(@Nullable Object obj) {
    if (obj instanceof UnsignedLong) {
      UnsignedLong other = (UnsignedLong) obj;
      return value == other.value;
    }
    return false;
  }

  
Returns a string representation of the UnsignedLong value, in base 10. /** Returns a string representation of the {@code UnsignedLong} value, in base 10. */
  @Override
  public String toString() {
    return UnsignedLongs.toString(value);
  }

  
Returns a string representation of the UnsignedLong value, in base radix. If radix < Character.MIN_RADIX or radix > Character.MAX_RADIX, the radix 
10 is used. /**
   * Returns a string representation of the {@code UnsignedLong} 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 UnsignedLongs.toString(value, radix);
  }
}