Class MutableInt128

java.lang.Object
net.algart.math.MutableInt128
All Implemented Interfaces:
Cloneable, Comparable<MutableInt128>

public final class MutableInt128 extends Object implements Cloneable, Comparable<MutableInt128>

Integer signed value with 128-bit precision: −2128<x<2128.

Note: this class cannot represent positive or negative values ±2128. (In comparison, long 64-bit primitive type can represent −263.)

Unlike BigInteger, this class is mutable, that allows to reuse one instance for 128-bit calculation without memory allocation. This class is not thread-safe, but is thread-compatible and can be synchronized manually if multithread access is necessary.

Author:
Daniel Alievsky
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates new instance of this class, containing integer value 0.
  • Method Summary

    Modifier and Type
    Method
    Description
    abs()
    Replaces this number with its absolute value.
    Adds the given other number to this one and stores the sum in this object.
    addLong(long value)
    Adds the given integer value to this number.
    addLongIntProduct(long firstMultiplier, int secondMultiplier)
    Calculate exact product firstMultiplier*secondMultiplier and adds it to this number.
    addLongLongProduct(long firstMultiplier, long secondMultiplier)
    Calculate exact product firstMultiplier*secondMultiplier and adds it to this number.
    addLongSqr(long value)
    Calculate exact exact square of the given value: value*value and adds it to this number.
    addUnsignedLongLongProduct(long firstMultiplier, long secondMultiplier)
    Calculate exact unsigned product firstMultiplier*secondMultiplier, where the arguments are interpreted as unsigned (non-negative) 64-bit integers, and adds it to this number.
    Replaces all bits of the absolute value of this number with bitwise AND of this and other number: |this| = |this| & |other|.
    int
    Returns the number of one-bits in the 128-bit absolute value of this number.
    Returns an exact copy of this integer number.
    int
    Compares this number with the specified one.
    boolean
    Indicates whether some other object is an instance of this class, equal to this number.
    boolean
    getBit(int index)
    Returns the bit #index of the absolute value of this number.
    int
    Returns the hash code of this number.
    long
    Returns high 64 bits of the absolute value of this number.
    boolean
    Returns true if and only if this number can be represented by long primitive type, i.e.
    boolean
    Returns true if and only if this number can be exactly represented by double primitive type, i.e.
    boolean
    Returns true if and only if this number is negative.
    boolean
    Returns true if and only if this number is positive.
    boolean
    Returns true if and only if the value of this number is zero.
    long
    Returns low 64 bits of the absolute value of this number.
    Sets this number to maximal possible value (+2128).
    Sets this number to minimal possible value (−2128).
    Changes the sign of this integer number and stores the result in this object.
    Creates new instance of this class, containing the maxnimal possible value (+2128).
    Creates new instance of this class, containing the minimal possible value (−2128).
    Creates new instance of this class, containing +1.
    Creates new instance of this class, containing 0.
    not()
    Inverts all bits of the absolute value of this number: |this| = ~|this|.
    int
    Returns the number of zero bits preceding the highest-order ("leftmost") one-bit in the 128-bit absolute value of this number.
    int
    Returns the number of zero bits following the lowest-order ("rightmost") one-bit in the 128-bit absolute value of this number.
    one()
    Sets this number to one value (+1).
    Replaces all bits of the absolute value of this number with bitwise OR of this and other number: |this| = |this| | |other|.
    setBit(int index, boolean value)
    Sets the bit #index of the absolute value of this number to the given value.
    Sets this number to be identical to the passed number.
    setToDouble(double value)
    Sets this number to be truncated 128-bit long approximation of the passed double value.
    setToLong(long value)
    Sets this number to be equal to the passed long value.
    setToLongIntProduct(long firstMultiplier, int secondMultiplier)
    Sets this object to be equal to the exact product firstMultiplier*secondMultiplier.
    setToLongLongProduct(long firstMultiplier, long secondMultiplier)
    Sets this object to be equal to the exact product firstMultiplier*secondMultiplier.
    setToLongSqr(long value)
    Sets this object to be equal to the exact square of the given value: value*value.
    setToUnsignedLong(long value)
    Sets this number to be equal to the passed long value, interpreted as unsigned 64-bit value.
    setToUnsignedLongLongProduct(long firstMultiplier, long secondMultiplier)
    Sets this object to be equal to the exact unsigned product firstMultiplier*secondMultiplier, where the arguments are interpreted as unsigned 64-bit integers.
    shiftLeft(int shift)
    Shifts all bits of the absolute value of this number leftwards by the specified number of bits.
    shiftRight(int shift)
    Shifts all bits of the absolute value of this number rightwards by the specified number of bits.
    shiftRightRounding(int shift)
    Divides the absolute value of this number by 2shift and rounds the result to the closest 128-bit integer value.
    static long
    shiftRightRounding(long value, int shift)
    Divides the given value by 2shift and rounds the result to the closest long value.
    int
    Returns the signum function of this number.
    Subtracts the given other number from this one and stores the difference in this object.
    Converts this number into BigInteger.
    double
    Converts this number into double value.
    long
    Returns this number as long value, if it is possible (this number is in range −263x≤263−1).
    Returns the decimal String representation of this number.
    toString(int radix)
    Returns the String representation of this number with the given radix.
    static long
    unsignedShiftRightRounding(long value, int shift)
    Divides the given value, interpreted as unsigned 64-bit value, by 2shift and rounds the result to the closest unsigned 64-bit long value.
    static double
    unsignedToDouble(long value)
    Converts the passed value, interpreted as unsigned 64-bit value, into double, and returns it.
    valueOf(long value)
    Creates new instance of this class, equal to the passed long value.
    valueOfDouble(double value)
    Creates new instance of this class, equal to the truncated 128-bit long approximation of the passed double value.
    valueOfUnsigned(long value)
    Creates new instance of this class, equal to the passed long value, interpreted as unsigned 64-bit value.
    Replaces all bits of the absolute value of this number with bitwise XOR of this and other number: |this| = |this| ^ |other|.
    Sets this number to zero value (0).

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • MutableInt128

      public MutableInt128()
      Creates new instance of this class, containing integer value 0.
  • Method Details

    • valueOf

      public static MutableInt128 valueOf(long value)
      Creates new instance of this class, equal to the passed long value.

      This method is equivalent to new MutableInt128().setToLong(value).

      Parameters:
      value - some long value.
      Returns:
      newly created object, containing this value.
    • valueOfUnsigned

      public static MutableInt128 valueOfUnsigned(long value)
      Creates new instance of this class, equal to the passed long value, interpreted as unsigned 64-bit value. The result is always non-negative.

      This method is equivalent to new MutableInt128().setToUnsignedLong(value).

      Parameters:
      value - some long value.
      Returns:
      newly created object, containing this value, interpreted as unsigned 64-bit integer.
    • valueOfDouble

      public static MutableInt128 valueOfDouble(double value)
      Creates new instance of this class, equal to the truncated 128-bit long approximation of the passed double value. This conversion is similar to the narrowing primitive conversion (long)value.

      This method is equivalent to new MutableInt128().setToDouble(value).

      Parameters:
      value - some long value.
      Returns:
      newly created object, containing the passed value, truncated to 128-bit integer.
    • newZero

      public static MutableInt128 newZero()
      Creates new instance of this class, containing 0.

      Note: this is just another form of calling the constructor.

      Returns:
      newly created object, containing 0 value.
    • newOne

      public static MutableInt128 newOne()
      Creates new instance of this class, containing +1.
      Returns:
      newly created object, containing +1 value.
    • newMinValue

      public static MutableInt128 newMinValue()
      Creates new instance of this class, containing the minimal possible value (−2128).
      Returns:
      newly created object, containing −2128 value.
    • newMaxValue

      public static MutableInt128 newMaxValue()
      Creates new instance of this class, containing the maxnimal possible value (+2128).
      Returns:
      newly created object, containing +2128 value.
    • isZero

      public boolean isZero()
      Returns true if and only if the value of this number is zero.
      Returns:
      if this value == 0.
      See Also:
    • isPositive

      public boolean isPositive()
      Returns true if and only if this number is positive. Note that zero number is not positive: this method returns false for it.
      Returns:
      if this value > 0.
    • isNegative

      public boolean isNegative()
      Returns true if and only if this number is negative. Note that zero number is non-negative: this method returns false for it.
      Returns:
      if this value < 0.
    • signum

      public int signum()
      Returns the signum function of this number.
      Returns:
      -1, 0 or 1 as the number is negative, zero or positive.
    • low64Bits

      public long low64Bits()
      Returns low 64 bits of the absolute value of this number. You can use this method together with shiftRight(int) to retrieve any bits of the absolute value.
      Returns:
      low 64 bits of the absolute value (unsigned long value).
    • high64Bits

      public long high64Bits()
      Returns high 64 bits of the absolute value of this number.

      The result of this method is equal to the following expression:

           thisNumber.shiftRight(64).low64Bits()

      but this method does not change the state of this object.

      Returns:
      high 64 bits of the absolute value (unsigned long value).
    • isExactlyConvertibleToDouble

      public boolean isExactlyConvertibleToDouble()
      Returns true if and only if this number can be exactly represented by double primitive type, i.e. if the number of significant bits is ≤53 (maximal precision of double type). In particular, this method returns true if this number is in range−253x≤253.

      In other words, this method returns true if and only if the method toDouble() is performed absolutely exactly, without precision loss.

      Returns:
      true if this number can be exactly represented by double type.
    • toDouble

      public double toDouble()
      Converts this number into double value. This conversion is similar to the narrowing primitive conversion, like described in comments to doubleValue() method of the standard BigInteger.

      Note: the returned value is en exact representation of this number, if the method isExactlyConvertibleToDouble() returns true. In this case, the reverse

      Returns:
      double, maximally close to this integer number.
    • isConvertibleToLong

      public boolean isConvertibleToLong()
      Returns true if and only if this number can be represented by long primitive type, i.e. it is in range−263x≤263−1.

      In other words, returns true if and only if the method toLongExact() does not throw an exception.

      Returns:
      true if this number can be represented as long.
    • toLongExact

      public long toLongExact()
      Returns this number as long value, if it is possible (this number is in range −263x≤263−1). If it is impossible, throws ArithmeticException.

      You can check, whether this number can be represented as long, with help of isConvertibleToLong() method.

      Returns:
      this number, represented by long type.
      Throws:
      ArithmeticException - in a case of arithmetic overflow.
    • toBigInteger

      public BigInteger toBigInteger()
      Converts this number into BigInteger.
      Returns:
      BigInteger value, containing the same integer value.
    • setTo

      public MutableInt128 setTo(MutableInt128 other)
      Sets this number to be identical to the passed number.
      Parameters:
      other - other number.
      Returns:
      a reference to this object.
      Throws:
      NullPointerException - if the argument is null.
    • setToLong

      public MutableInt128 setToLong(long value)
      Sets this number to be equal to the passed long value.
      Parameters:
      value - some long value.
      Returns:
      a reference to this object.
    • setToUnsignedLong

      public MutableInt128 setToUnsignedLong(long value)
      Sets this number to be equal to the passed long value, interpreted as unsigned 64-bit value.
      Parameters:
      value - some long value (interpreted as unsigned 64-bit integer).
      Returns:
      a reference to this object.
    • setToDouble

      public MutableInt128 setToDouble(double value)
      Sets this number to be truncated 128-bit long approximation of the passed double value. This conversion is similar to the narrowing primitive conversion (long)value.
      Parameters:
      value - some double value.
      Returns:
      a reference to this object.
    • zero

      public MutableInt128 zero()
      Sets this number to zero value (0).
      Returns:
      a reference to this object.
      See Also:
    • one

      public MutableInt128 one()
      Sets this number to one value (+1).
      Returns:
      a reference to this object.
    • minValue

      public MutableInt128 minValue()
      Sets this number to minimal possible value (−2128).
      Returns:
      a reference to this object.
    • maxValue

      public MutableInt128 maxValue()
      Sets this number to maximal possible value (+2128).
      Returns:
      a reference to this object.
    • getBit

      public boolean getBit(int index)
      Returns the bit #index of the absolute value of this number. For example, if index==0, this method returns true when this number is odd. If index is too large (≥128), this method returns false.
      Parameters:
      index - index of the bit of this number.
      Returns:
      value of this bit.
      Throws:
      IllegalArgumentException - if index argument is negative.
    • setBit

      public MutableInt128 setBit(int index, boolean value)
      Sets the bit #index of the absolute value of this number to the given value. If index is too large (≥128), this method does nothing.
      Parameters:
      index - index of the bit of this number.
      value - new value of the bit (true is 1, false is 0).
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if index argument is negative.
    • shiftRight

      public MutableInt128 shiftRight(int shift)
      Shifts all bits of the absolute value of this number rightwards by the specified number of bits. As the result, this number x is changed to
          x<0 ? −(−x)/2shift : x/2shift.

      If the argument shift is too large (≥128), the method sets this number to zero.

      Shifting by 0 bits (shift=0) or shifting zero value with any shift does not change the number.

      Parameters:
      shift - number of bits to shift.
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if shift argument is negative.
    • shiftLeft

      public MutableInt128 shiftLeft(int shift)
      Shifts all bits of the absolute value of this number leftwards by the specified number of bits. As the result, this number x is changed to
          x<0 ? −(−x)*2shift : x*2shift.

      If the resulting absolute value cannot be represented by 128-bit number, in particular, if current number is non-zero and shift≥128, the method throws ArithmeticException.

      Shifting by 0 bits (shift=0) or shifting zero value with any shift does not change the number.

      Parameters:
      shift - number of bits to shift.
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if shift argument is negative.
      ArithmeticException - in a case of arithmetic overflow.
    • shiftRightRounding

      public MutableInt128 shiftRightRounding(int shift)
      Divides the absolute value of this number by 2shift and rounds the result to the closest 128-bit integer value. If two integer numbers are equally close to the result of division, the result is the 128-bit integer value, which is even. In other words, this number x is changed to
          [x/2.0shift],
      where [w] means the mathematical integer, closest to w, like in Math.rint() method.

      If the argument shift is too large (≥128), the method sets this number to zero.

      Shifting by 0 bits (shift=0) or shifting zero value with any shift does not change the number.

      Parameters:
      shift - number of bits to shift.
      Returns:
      a reference to this object.
      Throws:
      IllegalArgumentException - if shift argument is negative.
    • and

      public MutableInt128 and(MutableInt128 other)
      Replaces all bits of the absolute value of this number with bitwise AND of this and other number: |this| = |this| & |other|.

      The sign of this number stays unchanged — excepting the case, when this number was non-zero, but the result is zero (i.e. not positive and not negative).

      Parameters:
      other - value to be AND'ed with this number.
      Returns:
      a reference to this object.
    • or

      public MutableInt128 or(MutableInt128 other)
      Replaces all bits of the absolute value of this number with bitwise OR of this and other number: |this| = |this| | |other|.

      The sign of this number stays unchanged — excepting the case, when this number was zero, but the result is nonzero (i.e. positive or negative).

      Parameters:
      other - value to be OR'ed with this number.
      Returns:
      a reference to this object.
    • xor

      public MutableInt128 xor(MutableInt128 other)
      Replaces all bits of the absolute value of this number with bitwise XOR of this and other number: |this| = |this| ^ |other|.

      The sign of this number stays unchanged — excepting the case, when this number or the result is zero (i.e. not positive and not negative).

      Parameters:
      other - value to be XOR'ed with this number.
      Returns:
      a reference to this object.
    • not

      public MutableInt128 not()
      Inverts all bits of the absolute value of this number: |this| = ~|this|.

      The sign of this number stays unchanged — excepting the case, when this number or the result is zero (i.e. not positive and not negative).

      Returns:
      a reference to this object.
    • numberOfLeadingZeros

      public int numberOfLeadingZeros()
      Returns the number of zero bits preceding the highest-order ("leftmost") one-bit in the 128-bit absolute value of this number. Returns 128 if this number is zero.

      It is a 128-bit analogue of the standard Long.numberOfLeadingZeros method, but working with the absolute value of this number (instead of two's complement binary representation).

      Returns:
      the number of leading zero bits in the absolute value of this number, or 128 for zero number.
    • numberOfTrailingZeros

      public int numberOfTrailingZeros()
      Returns the number of zero bits following the lowest-order ("rightmost") one-bit in the 128-bit absolute value of this number. Returns 128 if this number is zero.

      It is a 128-bit analogue of the standard Long.numberOfTrailingZeros method, but working with the absolute value of this number (instead of two's complement binary representation).

      Returns:
      the number of trailing zero bits in the absolute value of this number, or 128 for zero number.
    • bitCount

      public int bitCount()
      Returns the number of one-bits in the 128-bit absolute value of this number.

      It is a 128-bit analogue of the standard Long.bitCount method, but working with the absolute value of this number (instead of two's complement binary representation).

      Returns:
      the number of one-bits in the binary representation of the absolute value of this number.
    • negate

      public MutableInt128 negate()
      Changes the sign of this integer number and stores the result in this object. Note: this method does not anything for zero number.
      Returns:
      a reference to this object.
    • abs

      public MutableInt128 abs()
      Replaces this number with its absolute value.
      Returns:
      a reference to this object.
    • add

      public MutableInt128 add(MutableInt128 other) throws ArithmeticException
      Adds the given other number to this one and stores the sum in this object.
      Returns:
      a reference to this object.
      Throws:
      ArithmeticException - in a case of arithmetic overflow.
      NullPointerException - if the argument is null.
    • subtract

      public MutableInt128 subtract(MutableInt128 other) throws ArithmeticException
      Subtracts the given other number from this one and stores the difference in this object.
      Returns:
      a reference to this object.
      Throws:
      ArithmeticException - in a case of arithmetic overflow.
      NullPointerException - if the argument is null.
    • addLong

      public MutableInt128 addLong(long value)
      Adds the given integer value to this number.
      Parameters:
      value - any long value to add.
      Returns:
      a reference to this object.
      Throws:
      ArithmeticException - in a case of arithmetic overflow.
    • setToLongLongProduct

      public MutableInt128 setToLongLongProduct(long firstMultiplier, long secondMultiplier)
      Sets this object to be equal to the exact product firstMultiplier*secondMultiplier.
      Parameters:
      firstMultiplier - first multiplicand.
      secondMultiplier - second multiplicand.
      Returns:
      a reference to this object.
    • setToLongIntProduct

      public MutableInt128 setToLongIntProduct(long firstMultiplier, int secondMultiplier)
      Sets this object to be equal to the exact product firstMultiplier*secondMultiplier.

      Note: this method works faster than setToLongLongProduct(long, long).

      Parameters:
      firstMultiplier - first multiplicand.
      secondMultiplier - second multiplicand.
      Returns:
      a reference to this object.
    • setToUnsignedLongLongProduct

      public MutableInt128 setToUnsignedLongLongProduct(long firstMultiplier, long secondMultiplier)
      Sets this object to be equal to the exact unsigned product firstMultiplier*secondMultiplier, where the arguments are interpreted as unsigned 64-bit integers. The result is always non-negative.

      Note: this method works little faster than setToLongLongProduct(long, long).

      Parameters:
      firstMultiplier - first multiplicand (interpreted as unsigned 64-bit integer number).
      secondMultiplier - second multiplicand (interpreted as unsigned 64-bit integer number).
      Returns:
      a reference to this object.
    • setToLongSqr

      public MutableInt128 setToLongSqr(long value)
      Sets this object to be equal to the exact square of the given value: value*value. Equivalent to
          setToLongLongProduct(value, value)
       
      Parameters:
      value - some long signed value.
      Returns:
      a reference to this object.
    • addLongLongProduct

      public MutableInt128 addLongLongProduct(long firstMultiplier, long secondMultiplier)
      Calculate exact product firstMultiplier*secondMultiplier and adds it to this number. Equivalent to
          add(new MutableLongLong().setToLongLongProduct(firstMultiplier, secondMultiplier))
      Parameters:
      firstMultiplier - first multiplicand.
      secondMultiplier - second multiplicand.
      Returns:
      a reference to this object.
      Throws:
      ArithmeticException - in a case of arithmetic overflow while adding.
    • addLongIntProduct

      public MutableInt128 addLongIntProduct(long firstMultiplier, int secondMultiplier)
      Calculate exact product firstMultiplier*secondMultiplier and adds it to this number. Equivalent to
          add(new MutableLongLong().setToLongIntProduct(firstMultiplier, secondMultiplier))

      Note: this method works faster than addLongLongProduct(long, long).

      Parameters:
      firstMultiplier - first multiplicand.
      secondMultiplier - second multiplicand.
      Returns:
      a reference to this object.
      Throws:
      ArithmeticException - in a case of arithmetic overflow while adding.
    • addUnsignedLongLongProduct

      public MutableInt128 addUnsignedLongLongProduct(long firstMultiplier, long secondMultiplier)
      Calculate exact unsigned product firstMultiplier*secondMultiplier, where the arguments are interpreted as unsigned (non-negative) 64-bit integers, and adds it to this number. Equivalent to
          add(new MutableLongLong().setToUnsignedLongLongProduct(firstMultiplier, secondMultiplier))

      Note: this method works little faster than addLongLongProduct(long, long).

      Parameters:
      firstMultiplier - first multiplicand (interpreted as unsigned 64-bit integer number).
      secondMultiplier - second multiplicand (interpreted as unsigned 64-bit integer number).
      Returns:
      a reference to this object.
      Throws:
      ArithmeticException - in a case of arithmetic overflow while adding.
    • addLongSqr

      public MutableInt128 addLongSqr(long value)
      Calculate exact exact square of the given value: value*value and adds it to this number. Equivalent to
          add(new MutableLongLong().setToLongSqr(value))
      Parameters:
      value - some long signed value.
      Returns:
      a reference to this object.
      Throws:
      ArithmeticException - in a case of arithmetic overflow while adding.
    • clone

      public MutableInt128 clone()
      Returns an exact copy of this integer number.
      Overrides:
      clone in class Object
      Returns:
      a reference to the clone.
    • compareTo

      public int compareTo(MutableInt128 o)
      Compares this number with the specified one.
      Specified by:
      compareTo in interface Comparable<MutableInt128>
      Parameters:
      o - other number to which this number is to be compared.
      Returns:
      -1, 0 or 1 as this number is numerically less than, equal to, or greater than o.
      Throws:
      NullPointerException - if the argument is null.
    • toString

      public String toString()
      Returns the decimal String representation of this number.
      Overrides:
      toString in class Object
      Returns:
      decimal String representation of this number.
    • toString

      public String toString(int radix)
      Returns the String representation of this number with the given radix. If the radix is outside the range from Character.MIN_RADIX to Character.MAX_RADIX inclusive, it will default to 10 (as is the case for Integer.toString).
      Parameters:
      radix - radix of the String representation.
      Returns:
      decimal String representation of this number.
    • equals

      public boolean equals(Object o)
      Indicates whether some other object is an instance of this class, equal to this number. Note that two objects, containing zero number, are always equal, regardless on possible calling negate() method.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to be compared for equality with this instance.
      Returns:
      true if and only if the specified object is an instance of MutableInt128, containing the same mathematical integer number as this object.
    • hashCode

      public int hashCode()
      Returns the hash code of this number.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this number.
    • unsignedToDouble

      public static double unsignedToDouble(long value)
      Converts the passed value, interpreted as unsigned 64-bit value, into double, and returns it. The result of this method is always non-negative. This conversion is similar to the narrowing primitive conversion, like described in comments to doubleValue() method of the standard BigInteger.
      Parameters:
      value - some long value (interpreted as unsigned 64-bit integer).
      Returns:
      double, maximally close to this unsigned 64-bit integer number.
    • shiftRightRounding

      public static long shiftRightRounding(long value, int shift)
      Divides the given value by 2shift and rounds the result to the closest long value. If two integer numbers are equally close to the result of division, the result is the long integer value, which is even. In other words, this method returns
          [value/2.0shift],
      where [w] means the mathematical integer, closest to w, like in Math.rint() method.

      If the argument shift is too large (≥64), the method returns 0.

      Shifting by 0 bits (shift=0) returns unchanged value.

      Parameters:
      value - some (signed) long value.
      shift - number of bits to shift.
      Returns:
      the long integer, closest to value/2.0shift.
      Throws:
      IllegalArgumentException - if shift argument is negative.
    • unsignedShiftRightRounding

      public static long unsignedShiftRightRounding(long value, int shift)
      Divides the given value, interpreted as unsigned 64-bit value, by 2shift and rounds the result to the closest unsigned 64-bit long value. If two integer numbers are equally close to the result of division, the result is the unsigned 64-bit integer value, which is even. It is an unsigned analogue of shiftRightRounding(long, int) method.

      If the argument shift is too large (≥64), the method returns 0.

      Shifting by 0 bits (shift=0) returns unchanged value.

      Parameters:
      value - some (unsigned) 64-bit integer value.
      shift - number of bits to shift.
      Returns:
      the 64-bit unsigned integer, closest to value/2.0shift.
      Throws:
      IllegalArgumentException - if shift argument is negative.