# Buffer

public abstract class **Buffer** extends [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)  

|---|---|---|
| Known Direct Subclasses [ByteBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ByteBuffer.html), [CharBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/CharBuffer.html), [DoubleBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/DoubleBuffer.html), [FloatBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/FloatBuffer.html), [IntBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/IntBuffer.html), [LongBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/LongBuffer.html), [ShortBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ShortBuffer.html) |---|---| | [ByteBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ByteBuffer.html) | A byte buffer. | | [CharBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/CharBuffer.html) | A char buffer. | | [DoubleBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/DoubleBuffer.html) | A double buffer. | | [FloatBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/FloatBuffer.html) | A float buffer. | | [IntBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/IntBuffer.html) | An int buffer. | | [LongBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/LongBuffer.html) | A long buffer. | | [ShortBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ShortBuffer.html) | A short buffer. | |||

|---|---|---|
| Known Indirect Subclasses [MappedByteBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/MappedByteBuffer.html) |---|---| | [MappedByteBuffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/MappedByteBuffer.html) | A direct byte buffer whose content is a memory-mapped region of a file. | |||

A container for data of a specific primitive type.

A buffer is a linear, finite sequence of elements of a specific
primitive type. Aside from its content, the essential properties of a
buffer are its capacity, limit, and position:
> A buffer's *capacity* is the number of elements it contains. The
> capacity of a buffer is never negative and never changes.
>
> A buffer's *limit* is the index of the first element that should
> not be read or written. A buffer's limit is never negative and is never
> greater than its capacity.
>
> A buffer's *position* is the index of the next element to be
> read or written. A buffer's position is never negative and is never
> greater than its limit.

There is one subclass of this class for each non-boolean primitive type.


## Transferring data

Each subclass of this class defines two categories of *get* and
*put* operations:
> *Relative* operations read or write one or more elements starting
> at the current position and then increment the position by the number of
> elements transferred. If the requested transfer exceeds the limit then a
> relative *get* operation throws a `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/BufferUnderflowException.html`
> and a relative *put* operation throws a `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/BufferOverflowException.html`; in either case, no data is transferred.
>
> *Absolute* operations take an explicit element index and do not
> affect the position. Absolute *get* and *put* operations throw
> an `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IndexOutOfBoundsException.html` if the index argument exceeds the
> limit.

Data may also, of course, be transferred in to or out of a buffer by the
I/O operations of an appropriate channel, which are always relative to the
current position.


## Marking and resetting

A buffer's *mark* is the index to which its position will be reset
when the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#reset()` method is invoked. The mark is not always
defined, but when it is defined it is never negative and is never greater
than the position. If the mark is defined then it is discarded when the
position or the limit is adjusted to a value smaller than the mark. If the
mark is not defined then invoking the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#reset()` method causes an
`https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/InvalidMarkException.html` to be thrown.


## Invariants

The following invariant holds for the mark, position, limit, and
capacity values:

> 0 \<= *mark* \<= *position* \<= *limit* \<= *capacity*

A newly-created buffer always has a position of zero and a mark that is
undefined. The initial limit may be zero, or it may be some other value
that depends upon the type of the buffer and the manner in which it is
constructed. Each element of a newly-allocated buffer is initialized
to zero.


## Clearing, flipping, and rewinding

In addition to methods for accessing the position, limit, and capacity
values and for marking and resetting, this class also defines the following
operations upon buffers:

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#clear()` makes a buffer ready for a new sequence of
  channel-read or relative *put* operations: It sets the limit to the
  capacity and the position to zero.

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#flip()` makes a buffer ready for a new sequence of
  channel-write or relative *get* operations: It sets the limit to the
  current position and then sets the position to zero.

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#rewind()` makes a buffer ready for re-reading the data that
  it already contains: It leaves the limit unchanged and sets the position
  to zero.

## Read-only buffers

Every buffer is readable, but not every buffer is writable. The
mutation methods of each buffer class are specified as *optional operations* that will throw a `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ReadOnlyBufferException.html` when
invoked upon a read-only buffer. A read-only buffer does not allow its
content to be changed, but its mark, position, and limit values are mutable.
Whether or not a buffer is read-only may be determined by invoking its
`https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#isReadOnly()` method.


## Thread safety

Buffers are not safe for use by multiple concurrent threads. If a
buffer is to be used by more than one thread then access to the buffer
should be controlled by appropriate synchronization.


## Invocation chaining

Methods in this class that do not otherwise have a value to return are
specified to return the buffer upon which they are invoked. This allows
method invocations to be chained; for example, the sequence of statements

> ```
>  b.flip();
>  b.position(23);
>  b.limit(42);
> ```
can be replaced by the single, more compact statement
>
> ```
>  b.flip().position(23).limit(42);
> ```

<br />

### Public Method Summary

|---|---|
| abstract [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [array](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#array())() Returns the array that backs this buffer *(optional operation)*. |
| abstract int | [arrayOffset](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#arrayOffset())() Returns the offset within this buffer's backing array of the first element of the buffer *(optional operation)*. |
| final int | [capacity](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#capacity())() Returns this buffer's capacity. |
| [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html) | [clear](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#clear())() Clears this buffer. |
| [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html) | [flip](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#flip())() Flips this buffer. |
| abstract boolean | [hasArray](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#hasArray())() Tells whether or not this buffer is backed by an accessible array. |
| final boolean | [hasRemaining](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#hasRemaining())() Tells whether there are any elements between the current position and the limit. |
| abstract boolean | [isDirect](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#isDirect())() Tells whether or not this buffer is [*direct*](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ByteBuffer#direct). |
| abstract boolean | [isReadOnly](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#isReadOnly())() Tells whether or not this buffer is read-only. |
| final int | [limit](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#limit())() Returns this buffer's limit. |
| [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html) | [limit](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#limit(int))(int newLimit) Sets this buffer's limit. |
| [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html) | [mark](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#mark())() Sets this buffer's mark at its position. |
| [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html) | [position](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#position(int))(int newPosition) Sets this buffer's position. |
| final int | [position](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#position())() Returns this buffer's position. |
| final int | [remaining](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#remaining())() Returns the number of elements between the current position and the limit. |
| [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html) | [reset](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#reset())() Resets this buffer's position to the previously-marked position. |
| [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html) | [rewind](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#rewind())() Rewinds this buffer. |

### Inherited Method Summary

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#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](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#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](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

## Public Methods

#### public abstract [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)
**array**
()

Returns the array that backs this
buffer *(optional operation)*.

This method is intended to allow array-backed buffers to be
passed to native code more efficiently. Concrete subclasses
provide more strongly-typed return values for this method.

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

Invoke the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#hasArray()` method before invoking this
method in order to ensure that this buffer has an accessible backing
array.

<br />

##### Returns

- The array that backs this buffer

##### Throws

| [ReadOnlyBufferException](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ReadOnlyBufferException.html) | If this buffer is backed by an array but is read-only |
| [UnsupportedOperationException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/UnsupportedOperationException.html) | If this buffer is not backed by an accessible array |
|---|---|

#### public abstract int
**arrayOffset**
()

Returns the offset within this buffer's backing array of the first
element of the buffer *(optional operation)*.

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

Invoke the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#hasArray()` method before invoking this
method in order to ensure that this buffer has an accessible backing
array.

<br />

##### Returns

- The offset within this buffer's array of the first element of the buffer

##### Throws

| [ReadOnlyBufferException](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ReadOnlyBufferException.html) | If this buffer is backed by an array but is read-only |
| [UnsupportedOperationException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/UnsupportedOperationException.html) | If this buffer is not backed by an accessible array |
|---|---|

#### public final int
**capacity**
()

Returns this buffer's capacity.

##### Returns

- The capacity of this buffer

#### public [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html)
**clear**
()

Clears this buffer. The position is set to zero, the limit is set to
the capacity, and the mark is discarded.

Invoke this method before using a sequence of channel-read or
*put* operations to fill this buffer. For example:

> ```
>  buf.clear();     // Prepare buffer for reading
>  in.read(buf);    // Read data
> ```

This method does not actually erase the data in the buffer, but it
is named as if it did because it will most often be used in situations
in which that might as well be the case.

<br />

##### Returns

- This buffer

#### public [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html)
**flip**
()

Flips this buffer. The limit is set to the current position and then
the position is set to zero. If the mark is defined then it is
discarded.

After a sequence of channel-read or *put* operations, invoke
this method to prepare for a sequence of channel-write or relative
*get* operations. For example:

> ```
>  buf.put(magic);    // Prepend header
>  in.read(buf);      // Read data into rest of buffer
>  buf.flip();        // Flip buffer
>  out.write(buf);    // Write header + data to channel
> ```

This method is often used in conjunction with the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ByteBuffer.html#compact()` method when transferring data from
one place to another.

<br />

##### Returns

- This buffer

#### public abstract boolean
**hasArray**
()

Tells whether or not this buffer is backed by an accessible
array.

If this method returns true then the `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#array()`
and `https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html#arrayOffset()` methods may safely be invoked.

<br />

##### Returns

- true if, and only if, this buffer is backed by an array and is not read-only

#### public final boolean
**hasRemaining**
()

Tells whether there are any elements between the current position and
the limit.

##### Returns

- true if, and only if, there is at least one element remaining in this buffer

#### public abstract boolean
**isDirect**
()

Tells whether or not this buffer is
[*direct*](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/ByteBuffer#direct).

##### Returns

- true if, and only if, this buffer is direct

#### public abstract boolean
**isReadOnly**
()

Tells whether or not this buffer is read-only.

##### Returns

- true if, and only if, this buffer is read-only

#### public final int
**limit**
()

Returns this buffer's limit.

##### Returns

- The limit of this buffer

#### public [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html)
**limit**
(int newLimit)

Sets this buffer's limit. If the position is larger than the new limit
then it is set to the new limit. If the mark is defined and larger than
the new limit then it is discarded.

##### Parameters

| newLimit | The new limit value; must be non-negative and no larger than this buffer's capacity |
|---|---|

##### Returns

- This buffer

##### Throws

| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | If the preconditions on newLimit do not hold |
|---|---|

#### public [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html)
**mark**
()

Sets this buffer's mark at its position.

##### Returns

- This buffer

#### public [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html)
**position**
(int newPosition)

Sets this buffer's position. If the mark is defined and larger than the
new position then it is discarded.

##### Parameters

| newPosition | The new position value; must be non-negative and no larger than the current limit |
|---|---|

##### Returns

- This buffer

##### Throws

| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | If the preconditions on newPosition do not hold |
|---|---|

#### public final int
**position**
()

Returns this buffer's position.

##### Returns

- The position of this buffer

#### public final int
**remaining**
()

Returns the number of elements between the current position and the
limit.

##### Returns

- The number of elements remaining in this buffer

#### public [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html)
**reset**
()

Resets this buffer's position to the previously-marked position.

Invoking this method neither changes nor discards the mark's
value.

<br />

##### Returns

- This buffer

##### Throws

| [InvalidMarkException](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/InvalidMarkException.html) | If the mark has not been set |
|---|---|

#### public [Buffer](https://developers.google.com/j2objc/javadoc/jre/reference/java/nio/Buffer.html)
**rewind**
()

Rewinds this buffer. The position is set to zero and the mark is
discarded.

Invoke this method before a sequence of channel-write or *get*
operations, assuming that the limit has already been set
appropriately. For example:

> ```
>  out.write(buf);    // Write remaining data
>  buf.rewind();      // Rewind buffer
>  buf.get(array);    // Copy data into array
> ```

<br />

##### Returns

- This buffer