public abstract class

CharBuffer

extends Buffer
implements Appendable CharSequence Comparable<T> Readable
java.lang.Object
   ↳ java.nio.Buffer
     ↳ java.nio.CharBuffer

Class Overview

A buffer of chars.

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;
  • Use ByteBuffer.asCharBuffer to create a char buffer based on a byte buffer.

Summary

Public Methods
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, 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.
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.
final char[] array()
Returns the array that backs this buffer (optional operation).
final 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.
final 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.
CharBuffer get(char[] dst, int off, int len)
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()
Returns the char at the current position and increases the position by 1.
abstract char get(int index)
Returns a char at the specified index; the position is not changed.
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.
final 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.
final 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.
final 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.
abstract CharBuffer put(char c)
Writes the given char to the current position and increases the position by 1.
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.
abstract CharBuffer put(int index, char c)
Writes a char to the specified index of this buffer; the position is not changed.
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.
final 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 off, int len)
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.
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(CharSequence chseq, int start, int end)
Creates a new char buffer by wrapping the given char sequence.
static CharBuffer wrap(CharSequence chseq)
Creates a new char buffer by wrapping the given char sequence.
static CharBuffer wrap(char[] array, int start, int len)
Creates a new char buffer by wrapping the given char array.
static CharBuffer wrap(char[] array)
Creates a new char buffer by wrapping the given char array.
[Expand]
Inherited Methods
From class java.nio.Buffer
From class java.lang.Object
From interface java.lang.Appendable
From interface java.lang.CharSequence
From interface java.lang.Comparable
From interface java.lang.Readable

Public Methods

public static CharBuffer allocate (int capacity)

Since: API Level 1

Creates a char buffer based on a newly allocated char array.

Parameters
capacity the capacity of the new buffer.
Returns
  • the created char buffer.
Throws
IllegalArgumentException if capacity is less than zero.

public CharBuffer append (char c)

Since: API Level 1

Writes the given char to the current position and increases the position by 1.

Parameters
c the char to write.
Returns
  • this buffer.
Throws
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, int start, int end)

Since: API Level 1

Writes chars of the given CharSequence to the current position of this buffer, and increases the position by the number of chars written.

Parameters
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().
Returns
  • this buffer.
Throws
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 CharBuffer append (CharSequence csq)

Since: API Level 1

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.

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.

Parameters
csq the CharSequence to write.
Returns
  • this buffer.
Throws
BufferOverflowException if remaining() is less than the length of csq.
ReadOnlyBufferException if no changes may be made to the contents of this buffer.

public final char[] array ()

Since: API Level 1

Returns the array that backs this buffer (optional operation). The returned value is the actual array, not a copy, so modifications to the array write through to the 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.)

Returns
  • the array

public final int arrayOffset ()

Since: API Level 1

Returns the offset into the array returned by 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.)

Returns
  • the offset

public abstract CharBuffer asReadOnlyBuffer ()

Since: API Level 1

Returns a read-only buffer that shares its content with this buffer.

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.

Returns
  • a read-only version of this buffer.

public final char charAt (int index)

Since: API Level 1

Returns the character located at the specified index in the buffer. The index value is referenced from the current buffer position.

Parameters
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().
Returns
  • the character located at the specified index (referenced from the current position) in the buffer.
Throws
IndexOutOfBoundsException if the index is invalid.

public abstract CharBuffer compact ()

Since: API Level 1

Compacts this char buffer.

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.

Returns
  • this buffer.
Throws
ReadOnlyBufferException if no changes may be made to the contents of this buffer.

public int compareTo (CharBuffer otherBuffer)

Since: API Level 1

Compare the remaining chars of this buffer to another char buffer's remaining chars.

Parameters
otherBuffer another char buffer.
Returns
  • a negative value if this is less than otherBuffer; 0 if this equals to otherBuffer; a positive value if this is greater than otherBuffer.
Throws
ClassCastException if otherBuffer is not a char buffer.

public abstract CharBuffer duplicate ()

Since: API Level 1

Returns a duplicated buffer that shares its content with this buffer.

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.

Returns
  • a duplicated buffer that shares its content with this buffer.

public boolean equals (Object other)

Since: API Level 1

Checks whether this char buffer is equal to another object.

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.

Parameters
other the object to compare with this char buffer.
Returns
  • true if this char buffer is equal to other, false otherwise.

public CharBuffer get (char[] dst, int off, int len)

Since: API Level 1

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.

Parameters
dst the target char array.
off the offset of the char array, must not be negative and not greater than dst.length.
len The number of chars to read, must be no less than zero and no greater than dst.length - off.
Returns
  • this buffer.
Throws
IndexOutOfBoundsException if either off or len is invalid.
BufferUnderflowException if len is greater than remaining().

public abstract char get ()

Since: API Level 1

Returns the char at the current position and increases the position by 1.

Returns
  • the char at the current position.
Throws
BufferUnderflowException if the position is equal or greater than limit.

public abstract char get (int index)

Since: API Level 1

Returns a char at the specified index; the position is not changed.

Parameters
index the index, must not be negative and less than limit.
Returns
  • a char at the specified index.
Throws
IndexOutOfBoundsException if index is invalid.

public CharBuffer get (char[] dst)

Since: API Level 1

Reads chars from the current position into the specified char array and increases the position by the number of chars read.

Calling this method has the same effect as get(dst, 0, dst.length).

Parameters
dst the destination char array.
Returns
  • this buffer.
Throws
BufferUnderflowException if dst.length is greater than remaining().

public final boolean hasArray ()

Since: API Level 1

Returns true if 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 ()

Since: API Level 1

Calculates this buffer's hash code from the remaining chars. The position, limit, capacity and mark don't affect the hash code.

Returns
  • the hash code calculated from the remaining chars.

public abstract boolean isDirect ()

Since: API Level 1

Indicates whether this buffer is direct. A direct buffer will try its best to take advantage of native memory APIs and it may not stay in the Java heap, so it is not affected by garbage collection.

A char buffer is direct if it is based on a byte buffer and the byte buffer is direct.

Returns
  • true if this buffer is direct, false otherwise.

public final int length ()

Since: API Level 1

Returns the number of remaining chars.

Returns
  • the number of remaining chars.

public abstract ByteOrder order ()

Since: API Level 1

Returns the byte order used by this buffer when converting chars from/to bytes.

If this buffer is not based on a byte buffer, then this always returns the platform's native byte order.

Returns
  • the byte order used by this buffer when converting chars from/to bytes.

public final CharBuffer put (String str)

Since: API Level 1

Writes all chars of the given string to the current position of this buffer, and increases the position by the length of string.

Calling this method has the same effect as put(str, 0, str.length()).

Parameters
str the string to write.
Returns
  • this buffer.
Throws
BufferOverflowException if remaining() is less than the length of string.
ReadOnlyBufferException if no changes may be made to the contents of this buffer.

public abstract CharBuffer put (char c)

Since: API Level 1

Writes the given char to the current position and increases the position by 1.

Parameters
c the char to write.
Returns
  • this buffer.
Throws
BufferOverflowException if position is equal or greater than limit.
ReadOnlyBufferException if no changes may be made to the contents of this buffer.

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

Since: API Level 1

Writes chars of the given string to the current position of this buffer, and increases the position by the number of chars written.

Parameters
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().
Returns
  • this buffer.
Throws
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 put (int index, char c)

Since: API Level 1

Writes a char to the specified index of this buffer; the position is not changed.

Parameters
index the index, must be no less than zero and less than the limit.
c the char to write.
Returns
  • this buffer.
Throws
IndexOutOfBoundsException if index is invalid.
ReadOnlyBufferException if no changes may be made to the contents of this buffer.

public CharBuffer put (CharBuffer src)

Since: API Level 1

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.

Parameters
src the source char buffer.
Returns
  • this buffer.
Throws
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 final CharBuffer put (char[] src)

Since: API Level 1

Writes chars from the given char array to the current position and increases the position by the number of chars written.

Calling this method has the same effect as put(src, 0, src.length).

Parameters
src the source char array.
Returns
  • this buffer.
Throws
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 off, int len)

Since: API Level 1

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.

Parameters
src the source char array.
off the offset of char array, must not be negative and not greater than src.length.
len the number of chars to write, must be no less than zero and no greater than src.length - off.
Returns
  • this buffer.
Throws
BufferOverflowException if remaining() is less than len.
IndexOutOfBoundsException if either off or len is invalid.
ReadOnlyBufferException if no changes may be made to the contents of this buffer.

public int read (CharBuffer target)

Since: API Level 1

Reads characters from this buffer and puts them into 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.

Parameters
target the target char buffer.
Returns
  • the number of chars copied or -1 if there are no chars left to be read from this buffer.
Throws
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.

public abstract CharBuffer slice ()

Since: API Level 1

Returns a sliced buffer that shares its content with this buffer.

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.

Returns
  • a sliced buffer that shares its content with this buffer.

public abstract CharSequence subSequence (int start, int end)

Since: API Level 1

Returns a new char buffer representing a sub-sequence of this buffer's current remaining content.

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.

Parameters
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().
Returns
  • a new char buffer represents a sub-sequence of this buffer's current remaining content.
Throws
IndexOutOfBoundsException if either start or end is invalid.

public String toString ()

Since: API Level 1

Returns a string representing the current remaining chars of this buffer.

Returns
  • a string representing the current remaining chars of this buffer.

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

Since: API Level 1

Creates a new char buffer by wrapping the given char sequence.

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.

Parameters
chseq the char sequence which the new buffer will be based on.
start the start index, must not be negative and not greater than chseq.length().
end the end index, must be no less than start and no greater than chseq.length().
Returns
  • the created char buffer.
Throws
IndexOutOfBoundsException if either start or end is invalid.

public static CharBuffer wrap (CharSequence chseq)

Since: API Level 1

Creates a new char buffer by wrapping the given char sequence.

Calling this method has the same effect as wrap(chseq, 0, chseq.length()).

Parameters
chseq the char sequence which the new buffer will be based on.
Returns
  • the created char buffer.

public static CharBuffer wrap (char[] array, int start, int len)

Since: API Level 1

Creates a new char buffer by wrapping the given char array.

The new buffer's position will be start, limit will be start + len, capacity will be the length of the array.

Parameters
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.
len the length, must not be negative and not greater than array.length - start.
Returns
  • the created char buffer.
Throws
IndexOutOfBoundsException if either start or len is invalid.

public static CharBuffer wrap (char[] array)

Since: API Level 1

Creates a new char buffer by wrapping the given char array.

Calling this method has the same effect as wrap(array, 0, array.length).

Parameters
array the char array which the new buffer will be based on.
Returns
  • the created char buffer.