public abstract class CharBuffer extends Buffer implements Comparable<CharBuffer>, CharSequence, Appendable, Readable
A char buffer can be created in either one of the following ways:
Allocate
a new char array and create a buffer
based on it;Wrap
an existing char array to create a new
buffer;Wrap
an existing char sequence to create a
new buffer;ByteBuffer.asCharBuffer
to create a char buffer based on a byte buffer.Modifier and Type | Method and Description |
---|---|
static CharBuffer |
allocate(int capacity)
Creates a char buffer based on a newly allocated char array.
|
CharBuffer |
append(char c)
Writes the given char to the current position and increases the position
by 1.
|
CharBuffer |
append(CharSequence csq)
Writes all chars of the given character sequence
csq to the
current position of this buffer, and increases the position by the length
of the csq. |
CharBuffer |
append(CharSequence csq,
int start,
int end)
Writes chars of the given
CharSequence to the current position of
this buffer, and increases the position by the number of chars written. |
char[] |
array()
Returns the array that backs this buffer (optional operation).
|
int |
arrayOffset()
Returns the offset into the array returned by
array of the first
element of the buffer (optional operation). |
abstract CharBuffer |
asReadOnlyBuffer()
Returns a read-only buffer that shares its content with this buffer.
|
char |
charAt(int index)
Returns the character located at the specified index in the buffer.
|
abstract CharBuffer |
compact()
Compacts this char buffer.
|
int |
compareTo(CharBuffer otherBuffer)
Compare the remaining chars of this buffer to another char
buffer's remaining chars.
|
abstract CharBuffer |
duplicate()
Returns a duplicated buffer that shares its content with this buffer.
|
boolean |
equals(Object other)
Checks whether this char buffer is equal to another object.
|
abstract char |
get()
Returns the char at the current position and increases the position by 1.
|
CharBuffer |
get(char[] dst)
Reads chars from the current position into the specified char array and
increases the position by the number of chars read.
|
CharBuffer |
get(char[] dst,
int dstOffset,
int charCount)
Reads chars from the current position into the specified char array,
starting from the specified offset, and increases the position by the
number of chars read.
|
abstract char |
get(int index)
Returns a char at the specified index; the position is not changed.
|
boolean |
hasArray()
Returns true if
array and arrayOffset won't throw. |
int |
hashCode()
Calculates this buffer's hash code from the remaining chars.
|
abstract boolean |
isDirect()
Indicates whether this buffer is direct.
|
int |
length()
Returns the number of remaining chars.
|
abstract ByteOrder |
order()
Returns the byte order used by this buffer when converting chars from/to
bytes.
|
abstract CharBuffer |
put(char c)
Writes the given char to the current position and increases the position
by 1.
|
CharBuffer |
put(char[] src)
Writes chars from the given char array to the current position and
increases the position by the number of chars written.
|
CharBuffer |
put(char[] src,
int srcOffset,
int charCount)
Writes chars from the given char array, starting from the specified offset,
to the current position and increases the position by the number of chars
written.
|
CharBuffer |
put(CharBuffer src)
Writes all the remaining chars of the
src char buffer to this
buffer's current position, and increases both buffers' position by the
number of chars copied. |
abstract CharBuffer |
put(int index,
char c)
Writes a char to the specified index of this buffer; the position is not
changed.
|
CharBuffer |
put(String str)
Writes all chars of the given string to the current position of this
buffer, and increases the position by the length of string.
|
CharBuffer |
put(String str,
int start,
int end)
Writes chars of the given string to the current position of this buffer,
and increases the position by the number of chars written.
|
int |
read(CharBuffer target)
Reads characters from this buffer and puts them into
target . |
abstract CharBuffer |
slice()
Returns a sliced buffer that shares its content with this buffer.
|
abstract CharSequence |
subSequence(int start,
int end)
Returns a new char buffer representing a sub-sequence of this buffer's
current remaining content.
|
String |
toString()
Returns a string representing the current remaining chars of this buffer.
|
static CharBuffer |
wrap(char[] array)
Creates a new char buffer by wrapping the given char array.
|
static CharBuffer |
wrap(char[] array,
int start,
int charCount)
Creates a new char buffer by wrapping the given char array.
|
static CharBuffer |
wrap(CharSequence chseq)
Creates a new char buffer by wrapping the given char sequence.
|
static CharBuffer |
wrap(CharSequence cs,
int start,
int end)
Creates a new char buffer by wrapping the given char sequence.
|
public static CharBuffer allocate(int capacity)
capacity
- the capacity of the new buffer.IllegalArgumentException
- if capacity
is less than zero.public static CharBuffer wrap(char[] array)
Calling this method has the same effect as
wrap(array, 0, array.length)
.
array
- the char array which the new buffer will be based on.public static CharBuffer wrap(char[] array, int start, int charCount)
The new buffer's position will be start
, limit will be
start + charCount
, capacity will be the length of the array.
array
- the char array which the new buffer will be based on.start
- the start index, must not be negative and not greater than
array.length
.charCount
- the length, must not be negative and not greater than
array.length - start
.IndexOutOfBoundsException
- if either start
or charCount
is invalid.public static CharBuffer wrap(CharSequence chseq)
Calling this method has the same effect as
wrap(chseq, 0, chseq.length())
.
chseq
- the char sequence which the new buffer will be based on.public static CharBuffer wrap(CharSequence cs, int start, int end)
The new buffer's position will be start
, limit will be
end
, capacity will be the length of the char sequence. The new
buffer is read-only.
cs
- the char sequence which the new buffer will be based on.start
- the start index, must not be negative and not greater than
cs.length()
.end
- the end index, must be no less than start
and no
greater than cs.length()
.IndexOutOfBoundsException
- if either start
or end
is invalid.public final char[] array()
Buffer
Subclasses should override this method with a covariant return type to provide the exact type of the array.
Use hasArray
to ensure this method won't throw.
(A separate call to isReadOnly
is not necessary.)
public final int arrayOffset()
Buffer
array
of the first
element of the buffer (optional operation). The backing array (if there is one)
is not necessarily the same size as the buffer, and position 0 in the buffer is
not necessarily the 0th element in the array. Use
buffer.array()[offset + buffer.arrayOffset()
to access element offset
in buffer
.
Use hasArray
to ensure this method won't throw.
(A separate call to isReadOnly
is not necessary.)
arrayOffset
in class Buffer
public abstract CharBuffer asReadOnlyBuffer()
The returned buffer is guaranteed to be a new instance, even if this buffer is read-only itself. The new buffer's position, limit, capacity and mark are the same as this buffer's.
The new buffer shares its content with this buffer, which means this buffer's change of content will be visible to the new buffer. The two buffer's position, limit and mark are independent.
public final char charAt(int index)
charAt
in interface CharSequence
index
- the index referenced from the current buffer position. It must
not be less than zero but less than the value obtained from a
call to remaining()
.IndexOutOfBoundsException
- if the index is invalid.public abstract CharBuffer compact()
The remaining chars will be moved to the head of the buffer,
starting from position zero. Then the position is set to
remaining()
; the limit is set to capacity; the mark is cleared.
ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public int compareTo(CharBuffer otherBuffer)
compareTo
in interface Comparable<CharBuffer>
otherBuffer
- another char buffer.otherBuffer
; 0 if
this equals to otherBuffer
; a positive value if this is
greater than otherBuffer
.ClassCastException
- if otherBuffer
is not a char buffer.public abstract CharBuffer duplicate()
The duplicated buffer's initial position, limit, capacity and mark are the same as this buffer's. The duplicated buffer's read-only property and byte order are the same as this buffer's, too.
The new buffer shares its content with this buffer, which means either buffer's change of content will be visible to the other. The two buffer's position, limit and mark are independent.
public boolean equals(Object other)
If other
is not a char buffer then false
is returned. Two
char buffers are equal if and only if their remaining chars are exactly
the same. Position, limit, capacity and mark are not considered.
equals
in class Object
other
- the object to compare with this char buffer.true
if this char buffer is equal to other
,
false
otherwise.Object.hashCode()
public abstract char get()
BufferUnderflowException
- if the position is equal or greater than limit.public CharBuffer get(char[] dst)
Calling this method has the same effect as
get(dst, 0, dst.length)
.
dst
- the destination char array.BufferUnderflowException
- if dst.length
is greater than remaining()
.public CharBuffer get(char[] dst, int dstOffset, int charCount)
dst
- the target char array.dstOffset
- the offset of the char array, must not be negative and not
greater than dst.length
.charCount
- The number of chars to read, must be no less than zero and no
greater than dst.length - dstOffset
.IndexOutOfBoundsException
- if either dstOffset
or charCount
is invalid.BufferUnderflowException
- if charCount
is greater than remaining()
.public abstract char get(int index)
index
- the index, must not be negative and less than limit.IndexOutOfBoundsException
- if index is invalid.public final boolean hasArray()
Buffer
array
and arrayOffset
won't throw. This method does not
return true for buffers not backed by arrays because the other methods would throw
UnsupportedOperationException
, nor does it return true for buffers backed by
read-only arrays, because the other methods would throw ReadOnlyBufferException
.public int hashCode()
hashCode
in class Object
Object.equals(java.lang.Object)
public abstract boolean isDirect()
A char buffer is direct if it is based on a byte buffer and the byte buffer is direct.
public final int length()
length
in interface CharSequence
public abstract ByteOrder order()
If this buffer is not based on a byte buffer, then this always returns the platform's native byte order.
public abstract CharBuffer put(char c)
c
- the char to write.BufferOverflowException
- if position is equal or greater than limit.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public final CharBuffer put(char[] src)
Calling this method has the same effect as
put(src, 0, src.length)
.
src
- the source char array.BufferOverflowException
- if remaining()
is less than src.length
.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public CharBuffer put(char[] src, int srcOffset, int charCount)
src
- the source char array.srcOffset
- the offset of char array, must not be negative and not greater
than src.length
.charCount
- the number of chars to write, must be no less than zero and no
greater than src.length - srcOffset
.BufferOverflowException
- if remaining()
is less than charCount
.IndexOutOfBoundsException
- if either srcOffset
or charCount
is invalid.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public CharBuffer put(CharBuffer src)
src
char buffer to this
buffer's current position, and increases both buffers' position by the
number of chars copied.src
- the source char buffer.BufferOverflowException
- if src.remaining()
is greater than this buffer's
remaining()
.IllegalArgumentException
- if src
is this buffer.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public abstract CharBuffer put(int index, char c)
index
- the index, must be no less than zero and less than the limit.c
- the char to write.IndexOutOfBoundsException
- if index is invalid.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public final CharBuffer put(String str)
Calling this method has the same effect as
put(str, 0, str.length())
.
str
- the string to write.BufferOverflowException
- if remaining()
is less than the length of string.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public CharBuffer put(String str, int start, int end)
str
- the string to write.start
- the first char to write, must not be negative and not greater
than str.length()
.end
- the last char to write (excluding), must be less than
start
and not greater than str.length()
.BufferOverflowException
- if remaining()
is less than end - start
.IndexOutOfBoundsException
- if either start
or end
is invalid.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public abstract CharBuffer slice()
The sliced buffer's capacity will be this buffer's remaining()
,
and its zero position will correspond to this buffer's current position.
The new buffer's position will be 0, limit will be its capacity, and its
mark is cleared. The new buffer's read-only property and byte order are
same as this buffer.
The new buffer shares its content with this buffer, which means either buffer's change of content will be visible to the other. The two buffer's position, limit and mark are independent.
public abstract CharSequence subSequence(int start, int end)
The new buffer's position will be position() + start
, limit will
be position() + end
, capacity will be the same as this buffer.
The new buffer's read-only property and byte order are the same as this
buffer.
The new buffer shares its content with this buffer, which means either buffer's change of content will be visible to the other. The two buffer's position, limit and mark are independent.
subSequence
in interface CharSequence
start
- the start index of the sub-sequence, referenced from the
current buffer position. Must not be less than zero and not
greater than the value obtained from a call to
remaining()
.end
- the end index of the sub-sequence, referenced from the current
buffer position. Must not be less than start
and not
be greater than the value obtained from a call to
remaining()
.IndexOutOfBoundsException
- if either start
or end
is invalid.public String toString()
toString
in interface CharSequence
toString
in class Buffer
public CharBuffer append(char c)
append
in interface Appendable
c
- the char to write.BufferOverflowException
- if position is equal or greater than limit.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public CharBuffer append(CharSequence csq)
csq
to the
current position of this buffer, and increases the position by the length
of the csq.
Calling this method has the same effect as append(csq.toString())
.
If the CharSequence
is null
the string "null" will be
written to the buffer.
append
in interface Appendable
csq
- the CharSequence
to write.BufferOverflowException
- if remaining()
is less than the length of csq.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public CharBuffer append(CharSequence csq, int start, int end)
CharSequence
to the current position of
this buffer, and increases the position by the number of chars written.append
in interface Appendable
csq
- the CharSequence
to write.start
- the first char to write, must not be negative and not greater
than csq.length()
.end
- the last char to write (excluding), must be less than
start
and not greater than csq.length()
.BufferOverflowException
- if remaining()
is less than end - start
.IndexOutOfBoundsException
- if either start
or end
is invalid.ReadOnlyBufferException
- if no changes may be made to the contents of this buffer.public int read(CharBuffer target) throws IOException
target
. The
number of chars that are copied is either the number of remaining chars
in this buffer or the number of remaining chars in target
,
whichever is smaller.read
in interface Readable
target
- the target char buffer.IllegalArgumentException
- if target
is this buffer.IOException
- if an I/O error occurs.ReadOnlyBufferException
- if no changes may be made to the contents of target
.