Java Doc for X-Buffer.java in  » 6.0-JDK-Core » io-nio » java » nio » Java Source Code / Java DocumentationJava Source Code and Java Documentation

This class defines {#if[byte]?six:four} categories of operations upon $fulltype$ buffers:

• Absolute and relative $Type$Buffer.get() get and $Type$Buffer.put($type$) put methods that read and write single $fulltype$s;

• Relative $Type$Buffer.get($type$[]) bulk get methods that transfer contiguous sequences of $fulltype$s from this buffer into an array; {#if[!byte]?and}

• Relative $Type$Buffer.put($type$[]) bulk put methods that transfer contiguous sequences of $fulltype$s from $a$ $fulltype$ array{#if[char]?, a string,} or some other $fulltype$ buffer into this buffer;{#if[!byte]? and}

#if[byte]

• Absolute and relative $Type$Buffer.getChar() get and $Type$Buffer.putChar(char) put methods that read and write values of other primitive types, translating them to and from sequences of bytes in a particular byte order;

• Methods for creating view buffers, which allow a byte buffer to be viewed as a buffer containing values of some other primitive type; and

#end[byte]

• Methods for $Type$Buffer.compact compacting , $Type$Buffer.duplicate duplicating , and $Type$Buffer.sliceslicing $a$ $fulltype$ buffer.

$Fulltype$ buffers can be created either by $Type$Buffer.allocateallocation , which allocates space for the buffer's #if[byte] content, or by $Type$Buffer.wrap($type$[]) wrapping an existing $fulltype$ array {#if[char]?or string} into a buffer. #else[byte] content, by $Type$Buffer.wrap($type$[]) wrapping an existing $fulltype$ array {#if[char]?or string} into a buffer, or by creating a view of an existing byte buffer. #end[byte] #if[byte]

Direct vs. non-direct buffers

A direct byte buffer may also be created by java.nio.channels.FileChannel.map mapping a region of a file directly into memory. An implementation of the Java platform may optionally support the creation of direct byte buffers from native code via JNI. If an instance of one of these kinds of buffers refers to an inaccessible region of memory then an attempt to access that region will not change the buffer's content and will cause an unspecified exception to be thrown either at the time of the access or at some later time.

Whether a byte buffer is direct or non-direct may be determined by invoking its $Type$Buffer.isDirect isDirect method. This method is provided so that explicit buffer management can be done in performance-critical code.

Access to binary data

The new buffer's position will be zero, its limit will be its capacity, its mark will be undefined, and each of its elements will be initialized to zero.

The new buffer's position will be zero, its limit will be its capacity, its mark will be undefined, and each of its elements will be initialized to zero.

An invocation of this method of the form dst.append(csq) behaves in exactly the same way as the invocation

 dst.put(csq.toString()) 

Depending on the specification of toString for the character sequence csq, the entire sequence may not be appended.

An invocation of this method of the form dst.append(csq, start, end) when csq is not null, behaves in exactly the same way as the invocation

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

Modifications to this buffer's content will cause the returned array's content to be modified, and vice versa.

Invoke the $Type$Buffer.hasArray hasArray method before invoking this method in order to ensure that this buffer has an accessible backing array.

If this buffer is backed by an array then buffer position p corresponds to array index p + arrayOffset().

Invoke the $Type$Buffer.hasArray hasArray method before invoking this method in order to ensure that this buffer has an accessible backing array.

The content of the new buffer will be that of this buffer.

The $fulltype$s between the buffer's current position and its limit, if any, are copied to the beginning of the buffer.

The content of the new buffer will be that of this buffer.

Two $type$ buffers are equal if, and only if,

1. They have the same element type,

2. They have the same number of remaining elements, and

3. The two sequences of remaining elements, considered independently of their starting positions, are pointwise equal.

A $type$ buffer is not equal to any other type of object.

This method transfers $fulltype$s from this buffer into the given destination array.

This method transfers $fulltype$s from this buffer into the given destination array.

The hash code of a $type$ buffer depends only upon its remaining elements; that is, upon the elements from position() up to, and including, the element at limit() - 1.

Because buffer hash codes are content-dependent, it is inadvisable to use buffers as keys in hash maps or similar data structures unless it is known that their contents will not change.

When viewed as a character sequence, the length of a character buffer is simply the number of characters between the position (inclusive) and the limit (exclusive); that is, it is equivalent to remaining().

The byte order of $a$ $fulltype$ buffer created by allocation or by wrapping an existing $type$ array is the ByteOrder.nativeOrder native order of the underlying hardware.

The byte order is used when reading or writing multibyte values, and when creating buffers that are views of this byte buffer.

Writes the given $fulltype$ into this buffer at the current position, and then increments the position.

Writes the given $fulltype$ into this buffer at the given index.

This method transfers the $fulltype$s remaining in the given source buffer into this buffer.

This method transfers $fulltype$s into this buffer from the given source array.

This method transfers the entire content of the given source $fulltype$ array into this buffer.

This method transfers $fulltype$s from the given string into this buffer.

This method transfers the entire content of the given source string into this buffer.

The content of the new buffer will start at this buffer's current position.

The new buffer will share this buffer's content; that is, if the content of this buffer is mutable then modifications to one buffer will cause the other to be modified.

The first character of the resulting string will be the character at this buffer's position, while the last character will be the character at index limit() - 1.

The new buffer will be backed by the given $fulltype$ array; that is, modifications to the buffer will cause the array to be modified and vice versa.

The new buffer will be backed by the given $fulltype$ array; that is, modifications to the buffer will cause the array to be modified and vice versa.

The content of the new, read-only buffer will be the content of the given character sequence.

The content of the new, read-only buffer will be the content of the given character sequence.

The new buffer's position will be zero, its limit will be its capacity, its mark will be undefined, and each of its elements will be initialized to zero. It will have a $Type$Buffer.arraybacking array , and its $Type$Buffer.arrayOffset arrayoffset will be zero.
Parameters:
  capacity - The new buffer's capacity, in $fulltype$s The new $fulltype$ buffer
throws:
  IllegalArgumentException - If the capacity is a negative integer

The new buffer's position will be zero, its limit will be its capacity, its mark will be undefined, and each of its elements will be initialized to zero. Whether or not it has a $Type$Buffer.hasArray backing array is unspecified.
Parameters:
  capacity - The new buffer's capacity, in $fulltype$s The new $fulltype$ buffer
throws:
  IllegalArgumentException - If the capacity is a negative integer

An invocation of this method of the form dst.append(csq) behaves in exactly the same way as the invocation

 dst.put(csq.toString()) 

Depending on the specification of toString for the character sequence csq, the entire sequence may not be appended. For instance, invoking the $Type$Buffer.toStringtoString method of a character buffer will return a subsequence whose content depends upon the buffer's position and limit.
Parameters:
  csq - The character sequence to append. If csq isnull, then the four characters "null" areappended to this character buffer. This buffer
throws:
  BufferOverflowException - If there is insufficient space in this buffer
throws:
  ReadOnlyBufferException - If this buffer is read-only
since:
   1.5

An invocation of this method of the form dst.append(csq, start, end) when csq is not null, behaves in exactly the same way as the invocation

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

An invocation of this method of the form dst.append($x$) behaves in exactly the same way as the invocation

 dst.put($x$) 

Modifications to this buffer's content will cause the returned array's content to be modified, and vice versa.

Invoke the $Type$Buffer.hasArray hasArray method before invoking this method in order to ensure that this buffer has an accessible backing array.

If this buffer is backed by an array then buffer position p corresponds to array index p + arrayOffset().

Invoke the $Type$Buffer.hasArray hasArray method before invoking this method in order to ensure that this buffer has an accessible backing array.

The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer; the new buffer itself, however, will be read-only and will not allow the shared content to be modified. The two buffers' position, limit, and mark values will be independent.

The new buffer's capacity, limit, position, and mark values will be identical to those of this buffer.

If this buffer is itself read-only then this method behaves in exactly the same way as the $Type$Buffer.duplicate duplicate method.

The $fulltype$s between the buffer's current position and its limit, if any, are copied to the beginning of the buffer. That is, the $fulltype$ at index p = position() is copied to index zero, the $fulltype$ at index p + 1 is copied to index one, and so forth until the $fulltype$ at index limit() - 1 is copied to index n = limit() - 1 - p. The buffer's position is then set to n+1 and its limit is set to its capacity. The mark, if defined, is discarded.

The buffer's position is set to the number of $fulltype$s copied, rather than to zero, so that an invocation of this method can be followed immediately by an invocation of another relative put method.

Invoke this method after writing data from a buffer in case the write was incomplete. The following loop, for example, copies bytes from one channel to another via the buffer buf:

 buf.clear();          // Prepare buffer for use
 while (in.read(buf) >= 0 || buf.position != 0) {
 buf.flip();
 out.write(buf);
 buf.compact();    // In case of partial write
 }

Two $type$ buffers are compared by comparing their sequences of remaining elements lexicographically, without regard to the starting position of each sequence within its corresponding buffer.

A $type$ buffer is not comparable to any other type of object. A negative integer, zero, or a positive integer as this bufferis less than, equal to, or greater than the given buffer

The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.

The new buffer's capacity, limit, position, and mark values will be identical to those of this buffer. The new buffer will be direct if, and only if, this buffer is direct, and it will be read-only if, and only if, this buffer is read-only.

Two $type$ buffers are equal if, and only if,

1. They have the same element type,

2. They have the same number of remaining elements, and

3. The two sequences of remaining elements, considered independently of their starting positions, are pointwise equal.

A $type$ buffer is not equal to any other type of object.

This method transfers $fulltype$s from this buffer into the given destination array. If there are fewer $fulltype$s remaining in the buffer than are required to satisfy the request, that is, if length > remaining(), then no $fulltype$s are transferred and a BufferUnderflowException is thrown.

Otherwise, this method copies length $fulltype$s from this buffer into the given array, starting at the current position of this buffer and at the given offset in the array. The position of this buffer is then incremented by length.

In other words, an invocation of this method of the form src.get(dst, off, len) has exactly the same effect as the loop

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

This method transfers $fulltype$s from this buffer into the given destination array. An invocation of this method of the form src.get(a) behaves in exactly the same way as the invocation

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

If this method returns true then the $Type$Buffer.array() array and $Type$Buffer.arrayOffset() arrayOffset methods may safely be invoked.

The hash code of a $type$ buffer depends only upon its remaining elements; that is, upon the elements from position() up to, and including, the element at limit() - 1.

Because buffer hash codes are content-dependent, it is inadvisable to use buffers as keys in hash maps or similar data structures unless it is known that their contents will not change.

When viewed as a character sequence, the length of a character buffer is simply the number of characters between the position (inclusive) and the limit (exclusive); that is, it is equivalent to remaining().

The byte order of $a$ $fulltype$ buffer created by allocation or by wrapping an existing $type$ array is the ByteOrder.nativeOrder native order of the underlying hardware. The byte order of $a$ $fulltype$ buffer created as a view of a byte buffer is that of the byte buffer at the moment that the view is created.

The byte order is used when reading or writing multibyte values, and when creating buffers that are views of this byte buffer. The order of a newly-created byte buffer is always ByteOrder.BIG_ENDIANBIG_ENDIAN .

Writes the given $fulltype$ into this buffer at the current position, and then increments the position.

Writes the given $fulltype$ into this buffer at the given index.

This method transfers the $fulltype$s remaining in the given source buffer into this buffer. If there are more $fulltype$s remaining in the source buffer than in this buffer, that is, if src.remaining() > remaining(), then no $fulltype$s are transferred and a BufferOverflowException is thrown.

Otherwise, this method copies n = src.remaining() $fulltype$s from the given buffer into this buffer, starting at each buffer's current position. The positions of both buffers are then incremented by n.

In other words, an invocation of this method of the form dst.put(src) has exactly the same effect as the loop

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

This method transfers $fulltype$s into this buffer from the given source array. If there are more $fulltype$s to be copied from the array than remain in this buffer, that is, if length > remaining(), then no $fulltype$s are transferred and a BufferOverflowException is thrown.

Otherwise, this method copies length $fulltype$s from the given array into this buffer, starting at the given offset in the array and at the current position of this buffer. The position of this buffer is then incremented by length.

In other words, an invocation of this method of the form dst.put(src, off, len) has exactly the same effect as the loop

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

This method transfers the entire content of the given source $fulltype$ array into this buffer. An invocation of this method of the form dst.put(a) behaves in exactly the same way as the invocation

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

This method transfers $fulltype$s from the given string into this buffer. If there are more $fulltype$s to be copied from the string than remain in this buffer, that is, if end - start > remaining(), then no $fulltype$s are transferred and a BufferOverflowException is thrown.

Otherwise, this method copies n = end - start $fulltype$s from the given string into this buffer, starting at the given start index and at the current position of this buffer. The position of this buffer is then incremented by n.

In other words, an invocation of this method of the form dst.put(src, start, end) has exactly the same effect as the loop

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

This method transfers the entire content of the given source string into this buffer. An invocation of this method of the form dst.put(s) behaves in exactly the same way as the invocation

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

The content of the new buffer will start at this buffer's current position. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.

The new buffer's position will be zero, its capacity and its limit will be the number of $fulltype$s remaining in this buffer, and its mark will be undefined. The new buffer will be direct if, and only if, this buffer is direct, and it will be read-only if, and only if, this buffer is read-only.

The new buffer will share this buffer's content; that is, if the content of this buffer is mutable then modifications to one buffer will cause the other to be modified. The new buffer's capacity will be that of this buffer, its position will be position() + start, and its limit will be position() + end. The new buffer will be direct if, and only if, this buffer is direct, and it will be read-only if, and only if, this buffer is read-only.

The first character of the resulting string will be the character at this buffer's position, while the last character will be the character at index limit() - 1. Invoking this method does not change the buffer's position.

The new buffer will be backed by the given $fulltype$ array; that is, modifications to the buffer will cause the array to be modified and vice versa. The new buffer's capacity will be array.length, its position will be offset, its limit will be offset + length, and its mark will be undefined. Its $Type$Buffer.array backing array will be the given array, and its $Type$Buffer.arrayOffset array offset will be zero.

The new buffer will be backed by the given $fulltype$ array; that is, modifications to the buffer will cause the array to be modified and vice versa. The new buffer's capacity and limit will be array.length, its position will be zero, and its mark will be undefined. Its $Type$Buffer.array backing array will be the given array, and its $Type$Buffer.arrayOffset array offset will be zero.

The content of the new, read-only buffer will be the content of the given character sequence. The buffer's capacity will be csq.length(), its position will be start, its limit will be end, and its mark will be undefined.

The content of the new, read-only buffer will be the content of the given character sequence. The new buffer's capacity and limit will be csq.length(), its position will be zero, and its mark will be undefined.