java.nio
类 CharBuffer

java.lang.Object
  java.nio.Buffer
      java.nio.CharBuffer

所有已实现的接口：

Appendable, CharSequence, Comparable<CharBuffer>, Readable

public abstract class CharBuffer
extends Buffer
implements Comparable<CharBuffer>, Appendable, CharSequence, Readable

字符缓冲区。

此类定义了字符缓冲区上的四类操作：

• 读写单个字符的绝对和相对 get 和 put 方法；

• 将此缓冲区中的连续字符序列传输到数组中的相对批量 get 方法；

• 将字符数组、字符串或其他字符缓冲区中的连续字符序列传输到此缓冲区的相对批量 put 方法；以及

• 字符缓冲区的 compacting、duplicating 和 slicing 方法。

字符缓冲区可以通过 allocation 方法创建，此方法通过 wrapping 将一个现有字符数组或字符串包装到缓冲区中来为缓冲区内容分配空间，或者通过创建现有字节缓冲区的视图来创建。

像字节缓冲区一样，字符缓冲区要么是直接的，要么是非直接的。通过此类的 wrap 方法创建的字符缓冲区将是非直接的。当且仅当字节缓冲区本身为直接时，作为字节缓冲区的视图创建的字符缓冲区才是直接的。通过调用 isDirect 方法可以确定字符缓冲区是否为直接的。

此类实现 CharSequence 接口，以便字符缓冲区可以用于任何接受字符序列的地方，例如，在正则表达式包 java.util.regex 中。

指定此类中不返回其他值的那些方法返回它们被调用时所在的缓冲区。这允许对方法调用进行链接。 例如，语句序列

 cb.put("text/");
 cb.put(subtype);
 cb.put("; charset=");
 cb.put(enc);

 cb.put("text/").put(subtype).put("; charset=").put(enc);

从以下版本开始：

1.4

allocate

public static CharBuffer allocate(int capacity)

分配新的字符缓冲区。

新缓冲区的位置将为零，其界限将为其容量，其标记是未定义的。它将具有一个底层实现数组，且其数组偏移量将为零。

参数：

capacity - 新缓冲区的容量，以字符为单位

返回：

新的字符缓冲区

抛出：

IllegalArgumentException - 如果 capacity 为负整数

wrap

public static CharBuffer wrap(char[] array,
                              int offset,
                              int length)

将字符数组包装到缓冲区中。

给定的字符数组将支持新缓冲区；即缓冲区修改将导致数组修改，反之亦然。新缓冲区的容量将为 array.length，其位置将为 offset，其界限将为 offset + length，其标记是未定义的。其底层实现数组将为给定数组，并且其数组偏移量将为零。

参数：

array - 支持新缓冲区的数组

offset - 要使用的子数组的偏移量；必须为非负且不大于 array.length。将新缓冲区的位置设置为此值。

length - 要使用的子数组的长度；必须为非负且不大于 array.length - offset。新缓冲区的界限将被设置为 offset + length。

返回：

新的字符缓冲区

抛出：

IndexOutOfBoundsException - 如果关于 offset 和 length 参数的前提不成立

wrap

public static CharBuffer wrap(char[] array)

将字符数组包装到缓冲区中。

给定的字符数组将支持新缓冲区；即缓冲区修改将导致数组修改，反之亦然。新缓冲区的容量和界限将为 array.length，其位置将为零，其标记是未定义的。其底层实现数组将为给定数组，并且其数组偏移量将为零。

参数：

array - 实现此缓冲区的数组

返回：

新的字符缓冲区

read

public int read(CharBuffer target)
         throws IOException

试图将字符读入指定的字符缓冲区。缓冲区可照原样用作字符的存储库：所做的唯一更改是 put 操作的结果。不对缓冲区执行翻转或重绕操作。

指定者：

接口 Readable 中的 read

参数：

target - 要将字符读入的缓冲区

返回：

添加到缓冲区的字符数量，如果此字符源位于缓冲区末端，则返回 -1

抛出：

IOException - 如果发生 I/O 错误

NullPointerException - 如果目标为空

ReadOnlyBufferException - 如果目标是一个只读缓冲区

从以下版本开始：

1.5

wrap

public static CharBuffer wrap(CharSequence csq,
                              int start,
                              int end)

将字符序列包装到缓冲区中。

新的只读缓冲区的内容将为给定字符序列的内容。缓冲区的容量将为 csq.length()，其位置将为 start，其界限将为 end，其标记是未定义的。

参数：

csq - 字符序列，新的字符缓冲区将从中创建

start - 要使用的第一个字符的索引；必须为非负且不大于 csq.length()。新缓冲区的位置将被设置为此值。

end - 要使用的最后一个字符后面的字符的索引；必须不小于 start 且不大于 csq.length()。将新缓冲区的界限设置为此值。

返回：

新的字符缓冲区

抛出：

IndexOutOfBoundsException - 如果关于 offset 和 length 参数的前提不成立

wrap

public static CharBuffer wrap(CharSequence csq)

将字符序列包装到缓冲区中。

新的只读缓冲区的内容将为给定字符序列的内容。新缓冲区的容量和界限将为 csq.length()，其位置将为零，其标记是未定义的。

参数：

csq - 新的字符缓冲区要从其创建的字符序列

返回：

新的字符缓冲区

slice

public abstract CharBuffer slice()

创建新的字符缓冲区，其内容为此缓冲区内容的共享子序列。

新缓冲区的内容将从此缓冲区的当前位置开始。此缓冲区内容的更改在新缓冲区中是可见的，反之亦然；这两个缓冲区的位置、界限和标记值是相互独立的。

新缓冲区的位置将为零，其容量和界限将为此缓冲区中所剩余的字符数量，其标记是未定义的。当且仅当此缓冲区为直接时，新缓冲区才是直接的，当且仅当此缓冲区为只读时，新缓冲区才是只读的。

返回：

新的字符缓冲区

duplicate

public abstract CharBuffer duplicate()

创建共享此缓冲区内容的新的字符缓冲区。

新缓冲区的内容将为此缓冲区的内容。此缓冲区内容的更改在新缓冲区中是可见的，反之亦然；这两个缓冲区的位置、界限和标记值是相互独立的。

新缓冲区的容量、界限、位置和标记值将与此缓冲区相同。当且仅当此缓冲区为直接时，新缓冲区才是直接的，当且仅当此缓冲区为只读时，新缓冲区才是只读的。

返回：

新的字符缓冲区

asReadOnlyBuffer

public abstract CharBuffer asReadOnlyBuffer()

创建共享此缓冲区内容的新的只读字符缓冲区。

新缓冲区的内容将为此缓冲区的内容。此缓冲区的更改在新缓冲区中是可见的，但新缓冲区将是只读的并且不允许修改共享内容。两个缓冲区的位置、界限和标记值是相互独立的。

新缓冲区的容量、界限、位置和标记值将与此缓冲区相同。

如果此缓冲区本身是只读的，则此方法与 duplicate 方法完全相同。

返回：

新的只读字符缓冲区

get

public abstract char get()

相对 get 方法。读取此缓冲区当前位置的字符，然后该位置递增。

返回：

缓冲区当前位置的字符

抛出：

BufferUnderflowException - 如果缓冲区当前位置不小于其界限

put

public abstract CharBuffer put(char c)

相对 put 方法（可选操作）。

将给定字符写入此缓冲区的当前位置，然后该位置递增。

参数：

c - 要写入的字符

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区的当前位置不小于界限

ReadOnlyBufferException - 如果此缓冲区是只读的

get

public abstract char get(int index)

绝对 get 方法。读取给定索引处的字符。

参数：

index - 将读取字符的位置的索引

返回：

给定索引处的字符

抛出：

IndexOutOfBoundsException - 如果 index 为负或不小于缓冲区界限

put

public abstract CharBuffer put(int index,
                               char c)

绝对 put 方法（可选操作）。

将给定字符写入此缓冲区的给定索引处。

参数：

index - 将在该位置写入字符

c - 要写入的字符值

返回：

此缓冲区

抛出：

IndexOutOfBoundsException - 如果 index 为负或不小于缓冲区界限

ReadOnlyBufferException - 如果此缓冲区是只读的

get

public CharBuffer get(char[] dst,
                      int offset,
                      int length)

相对批量 get 方法。

此方法将此缓冲区中的字符传输到给定的目标数组中。如果缓冲区中剩余的字符少于满足请求所需的字符，即如果 length > remaining()，则不传输字符且抛出 BufferUnderflowException。

否则，此方法将此缓冲区中的 length 个字符复制到给定数组中，从此缓冲区的当前位置和数组中的给定偏移量位置开始复制。然后此缓冲区的位置递增 length。

换句话说，调用此方法的形式为 src.get(dst, off, len)，效果与以下循环语句完全相同：

     for (int i = off; i < off + len; i++)
         dst[i] = src.get(); 

区别在于它首先检查此缓冲区中是否具有足够的字符，这样可能效率更高。

参数：

dst - 要写入字符的数组

offset - 要写入的第一个字符在数组中的偏移量；必须为非负且不大于 dst.length

length - 要写入给定数组中的字符的最大数量；必须为非负且不大于 dst.length - offset

返回：

此缓冲区

抛出：

BufferUnderflowException - 如果此缓冲区中的剩余字符少于 length

IndexOutOfBoundsException - 如果关于 offset 和 length 参数的前提不成立

get

public CharBuffer get(char[] dst)

相对批量 get 方法。

此方法将此缓冲区的字符传输到给定的目标数组中。调用此方法的形式为 src.get(a)，该调用与以下调用完全相同：

     src.get(a, 0, a.length) 

返回：

此缓冲区

抛出：

BufferUnderflowException - 如果此缓冲区中的剩余字符少于 length

put

public CharBuffer put(CharBuffer src)

相对批量 put 方法（可选操作）。

此方法将给定源缓冲区中的剩余字符传输到此缓冲区中。如果源缓冲区中的剩余字符多于此缓冲区的剩余字符空间，即 src.remaining() > remaining()，则不传输字符且抛出 BufferOverflowException。

否则，此方法将给定缓冲区中的 n = src.remaining() 个字符复制到此缓冲区中，从每个缓冲区的当前位置开始复制。然后这两个缓冲区的位置均递增 n。

换句话说，调用此方法的形式为 dst.put(src)，效果与以下循环语句完全相同：

     while (src.hasRemaining())
         dst.put(src.get()); 

区别在于它首先检查此缓冲区中是否有足够空间，这样可能效率更高。

参数：

src - 要从中读取字符的源缓冲区；不能为此缓冲区

返回：

此缓冲区

抛出：

BufferOverflowException - 如果对于源缓冲区中剩余的字符，此缓冲区没有足够空间

IllegalArgumentException - 如果源缓冲区为此缓冲区

ReadOnlyBufferException - 如果此缓冲区是只读的

put

public CharBuffer put(char[] src,
                      int offset,
                      int length)

相对批量 put 方法（可选操作）。

此方法将给定源数组中的字符传输到此缓冲区中。如果要从数组复制的字符多于此缓冲区中的剩余字符空间，即如果 length > remaining()，则不传输字符且抛出 BufferOverflowException。

否则，此方法将给定数组中的 length 个字符复制到此缓冲区中，从数组中给定偏移量位置和此缓冲区的当前位置开始复制。然后此缓冲区的位置递增 length。

换句话说，调用此方法的形式为 dst.put(src, off, len)，效果与以下循环语句完全相同：

     for (int i = off; i < off + len; i++)
         dst.put(a[i]); 

区别在于它首先检查此缓冲区中是否有足够空间，这样可能效率更高。

参数：

src - 要从中读取字符的数组

offset - 要读取的第一个字符在数组中的偏移量；必须为非负且不大于 array.length

length - 要从给定数组读取的字符数量；必须为非负且不大于 array.length - offset

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区没有足够空间

IndexOutOfBoundsException - 如果关于 offset 和 length 参数的前提不成立

ReadOnlyBufferException - 如果此缓冲区是只读的

put

public final CharBuffer put(char[] src)

相对批量 put 方法（可选操作）。

此方法将给定源字符数组的所有内容传输到此缓冲区中。调用此方法的形式为 dst.put(a)，该调用与以下调用完全相同：

     dst.put(a, 0, a.length) 

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区没有足够空间

ReadOnlyBufferException - 如果此缓冲区是只读的

put

public CharBuffer put(String src,
                      int start,
                      int end)

相对批量 put 方法（可选操作）。

此方法将给定字符串中的字符传输到此缓冲区中。如果要从字符串复制的字符多于此缓冲区中的剩余字符空间，即如果 end - start > remaining()，则不传输字符且抛出 BufferOverflowException。

否则，此方法将给定字符串的 n = end - start 个字符复制到此缓冲区中，从给定的 start 索引处和此缓冲区的当前位置开始复制。然后此缓冲区的位置递增 n。

换句话说，调用此方法的形式为 dst.put(src, start, end)，效果与以下循环语句完全相同：

     for (int i = start; i < end; i++)
         dst.put(src.charAt(i)); 

区别在于它首先检查此缓冲区中是否有足够空间，这样可能效率更高。

参数：

src - 要从中读取字符的字符串

start - 要读取的第一个字符在字符串中的偏移量；必须为非负且不大于 string.length()

end - 要读取的最后一个字符在字符串中的偏移量加上 1；必须为非负且不大于 string.length()

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区没有足够空间

IndexOutOfBoundsException - 如果关于 start 和 end 参数的前提不成立

ReadOnlyBufferException - 如果此缓冲区是只读的

put

public final CharBuffer put(String src)

相对批量 put 方法（可选操作）。

此方法将给定源字符串中的所有内容传输到此缓冲区中。调用此方法的形式为 dst.put(s)，该调用与以下调用完全相同：

     dst.put(s, 0, s.length()) 

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区没有足够空间

ReadOnlyBufferException - 如果此缓冲区是只读的

hasArray

public final boolean hasArray()

判断该缓冲区是否可通过一个可访问的字符数组实现。

如果此方法返回 true，则可以安全地调用 array 和 arrayOffset 方法。

指定者：

类 Buffer 中的 hasArray

返回：

当且仅当存在实现此缓冲区的数组，并且此缓冲区不是只读缓冲区时，返回 true

array

public final char[] array()

返回实现此缓冲区的字符数组（可选操作）。

此缓冲区的内容修改将导致返回的数组内容修改，反之亦然。

调用此方法之前要调用 hasArray 方法，以确保此缓冲区具有可访问的底层实现数组。

指定者：

类 Buffer 中的 array

返回：

实现此缓冲区的数组

抛出：

ReadOnlyBufferException - 如果存在实现此缓冲区的数组，但缓冲区是只读的

UnsupportedOperationException - 如果不存在某个可访问的数组实现此缓冲区

arrayOffset

public final int arrayOffset()

返回此缓冲区中的第一个元素在缓冲区的底层实现数组中的偏移量（可选操作）。

如果存在实现此缓冲区的数组，则缓冲区位置 p 对应于数组索引 p + arrayOffset()。

调用此方法之前要调用 hasArray 方法，以确保此缓冲区具有可访问的底层实现数组。

指定者：

类 Buffer 中的 arrayOffset

返回：

此缓冲区的第一个元素在缓冲区数组中的偏移量

抛出：

ReadOnlyBufferException - 如果存在实现此缓冲区的数组，但缓冲区是只读的

UnsupportedOperationException - 如果不存在某个可访问的数组实现此缓冲区

compact

public abstract CharBuffer compact()

压缩此缓冲区（可选操作）。

将缓冲区当前位置和界限之间的字符（如果有）复制到缓冲区的开始处。即将索引 p = position() 处的字符复制到索引 0 处，将索引 p + 1 处的字符复制到索引 1 处，依此类推，直到将索引 limit() - 1 处的字符复制到索引 n = limit() - 1 - p 处。然后将缓冲区的位置设置为 n+1，并将其界限设置为其容量。如果已定义了标记，则丢弃它。

将缓冲区的位置设置为复制的字符数，而不是零，以便调用此方法后可以紧接着调用另一个相对 put 方法。

返回：

此缓冲区

抛出：

ReadOnlyBufferException - 如果此缓冲区是只读的

isDirect

public abstract boolean isDirect()

判断此字符缓冲区是否为直接的。

指定者：

类 Buffer 中的 isDirect

返回：

当且仅当此缓冲区为直接时，返回 true

hashCode

public int hashCode()

返回此缓冲区的当前哈希码。

字符缓冲区的哈希码只取决于其剩余元素；即取决于从 position() 开始一直到（包括） limit() - 1 处的元素。

因为缓冲区哈希码与内容有关，因此建议不要在哈希映射或其他类似数据结构中将缓冲区用作键，除非知道其内容不会发生更改。

覆盖：

类 Object 中的 hashCode

返回：

此缓冲区的当前哈希码

另请参见：

Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object ob)

判断此缓冲区是否与另一个对象相同。

两个字符缓冲区是相同的，当且仅当：

1. 它们具有相同的元素类型，

2. 它们具有相同数量的剩余元素，并且

3. 两个剩余元素序列（与它们的起始位置无关）逐点相同。

字符缓冲区与任何其他类型的对象都不同。

覆盖：

类 Object 中的 equals

参数：

ob - 此缓冲区要比较的对象

返回：

当且仅当此缓冲区与给定对象相同时，返回 true

另请参见：

Object.hashCode(), Hashtable

compareTo

public int compareTo(CharBuffer that)

将此缓冲区与另一个缓冲区进行比较。

比较两个字符缓冲区的方法是按字典顺序比较它们的剩余元素序列，而不考虑每个序列在其对应缓冲区中的起始位置。

字符缓冲区不能与任何其他类型的对象进行比较。

指定者：

接口 Comparable<CharBuffer> 中的 compareTo

参数：

that - 要比较的对象。

返回：

如果此缓冲区小于、等于或大于给定缓冲区，则相应返回负整数、零或正整数

toString

public String toString()

返回包含此缓冲区中字符的字符串。

所得字符串的第一个字符将为此缓冲区位置处的字符，最后一个字符将为索引 limit() - 1 处的字符。调用此方法不更改缓冲区的位置。

指定者：

接口 CharSequence 中的 toString

覆盖：

类 Object 中的 toString

返回：

指定的字符串

length

public final int length()

返回此字符缓冲区的长度。

当将字符缓冲区视为字符序列时，长度只是该位置（包括）和界限（不包括）之间的字符数；即长度等效于 remaining()。

指定者：

接口 CharSequence 中的 length

返回：

此字符缓冲区的长度

charAt

public final char charAt(int index)

读取相对于当前位置的给定索引处的字符。

指定者：

接口 CharSequence 中的 charAt

参数：

index - 要读取的相对于该位置的字符的索引；必须为非负且小于 remaining()

返回：

索引 position() + index 处的字符

抛出：

IndexOutOfBoundsException - 如果关于 index 的前提不成立

subSequence

public abstract CharSequence subSequence(int start,
                                         int end)

创建表示此缓冲区的指定序列、相对于当前位置的新字符缓冲区。

新缓冲区将共享此缓冲区的内容；即如果此缓冲区的内容是可变的，则修改一个缓冲区将导致另一个缓冲区被修改。新缓冲区的容量将为此缓冲区的容量，其位置将为 position() + start，其界限将为 position() + end。当且仅当此缓冲区为直接时，新缓冲区才是直接的，当且仅当此缓冲区为只读时，新缓冲区才是只读的。

指定者：

接口 CharSequence 中的 subSequence

参数：

start - 子序列中第一个字符相对于当前位置的索引；必须为非负且不大于 remaining()

end - 子序列中最后一个字符后面的字符相对于当前位置的索引；必须不小于 start 且不大于 remaining()

返回：

新的字符序列

抛出：

IndexOutOfBoundsException - 如果关于 start 和 end 的前提不成立

append

public CharBuffer append(CharSequence csq)

将指定的字符序列添加到此缓冲区（可选操作）。

调用此方法的形式为 dst.append(csq)，该调用与以下调用完全相同：

     dst.put(csq.toString()) 

可能没有添加整个序列，这取决于针对字符序列 csq 的 toString 规范。例如，调用字符缓冲区的 toString 方法将返回一个子序列，其内容取决于缓冲区的位置和界限。

指定者：

接口 Appendable 中的 append

参数：

csq - 要添加的字符序列。如果 csq 为 null，则向此字符缓冲区添加四个字符 "null"。

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区没有足够空间

ReadOnlyBufferException - 如果此缓冲区是只读的

从以下版本开始：

1.5

append

public CharBuffer append(CharSequence csq,
                         int start,
                         int end)

将指定字符序列的子序列添加到此缓冲区（可选操作）。

当 csq 不为 null 时，调用此方法的形式为 dst.append(csq, start, end)，该调用与以下调用完全相同：

     dst.put(csq.subSequence(start, end).toString()) 

指定者：

接口 Appendable 中的 append

参数：

csq - 要添加其子序列的字符序列。如果 csq 为 null，则按 csq 包含四个字符 "null" 的方式添加这些字符。

start - 子序列中第一个字符的索引

end - 紧随子序列中最后一个字符的字符的索引

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区没有足够空间

IndexOutOfBoundsException - 如果 start 或 end 为负，而 start 大于 end 或者 end 大于 csq.length()

ReadOnlyBufferException - 如果此缓冲区是只读的

从以下版本开始：

1.5

append

public CharBuffer append(char c)

将指定字符添加到此缓冲区（可选操作）。

调用此方法的形式为 dst.append(c)，该调用与以下调用完全相同：

     dst.put(c) 

指定者：

接口 Appendable 中的 append

参数：

c - 要添加的 16 位字符

返回：

此缓冲区

抛出：

BufferOverflowException - 如果此缓冲区没有足够空间

ReadOnlyBufferException - 如果此缓冲区是只读的

从以下版本开始：

1.5

order

public abstract ByteOrder order()

获取此缓冲区的字节顺序。

通过分配或通过包装现有 char 数组而创建的字符缓冲区的字节顺序是底层硬件的 native order。作为字节缓冲区的视图而创建的字符缓冲区的字节顺序是创建视图时字节缓冲区的字节顺序。

返回：

此缓冲区的字节顺序

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