java.nio
Class CharBuffer

java.lang.Object
  extended by java.nio.Buffer
      extended by java.nio.CharBuffer
All Implemented Interfaces:
Appendable, CharSequence, Comparable<CharBuffer>, Readable

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

Since:
1.4

Method Summary
static CharBuffer allocate(int capacity)
          Allocates a new CharBuffer object with a given capacity.
 CharBuffer append(char c)
          Appends the Unicode character, c, to this Appendable object.
 CharBuffer append(CharSequence cs)
          Appends the specified sequence of Unicode characters to this Appendable object.
 CharBuffer append(CharSequence cs, int start, int end)
          Appends the specified subsequence of Unicode characters to this Appendable object, starting and ending at the specified positions within the sequence.
 char[] array()
          Returns the char array that backs this buffer.
 int arrayOffset()
          Returns the offset within this buffer's backing array of the first element.
abstract  CharBuffer asReadOnlyBuffer()
          Creates a new read-only CharBuffer that shares this buffer's content.
 char charAt(int index)
          Returns the character at position() + index.
abstract  CharBuffer compact()
          Compacts this buffer.
 int compareTo(CharBuffer other)
          Compares two CharBuffer objects.
abstract  CharBuffer duplicate()
          Creates a new CharBuffer that shares this buffer's content.
 boolean equals(Object obj)
          Checks if this buffer is equal to obj.
abstract  char get()
          Reads the char at this buffer's current position, and then increments the position.
 CharBuffer get(char[] dst)
          This method transfers chars from this buffer into the given destination array.
 CharBuffer get(char[] dst, int offset, int length)
          This method transfers chars from this buffer into the given destination array.
abstract  char get(int index)
          Absolute get method.
 boolean hasArray()
          Tells whether ot not this buffer is backed by an accessible char array.
 int hashCode()
          Calculates a hash code for this buffer.
abstract  boolean isDirect()
          Tells wether or not this buffer is direct.
 int length()
          Returns the length of the remaining chars in this buffer.
abstract  ByteOrder order()
          Returns the byte order of this buffer.
abstract  CharBuffer put(char b)
          Writes the char at this buffer's current position, and then increments the position.
 CharBuffer put(char[] src)
          Writes the content of the the char array src into the buffer.
 CharBuffer put(char[] src, int offset, int length)
          Writes the content of the the char array src into the buffer.
 CharBuffer put(CharBuffer src)
          Writes the content of the the CharBUFFER src into the buffer.
abstract  CharBuffer put(int index, char b)
          Absolute put method.
 CharBuffer put(String str)
          Relative put method.
 CharBuffer put(String str, int start, int length)
          Relative put method.
 int read(CharBuffer buffer)
          Adds the character data supplied by this Readable to the specified character buffer.
abstract  CharBuffer slice()
          Creates a new CharBuffer whose content is a shared subsequence of this buffer's content.
abstract  CharSequence subSequence(int start, int length)
          Creates a new character buffer that represents the specified subsequence of this buffer, relative to the current position.
 String toString()
          Returns the remaining content of the buffer as a string.
static CharBuffer wrap(char[] array)
          Wraps a char array into a CharBuffer object.
static CharBuffer wrap(char[] array, int offset, int length)
          Wraps a char array into a CharBuffer object.
static CharBuffer wrap(CharSequence seq)
          Wraps a character sequence into a CharBuffer object.
static CharBuffer wrap(CharSequence seq, int start, int end)
          Wraps a character sequence into a CharBuffer object.
 
Methods inherited from class java.nio.Buffer
capacity, clear, flip, hasRemaining, isReadOnly, limit, limit, mark, position, position, remaining, reset, rewind
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

allocate

public static CharBuffer allocate(int capacity)
Allocates a new CharBuffer object with a given capacity.


wrap

public static final CharBuffer wrap(char[] array,
                                    int offset,
                                    int length)
Wraps a char array into a CharBuffer object.

Parameters:
array - the array to wrap
offset - the offset of the region in the array to wrap
length - the length of the region in the array to wrap
Returns:
a new CharBuffer object
Throws:
IndexOutOfBoundsException - If the preconditions on the offset and length parameters do not hold

wrap

public static final CharBuffer wrap(CharSequence seq)
Wraps a character sequence into a CharBuffer object.

Parameters:
seq - the sequence to wrap
Returns:
a new CharBuffer object

wrap

public static final CharBuffer wrap(CharSequence seq,
                                    int start,
                                    int end)
Wraps a character sequence into a CharBuffer object.

Parameters:
seq - the sequence to wrap
start - the index of the first character to wrap
end - the index of the first character not to wrap
Returns:
a new CharBuffer object
Throws:
IndexOutOfBoundsException - If the preconditions on the offset and length parameters do not hold

wrap

public static final CharBuffer wrap(char[] array)
Wraps a char array into a CharBuffer object.

Parameters:
array - the array to wrap
Returns:
a new CharBuffer object

get

public CharBuffer get(char[] dst,
                      int offset,
                      int length)
This method transfers chars from this buffer into the given destination array. Before the transfer, it checks if there are fewer than length chars remaining in this buffer.

Parameters:
dst - The destination array
offset - The offset within the array of the first char to be written; must be non-negative and no larger than dst.length.
length - The maximum number of bytes to be written to the given array; must be non-negative and no larger than dst.length - offset.
Throws:
BufferUnderflowException - If there are fewer than length chars remaining in this buffer.
IndexOutOfBoundsException - If the preconditions on the offset and length parameters do not hold.

read

public int read(CharBuffer buffer)
         throws IOException
Description copied from interface: Readable
Adds the character data supplied by this Readable to the specified character buffer. This method simply places each character into the buffer as supplied, using put(), without flipping or rewinding.

Specified by:
read in interface Readable
Parameters:
buffer - the buffer to place the character data in.
Returns:
the number of char values placed in the buffer, or -1 if no more characters are available.
Throws:
IOException - if an I/O error occurs.
Since:
1.5

get

public CharBuffer get(char[] dst)
This method transfers chars from this buffer into the given destination array.

Parameters:
dst - The byte array to write into.
Throws:
BufferUnderflowException - If there are fewer than dst.length chars remaining in this buffer.

put

public CharBuffer put(CharBuffer src)
Writes the content of the the CharBUFFER src into the buffer. Before the transfer, it checks if there is fewer than src.remaining() space remaining in this buffer.

Parameters:
src - The source data.
Throws:
BufferOverflowException - If there is insufficient space in this buffer for the remaining chars in the source buffer.
IllegalArgumentException - If the source buffer is this buffer.
ReadOnlyBufferException - If this buffer is read-only.

put

public CharBuffer put(char[] src,
                      int offset,
                      int length)
Writes the content of the the char array src into the buffer. Before the transfer, it checks if there is fewer than length space remaining in this buffer.

Parameters:
src - The array to copy into the buffer.
offset - The offset within the array of the first byte to be read; must be non-negative and no larger than src.length.
length - The number of bytes to be read from the given array; must be non-negative and no larger than src.length - offset.
Throws:
BufferOverflowException - If there is insufficient space in this buffer for the remaining chars in the source array.
IndexOutOfBoundsException - If the preconditions on the offset and length parameters do not hold
ReadOnlyBufferException - If this buffer is read-only.

put

public final CharBuffer put(char[] src)
Writes the content of the the char array src into the buffer.

Parameters:
src - The array to copy into the buffer.
Throws:
BufferOverflowException - If there is insufficient space in this buffer for the remaining chars in the source array.
ReadOnlyBufferException - If this buffer is read-only.

hasArray

public final boolean hasArray()
Tells whether ot not this buffer is backed by an accessible char array.


array

public final char[] array()
Returns the char array that backs this buffer.

Throws:
ReadOnlyBufferException - If this buffer is read-only.
UnsupportedOperationException - If this buffer is not backed by an accessible array.

arrayOffset

public final int arrayOffset()
Returns the offset within this buffer's backing array of the first element.

Throws:
ReadOnlyBufferException - If this buffer is read-only.
UnsupportedOperationException - If this buffer is not backed by an accessible array.

hashCode

public int hashCode()
Calculates a hash code for this buffer. This is done with int arithmetic, where ** represents exponentiation, by this formula:
s[position()] + 31 + (s[position()+1] + 30)*31**1 + ... + (s[limit()-1]+30)*31**(limit()-1). Where s is the buffer data. Note that the hashcode is dependent on buffer content, and therefore is not useful if the buffer content may change.

Overrides:
hashCode in class Object
Returns:
the hash code for this Object
See Also:
Object.equals(Object), System.identityHashCode(Object)

equals

public boolean equals(Object obj)
Checks if this buffer is equal to obj.

Overrides:
equals in class Object
Parameters:
obj - the Object to compare to
Returns:
whether this Object is semantically equal to another
See Also:
Object.hashCode()

compareTo

public int compareTo(CharBuffer other)
Compares two CharBuffer objects.

Specified by:
compareTo in interface Comparable<CharBuffer>
Parameters:
other - the object to be compared
Returns:
an integer describing the comparison
Throws:
ClassCastException - If obj is not an object derived from CharBuffer.

order

public abstract ByteOrder order()
Returns the byte order of this buffer.


get

public abstract char get()
Reads the char at this buffer's current position, and then increments the position.

Throws:
BufferUnderflowException - If there are no remaining chars in this buffer.

put

public abstract CharBuffer put(char b)
Writes the char at this buffer's current position, and then increments the position.

Throws:
BufferOverflowException - If there no remaining chars in this buffer.
ReadOnlyBufferException - If this buffer is read-only.

get

public abstract char get(int index)
Absolute get method.

Throws:
IndexOutOfBoundsException - If index is negative or not smaller than the buffer's limit.

put

public abstract CharBuffer put(int index,
                               char b)
Absolute put method.

Throws:
IndexOutOfBoundsException - If index is negative or not smaller than the buffer's limit.
ReadOnlyBufferException - If this buffer is read-only.

compact

public abstract CharBuffer compact()
Compacts this buffer.

Throws:
ReadOnlyBufferException - If this buffer is read-only.

isDirect

public abstract boolean isDirect()
Tells wether or not this buffer is direct.


slice

public abstract CharBuffer slice()
Creates a new CharBuffer whose content is a shared subsequence of this buffer's content.


duplicate

public abstract CharBuffer duplicate()
Creates a new CharBuffer that shares this buffer's content.


asReadOnlyBuffer

public abstract CharBuffer asReadOnlyBuffer()
Creates a new read-only CharBuffer that shares this buffer's content.


toString

public String toString()
Returns the remaining content of the buffer as a string.

Specified by:
toString in interface CharSequence
Overrides:
toString in class Object
Returns:
the String representing this Object, which may be null
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

length

public final int length()
Returns the length of the remaining chars in this buffer.

Specified by:
length in interface CharSequence
Returns:
the sequence length

subSequence

public abstract CharSequence subSequence(int start,
                                         int length)
Creates a new character buffer that represents the specified subsequence of this buffer, relative to the current position.

Specified by:
subSequence in interface CharSequence
Parameters:
start - the start index (inclusive)
length - the end index (exclusive)
Returns:
a subsequence of this
Throws:
IndexOutOfBoundsException - If the preconditions on start and end do not hold.

put

public CharBuffer put(String str,
                      int start,
                      int length)
Relative put method.

Throws:
BufferOverflowException - If there is insufficient space in this buffer.
IndexOutOfBoundsException - If the preconditions on the start and end parameters do not hold.
ReadOnlyBufferException - If this buffer is read-only.

put

public final CharBuffer put(String str)
Relative put method.

Throws:
BufferOverflowException - If there is insufficient space in this buffer.
ReadOnlyBufferException - If this buffer is read-only.

charAt

public final char charAt(int index)
Returns the character at position() + index.

Specified by:
charAt in interface CharSequence
Parameters:
index - the index to retrieve from
Returns:
the character at that location
Throws:
IndexOutOfBoundsException - If index is negative not smaller than remaining().

append

public CharBuffer append(char c)
Description copied from interface: Appendable
Appends the Unicode character, c, to this Appendable object.

Specified by:
append in interface Appendable
Parameters:
c - the character to append.
Returns:
a reference to this object.
Since:
1.5

append

public CharBuffer append(CharSequence cs)
Description copied from interface: Appendable
Appends the specified sequence of Unicode characters to this Appendable object. The entire sequence may not be appended, if constrained by the underlying implementation. For example, a buffer may reach its size limit before the entire sequence is appended.

Specified by:
append in interface Appendable
Parameters:
cs - the character sequence to append. If seq is null, then the string "null" (the string representation of null) is appended.
Returns:
a reference to this object.
Since:
1.5

append

public CharBuffer append(CharSequence cs,
                         int start,
                         int end)
Description copied from interface: Appendable
Appends the specified subsequence of Unicode characters to this Appendable object, starting and ending at the specified positions within the sequence. The entire sequence may not be appended, if constrained by the underlying implementation. For example, a buffer may reach its size limit before the entire sequence is appended. The behaviour of this method matches the behaviour of append(seq.subSequence(start,end)) when the sequence is not null.

Specified by:
append in interface Appendable
Parameters:
cs - the character sequence to append. If seq is null, then the string "null" (the string representation of null) is appended.
start - the index of the first Unicode character to use from the sequence.
end - the index of the last Unicode character to use from the sequence.
Returns:
a reference to this object.
Since:
1.5