net.sf.ivmaidns.util
Class UnsignedLong

java.lang.Object
  java.lang.Number
      net.sf.ivmaidns.util.UnsignedLong

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Immutable, ReallyCloneable, Sortable

public final class UnsignedLong
extends java.lang.Number
implements Immutable, ReallyCloneable, Sortable

Class for unsigned 'long' wrappers. This class wraps a primitive unsigned long value (like Long class). The class also contains static methods for the unsigned long integer arithmetic: comparison, median, multiplication (simple and modular), division, remainder, power, logarithm, factorial, 'greatest common divisor', modular inversion, conversion to/from a byte array (in the direct and reversed orders), stream bits writing/reading, conversion to/from a string (in some given radix).

Version:

2.0

Author:

Ivan Maidanski

See Also:

UnsignedInt, LongVector, ByteVector, PseudoRandom, JavaConsts, Serialized Form

Field Summary

protected long

unsignedValue The wrapped (encapsulated) unsigned long value.

Constructor Summary

UnsignedLong(long unsignedValue)
Constructs a new object that represents the specified primitive unsigned long value.

Method Summary

static int	binLog(long unsignedValue) Returns the integer part of binary logarithm of a given unsigned value.
java.lang.Object	clone() Creates and returns a copy of this object.
static int	compare(long unsignedA, long unsignedB) Compares two given unsigned integer values.
static long	decode(java.lang.String str, int beginIndex, int endIndex) Decodes a given string region as an unsigned octal/decimal/hexadecimal integer value.
static long	div(long unsignedA, long unsignedB) Returns the result of integer division of one given unsigned value by another one.
static long	divHigh(long unsignedHighA, long unsignedLowA, long unsignedB) Returns the highest half of the result of integer division of join of two given halves of unsigned value by another one.
static long	divLow(long unsignedHighA, long unsignedLowA, long unsignedB) Returns the lowest half of the result of integer division of join of two given halves of unsigned value by another one.
double	doubleValue() Returns the value of this number as double.
boolean	equals(java.lang.Object obj) Indicates whether this object is equal to the specified one.
static long	factorial(int value) Computes the factorial of a given value.
float	floatValue() Returns the value of this number as float.
static long	gcd(long unsignedA, long unsignedB) Computes the greatest 'common divisor' (gcd) of two given unsigned non-zero values.
static long	getFromByteArray(byte[] bytes, int offset, int len) Converts the specified region of a given byte array into an unsigned value.
static long	getFromIntelArray(byte[] bytes, int offset, int len) Converts the specified region of a given byte array into an unsigned value in the reversed order.
static boolean	greater(long unsignedA, long unsignedB) Tests whether the first specified unsigned integer is greater than the second one.
static boolean	greaterOrEqual(long unsignedA, long unsignedB) Tests whether the first specified unsigned integer is greater or equal to the second one.
boolean	greaterThan(java.lang.Object obj) Tests for being semantically greater than the argument.
int	hashCode() Returns a hash code value for the object.
static int	hashCode(long value) Converts long value into its hash code value.
int	intValue() Returns the value of this number as int.
static long	inverseMod(long unsignedA, long unsignedMax) Computes the modular 'inversion' of a given unsigned value.
long	longValue() Returns the value of this number as long.
static long	max(long unsignedA, long unsignedB) Returns the maximum of two given unsigned integer values.
static long	median(long unsignedA, long unsignedB, long unsignedC) Returns the 'median' (middle value) of three given unsigned integer values.
static long	min(long unsignedA, long unsignedB) Returns the minimum of two given unsigned integer values.
static long	mulDiv(long unsignedA, long unsignedB, long unsignedC, boolean roundUp) Returns the lowest half of the result of integer division of 'long' (full) product of the first two given unsigned non-zero values by the third given unsigned non-zero value.
static long	mulHigh(long unsignedA, long unsignedB) Returns the highest half of 'long' (full) product of two given unsigned integers.
static long	mulLow(long unsignedA, long unsignedB) Returns the lowest half of 'long' (full) product of two given unsigned integers.
static long	mulMod(long unsignedA, long unsignedB, long unsignedMax) Computes the modular 'multiplication' of two given unsigned values.
static long	parse(java.lang.String str, int beginIndex, int endIndex, boolean isUnsigned, int radix) Parses a given string region as a signed/unsigned integer in the specified radix.
static long	power(long value, int degree) Returns a given value involved to the power of the specified degree.
static void	putToByteArray(byte[] bytes, int offset, long unsignedValue, int len) Puts a given value into the specified byte array.
static void	putToIntelArray(byte[] bytes, int offset, long unsignedValue, int len) Puts a given value into the specified byte array in the reversed order.
static long	readBits(java.io.InputStream in, int count) Reads a group of bits from a given input stream.
static long	rem(long unsignedA, long unsignedB) Returns the remainder of integer division of one given unsigned value by another one.
static long	remLow(long unsignedHighA, long unsignedLowA, long unsignedB) Returns the remainder of integer division of join of two given halves of unsigned value by another one.
static int	signedCompare(long valueA, long valueB) Compares two given (signed) integer values.
static long	signedMedian(long valueA, long valueB, long valueC) Returns the 'median' (middle value) of three given (signed) integer values.
static java.lang.String	toBinaryString(long unsignedValue, int minLength) Converts a given unsigned value into its binary string representation.
static byte[]	toByteArray(long unsignedValue, int len) Converts a given value into a byte array.
static java.lang.String	toHexString(long unsignedValue, boolean upperCase, int minLength) Converts a given unsigned value into its hexadecimal string representation.
static byte[]	toIntelArray(long unsignedValue, int len) Converts a given value in the reversed order into a byte array.
static java.lang.String	toOctalString(long unsignedValue, int minLength) Converts a given unsigned value into its octal string representation.
java.lang.String	toString() Converts this object to its 'in-line' string representation.
static java.lang.String	toString(long value, boolean isUnsigned) Converts a given signed/unsigned value into its decimal string representation.
static java.lang.String	toString(long value, boolean isUnsigned, boolean forceSign, int radix, boolean upperCase, int minLength) Converts a given signed/unsigned value into its string representation in the specified radix.
static UnsignedLong	valueOf(java.lang.String str) Converts a given string to an instance of this class.
static void	writeBits(java.io.OutputStream out, long unsignedValue, int count) Writes a group of bits to a given output stream.

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

unsignedValue

protected long unsignedValue

The wrapped (encapsulated) unsigned long value. Important notes: this value is constant.

See Also:

UnsignedLong(long), valueOf(java.lang.String), clone(), hashCode(), intValue(), longValue(), floatValue(), doubleValue(), equals(java.lang.Object), greaterThan(java.lang.Object), toString()

Constructor Detail

UnsignedLong

public UnsignedLong(long unsignedValue)

Constructs a new object that represents the specified primitive unsigned long value.

Parameters:

unsignedValue - the unsigned value to be wrapped.

See Also:

valueOf(java.lang.String), clone(), intValue(), longValue(), equals(java.lang.Object), greaterThan(java.lang.Object), toString()

Method Detail

hashCode

public static final int hashCode(long value)

Converts long value into its hash code value. The bits of the specified value are mixed in a particular order to produce a single int 'hash' value.

Parameters:

value - the signed/unsigned value to be hashed.

Returns:

the resulting hash code value.

Since:

1.1

See Also:

hashCode(), intValue()

greater

public static final boolean greater(long unsignedA,
                                    long unsignedB)

Tests whether the first specified unsigned integer is greater than the second one.

Parameters:

unsignedA - the first compared unsigned value.

unsignedB - the second compared unsigned value.

Returns:

true if and only if unsignedA is greater than unsignedB (in the unsigned manner).

See Also:

greaterOrEqual(long, long), compare(long, long), min(long, long), max(long, long), median(long, long, long), greaterThan(java.lang.Object)

greaterOrEqual

public static final boolean greaterOrEqual(long unsignedA,
                                           long unsignedB)

Tests whether the first specified unsigned integer is greater or equal to the second one.

Parameters:

unsignedA - the first compared unsigned value.

unsignedB - the second compared unsigned value.

Returns:

true if and only if unsignedA is not less than unsignedB (in the unsigned manner).

See Also:

greater(long, long), compare(long, long), min(long, long), max(long, long), median(long, long, long), equals(java.lang.Object), greaterThan(java.lang.Object)

compare

public static final int compare(long unsignedA,
                                long unsignedB)

Compares two given unsigned integer values. This method returns a signed integer indicating 'less-equal-greater' relation between the specified long values.

Parameters:

unsignedA - the first compared unsigned value.

unsignedB - the second compared unsigned value.

Returns:

a negative integer, zero, or a positive integer as valueA is less than, equal to, or greater than valueB (in the unsigned manner).

See Also:

signedCompare(long, long), greater(long, long), greaterOrEqual(long, long), min(long, long), max(long, long), median(long, long, long), equals(java.lang.Object), greaterThan(java.lang.Object)

signedCompare

public static final int signedCompare(long valueA,
                                      long valueB)

Compares two given (signed) integer values. This method returns a signed integer indicating 'less-equal-greater' relation between the specified long values.

Parameters:

valueA - the first compared (signed) value.

valueB - the second compared (signed) value.

Returns:

a negative integer, zero, or a positive integer as valueA is less than, equal to, or greater than valueB.

Since:

2.0

See Also:

compare(long, long), signedMedian(long, long, long)

min

public static final long min(long unsignedA,
                             long unsignedB)

Returns the minimum of two given unsigned integer values.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

Returns:

unsignedA if unsignedA is less (in the unsigned manner) than unsignedB, else unsignedB.

See Also:

max(long, long), median(long, long, long), greater(long, long), greaterOrEqual(long, long), compare(long, long)

max

public static final long max(long unsignedA,
                             long unsignedB)

Returns the maximum of two given unsigned integer values.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

Returns:

unsignedA if unsignedA is greater (in the unsigned manner) than unsignedB, else unsignedB.

See Also:

min(long, long), median(long, long, long), greater(long, long), greaterOrEqual(long, long), compare(long, long)

median

public static final long median(long unsignedA,
                                long unsignedB,
                                long unsignedC)

Returns the 'median' (middle value) of three given unsigned integer values.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

unsignedC - the third unsigned value.

Returns:

unsignedA, unsignedB or unsignedC according to which one of these values is between (in the unsigned manner) the other values.

Since:

1.1

See Also:

signedMedian(long, long, long), min(long, long), max(long, long), greater(long, long), greaterOrEqual(long, long), compare(long, long)

signedMedian

public static final long signedMedian(long valueA,
                                      long valueB,
                                      long valueC)

Returns the 'median' (middle value) of three given (signed) integer values.

Parameters:

valueA - the first (signed) value.

valueB - the second (signed) value.

valueC - the third (signed) value.

Returns:

valueA, valueB or valueC according to which one of these values is between the other values.

Since:

1.1

See Also:

median(long, long, long), signedCompare(long, long)

mulHigh

public static final long mulHigh(long unsignedA,
                                 long unsignedB)

Returns the highest half of 'long' (full) product of two given unsigned integers.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the (unsigned) top half of unsignedA multiplied by unsignedB.

See Also:

divHigh(long, long, long), mulLow(long, long), mulDiv(long, long, long, boolean), mulMod(long, long, long), power(long, int), factorial(int)

mulLow

public static final long mulLow(long unsignedA,
                                long unsignedB)

Returns the lowest half of 'long' (full) product of two given unsigned integers.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the (unsigned) bottom half of unsignedA multiplied by unsignedB.

See Also:

divLow(long, long, long), remLow(long, long, long), mulHigh(long, long), mulDiv(long, long, long, boolean), mulMod(long, long, long), power(long, int), factorial(int)

div

public static final long div(long unsignedA,
                             long unsignedB)
                      throws java.lang.ArithmeticException

Returns the result of integer division of one given unsigned value by another one.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the unsigned result of unsignedA divided by unsignedB.

Throws:

java.lang.ArithmeticException - if unsignedB is 0.

See Also:

mulLow(long, long), rem(long, long), divHigh(long, long, long), divLow(long, long, long), mulDiv(long, long, long, boolean), gcd(long, long), inverseMod(long, long)

divHigh

public static final long divHigh(long unsignedHighA,
                                 long unsignedLowA,
                                 long unsignedB)
                          throws java.lang.ArithmeticException

Returns the highest half of the result of integer division of join of two given halves of unsigned value by another one. The result is the same as of div(unsignedHighA, unsignedB).

Parameters:

unsignedHighA - the top half of the first unsigned value.

unsignedLowA - the bottom half of the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the top half of the unsigned result of joined unsignedHighA:unsignedLowA divided by unsignedB.

Throws:

java.lang.ArithmeticException - if unsignedB is 0.

See Also:

divLow(long, long, long), mulHigh(long, long), mulLow(long, long), div(long, long), mulDiv(long, long, long, boolean)

divLow

public static final long divLow(long unsignedHighA,
                                long unsignedLowA,
                                long unsignedB)
                         throws java.lang.ArithmeticException

Returns the lowest half of the result of integer division of join of two given halves of unsigned value by another one.

Parameters:

unsignedHighA - the top half of the first unsigned value.

unsignedLowA - the bottom half of the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the bottom half of the unsigned result of joined unsignedHighA:unsignedLowA divided by unsignedB.

Throws:

java.lang.ArithmeticException - if unsignedB is 0.

See Also:

divHigh(long, long, long), remLow(long, long, long), mulHigh(long, long), mulLow(long, long), div(long, long), mulDiv(long, long, long, boolean), gcd(long, long)

rem

public static final long rem(long unsignedA,
                             long unsignedB)
                      throws java.lang.ArithmeticException

Returns the remainder of integer division of one given unsigned value by another one. The result is the same as of (unsignedA - div(unsignedA, unsignedB) * unsignedB).

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the unsigned remainder when unsignedA is divided by unsignedB.

Throws:

java.lang.ArithmeticException - if unsignedB is 0.

See Also:

mulLow(long, long), div(long, long), remLow(long, long, long), inverseMod(long, long)

remLow

public static final long remLow(long unsignedHighA,
                                long unsignedLowA,
                                long unsignedB)
                         throws java.lang.ArithmeticException

Returns the remainder of integer division of join of two given halves of unsigned value by another one.

Parameters:

unsignedHighA - the top half of the first unsigned value.

unsignedLowA - the bottom half of the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the unsigned remainder when joined unsignedHighA:unsignedLowA is divided by unsignedB.

Throws:

java.lang.ArithmeticException - if unsignedB is 0.

See Also:

rem(long, long), divLow(long, long, long), mulHigh(long, long), mulLow(long, long), mulMod(long, long, long)

power

public static final long power(long value,
                               int degree)

Returns a given value involved to the power of the specified degree. Overflow is not checked. If degree is negative then 0 is returned. Important notes: value may be signed or unsigned.

Parameters:

value - the signed/unsigned value to be involved to the power.

degree - the degree of the power.

Returns:

the signed/unsigned result of involving value to the power of degree.

Since:

1.1

See Also:

mulLow(long, long), binLog(long), factorial(int)

binLog

public static final int binLog(long unsignedValue)

Returns the integer part of binary logarithm of a given unsigned value. If unsignedValue is zero then -1 is returned, else the result is in the range from 0 to (JavaConsts LONG_SIZE - 1), inclusive.

Parameters:

unsignedValue - the unsigned argument of the logarithm.

Returns:

the result of logarithm computation for unsignedValue.

Since:

1.2

See Also:

power(long, int), factorial(int)

factorial

public static final long factorial(int value)

Computes the factorial of a given value. Overflow is not checked. If value is negative or zero then 0 is returned.

Parameters:

value - the factorial argument.

Returns:

the unsigned result of the factorial computation for value.

Since:

1.1

See Also:

mulLow(long, long), power(long, int), binLog(long)

gcd

public static final long gcd(long unsignedA,
                             long unsignedB)

Computes the greatest 'common divisor' (gcd) of two given unsigned non-zero values. Important notes: zero value (for any argument or result) is treated as the largest unsigned long value plus one.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

Returns:

the unsigned greatest common divisor of both unsignedA and unsignedB.

Since:

1.1

See Also:

inverseMod(long, long), mulMod(long, long, long), mulDiv(long, long, long, boolean), binLog(long)

inverseMod

public static final long inverseMod(long unsignedA,
                                    long unsignedMax)

Computes the modular 'inversion' of a given unsigned value. It is the inverse operation for modular multiplication. That is, if both unsignedA and unsignedMax are non-zero and gcd(unsignedA, unsignedMax + 1) == 1 then mulMod(result, unsignedA, unsignedMax) is 1. The result of modular inversion is in the range from 1 to max(unsignedMax, 1), inclusive.

Parameters:

unsignedA - the unsigned value to inverse.

unsignedMax - the unsigned maximum for modular multiplication.

Returns:

the unsigned result (not zero) of modular inversion of unsignedA with respect to unsignedMax.

Since:

1.1

See Also:

mulMod(long, long, long), gcd(long, long), div(long, long), rem(long, long)

mulMod

public static final long mulMod(long unsignedA,
                                long unsignedB,
                                long unsignedMax)

Computes the modular 'multiplication' of two given unsigned values. This method returns the remainder of the result of integer division of 'long' (full) product of unsignedA and unsignedB by (unsignedMax plus one). The result is in the range from 0 to unsignedMax, inclusive.

Parameters:

unsignedA - the first unsigned value to multiply.

unsignedB - the second unsigned value to multiply.

unsignedMax - the unsigned maximum value for the result to have.

Returns:

the unsigned result of modular multiplication of unsignedA and unsignedB with respect to unsignedMax.

Since:

1.1

See Also:

inverseMod(long, long), gcd(long, long), mulDiv(long, long, long, boolean), mulHigh(long, long), remLow(long, long, long)

mulDiv

public static final long mulDiv(long unsignedA,
                                long unsignedB,
                                long unsignedC,
                                boolean roundUp)

Returns the lowest half of the result of integer division of 'long' (full) product of the first two given unsigned non-zero values by the third given unsigned non-zero value. Important notes: zero value (for any argument) is treated as the largest unsigned long value plus one.

Parameters:

unsignedA - the first unsigned value.

unsignedB - the second unsigned value.

unsignedC - the unsigned divisor value.

roundUp - true if the result of division is rounded upwards (to the nearest greater integer value), else it is rounded towards zero.

Returns:

the bottom half of the unsigned result of unsignedA multiplied by unsignedB and divided by unsignedC.

See Also:

mulHigh(long, long), mulLow(long, long), divLow(long, long, long), gcd(long, long), mulMod(long, long, long), inverseMod(long, long)

putToByteArray

public static final void putToByteArray(byte[] bytes,
                                        int offset,
                                        long unsignedValue,
                                        int len)
                                 throws java.lang.NullPointerException,
                                        java.lang.ArrayIndexOutOfBoundsException

Puts a given value into the specified byte array. This method splits unsignedValue to separate bytes and puts them into bytes array sequentially (the last put byte is the lowest of unsignedValue), starting at offset. Negative len is treated as zero. If an exception is thrown then bytes remains changed. Else bytes content is altered. Important notes: if len is greater than JavaConsts LONG_LENGTH then unsignedValue is zero-extended.

Parameters:

bytes - the byte array (must be non-null) to put to.

offset - the first array index (must be in the range) to put at.

unsignedValue - the value, containing the bytes (in its lowest part) to be put.

len - the amount of bytes to put.

Throws:

java.lang.NullPointerException - if bytes is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of bytes minus len).

Since:

1.1

See Also:

toByteArray(long, int), getFromByteArray(byte[], int, int), putToIntelArray(byte[], int, long, int), writeBits(java.io.OutputStream, long, int)

toByteArray

public static final byte[] toByteArray(long unsignedValue,
                                       int len)

Converts a given value into a byte array. This method splits unsignedValue to separate bytes and sequentially puts them into a newly created byte array (the last put byte is the lowest of unsignedValue) of len length. Negative len is treated as zero. Important notes: if len is greater than JavaConsts LONG_LENGTH then unsignedValue is zero-extended.

Parameters:

unsignedValue - the value, containing the bytes (in its lowest part) to be put.

len - the amount of bytes to put (length of the array to create).

Returns:

a newly created byte array (not null, with length the same as non-negative len), containing the bytes of unsignedValue.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

Since:

1.1

See Also:

putToByteArray(byte[], int, long, int), getFromByteArray(byte[], int, int), toIntelArray(long, int), writeBits(java.io.OutputStream, long, int)

getFromByteArray

public static final long getFromByteArray(byte[] bytes,
                                          int offset,
                                          int len)
                                   throws java.lang.NullPointerException,
                                          java.lang.ArrayIndexOutOfBoundsException

Converts the specified region of a given byte array into an unsigned value. This method gets the elements of bytes array sequentially starting at offset and joins them into an unsigned value (the last got byte is the lowest of the result). Negative len is treated as zero. bytes content is not modified.

Parameters:

bytes - the byte array (must be non-null) to get from.

offset - the first array index (must be in the range) to get at.

len - the amount of bytes to get.

Returns:

an unsigned value, containing the got bytes (in its lowest part).

Throws:

java.lang.NullPointerException - if bytes is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of bytes minus len).

Since:

1.1

See Also:

putToByteArray(byte[], int, long, int), toByteArray(long, int), getFromIntelArray(byte[], int, int), readBits(java.io.InputStream, int)

putToIntelArray

public static final void putToIntelArray(byte[] bytes,
                                         int offset,
                                         long unsignedValue,
                                         int len)
                                  throws java.lang.NullPointerException,
                                         java.lang.ArrayIndexOutOfBoundsException

Puts a given value into the specified byte array in the reversed order. This method splits unsignedValue to separate bytes and puts them into bytes array sequentially but in the reversed ('Intel') order (the first put byte is the lowest of unsignedValue), starting at offset (and moving forward). Negative len is treated as zero. If an exception is thrown then bytes remains changed. Else bytes content is altered. Important notes: if len is greater than JavaConsts LONG_LENGTH then unsignedValue is zero-extended.

Parameters:

bytes - the byte array (must be non-null) to put to.

offset - the first array index (must be in the range) to put at.

unsignedValue - the value, containing the bytes (in its lowest part) to be put.

len - the amount of bytes to put.

Throws:

java.lang.NullPointerException - if bytes is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of bytes minus len).

Since:

2.0

See Also:

toIntelArray(long, int), getFromIntelArray(byte[], int, int), putToByteArray(byte[], int, long, int)

toIntelArray

public static final byte[] toIntelArray(long unsignedValue,
                                        int len)

Converts a given value in the reversed order into a byte array. This method splits unsignedValue to separate bytes and sequentially puts them into a newly created byte array but in the reversed ('Intel') order (the first put byte is the lowest of unsignedValue) of len length. Negative len is treated as zero. Important notes: if len is greater than JavaConsts LONG_LENGTH then unsignedValue is zero-extended.

Parameters:

unsignedValue - the value, containing the bytes (in its lowest part) to be put.

len - the amount of bytes to put (length of the array to create).

Returns:

a newly created byte array (not null, with length the same as non-negative len), containing the bytes of unsignedValue.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

Since:

2.0

See Also:

putToIntelArray(byte[], int, long, int), getFromIntelArray(byte[], int, int), toByteArray(long, int)

getFromIntelArray

public static final long getFromIntelArray(byte[] bytes,
                                           int offset,
                                           int len)
                                    throws java.lang.NullPointerException,
                                           java.lang.ArrayIndexOutOfBoundsException

Converts the specified region of a given byte array into an unsigned value in the reversed order. This method gets the elements of bytes array sequentially but in the reversed ('Intel') order, starting at offset (and moving forward) and joins them into an unsigned value (the first got byte is the lowest of the result). Negative len is treated as zero. bytes content is not modified.

Parameters:

bytes - the byte array (must be non-null) to get from.

offset - the first array index (must be in the range) to get at.

len - the amount of bytes to get.

Returns:

an unsigned value, containing the got bytes (in its lowest part).

Throws:

java.lang.NullPointerException - if bytes is null.

java.lang.ArrayIndexOutOfBoundsException - if len is positive and (offset is negative or is greater than length of bytes minus len).

Since:

2.0

See Also:

putToIntelArray(byte[], int, long, int), toIntelArray(long, int), getFromByteArray(byte[], int, int)

writeBits

public static final void writeBits(java.io.OutputStream out,
                                   long unsignedValue,
                                   int count)
                            throws java.lang.NullPointerException,
                                   java.io.IOException

Writes a group of bits to a given output stream. Negative count is treated as zero. Important notes: if count is greater than JavaConsts LONG_SIZE then the specified value (containing the bits to write) is zero-extended; out is a byte-oriented stream, so given bits are padded with zeros (on the most significant side); the bits are written starting from the most significant one.

Parameters:

out - the stream (must be non-null) to write to.

unsignedValue - the unsigned value, containing bits (in its lowest part) to be written.

count - the amount of bits to be written.

Throws:

java.lang.NullPointerException - if out is null.

java.io.IOException - if an I/O error occurs.

Since:

1.1

See Also:

readBits(java.io.InputStream, int)

readBits

public static final long readBits(java.io.InputStream in,
                                  int count)
                           throws java.lang.NullPointerException,
                                  java.io.IOException

Reads a group of bits from a given input stream. Negative count is treated as zero. If the end-of-stream is detected then EOFException (subclass of IOException) is thrown. Important notes: if count is greater than JavaConsts LONG_SIZE then the result contains only tail (the least significant) read bits portion fit the result; in is a byte-oriented stream, so padding bits are read but set to zero (on the most significant side); the bits are read starting from the most significant one.

Parameters:

in - the stream (must be non-null) to read from.

count - the amount of bits to be read.

Returns:

an unsigned value, containing read bits (in its lowest part, the highest part of the result is set to zero if count is less than JavaConsts LONG_SIZE).

Throws:

java.lang.NullPointerException - if in is null.

java.io.IOException - if the end-of-stream has been reached or an I/O error occurs.

Since:

1.1

See Also:

writeBits(java.io.OutputStream, long, int)

toString

public static final java.lang.String toString(long value,
                                              boolean isUnsigned,
                                              boolean forceSign,
                                              int radix,
                                              boolean upperCase,
                                              int minLength)

Converts a given signed/unsigned value into its string representation in the specified radix. value is unsigned only if isUnsigned and not forceSign. If forceSign then result always has a sign (if isUnsigned then the positive sign is space else '+' character) else result has a sign ('-' character) if value is negative. The result is left-padded with spaces (before the sign prefix) if minLength is negative else with '0' characters (after the sign prefix). The absolute value of minLength specifies the minimal length of the result (anyhow, the result contains at least one digit). The full digits character set is '0' through '9', 'A' through 'Z' and 'a' through 'z'. If the specified radix is invalid (less than two or too big) then it is corrected to the nearest valid one.

Parameters:

value - the signed/unsigned value to be converted.

isUnsigned - true if value must be treated as an unsigned value (but only if not forceSign), else value is signed.

forceSign - true if and only if the result must always have a sign (positive or negative).

radix - the radix (any value) to be used as a base of the value string format.

upperCase - true if and only if (digit) characters in the result are in the upper case.

minLength - the minimal length of the result (absolute value) and pad prefix specifier (if negative then space padding else zero padding).

Returns:

the string representation (not null, with length() not less than max(abs(minLength), 1)) of value in the specified radix.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

toBinaryString(long, int), toOctalString(long, int), toString(long, boolean), toHexString(long, boolean, int), parse(java.lang.String, int, int, boolean, int), decode(java.lang.String, int, int)

toString

public static final java.lang.String toString(long value,
                                              boolean isUnsigned)

Converts a given signed/unsigned value into its decimal string representation.

Parameters:

value - the signed/unsigned value to be converted.

isUnsigned - true if value must be treated as an unsigned value, else value is signed.

Returns:

the string representation (not null, with non-zero length()) of value in the decimal radix.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

toString(long, boolean, boolean, int, boolean, int), toBinaryString(long, int), toOctalString(long, int), toHexString(long, boolean, int), parse(java.lang.String, int, int, boolean, int), decode(java.lang.String, int, int)

toBinaryString

public static final java.lang.String toBinaryString(long unsignedValue,
                                                    int minLength)

Converts a given unsigned value into its binary string representation. The result is left-padded with spaces if minLength is negative else with '0' characters. The absolute value of minLength specifies the minimal length of the result (anyhow, the result contains at least one digit).

Parameters:

unsignedValue - the unsigned value to be converted.

minLength - the minimal length of the result (absolute value) and pad prefix specifier (if negative then space padding else zero padding).

Returns:

the string representation (not null, with length() not less than max(abs(minLength), 1)) of unsignedValue in the binary radix.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

toString(long, boolean, boolean, int, boolean, int), toOctalString(long, int), toString(long, boolean), toHexString(long, boolean, int), parse(java.lang.String, int, int, boolean, int)

toOctalString

public static final java.lang.String toOctalString(long unsignedValue,
                                                   int minLength)

Converts a given unsigned value into its octal string representation. The result is left-padded with spaces if minLength is negative else with '0' characters. The absolute value of minLength specifies the minimal length of the result (anyhow, the result contains at least one digit).

Parameters:

unsignedValue - the unsigned value to be converted.

minLength - the minimal length of the result (absolute value) and pad prefix specifier (if negative then space padding else zero padding).

Returns:

the string representation (not null, with length() not less than max(abs(minLength), 1)) of unsignedValue in the octal radix.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

toString(long, boolean, boolean, int, boolean, int), toBinaryString(long, int), toString(long, boolean), toHexString(long, boolean, int), parse(java.lang.String, int, int, boolean, int), decode(java.lang.String, int, int)

toHexString

public static final java.lang.String toHexString(long unsignedValue,
                                                 boolean upperCase,
                                                 int minLength)

Converts a given unsigned value into its hexadecimal string representation. The result is left-padded with spaces if minLength is negative else with '0' characters. The absolute value of minLength specifies the minimal length of the result (anyhow, the result contains at least one digit).

Parameters:

unsignedValue - the unsigned value to be converted.

upperCase - true if and only if (digit) characters in the result are in the upper case.

minLength - the minimal length of the result (absolute value) and pad prefix specifier (if negative then space padding else zero padding).

Returns:

the string representation (not null, with length() not less than max(abs(minLength), 1)) of unsignedValue in the hexadecimal radix.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

toString(long, boolean, boolean, int, boolean, int), toBinaryString(long, int), toOctalString(long, int), toString(long, boolean), parse(java.lang.String, int, int, boolean, int), decode(java.lang.String, int, int)

parse

public static final long parse(java.lang.String str,
                               int beginIndex,
                               int endIndex,
                               boolean isUnsigned,
                               int radix)
                        throws java.lang.NullPointerException,
                               java.lang.StringIndexOutOfBoundsException,
                               ParserException

Parses a given string region as a signed/unsigned integer in the specified radix. Leading spaces (before the sign prefix) are ignored. Sign prefix ('+' or '-') is permitted only if not isUnsigned. Any leading '0' characters (after the sign prefix or leading spaces) are ignored too. The next characters in the string region must all be digits of the specified radix (the full digits character set is '0' through '9', 'A' through 'Z' and 'a' through 'z'). Number overflow is checked properly (ParserException is thrown if overflow occurs). If the specified radix is invalid (less than two or too big) then it is corrected to the nearest valid one. Important notes: use ('9' - '0' + 1) to parse a decimal number.

Parameters:

str - the string (must be non-null), which region to parse.

beginIndex - the string region beginning index (must be in the range), inclusive.

endIndex - the string region ending index (must be in the range), exclusive.

isUnsigned - true if and only if the result must be an unsigned value.

radix - the radix (any value) to be used as a base of the value string format.

Returns:

a signed/unsigned integer value represented by str region.

Throws:

java.lang.NullPointerException - if str is null.

java.lang.StringIndexOutOfBoundsException - if beginIndex is negative, or if endIndex is less than beginIndex or is greater than length() of str.

ParserException - if str region cannot be parsed as a signed/unsigned integer (error is set to 1, 2 or 3 in the exception, meaning an illegal character is found, number overflow occurs or unexpected end of region is encountered at index, respectively).

See Also:

toString(long, boolean, boolean, int, boolean, int), toBinaryString(long, int), toOctalString(long, int), toString(long, boolean), toHexString(long, boolean, int), decode(java.lang.String, int, int), valueOf(java.lang.String)

decode

public static final long decode(java.lang.String str,
                                int beginIndex,
                                int endIndex)
                         throws java.lang.NullPointerException,
                                java.lang.StringIndexOutOfBoundsException,
                                ParserException

Decodes a given string region as an unsigned octal/decimal/hexadecimal integer value. The following unsigned long value formats are accepted: decimal, hexadecimal (with '0x', '0X' or '#' prefix) and octal (with '0' prefix). Leading spaces (before the prefix) are ignored. Sign prefix is not permitted. Leading '0' characters (after the prefix) are ignored too.

Parameters:

str - the string (must be non-null), which region to parse.

beginIndex - the string region beginning index (must be in the range), inclusive.

endIndex - the string region ending index (must be in the range), exclusive.

Returns:

an unsigned integer value represented by str region.

Throws:

java.lang.NullPointerException - if str is null.

java.lang.StringIndexOutOfBoundsException - if beginIndex is negative, or if endIndex is less than beginIndex or is greater than length() of str.

ParserException - if str region cannot be parsed (decoded) as an unsigned integer (error is set to 1, 2 or 3 in the exception, meaning an illegal character is found, number overflow occurs or unexpected end of region is encountered at index, respectively).

See Also:

parse(java.lang.String, int, int, boolean, int), toString(long, boolean, boolean, int, boolean, int), toOctalString(long, int), toString(long, boolean), toHexString(long, boolean, int), valueOf(java.lang.String)

valueOf

public static UnsignedLong valueOf(java.lang.String str)
                            throws java.lang.NullPointerException,
                                   ParserException

Converts a given string to an instance of this class. This method returns a new UnsignedLong object initialized to the unsigned decimal integer value of the specified string.

Parameters:

str - the string (must be non-null, representing a valid unsigned decimal integer) to be parsed.

Returns:

a newly constructed UnsignedLong instance (not null) initialized to the value represented by str.

Throws:

java.lang.NullPointerException - if str is null.

ParserException - if str cannot be parsed as an unsigned integer (error is set to 1, 2 or 3 in the exception, meaning an illegal character is found, number overflow occurs or unexpected end of string is encountered at index, respectively).

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

UnsignedLong(long), parse(java.lang.String, int, int, boolean, int), decode(java.lang.String, int, int), longValue(), toString()

intValue

public int intValue()

Returns the value of this number as int. The result is the same as of (int)longValue().

Specified by:

intValue in class java.lang.Number

Returns:

the numeric int value represented by the object.

See Also:

UnsignedLong(long), longValue(), floatValue(), doubleValue(), toString()

longValue

public long longValue()

Returns the value of this number as long.

Specified by:

longValue in class java.lang.Number

Returns:

the numeric long value represented by the object.

See Also:

UnsignedLong(long), intValue(), floatValue(), doubleValue(), toString()

floatValue

public float floatValue()

Returns the value of this number as float. The result is the same as of (float)doubleValue(). Important notes: this may involve rounding; the result is always non-negative.

Specified by:

floatValue in class java.lang.Number

Returns:

the numeric float value represented by the object.

See Also:

UnsignedLong(long), intValue(), longValue(), doubleValue(), toString()

doubleValue

public double doubleValue()

Returns the value of this number as double. Important notes: this may involve rounding; the result is always non-negative.

Specified by:

doubleValue in class java.lang.Number

Returns:

the numeric double value represented by the object.

See Also:

UnsignedLong(long), intValue(), longValue(), floatValue(), toString()

clone

public java.lang.Object clone()

Creates and returns a copy of this object. The result is the same as of new UnsignedLong(longValue()).

Specified by:

clone in interface ReallyCloneable

Overrides:

clone in class java.lang.Object

Returns:

a copy (not null and != this) of this instance.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

UnsignedLong(long), valueOf(java.lang.String), longValue(), equals(java.lang.Object)

hashCode

public int hashCode()

Returns a hash code value for the object. The bits of the wrapped unsigned long value are mixed in a particular order to produce a single int 'hash' value. The result is the same as of hashCode(longValue()).

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.

See Also:

hashCode(long), longValue(), equals(java.lang.Object)

equals

public boolean equals(java.lang.Object obj)

Indicates whether this object is equal to the specified one. This method returns true if and only if obj is instance of this class, and the wrapped values of this and of obj are equal.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the second compared object (may be null).

Returns:

true if and only if this value is the same as obj value.

See Also:

compare(long, long), longValue(), hashCode(), greaterThan(java.lang.Object)

greaterThan

public boolean greaterThan(java.lang.Object obj)

Tests for being semantically greater than the argument. The result is true if and only if obj is instance of this class and the wrapped value of this object is greater (in the unsigned manner) than the wrapped value of the specified object.

Specified by:

greaterThan in interface Sortable

Parameters:

obj - the second compared object (may be null).

Returns:

true if obj is comparable with this and this object is greater than obj, else false.

Since:

2.0

See Also:

greater(long, long), compare(long, long), longValue(), equals(java.lang.Object)

toString

public java.lang.String toString()

Converts this object to its 'in-line' string representation. The wrapped value is converted to its unsigned decimal representation and returned as a string, exactly as by toString(longValue(), true).

Overrides:

toString in class java.lang.Object

Returns:

the string representation (not null, with non-zero length()) of this object.

Throws:

java.lang.OutOfMemoryError - if there is not enough memory.

See Also:

UnsignedLong(long), longValue(), toString(long, boolean), toString(long, boolean, boolean, int, boolean, int), valueOf(java.lang.String)