to top

Summary: Methods | Inherited Methods | [Expand All]

Since: API Level 1

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 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() 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 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.
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 cs, 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 charCount) 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

abstract Object	array() Returns the array that backs this buffer (optional operation).
abstract int	arrayOffset() Returns the offset into the array returned by `array` of the first element of the buffer (optional operation).
final int	capacity() Returns the capacity of this buffer.
final Buffer	clear() Clears this buffer.
final Buffer	flip() Flips this buffer.
abstract boolean	hasArray() Returns true if `array` and `arrayOffset` won't throw.
final boolean	hasRemaining() Indicates if there are elements remaining in this buffer, that is if `position < limit`.
abstract boolean	isDirect() Returns true if this is a direct buffer.
abstract boolean	isReadOnly() Indicates whether this buffer is read-only.
final int	limit() Returns the limit of this buffer.
final Buffer	limit(int newLimit) Sets the limit of this buffer.
final Buffer	mark() Marks the current position, so that the position may return to this point later by calling `reset()`.
final Buffer	position(int newPosition) Sets the position of this buffer.
final int	position() Returns the position of this buffer.
final int	remaining() Returns the number of remaining elements in this buffer, that is `limit - position`.
final Buffer	reset() Resets the position of this buffer to the `mark`.
final Buffer	rewind() Rewinds this buffer.
String	toString() Returns a string containing a concise, human-readable description of this object.

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

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 dstOffset, int charCount)

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.
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`.

Returns

this buffer.

Throws

IndexOutOfBoundsException	if either `dstOffset` or `charCount` is invalid.
BufferUnderflowException	if `charCount` 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 srcOffset, int charCount)

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.
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`.

Returns

this buffer.

Throws

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 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 printable representation of this object.

public static CharBuffer wrap (CharSequence cs, 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

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()`.

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 charCount)

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 + charCount, 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`.
charCount	the length, must not be negative and not greater than `array.length - start`.

Returns

the created char buffer.

Throws

IndexOutOfBoundsException	if either `start` or `charCount` 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.

Results

Classes

Exceptions

CharBuffer

Class Overview

Summary

Public Methods

public static CharBuffer allocate (int capacity)

Parameters

Returns

Throws

public CharBuffer append (char c)

Parameters

Returns

Throws

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

Parameters

Returns

Throws

public CharBuffer append (CharSequence csq)

Parameters

Returns

Throws

public final char[] array ()

Returns

public final int arrayOffset ()

Returns

public abstract CharBuffer asReadOnlyBuffer ()

Returns

public final char charAt (int index)

Parameters

Returns

Throws

public abstract CharBuffer compact ()

Returns

Throws

public int compareTo (CharBuffer otherBuffer)

Parameters

Returns

Throws

public abstract CharBuffer duplicate ()

Returns

public boolean equals (Object other)

Parameters

Returns

public CharBuffer get (char[] dst, int dstOffset, int charCount)

Parameters

Returns

Throws

public abstract char get ()

Returns

Throws

public abstract char get (int index)

Parameters

Returns

Throws

public CharBuffer get (char[] dst)

Parameters

Returns

Throws

public final boolean hasArray ()

public int hashCode ()

Returns

public abstract boolean isDirect ()

Returns

public final int length ()

Returns

public abstract ByteOrder order ()

Returns

public final CharBuffer put (String str)

Parameters

Returns

Throws

public abstract CharBuffer put (char c)

Parameters

Returns

Throws

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

Parameters

Returns