JavaTM 2 Platform
Standard Ed. 5.0

java.lang
类 Long

java.lang.Object
  继承者 java.lang.Number
      继承者 java.lang.Long
所有已实现的接口:
Serializable, Comparable<Long>

public final class Long
extends Number
implements Comparable<Long>

Long 类在对象中封装了基本类型 long 的值。每个 Long 类型的对象都包含一个 long 类型的字段。

此外,该类提供了多个方法,可以将 long 转换为 String,将 String 转换为 long,除此之外,还提供了其他一些处理 long 时有用的常量和方法。

实现注意事项:"bit twiddling" 方法(如 highestOneBitnumberOfTrailingZeros)的实现基于 Henry S. Warren 和 Jr. 撰写的《Hacker's Delight》(Addison Wesley, 2002) 一书中的资料。

从以下版本开始:
JDK1.0
另请参见:
序列化表格

字段摘要
static long MAX_VALUE
          保持 long 类型的最大值的常量,该值为 263-1。
static long MIN_VALUE
          保持 long 类型的最小值的常量,该值为 -263
static int SIZE
          用来以二进制补码形式表示 long 值的位数。
static Class<Long> TYPE
          表示基本类型 longClass 实例。
 
构造方法摘要
Long(long value)
          构造新分配的 Long 对象,表示指定的 long 参数。
Long(String s)
          构造新分配的 Long 对象,表示由 String 参数指示的 long 值。
 
方法摘要
static int bitCount(long i)
          返回指定 long 值的二进制补码表示形式中的 1 位的数量。
 byte byteValue()
          以 byte 形式返回此 Long 的值。
 int compareTo(Long anotherLong)
          在数字上比较两个 Long 对象。
static Long decode(String nm)
          将 String 解码成 Long
 double doubleValue()
          以 double 形式返回此 Long 的值。
 boolean equals(Object obj)
          将此对象与指定对象进行比较。
 float floatValue()
          以 float 形式返回此 Long 的值。
static Long getLong(String nm)
          确定具有指定名称的系统属性的 long 值。
static Long getLong(String nm, long val)
          使用指定名称确定系统属性的 long 值。
static Long getLong(String nm, Long val)
          使用指定名称返回系统属性的 long 值。
 int hashCode()
          返回 Long 的哈希码。
static long highestOneBit(long i)
          返回至多有一个 1 位的 long 值,在指定的 long 值中最高位(最左边)的 1 位的位置。
 int intValue()
          以 int 形式返回此 Long 的值。
 long longValue()
          以 long 值的形式返回此 Long 的值。
static long lowestOneBit(long i)
          返回至多有一个 1 位的 long 值,在指定的 long 值中最低位(最右边)的 1 位的位置。
static int numberOfLeadingZeros(long i)
          在指定 long 值的二进制补码表示形式中最高位(最左)的 1 位之前,返回零位的数量。
static int numberOfTrailingZeros(long i)
          返回在指定 long 值的二进制补码表示形式中最低位(最右)的 1 位之后的零位的数量。
static long parseLong(String s)
          将 string 参数分析为有符号十进制 long
static long parseLong(String s, int radix)
          将 string 参数分析为有符号的 long,基数由第二个参数指定。
static long reverse(long i)
          返回通过反转指定 long 值的二进制补码表示形式中位的顺序而获得的值。
static long reverseBytes(long i)
          返回通过反转指定 long 值的二进制补码表示形式中字节的顺序而获得的值。
static long rotateLeft(long i, int distance)
          返回根据指定的位数循环左移指定的 long 值的二进制补码表示形式而得到的值。
static long rotateRight(long i, int distance)
          返回根据指定的位数循环右移指定的 long 值的二进制补码表示形式而得到的值。
 short shortValue()
          以 short 形式返回此 Long 的值。
static int signum(long i)
          返回指定 long 值的符号函数。
static String toBinaryString(long i)
          以二进制无符号整数形式返回 long 参数的字符串表示形式。
static String toHexString(long i)
          以十六进制无符号整数形式返回 long 参数的字符串表示形式。
static String toOctalString(long i)
          以八进制无符号整数形式返回 long 参数的字符串表示形式。
 String toString()
          返回表示 Long 值的 String 对象。
static String toString(long i)
          返回表示指定 longString 对象。
static String toString(long i, int radix)
          返回在使用第二个参数指定的基数时第一个参数的字符串表示形式。
static Long valueOf(long l)
          返回表示指定 long 值的 Long 实例。
static Long valueOf(String s)
          返回保持指定 String 的值的 Long 对象。
static Long valueOf(String s, int radix)
          当使用第二个参数给出的基数进行分析时,返回保持从指定 String 中提取的值的 Long 对象。
 
从类 java.lang.Object 继承的方法
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

字段详细信息

MIN_VALUE

public static final long MIN_VALUE
保持 long 类型的最小值的常量,该值为 -263

另请参见:
常量字段值

MAX_VALUE

public static final long MAX_VALUE
保持 long 类型的最大值的常量,该值为 263-1。

另请参见:
常量字段值

TYPE

public static final Class<Long> TYPE
表示基本类型 longClass 实例。

从以下版本开始:
JDK1.1

SIZE

public static final int SIZE
用来以二进制补码形式表示 long 值的位数。

从以下版本开始:
1.5
另请参见:
常量字段值
构造方法详细信息

Long

public Long(long value)
构造新分配的 Long 对象,表示指定的 long 参数。

参数:
value - Long 对象表示的值。

Long

public Long(String s)
     throws NumberFormatException
构造新分配的 Long 对象,表示由 String 参数指示的 long 值。该字符串被转换为 long 值,其方式与 radix 参数为 10 的 parseLong 方法所使用的方式一致。

参数:
s - 要转换为 LongString
抛出:
NumberFormatException - 如果 String 不包含可分析的 long
另请参见:
parseLong(java.lang.String, int)
方法详细信息

toString

public static String toString(long i,
                              int radix)
返回在使用第二个参数指定的基数时第一个参数的字符串表示形式。

如果该基数小于 Character.MIN_RADIX,或大于 Character.MAX_RADIX,则使用基数 10

如果第一个参数是负数,则结果的第一个元素是 ASCII 字符的减号 '-' ('\u002d')。如果第一个参数非负,则结果中不会出现符号字符。

结果的其余字符表示第一个参数的大小。如果大小为零,则用单个零字符 '0' 表示它 ('\u0030');否则大小表示形式中的第一个字符将不是零字符。以下 ASCII 字符均被用作数字:

0123456789abcdefghijklmnopqrstuvwxyz
 
这些是从 '\u0030''\u0039' 和从 '\u0061''\u007a' 的字符。如果 radixN,则这些字符的第一个 N 用作显示顺序中基数 N 的数字。因此,该数字的十六进制(基数 16)表示形式为 0123456789abcdef。如果需要使用大写字母,则可以在结果上调用 String.toUpperCase() 方法:
Long.toString(n, 16).toUpperCase()
 

参数:
i - 要转换为字符串的 long
radix - 将在字符串表示形式中使用的基数。
返回:
指定基数中参数的字符串表示形式。
另请参见:
Character.MAX_RADIX, Character.MIN_RADIX

toHexString

public static String toHexString(long i)
以十六进制无符号整数形式返回 long 参数的字符串表示形式。

如果参数为负,则无符号 long 值为该参数加上 264;否则,它等于该参数。此值将被转换为不带附加前导 0 的十六进制(基数 16)ASCII 数字字符串。如果无符号大小为零,则该数字由单个零字符 '0' 表示 ('\u0030');否则,无符号大小表示形式中的第一个字符将不是零字符。下列字符都被用作十六进制数字:

0123456789abcdef
 
这些是从 '\u0030''\u0039' 和从 '\u0061''\u0066' 的字符。如果需要使用大写字母,则可以在结果上调用 String.toUpperCase() 方法:
Long.toHexString(n).toUpperCase()
 

参数:
i - 要转换为字符串的 long
返回:
十六进制(基数 16)参数表示的无符号 long 值的字符串表示形式。
从以下版本开始:
JDK 1.0.2

toOctalString

public static String toOctalString(long i)
以八进制无符号整数形式返回 long 参数的字符串表示形式。

如果参数为负,则无符号 long 值为该参数加上 264;否则,它等于该参数。此值将被转换为不带附加前导 0 的八进制(基数 8)ASCII 数字字符串。

如果无符号大小为零,则该数字用单个零字符 '0' ('\u0030') 表示,否则无符号大小表示形式中的第一个字符将不是零字符。以下字符都用作八进制数字:

 01234567
 
这些是从 '\u0030''\u0037' 的字符。

参数:
i - 要转换为字符串的 long
返回:
八进制(基数 8)参数表示的无符号 long 值的字符串表示形式。
从以下版本开始:
JDK 1.0.2

toBinaryString

public static String toBinaryString(long i)
以二进制无符号整数形式返回 long 参数的字符串表示形式。

如果参数为负数,则无符号 long 值为该参数加上 264;否则,它等于该参数。此值将被转换为不带附加前导 0 的二进制(基数 2)ASCII 数字字符串。如果无符号大小为零,则用单个零字符 '0' 表示它 ('\u0030');否则,无符号大小表示形式中的第一个字符将不是零字符。字符 '0' ('\u0030') 和 '1' ('\u0031') 被用作二进制位。

参数:
i - 要转换为字符串的 long
返回:
二进制 (base 2) 参数表示的无符号 long 值的字符串表示形式。
从以下版本开始:
JDK 1.0.2

toString

public static String toString(long i)
返回表示指定 longString 对象。该参数被转换为有符号的十进制表示形式,并作为字符串返回,该字符串与用该参数和基数 10 作为参数的 toString(long, int) 方法所得到的值非常相似。

参数:
i - 要转换的 long
返回:
十进制参数的字符串表示形式。

parseLong

public static long parseLong(String s,
                             int radix)
                      throws NumberFormatException
将 string 参数分析为有符号的 long,基数由第二个参数指定。字符串中的字符必须为指定基数中的数字(由 Character.digit(char, int) 是否返回一个非负值来确定),除非第一个字符为 ASCII 字符的减号 '-' ('\u002D'),它表示一个负值。返回得到的 long 值。

注意,不允许将字符 L ('\u004C') 和 l ('\u006C') 作为类型指示符出现在字符串的结尾处,而这一点在 Java 编程语言源代码中是允许的——除非 Ll 以大于 22 的基数形式出现。

如果出现以下情形之一,则抛出 NumberFormatException 类型的异常:

示例:

parseLong("0", 10) returns 0L
parseLong("473", 10) returns 473L
parseLong("-0", 10) returns 0L
parseLong("-FF", 16) returns -255L
parseLong("1100110", 2) returns 102L
parseLong("99", 8) returns NumberFormatException
parseLong("Hazelnut", 10) returns NumberFormatException
parseLong("Hazelnut", 36) returns 1356099454469L

参数:
s - 包含要分析的 long 表示形式的 String
radix - 将在分析 s 时使用的基数。
返回:
由指定基数中的字符串参数表示的 long
抛出:
NumberFormatException - 如果字符串不包含可分析的 long

parseLong

public static long parseLong(String s)
                      throws NumberFormatException
将 string 参数分析为有符号十进制 long。字符串中的字符必须都是十进制数字,除非第一个字符是 ASCII 字符的减号 '-' (\u002D'),它表示一个负值。返回得到的 long 值,该值与用该参数和基数 10 作为参数的 parseLong(java.lang.String, int) 方法得到的值非常相似。

注意,不允许将字符 L ('\u004C') 和 l ('\u006C') 作为类型指示符出现在字符串的结尾处,这一点在 Java 编程语言源代码中是允许的。

参数:
s - 包含要分析的 long 表示形式的 String
返回:
十进制参数表示的 long
抛出:
NumberFormatException - 如果字符串不包含可分析的 long

valueOf

public static Long valueOf(String s,
                           int radix)
                    throws NumberFormatException
当使用第二个参数给出的基数进行分析时,返回保持从指定 String 中提取的值的 Long 对象。第一个参数被解释为有符号的 long,基数由第二个参数指定,该值与用该参数作为参数的 parseLong(java.lang.String, int) 方法得到的值非常类似。结果是表示字符串指定的 long 值的 Long 对象。

换句话说,此方法返回一个 Long 对象,它的值等于:

new Long(Long.parseLong(s, radix))

参数:
s - 要分析的字符串
radix - 将在解释 s 时使用的基数
返回:
保持由指定基数中的字符串参数表示的值的 Long 对象。
抛出:
NumberFormatException - 如果 String 不包含可分析的 long

valueOf

public static Long valueOf(String s)
                    throws NumberFormatException
返回保持指定 String 的值的 Long 对象。该参数被解释为表示一个有符号的十进制 long,该值与用该参数作为参数的 parseLong(java.lang.String) 方法得到的值非常相似。结果是表示由字符串指定的整数值的 Long 对象。

换句话说,此方法返回一个 Long 对象,它的值等于:

new Long(Long.parseLong(s))
 

参数:
s - 要分析的字符串。
返回:
包含由字符串参数表示的值的 Long 对象。
抛出:
NumberFormatException - 如果不能将字符串分析为 long

valueOf

public static Long valueOf(long l)
返回表示指定 long 值的 Long 实例。如果不需要 Long 实例,则通常优先使用此方法,而不是使用构造方法 Long(long),因为此方法通过缓存频繁请求的值,可以显著提高时间和空间性能。

参数:
l - long 值。
返回:
表示 lLong 实例。
从以下版本开始:
1.5

decode

public static Long decode(String nm)
                   throws NumberFormatException
String 解码成 Long。接受通过以下语法给出的十进制、十六进制和八进制数:
DecodableString:
Signopt DecimalNumeral
Signopt 0x HexDigits
Signopt 0X HexDigits
Signopt # HexDigits
Signopt 0 OctalDigits

Sign:
-
DecimalNumeralHexDigitsOctalDigitsJava Language Specification 中的§3.10.1 中已经定义。

跟在(可选)负号和/或基数说明符("0x"、"0X"、"#" 或前导零)后面的字符的顺序由 Long.parseLong 方法通过指示的基数(10、16 或 8)来分析。字符的顺序必须表示为一个正值,否则将抛出 NumberFormatException。如果指定 String 的第一个字符是减号,则结果无效。String 中不允许出现空白字符。

参数:
nm - 要解码的 String
返回:
保持由 nm 表示的 long 值的 Long 对象
抛出:
NumberFormatException - 如果 String 不包含可分析的 long
从以下版本开始:
1.2
另请参见:
parseLong(String, int)

byteValue

public byte byteValue()
byte 形式返回此 Long 的值。

覆盖:
Number 中的 byteValue
返回:
转换为 byte 类型后该对象表示的数值。

shortValue

public short shortValue()
short 形式返回此 Long 的值。

覆盖:
Number 中的 shortValue
返回:
转换为 short 类型后该对象表示的数值。

intValue

public int intValue()
int 形式返回此 Long 的值。

指定者:
Number 中的 intValue
返回:
转换为 int 类型后该对象表示的数值。

longValue

public long longValue()
long 值的形式返回此 Long 的值。

指定者:
Number 中的 longValue
返回:
转换为 long 类型后该对象表示的数值。

floatValue

public float floatValue()
float 形式返回此 Long 的值。

指定者:
Number 中的 floatValue
返回:
转换为 float 类型后该对象表示的数值。

doubleValue

public double doubleValue()
double 形式返回此 Long 的值。

指定者:
Number 中的 doubleValue
返回:
转换为 double 类型后该对象表示的数值。

toString

public String toString()
返回表示 Long 值的 String 对象。该值被转换为有符号十进制表示形式,并作为字符串返回,该字符串与用 long 值作为参数的 toString(long) 方法得到的字符串非常相似。

覆盖:
Object 中的 toString
返回:
十进制对象值的字符串表示形式。

hashCode

public int hashCode()
返回 Long 的哈希码。结果是此 Long 对象保持的基本 long 值的两个部分的异或 (XOR)。也就是说,哈希码就是表达式的值:
(int)(this.longValue()^(this.longValue()>>>32))
 

覆盖:
Object 中的 hashCode
返回:
此对象的哈希码值。
另请参见:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)
将此对象与指定对象进行比较。当且仅当该参数不是 null,且 Long 对象与此对象包含相同的 long 值时,结果才为 true

覆盖:
Object 中的 equals
参数:
obj - 要与之进行比较的对象。
返回:
如果对象相同,则返回 true;否则,返回 false
另请参见:
Object.hashCode(), Hashtable

getLong

public static Long getLong(String nm)
确定具有指定名称的系统属性的 long 值。

第一个参数被视为系统属性的名称。通过 System.getProperty(java.lang.String) 方法可以访问该系统属性。然后,以 long 值的形式解释此属性的字符串值,并返回表示此值的 Long 对象。在 getProperty 的定义中可以找到可能的数字格式的详细信息。

如果指定名称没有属性,或者指定名称为空或 null,抑或属性不具有正确的数字格式时,则返回 null

换句话说,此方法返回一个 Long 对象,它的值等于:

getLong(nm, null)

参数:
nm - 属性名。
返回:
属性的 Long 值。
另请参见:
System.getProperty(java.lang.String), System.getProperty(java.lang.String, java.lang.String)

getLong

public static Long getLong(String nm,
                           long val)
使用指定名称确定系统属性的 long 值。

第一个参数被视为系统属性的名称。通过 System.getProperty(java.lang.String) 方法可以访问该系统属性。然后,以 long 值的形式解释此属性的字符串值,并返回表示此值的 Long 对象。在 getProperty 的定义中可以找到可能的数字格式的详细信息。

第二个参数是默认值。如果指定的名称没有属性,或者该属性不具备正确的数字格式,抑或指定名称为空或 null,则返回表示第二个参数的值的 Long 对象。

换句话说,此方法返回一个 Long 对象,它的值等于:

getLong(nm, new Long(val))
但是实际上,它可能通过以下方式实现:
Long result = getLong(nm, null);
return (result == null) ? new Long(val) :result;
 
这样可以避免不需要默认值时进行的不必要的 Long 对象分配。

参数:
nm - 属性名。
val - 默认值。
返回:
属性的 Long 值。
另请参见:
System.getProperty(java.lang.String), System.getProperty(java.lang.String, java.lang.String)

getLong

public static Long getLong(String nm,
                           Long val)
使用指定名称返回系统属性的 long 值。第一个参数被视为系统属性的名称。通过 System.getProperty(java.lang.String) 方法可以访问该系统属性。然后,以 long 值的形式解释此属性的字符串值,并且按照 Long.decode 方法返回表示此值的 Long 对象。

注意,在所有情况下,都不允许将 L ('\u004C') 和 l ('\u006C') 作为类型指示符出现在属性值的结尾处,这一点在 Java 编程语言源代码中是允许的。

第二个参数是默认值。如果指定的名称没有属性,或者属性不具有正确的数字格式,抑或指定名称为空或 null,则返回默认值。

参数:
nm - 属性名。
val - 默认值。
返回:
属性的 Long 值。
另请参见:
System.getProperty(java.lang.String), System.getProperty(java.lang.String, java.lang.String), decode(java.lang.String)

compareTo

public int compareTo(Long anotherLong)
在数字上比较两个 Long 对象。

指定者:
接口 Comparable<Long> 中的 compareTo
参数:
anotherLong - 要比较的 Long
返回:
如果 Long 等于参数 Long,则返回 0 值;如果 Long 在数字上小于参数 Long,则返回小于 0 的值;如果 Long 在数字上大于参数 Long,则返回大于 0 的值(有符号比较)。
从以下版本开始:
1.2

highestOneBit

public static long highestOneBit(long i)
返回至多有一个 1 位的 long 值,在指定的 long 值中最高位(最左边)的 1 位的位置。如果指定值在其二进制补码表示形式中没有 1 位,即等于零,则返回零。

返回:
返回具有单个 1 位的 long 值,在指定值中最高位的 1 位的位置;否则,如果指定值本身等于零,则返回零。
从以下版本开始:
1.5

lowestOneBit

public static long lowestOneBit(long i)
返回至多有一个 1 位的 long 值,在指定的 long 值中最低位(最右边)的 1 位的位置。如果指定值在其二进制补码表示形式中没有 1 位,即等于零,则返回零。

返回:
返回具有单个 1 位的 long 值,在指定值中最低位的 1 位的位置;否则,如果指定值本身等于零,则返回零。
从以下版本开始:
1.5

numberOfLeadingZeros

public static int numberOfLeadingZeros(long i)
在指定 long 值的二进制补码表示形式中最高位(最左)的 1 位之前,返回零位的数量。如果指定值在其二进制补码表示形式中不存在 1 位,换句话说,如果它等于零,则返回 64。

注意,此方法与二进制对数密切相关。对于所有的正 long 值 x:

返回:
返回在指定 long 值的二进制补码表示形式中最高位(最左)的 1 位之前的零位的数量;否则,如果该值等于零,则返回 64。
从以下版本开始:
1.5

numberOfTrailingZeros

public static int numberOfTrailingZeros(long i)
返回在指定 long 值的二进制补码表示形式中最低位(最右)的 1 位之后的零位的数量。如果指定值在其二进制补码表示形式中不存在 1 位,换句话说,如果它等于零,则返回 64。

返回:
返回在指定 long 值的二进制补码表示形式中最低位(最右)的 1 位之后零位的数量;否则,如果该值等于零,则返回 64。
从以下版本开始:
1.5

bitCount

public static int bitCount(long i)
返回指定 long 值的二进制补码表示形式中的 1 位的数量。此功能有时被称为填充计算

返回:
返回指定 long 值的二进制补码表示形式的 1 位的数量。
从以下版本开始:
1.5

rotateLeft

public static long rotateLeft(long i,
                              int distance)
返回根据指定的位数循环左移指定的 long 值的二进制补码表示形式而得到的值。(位是从左边(即高位)移出,从右边(即低位)再进入)

注意,使用负距离的左循环等同于右循环:rotateLeft(val, -distance) == rotateRight(val, distance)。另请注意,使用 64 的倍数循环无效,因此除了最后六位,所有循环距离都可以忽略,即使距离是负值:rotateLeft(val, distance) == rotateLeft(val, distance & 0x3F)

返回:
返回根据指定的位数循环左移指定的 long 值的二进制补码表示形式而得到的值。
从以下版本开始:
1.5

rotateRight

public static long rotateRight(long i,
                               int distance)
返回根据指定的位数循环右移指定的 long 值的二进制补码表示形式而得到的值。(位是从右边(即低位)移出,从左边(即高位)再进入)

注意,使用负距离右循环等于左循环:rotateRight(val, -distance) == rotateLeft(val, distance)。另请注意,使用 64 的倍数循环无效,因此除了最后六位,所有循环距离都可以忽略,即使距离是负值:rotateRight(val, distance) == rotateRight(val, distance & 0x3F)

返回:
返回根据指定的位数循环右移指定的 long 值的二进制补码表示形式而得到的值。
从以下版本开始:
1.5

reverse

public static long reverse(long i)
返回通过反转指定 long 值的二进制补码表示形式中位的顺序而获得的值。

返回:
返回通过反转指定 long 值中位的顺序而获得的值。
从以下版本开始:
1.5

signum

public static int signum(long i)
返回指定 long 值的符号函数。(如果指定值为负,则返回值 -1;如果指定值为零,则返回 0;如果指定值为正,则返回 1。)

返回:
返回指定 long 值的符号函数。
从以下版本开始:
1.5

reverseBytes

public static long reverseBytes(long i)
返回通过反转指定 long 值的二进制补码表示形式中字节的顺序而获得的值。

返回:
返回通过反转指定 long 值中的字节而获得的值。
从以下版本开始:
1.5

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策