/*

* Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved.

* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*

*/

// -- This file was mechanically generated: Do not edit! -- //

package java.nio;

/**

* An int buffer.

*

* <p> This class defines four categories of operations upon

* int buffers:

*

* <ul>

*

* <li><p> Absolute and relative {@link #get() </code><i>get</i><code>} and

* {@link #put(int) </code><i>put</i><code>} methods that read and write

* single ints; </p></li>

*

* <li><p> Relative {@link #get(int[]) </code><i>bulk get</i><code>}

* methods that transfer contiguous sequences of ints from this buffer

* into an array; and</p></li>

*

* <li><p> Relative {@link #put(int[]) </code><i>bulk put</i><code>}

* methods that transfer contiguous sequences of ints from an

* int array or some other int

* buffer into this buffer;&#32;and </p></li>

*

*

* <li><p> Methods for {@link #compact </code>compacting<code>}, {@link

* #duplicate </code>duplicating<code>}, and {@link #slice

* </code>slicing<code>} an int buffer. </p></li>

*

* </ul>

*

* <p> Int buffers can be created either by {@link #allocate

* </code><i>allocation</i><code>}, which allocates space for the buffer's

*

*

* content, by {@link #wrap(int[]) </code><i>wrapping</i><code>} an existing

* int array into a buffer, or by creating a

* <a href="ByteBuffer.html#views"><i>view</i></a> of an existing byte buffer.

*

*

*

*

* <p> Like a byte buffer, an int buffer is either <a

* href="ByteBuffer.html#direct"><i>direct</i> or <i>non-direct</i></a>. A

* int buffer created via the <tt>wrap</tt> methods of this class will

* be non-direct. An int buffer created as a view of a byte buffer will

* be direct if, and only if, the byte buffer itself is direct. Whether or not

* an int buffer is direct may be determined by invoking the {@link

* #isDirect isDirect} method. </p>

*

*

*

*

* <p> 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.

*

*

*

* @author Mark Reinhold

* @author JSR-51 Expert Group

* @since 1.4

*/

public abstract class IntBuffer

extends Buffer

implements Comparable<IntBuffer>

{

// These fields are declared here rather than in Heap-X-Buffer in order to

// reduce the number of virtual method invocations needed to access these

// values, which is especially costly when coding small buffers.

//

final int[] hb; // Non-null only for heap buffers

final int offset;

boolean isReadOnly; // Valid only for heap buffers

// Creates a new buffer with the given mark, position, limit, capacity,

// backing array, and array offset

//

IntBuffer(int mark, int pos, int lim, int cap, // package-private

int[] hb, int offset)

{

super(mark, pos, lim, cap);

this.hb = hb;

this.offset = offset;

}

// Creates a new buffer with the given mark, position, limit, and capacity

//

IntBuffer(int mark, int pos, int lim, int cap) { // package-private

this(mark, pos, lim, cap, null, 0);

}

/**

* Allocates a new int buffer.

*

* <p> 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 {@link #array

* </code>backing array<code>}, and its {@link #arrayOffset </code>array

* offset<code>} will be zero.

*

* @param capacity

* The new buffer's capacity, in ints

*

* @return The new int buffer

*

* @throws IllegalArgumentException

* If the <tt>capacity</tt> is a negative integer

*/

public static IntBuffer allocate(int capacity) {

if (capacity < 0)

throw new IllegalArgumentException();

return new HeapIntBuffer(capacity, capacity);

}

/**

* Wraps an int array into a buffer.

*

* <p> The new buffer will be backed by the given int array;

* that is, modifications to the buffer will cause the array to be modified

* and vice versa. The new buffer's capacity will be

* <tt>array.length</tt>, its position will be <tt>offset</tt>, its limit

* will be <tt>offset + length</tt>, and its mark will be undefined. Its

* {@link #array </code>backing array<code>} will be the given array, and

* its {@link #arrayOffset </code>array offset<code>} will be zero. </p>

*

* @param array

* The array that will back the new buffer

*

* @param offset

* The offset of the subarray to be used; must be non-negative and

* no larger than <tt>array.length</tt>. The new buffer's position

* will be set to this value.

*

* @param length

* The length of the subarray to be used;

* must be non-negative and no larger than

* <tt>array.length - offset</tt>.

* The new buffer's limit will be set to <tt>offset + length</tt>.

*

* @return The new int buffer

*

* @throws IndexOutOfBoundsException

* If the preconditions on the <tt>offset</tt> and <tt>length</tt>

* parameters do not hold

*/

public static IntBuffer wrap(int[] array,

int offset, int length)

{

try {

return new HeapIntBuffer(array, offset, length);

} catch (IllegalArgumentException x) {

throw new IndexOutOfBoundsException();

}

}

/**

* Wraps an int array into a buffer.

*

* <p> The new buffer will be backed by the given int 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

* <tt>array.length</tt>, its position will be zero, and its mark will be

* undefined. Its {@link #array </code>backing array<code>} will be the

* given array, and its {@link #arrayOffset </code>array offset<code>} will

* be zero. </p>

*

* @param array

* The array that will back this buffer

*

* @return The new int buffer

*/

public static IntBuffer wrap(int[] array) {

return wrap(array, 0, array.length);

}

/**

* Creates a new int buffer whose content is a shared subsequence of

* this buffer's content.

*

* <p> 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.

*

* <p> The new buffer's position will be zero, its capacity and its limit

* will be the number of ints 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. </p>

*

* @return The new int buffer

*/

public abstract IntBuffer slice();

/**

* Creates a new int buffer that shares this buffer's content.

*

* <p> 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.

*

* <p> 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. </p>

*

* @return The new int buffer

*/

public abstract IntBuffer duplicate();

/**

* Creates a new, read-only int buffer that shares this buffer's

* content.

*

* <p> 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.

*

* <p> The new buffer's capacity, limit, position, and mark values will be

* identical to those of this buffer.

*

* <p> If this buffer is itself read-only then this method behaves in

* exactly the same way as the {@link #duplicate duplicate} method. </p>

*

* @return The new, read-only int buffer

*/

public abstract IntBuffer asReadOnlyBuffer();

// -- Singleton get/put methods --

/**

* Relative <i>get</i> method. Reads the int at this buffer's

* current position, and then increments the position. </p>

*

* @return The int at the buffer's current position

*

* @throws BufferUnderflowException

* If the buffer's current position is not smaller than its limit

*/

public abstract int get();

/**

* Relative <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> Writes the given int into this buffer at the current

* position, and then increments the position. </p>

*

* @param i

* The int to be written

*

* @return This buffer

*

* @throws BufferOverflowException

* If this buffer's current position is not smaller than its limit

*

* @throws ReadOnlyBufferException

* If this buffer is read-only

*/

public abstract IntBuffer put(int i);

/**

* Absolute <i>get</i> method. Reads the int at the given

* index. </p>

*

* @param index

* The index from which the int will be read

*

* @return The int at the given index

*

* @throws IndexOutOfBoundsException

* If <tt>index</tt> is negative

* or not smaller than the buffer's limit

*/

public abstract int get(int index);

/**

* Absolute <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> Writes the given int into this buffer at the given

* index. </p>

*

* @param index

* The index at which the int will be written

*

* @param i

* The int value to be written

*

* @return This buffer

*

* @throws IndexOutOfBoundsException

* If <tt>index</tt> is negative

* or not smaller than the buffer's limit

*

* @throws ReadOnlyBufferException

* If this buffer is read-only

*/

public abstract IntBuffer put(int index, int i);

// -- Bulk get operations --

/**

* Relative bulk <i>get</i> method.

*

* <p> This method transfers ints from this buffer into the given

* destination array. If there are fewer ints remaining in the

* buffer than are required to satisfy the request, that is, if

* <tt>length</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>, then no

* ints are transferred and a {@link BufferUnderflowException} is

* thrown.

*

* <p> Otherwise, this method copies <tt>length</tt> ints 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 <tt>length</tt>.

*

* <p> In other words, an invocation of this method of the form

* <tt>src.get(dst,&nbsp;off,&nbsp;len)</tt> has exactly the same effect as

* the loop

*

* <pre>

* for (int i = off; i < off + len; i++)

* dst[i] = src.get(); </pre>

*

* except that it first checks that there are sufficient ints in

* this buffer and it is potentially much more efficient. </p>

*

* @param dst

* The array into which ints are to be written

*

* @param offset

* The offset within the array of the first int to be

* written; must be non-negative and no larger than

* <tt>dst.length</tt>

*

* @param length

* The maximum number of ints to be written to the given

* array; must be non-negative and no larger than

* <tt>dst.length - offset</tt>

*

* @return This buffer

*

* @throws BufferUnderflowException

* If there are fewer than <tt>length</tt> ints

* remaining in this buffer

*

* @throws IndexOutOfBoundsException

* If the preconditions on the <tt>offset</tt> and <tt>length</tt>

* parameters do not hold

*/

public IntBuffer get(int[] dst, int offset, int length) {

checkBounds(offset, length, dst.length);

if (length > remaining())

throw new BufferUnderflowException();

int end = offset + length;

for (int i = offset; i < end; i++)

dst[i] = get();

return this;

}

/**

* Relative bulk <i>get</i> method.

*

* <p> This method transfers ints from this buffer into the given

* destination array. An invocation of this method of the form

* <tt>src.get(a)</tt> behaves in exactly the same way as the invocation

*

* <pre>

* src.get(a, 0, a.length) </pre>

*

* @return This buffer

*

* @throws BufferUnderflowException

* If there are fewer than <tt>length</tt> ints

* remaining in this buffer

*/

public IntBuffer get(int[] dst) {

return get(dst, 0, dst.length);

}

// -- Bulk put operations --

/**

* Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> This method transfers the ints remaining in the given source

* buffer into this buffer. If there are more ints remaining in the

* source buffer than in this buffer, that is, if

* <tt>src.remaining()</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>,

* then no ints are transferred and a {@link

* BufferOverflowException} is thrown.

*

* <p> Otherwise, this method copies

* <i>n</i>&nbsp;=&nbsp;<tt>src.remaining()</tt> ints from the given

* buffer into this buffer, starting at each buffer's current position.

* The positions of both buffers are then incremented by <i>n</i>.

*

* <p> In other words, an invocation of this method of the form

* <tt>dst.put(src)</tt> has exactly the same effect as the loop

*

* <pre>

* while (src.hasRemaining())

* dst.put(src.get()); </pre>

*

* except that it first checks that there is sufficient space in this

* buffer and it is potentially much more efficient. </p>

*

* @param src

* The source buffer from which ints are to be read;

* must not be this buffer

*

* @return This buffer

*

* @throws BufferOverflowException

* If there is insufficient space in this buffer

* for the remaining ints in the source buffer

*

* @throws IllegalArgumentException

* If the source buffer is this buffer

*

* @throws ReadOnlyBufferException

* If this buffer is read-only

*/

public IntBuffer put(IntBuffer src) {

if (src == this)

throw new IllegalArgumentException();

int n = src.remaining();

if (n > remaining())

throw new BufferOverflowException();

for (int i = 0; i < n; i++)

put(src.get());

return this;

}

/**

* Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> This method transfers ints into this buffer from the given

* source array. If there are more ints to be copied from the array

* than remain in this buffer, that is, if

* <tt>length</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>, then no

* ints are transferred and a {@link BufferOverflowException} is

* thrown.

*

* <p> Otherwise, this method copies <tt>length</tt> ints 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 <tt>length</tt>.

*

* <p> In other words, an invocation of this method of the form

* <tt>dst.put(src,&nbsp;off,&nbsp;len)</tt> has exactly the same effect as

* the loop

*

* <pre>

* for (int i = off; i < off + len; i++)

* dst.put(a[i]); </pre>

*

* except that it first checks that there is sufficient space in this

* buffer and it is potentially much more efficient. </p>

*

* @param src

* The array from which ints are to be read

*

* @param offset

* The offset within the array of the first int to be read;

* must be non-negative and no larger than <tt>array.length</tt>

*

* @param length

* The number of ints to be read from the given array;

* must be non-negative and no larger than

* <tt>array.length - offset</tt>

*

* @return This buffer

*

* @throws BufferOverflowException

* If there is insufficient space in this buffer

*

* @throws IndexOutOfBoundsException

* If the preconditions on the <tt>offset</tt> and <tt>length</tt>

* parameters do not hold

*

* @throws ReadOnlyBufferException

* If this buffer is read-only

*/

public IntBuffer put(int[] src, int offset, int length) {

checkBounds(offset, length, src.length);

if (length > remaining())

throw new BufferOverflowException();

int end = offset + length;

for (int i = offset; i < end; i++)

this.put(src[i]);

return this;

}

/**

* Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> This method transfers the entire content of the given source

* int array into this buffer. An invocation of this method of the

* form <tt>dst.put(a)</tt> behaves in exactly the same way as the

* invocation

*

* <pre>

* dst.put(a, 0, a.length) </pre>

*

* @return This buffer

*

* @throws BufferOverflowException

* If there is insufficient space in this buffer

*

* @throws ReadOnlyBufferException

* If this buffer is read-only

*/

public final IntBuffer put(int[] src) {

return put(src, 0, src.length);

}

// -- Other stuff --

/**

* Tells whether or not this buffer is backed by an accessible int

* array.

*

* <p> If this method returns <tt>true</tt> then the {@link #array() array}

* and {@link #arrayOffset() arrayOffset} methods may safely be invoked.

* </p>

*

* @return <tt>true</tt> if, and only if, this buffer

* is backed by an array and is not read-only

*/

public final boolean hasArray() {

return (hb != null) && !isReadOnly;

}

/**

* Returns the int array that backs this

* buffer&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> Modifications to this buffer's content will cause the returned

* array's content to be modified, and vice versa.

*

* <p> Invoke the {@link #hasArray hasArray} method before invoking this

* method in order to ensure that this buffer has an accessible backing

* array. </p>

*

* @return The array that backs this buffer

*

* @throws ReadOnlyBufferException

* If this buffer is backed by an array but is read-only

*

* @throws UnsupportedOperationException

* If this buffer is not backed by an accessible array

*/

public final int[] array() {

if (hb == null)

throw new UnsupportedOperationException();

if (isReadOnly)

throw new ReadOnlyBufferException();

return hb;

}

/**

* Returns the offset within this buffer's backing array of the first

* element of the buffer&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> If this buffer is backed by an array then buffer position <i>p</i>

* corresponds to array index <i>p</i>&nbsp;+&nbsp;<tt>arrayOffset()</tt>.

*

* <p> Invoke the {@link #hasArray hasArray} method before invoking this

* method in order to ensure that this buffer has an accessible backing

* array. </p>

*

* @return The offset within this buffer's array

* of the first element of the buffer

*

* @throws ReadOnlyBufferException

* If this buffer is backed by an array but is read-only

*

* @throws UnsupportedOperationException

* If this buffer is not backed by an accessible array

*/

public final int arrayOffset() {

if (hb == null)

throw new UnsupportedOperationException();

if (isReadOnly)

throw new ReadOnlyBufferException();

return offset;

}

/**

* Compacts this buffer&nbsp;&nbsp;<i>(optional operation)</i>.

*

* <p> The ints between the buffer's current position and its limit,

* if any, are copied to the beginning of the buffer. That is, the

* int at index <i>p</i>&nbsp;=&nbsp;<tt>position()</tt> is copied

* to index zero, the int at index <i>p</i>&nbsp;+&nbsp;1 is copied

* to index one, and so forth until the int at index