The
Long class wraps a value of the primitive type
long in an object. An object of type
Long contains a
single field whose type is
long .
In addition, this class provides several methods for converting
a
long to a
String and a
String to a
long , as well as other constants and methods useful when dealing
with a
long .
Implementation note: The implementations of the "bit twiddling"
methods (such as
Long.highestOneBit(long) highestOneBit and
Long.numberOfTrailingZeros(long) numberOfTrailingZeros ) are
based on material from Henry S. Warren, Jr.'s Hacker's
Delight, (Addison Wesley, 2002).
author: Lee Boynton author: Arthur van Hoff author: Josh Bloch author: Joseph D. Darcy version: 1.91, 07/12/07 since: JDK1.0
Field Summary
final public static long
MAX_VALUE A constant holding the maximum value a
long can
have, 263-1.
final public static long
MIN_VALUE A constant holding the minimum value a
long can
have, -263.
final public static int
SIZE The number of bits used to represent a
long value in two's
complement binary form.
The sequence of characters following an optional
sign and/or radix specifier ("
0x ", "
0X ",
"
# ", or leading zero) is parsed as by the
Long.parseLong method with the indicated radix (10, 16, or 8).
This sequence of characters must represent a positive value or
a
NumberFormatException will be thrown.
public double
doubleValue() Returns the value of this
Long as a
double .
public boolean
equals(Object obj) Compares this object to the specified object.
public float
floatValue() Returns the value of this
Long as a
float .
static void
getChars(long i, int index, char[] buf) Places characters representing the integer i into the
character array buf.
highestOneBit(long i) Returns a
long value with at most a single one-bit, in the
position of the highest-order ("leftmost") one-bit in the specified
long value.
public int
intValue() Returns the value of this
Long as an
int .
public long
longValue() Returns the value of this
Long as a
long value.
public static long
lowestOneBit(long i) Returns a
long value with at most a single one-bit, in the
position of the lowest-order ("rightmost") one-bit in the specified
long value.
public static int
numberOfLeadingZeros(long i) Returns the number of zero bits preceding the highest-order
("leftmost") one-bit in the two's complement binary representation
of the specified
long value.
public static int
numberOfTrailingZeros(long i) Returns the number of zero bits following the lowest-order ("rightmost")
one-bit in the two's complement binary representation of the specified
long value.
public static long
parseLong(String s, int radix) Parses the string argument as a signed
long in the
radix specified by the second argument.
public static long
parseLong(String s) Parses the string argument as a signed decimal
long .
The characters in the string must all be decimal digits, except
that the first character may be an ASCII minus sign
'-' (\u002D') to indicate a negative value or an
ASCII plus sign
'+' ('\u002B') to
indicate a positive value.
public static long
reverse(long i) Returns the value obtained by reversing the order of the bits in the
two's complement binary representation of the specified
long value.
public static long
reverseBytes(long i) Returns the value obtained by reversing the order of the bytes in the
two's complement representation of the specified
long value.
public static long
rotateLeft(long i, int distance) Returns the value obtained by rotating the two's complement binary
representation of the specified
long value left by the
specified number of bits.
public static long
rotateRight(long i, int distance) Returns the value obtained by rotating the two's complement binary
representation of the specified
long value right by the
specified number of bits.
public short
shortValue() Returns the value of this
Long as a
short .
public static int
signum(long i) Returns the signum function of the specified
long value.
valueOf(String s, int radix) Returns a
Long object holding the value
extracted from the specified
String when parsed
with the radix given by the second argument.
valueOf(long l) Returns a
Long instance representing the specified
long value.
If a new
Long instance is not required, this method
should generally be used in preference to the constructor
Long.Long(long) , as this method is likely to yield
significantly better space and time performance by caching
frequently requested values.
Parameters: l - a long value.
Constructs a newly allocated
Long object that
represents the specified
long argument.
Parameters: value - the value to be represented by the Long object.
Constructs a newly allocated
Long object that
represents the
long value indicated by the
String parameter. The string is converted to a
long value in exactly the manner used by the
parseLong method for radix 10.
Parameters: s - the String to be converted to a Long . throws: NumberFormatException - if the String does notcontain a parsable long . See Also:java.lang.Long.parseLong(java.lang.Stringint)
Returns the number of one-bits in the two's complement binary
representation of the specified
long value. This function is
sometimes referred to as the population count.
the number of one-bits in the two's complement binaryrepresentation of the specified long value. since: 1.5
Compares two
Long objects numerically.
Parameters: anotherLong - the Long to be compared. the value 0 if this Long isequal to the argument Long ; a value less than 0 if this Long is numerically lessthan the argument Long ; and a value greater than 0 if this Long is numericallygreater than the argument Long (signedcomparison). since: 1.2
The sequence of characters following an optional
sign and/or radix specifier ("
0x ", "
0X ",
"
# ", or leading zero) is parsed as by the
Long.parseLong method with the indicated radix (10, 16, or 8).
This sequence of characters must represent a positive value or
a
NumberFormatException will be thrown. The result is
negated if first character of the specified
String is
the minus sign. No whitespace characters are permitted in the
String .
Parameters: nm - the String to decode. a Long object holding the long value represented by nm throws: NumberFormatException - if the String does notcontain a parsable long . See Also:java.lang.Long.parseLong(Stringint) since: 1.2
Compares this object to the specified object. The result is
true if and only if the argument is not
null and is a
Long object that
contains the same
long value as this object.
Parameters: obj - the object to compare with. true if the objects are the same; false otherwise.
static void getChars(long i, int index, char[] buf)(Code)
Places characters representing the integer i into the
character array buf. The characters are placed into
the buffer backwards starting with the least significant
digit at the specified index (exclusive), and working
backwards from there.
Will fail if i == Long.MIN_VALUE
Determines the
long value of the system property
with the specified name.
The first argument is treated as the name of a system property.
System properties are accessible through the
java.lang.System.getProperty(java.lang.String) method. The
string value of this property is then interpreted as a
long value and a
Long object
representing this value is returned. Details of possible
numeric formats can be found with the definition of
getProperty .
If there is no property with the specified name, if the
specified name is empty or
null , or if the
property does not have the correct numeric format, then
null is returned.
In other words, this method returns a
Long object equal to
the value of:
Determines the
long value of the system property
with the specified name.
The first argument is treated as the name of a system property.
System properties are accessible through the
java.lang.System.getProperty(java.lang.String) method. The
string value of this property is then interpreted as a
long value and a
Long object
representing this value is returned. Details of possible
numeric formats can be found with the definition of
getProperty .
The second argument is the default value. A
Long object
that represents the value of the second argument is returned if there
is no property of the specified name, if the property does not have
the correct numeric format, or if the specified name is empty or null.
In other words, this method returns a
Long object equal
to the value of:
getLong(nm, new Long(val))
but in practice it may be implemented in a manner such as:
Long result = getLong(nm, null);
return (result == null) ? new Long(val) : result;
Returns the
long value of the system property with
the specified name. The first argument is treated as the name
of a system property. System properties are accessible through
the
java.lang.System.getProperty(java.lang.String) method. The string value of this property is then interpreted
as a
long value, as per the
Long.decode method, and a
Long object
representing this value is returned.
If the property value begins with the two ASCII characters
0x or the ASCII character
# , not followed by
a minus sign, then the rest of it is parsed as a hexadecimal integer
exactly as for the method
Long.valueOf(java.lang.String,int)
with radix 16.
If the property value begins with the ASCII character
0 followed by another character, it is parsed as
an octal integer exactly as by the method
Long.valueOf(java.lang.String,int) with radix 8.
Note that, in every case, neither
L ('\u004C') nor
l ('\u006C') is permitted to appear at the end
of the property value as a type indicator, as would be
permitted in Java programming language source code.
Returns a hash code for this
Long . The result is
the exclusive OR of the two halves of the primitive
long value held by this
Long object. That is, the hashcode is the value of the expression:
Returns a
long value with at most a single one-bit, in the
position of the highest-order ("leftmost") one-bit in the specified
long value. Returns zero if the specified value has no
one-bits in its two's complement binary representation, that is, if it
is equal to zero.
a long value with a single one-bit, in the positionof the highest-order one-bit in the specified value, or zero ifthe specified value is itself equal to zero. since: 1.5
Returns a
long value with at most a single one-bit, in the
position of the lowest-order ("rightmost") one-bit in the specified
long value. Returns zero if the specified value has no
one-bits in its two's complement binary representation, that is, if it
is equal to zero.
a long value with a single one-bit, in the positionof the lowest-order one-bit in the specified value, or zero ifthe specified value is itself equal to zero. since: 1.5
numberOfLeadingZeros
public static int numberOfLeadingZeros(long i)(Code)
Returns the number of zero bits preceding the highest-order
("leftmost") one-bit in the two's complement binary representation
of the specified
long value. Returns 64 if the
specified value has no one-bits in its two's complement representation,
in other words if it is equal to zero.
Note that this method is closely related to the logarithm base 2.
For all positive
long values x:
floor(log2(x)) =
63 - numberOfLeadingZeros(x)
ceil(log2(x)) =
64 - numberOfLeadingZeros(x - 1)
the number of zero bits preceding the highest-order("leftmost") one-bit in the two's complement binary representationof the specified long value, or 64 if the valueis equal to zero. since: 1.5
numberOfTrailingZeros
public static int numberOfTrailingZeros(long i)(Code)
Returns the number of zero bits following the lowest-order ("rightmost")
one-bit in the two's complement binary representation of the specified
long value. Returns 64 if the specified value has no
one-bits in its two's complement representation, in other words if it is
equal to zero.
the number of zero bits following the lowest-order ("rightmost")one-bit in the two's complement binary representation of thespecified long value, or 64 if the value is equalto zero. since: 1.5
Parses the string argument as a signed
long in the
radix specified by the second argument. The characters in the
string must all be digits of the specified radix (as determined
by whether
java.lang.Character.digit(charint) returns
a nonnegative value), except that the first character may be an
ASCII minus sign
'-' ('\u002D') to
indicate a negative value or an ASCII plus sign
'+' ('\u002B') to indicate a positive value. The
resulting
long value is returned.
Note that neither the character
L ('\u004C') nor
l ('\u006C') is permitted to appear at the end
of the string as a type indicator, as would be permitted in
Java programming language source code - except that either
L or
l may appear as a digit for a
radix greater than 22.
An exception of type
NumberFormatException is
thrown if any of the following situations occurs:
The first argument is
null or is a string of
length zero.
Any character of the string is not a digit of the specified
radix, except that the first character may be a minus sign
'-' ('\u002d') or plus sign
'+' ('\u002B') provided that the string is
longer than length 1.
The value represented by the string is not a value of type
long .
Parameters: s - the String containing the long representation to be parsed. Parameters: radix - the radix to be used while parsing s . the long represented by the string argument inthe specified radix. throws: NumberFormatException - if the string does not contain aparsable long .
Parses the string argument as a signed decimal
long .
The characters in the string must all be decimal digits, except
that the first character may be an ASCII minus sign
'-' (\u002D') to indicate a negative value or an
ASCII plus sign
'+' ('\u002B') to
indicate a positive value. The resulting
long value is
returned, exactly as if the argument and the radix
10 were given as arguments to the
Long.parseLong(java.lang.String,int) method.
Note that neither the character
L ('\u004C') nor
l ('\u006C') is permitted to appear at the end
of the string as a type indicator, as would be permitted in
Java programming language source code.
Parameters: s - a String containing the long representation to be parsed the long represented by the argument in decimal. throws: NumberFormatException - if the string does not contain aparsable long .
Returns the value obtained by reversing the order of the bits in the
two's complement binary representation of the specified
long value.
the value obtained by reversing order of the bits in thespecified long value. since: 1.5
Returns the value obtained by reversing the order of the bytes in the
two's complement representation of the specified
long value.
the value obtained by reversing the bytes in the specified long value. since: 1.5
rotateLeft
public static long rotateLeft(long i, int distance)(Code)
Returns the value obtained by rotating the two's complement binary
representation of the specified
long value left by the
specified number of bits. (Bits shifted out of the left hand, or
high-order, side reenter on the right, or low-order.)
Note that left rotation with a negative distance is equivalent to
right rotation:
rotateLeft(val, -distance) == rotateRight(val, distance) . Note also that rotation by any multiple of 64 is a
no-op, so all but the last six bits of the rotation distance can be
ignored, even if the distance is negative:
rotateLeft(val, distance) == rotateLeft(val, distance & 0x3F) .
the value obtained by rotating the two's complement binaryrepresentation of the specified long value left by thespecified number of bits. since: 1.5
rotateRight
public static long rotateRight(long i, int distance)(Code)
Returns the value obtained by rotating the two's complement binary
representation of the specified
long value right by the
specified number of bits. (Bits shifted out of the right hand, or
low-order, side reenter on the left, or high-order.)
Note that right rotation with a negative distance is equivalent to
left rotation:
rotateRight(val, -distance) == rotateLeft(val, distance) . Note also that rotation by any multiple of 64 is a
no-op, so all but the last six bits of the rotation distance can be
ignored, even if the distance is negative:
rotateRight(val, distance) == rotateRight(val, distance & 0x3F) .
the value obtained by rotating the two's complement binaryrepresentation of the specified long value right by thespecified number of bits. since: 1.5
Returns the signum function of the specified
long value. (The
return value is -1 if the specified value is negative; 0 if the
specified value is zero; and 1 if the specified value is positive.)
the signum function of the specified long value. since: 1.5
Returns a string representation of the
long argument as an unsigned integer in base 2.
The unsigned
long value is the argument plus
264 if the argument is negative; otherwise, it is
equal to the argument. This value is converted to a string of
ASCII digits in binary (base 2) with no extra leading
0 s. If the unsigned magnitude is zero, it is
represented by a single zero character
'0' ('\u0030'); otherwise, the first character of
the representation of the unsigned magnitude will not be the
zero character. The characters
'0' ('\u0030') and
'1' ('\u0031') are used as binary digits.
Parameters: i - a long to be converted to a string. the string representation of the unsigned long value represented by the argument in binary (base 2). since: JDK 1.0.2
Returns a string representation of the
long argument as an unsigned integer in base 16.
The unsigned
long value is the argument plus
264 if the argument is negative; otherwise, it is
equal to the argument. This value is converted to a string of
ASCII digits in hexadecimal (base 16) with no extra
leading
0 s. If the unsigned magnitude is zero, it
is represented by a single zero character
'0' ('\u0030'); otherwise, the first character of
the representation of the unsigned magnitude will not be the
zero character. The following characters are used as
hexadecimal digits:
0123456789abcdef
These are the characters '\u0030' through
'\u0039' and '\u0061' through
'\u0066'. If uppercase letters are desired,
the
java.lang.String.toUpperCase method may be called
on the result:
Long.toHexString(n).toUpperCase()
Parameters: i - a long to be converted to a string. the string representation of the unsigned long value represented by the argument in hexadecimal(base 16). since: JDK 1.0.2
Returns a string representation of the
long argument as an unsigned integer in base 8.
The unsigned
long value is the argument plus
264 if the argument is negative; otherwise, it is
equal to the argument. This value is converted to a string of
ASCII digits in octal (base 8) with no extra leading
0 s.
If the unsigned magnitude is zero, it is represented by a
single zero character
'0' ('\u0030'); otherwise, the first character of
the representation of the unsigned magnitude will not be the
zero character. The following characters are used as octal
digits:
01234567
These are the characters '\u0030' through
'\u0037'.
Parameters: i - a long to be converted to a string. the string representation of the unsigned long value represented by the argument in octal (base 8). since: JDK 1.0.2
toString
public static String toString(long i, int radix)(Code)
Returns a string representation of the first argument in the
radix specified by the second argument.
If the radix is smaller than
Character.MIN_RADIX or larger than
Character.MAX_RADIX , then the radix
10 is used instead.
If the first argument is negative, the first element of the
result is the ASCII minus sign
'-' ('\u002d'). If the first argument is not
negative, no sign character appears in the result.
The remaining characters of the result represent the magnitude
of the first argument. If the magnitude is zero, it is
represented by a single zero character
'0' ('\u0030'); otherwise, the first character of
the representation of the magnitude will not be the zero
character. The following ASCII characters are used as digits:
0123456789abcdefghijklmnopqrstuvwxyz
These are '\u0030' through
'\u0039' and '\u0061' through
'\u007a'. If
radix is
N, then the first N of these characters
are used as radix-N digits in the order shown. Thus,
the digits for hexadecimal (radix 16) are
0123456789abcdef . If uppercase letters are
desired, the
java.lang.String.toUpperCase method may
be called on the result:
Long.toString(n, 16).toUpperCase()
Parameters: i - a long to be converted to a string. Parameters: radix - the radix to use in the string representation. a string representation of the argument in the specified radix. See Also:java.lang.Character.MAX_RADIX See Also:java.lang.Character.MIN_RADIX
Returns a
String object representing the specified
long . The argument is converted to signed decimal
representation and returned as a string, exactly as if the
argument and the radix 10 were given as arguments to the
Long.toString(long,int) method.
Parameters: i - a long to be converted. a string representation of the argument in base 10.
Returns a
String object representing this
Long 's value. The value is converted to signed
decimal representation and returned as a string, exactly as if
the
long value were given as an argument to the
java.lang.Long.toString(long) method.
a string representation of the value of this object inbase 10.
Returns a
Long object holding the value
extracted from the specified
String when parsed
with the radix given by the second argument. The first
argument is interpreted as representing a signed
long in the radix specified by the second
argument, exactly as if the arguments were given to the
Long.parseLong(java.lang.String,int) method. The result is a
Long object that represents the
long value specified by the string.
In other words, this method returns a
Long object equal
to the value of:
new Long(Long.parseLong(s, radix))
Parameters: s - the string to be parsed Parameters: radix - the radix to be used in interpreting s a Long object holding the valuerepresented by the string argument in the specifiedradix. throws: NumberFormatException - If the String does notcontain a parsable long .
Returns a
Long object holding the value
of the specified
String . The argument is
interpreted as representing a signed decimal
long ,
exactly as if the argument were given to the
Long.parseLong(java.lang.String) method. The result is a
Long object that represents the integer value
specified by the string.
In other words, this method returns a
Long object
equal to the value of:
new Long(Long.parseLong(s))
Parameters: s - the string to be parsed. a Long object holding the valuerepresented by the string argument. throws: NumberFormatException - If the string cannot be parsedas a long .
Returns a
Long instance representing the specified
long value.
If a new
Long instance is not required, this method
should generally be used in preference to the constructor
Long.Long(long) , as this method is likely to yield
significantly better space and time performance by caching
frequently requested values.
Parameters: l - a long value. a Long instance representing l . since: 1.5
