/*

 * Copyright 2000-2008 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

#warn This file is preprocessed before being compiled

package java.nio;

#if[char]

import java.io.IOException;

#end[char]

/**

 * $A$ $fulltype$ buffer.

 *

 * <p> This class defines {#if[byte]?six:four} categories of operations upon

 * $fulltype$ buffers:

 *

 * <ul>

 *

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

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

 *   single $fulltype$s; </p></li>

 *

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

 *   methods that transfer contiguous sequences of $fulltype$s from this buffer

 *   into an array; {#if[!byte]?and}</p></li>

 *

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

 *   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]?&#32;and} </p></li>

 *

#if[byte]

 *

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

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

 *   write values of other primitive types, translating them to and from

 *   sequences of bytes in a particular byte order; </p></li>

 *

 *   <li><p> Methods for creating <i><a href="#views">view buffers</a></i>,

 *   which allow a byte buffer to be viewed as a buffer containing values of

 *   some other primitive type; and </p></li>

 *

#end[byte]

 *

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

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

 *   </code>slicing<code>} $a$ $fulltype$ buffer.  </p></li>

 *

 * </ul>

 *

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

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

 *

#if[byte]

 *

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

 * existing $fulltype$ array {#if[char]?or string} into a buffer.

 *

#else[byte]

 *

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

 * $fulltype$ array {#if[char]?or string} into a buffer, or by creating a

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

 *

#end[byte]

 *

#if[byte]

 *

 * <a name="direct">

 * <h4> Direct <i>vs.</i> non-direct buffers </h4>

 *

 * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>.  Given a

 * direct byte buffer, the Java virtual machine will make a best effort to

 * perform native I/O operations directly upon it.  That is, it will attempt to

 * avoid copying the buffer's content to (or from) an intermediate buffer

 * before (or after) each invocation of one of the underlying operating

 * system's native I/O operations.

 *

 * <p> A direct byte buffer may be created by invoking the {@link

 * #allocateDirect(int) allocateDirect} factory method of this class.  The

 * buffers returned by this method typically have somewhat higher allocation

 * and deallocation costs than non-direct buffers.  The contents of direct

 * buffers may reside outside of the normal garbage-collected heap, and so

 * their impact upon the memory footprint of an application might not be

 * obvious.  It is therefore recommended that direct buffers be allocated

 * primarily for large, long-lived buffers that are subject to the underlying

 * system's native I/O operations.  In general it is best to allocate direct

 * buffers only when they yield a measureable gain in program performance.

 *

 * <p> A direct byte buffer may also be created by {@link

 * java.nio.channels.FileChannel#map </code>mapping<code>} 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.

 *

 * <p> Whether a byte buffer is direct or non-direct may be determined by

 * invoking its {@link #isDirect isDirect} method.  This method is provided so

 * that explicit buffer management can be done in performance-critical code.

 *

 *

 * <a name="bin">

 * <h4> Access to binary data </h4>

 *

 * <p> This class defines methods for reading and writing values of all other

 * primitive types, except <tt>boolean</tt>.  Primitive values are translated

 * to (or from) sequences of bytes according to the buffer's current byte

 * order, which may be retrieved and modified via the {@link #order order}

 * methods.  Specific byte orders are represented by instances of the {@link

 * ByteOrder} class.  The initial order of a byte buffer is always {@link

 * ByteOrder#BIG_ENDIAN BIG_ENDIAN}.

 *

 * <p> For access to heterogeneous binary data, that is, sequences of values of

 * different types, this class defines a family of absolute and relative

 * <i>get</i> and <i>put</i> methods for each type.  For 32-bit floating-point

 * values, for example, this class defines:

 *

 * <blockquote><pre>

 * float  {@link #getFloat()}

 * float  {@link #getFloat(int) getFloat(int index)}

 *  void  {@link #putFloat(float) putFloat(float f)}

 *  void  {@link #putFloat(int,float) putFloat(int index, float f)}</pre></blockquote>

 *

 * <p> Corresponding methods are defined for the types <tt>char</tt>,

 * <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and <tt>double</tt>.  The index

 * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of

 * bytes rather than of the type being read or written.

 *

 * <a name="views">

 *

 * <p> For access to homogeneous binary data, that is, sequences of values of

 * the same type, this class defines methods that can create <i>views</i> of a

 * given byte buffer.  A <i>view buffer</i> is simply another buffer whose

 * content is backed by the byte buffer.  Changes to the byte buffer's content

 * will be visible in the view buffer, and vice versa; the two buffers'

 * position, limit, and mark values are independent.  The {@link

 * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of

 * the {@link FloatBuffer} class that is backed by the byte buffer upon which

 * the method is invoked.  Corresponding view-creation methods are defined for

 * the types <tt>char</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and

 * <tt>double</tt>.

 *

 * <p> View buffers have three important advantages over the families of

 * type-specific <i>get</i> and <i>put</i> methods described above:

 *

 * <ul>

 *

 *   <li><p> A view buffer is indexed not in terms of bytes but rather in terms

 *   of the type-specific size of its values;  </p></li>

 *

 *   <li><p> A view buffer provides relative bulk <i>get</i> and <i>put</i>

 *   methods that can transfer contiguous sequences of values between a buffer

 *   and an array or some other buffer of the same type; and  </p></li>

 *

 *   <li><p> A view buffer is potentially much more efficient because it will

 *   be direct if, and only if, its backing byte buffer is direct.  </p></li>

 *

 * </ul>

 *

 * <p> The byte order of a view buffer is fixed to be that of its byte buffer

 * at the time that the view is created.  </p>

 *

#end[byte]

*

#if[!byte]

 *

 * <p> Like a byte buffer, $a$ $fulltype$ buffer is either <a

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

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

 * be non-direct.  $A$ $fulltype$ 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

 * $a$ $fulltype$ buffer is direct may be determined by invoking the {@link

 * #isDirect isDirect} method.  </p>

 *

#end[!byte]

*

#if[char]

 *

 * <p> This class implements the {@link CharSequence} interface so that

 * character buffers may be used wherever character sequences are accepted, for

 * example in the regular-expression package <tt>{@link java.util.regex}</tt>.

 * </p>

 *

#end[char]

 *

#if[byte]

 * <h4> Invocation chaining </h4>

#end[byte]

 *

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

 *

#if[byte]

 *

 * The sequence of statements

 *

 * <blockquote><pre>

 * bb.putInt(0xCAFEBABE);

 * bb.putShort(3);

 * bb.putShort(45);</pre></blockquote>

 *

 * can, for example, be replaced by the single statement

 *

 * <blockquote><pre>

 * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote>

 *

#end[byte]

#if[char]

 *

 * The sequence of statements

 *

 * <blockquote><pre>

 * cb.put("text/");

 * cb.put(subtype);

 * cb.put("; charset=");

 * cb.put(enc);</pre></blockquote>

 *

 * can, for example, be replaced by the single statement

 *

 * <blockquote><pre>

 * cb.put("text/").put(subtype).put("; charset=").put(enc);</pre></blockquote>

 *

#end[char]

 *

 *

 * @author Mark Reinhold

 * @author JSR-51 Expert Group

 * @since 1.4

 */

public abstract class $Type$Buffer

    extends Buffer

    implements Comparable<$Type$Buffer>{#if[char]?, Appendable, CharSequence, Readable}

{

    // 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 $type$[] 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

    //

    $Type$Buffer(int mark, int pos, int lim, int cap,   // package-private

                 $type$[] 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

    //

    $Type$Buffer(int mark, int pos, int lim, int cap) { // package-private

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

    }

#if[byte]

    /**

     * Allocates a new direct $fulltype$ 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.  Whether or not it has a

     * {@link #hasArray </code>backing array<code>} is unspecified.

     *

     * @param  capacity

     *         The new buffer's capacity, in $fulltype$s

     *

     * @return  The new $fulltype$ buffer

     *

     * @throws  IllegalArgumentException

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

     */

    public static $Type$Buffer allocateDirect(int capacity) {

        return new Direct$Type$Buffer(capacity);

    }

#end[byte]

    /**

     * Allocates a new $fulltype$ 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 $fulltype$s

     *

     * @return  The new $fulltype$ buffer

     *

     * @throws  IllegalArgumentException

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

     */

    public static $Type$Buffer allocate(int capacity) {

        if (capacity < 0)

            throw new IllegalArgumentException();

        return new Heap$Type$Buffer(capacity, capacity);

    }

    /**

     * Wraps $a$ $fulltype$ array into a buffer.

     *

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

     * <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 $fulltype$ buffer

     *

     * @throws  IndexOutOfBoundsException

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

     *          parameters do not hold

     */

    public static $Type$Buffer wrap($type$[] array,

                                    int offset, int length)

    {

        try {

            return new Heap$Type$Buffer(array, offset, length);

        } catch (IllegalArgumentException x) {

            throw new IndexOutOfBoundsException();

        }

    }

    /**

     * Wraps $a$ $fulltype$ array into a buffer.

     *

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

     * <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 $fulltype$ buffer

     */

    public static $Type$Buffer wrap($type$[] array) {

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

    }

#if[char]

    /**

     * Attempts to read characters into the specified character buffer.

     * The buffer is used as a repository of characters as-is: the only

     * changes made are the results of a put operation. No flipping or

     * rewinding of the buffer is performed.

     *

     * @param target the buffer to read characters into

     * @return The number of characters added to the buffer, or

     *         -1 if this source of characters is at its end

     * @throws IOException if an I/O error occurs

     * @throws NullPointerException if target is null

     * @throws ReadOnlyBufferException if target is a read only buffer

     * @since 1.5

     */

    public int read(CharBuffer target) throws IOException {

        // Determine the number of bytes n that can be transferred

        int targetRemaining = target.remaining();

        int remaining = remaining();

        if (remaining == 0)

            return -1;

        int n = Math.min(remaining, targetRemaining);

        int limit = limit();

        // Set source limit to prevent target overflow

        if (targetRemaining < remaining)

            limit(position() + n);

        try {

            if (n > 0)

                target.put(this);

        } finally {

            limit(limit); // restore real limit

        }

        return n;

    }

    /**

     * Wraps a character sequence into a buffer.

     *

     * <p> The content of the new, read-only buffer will be the content of the

     * given character sequence.  The buffer's capacity will be

     * <tt>csq.length()</tt>, its position will be <tt>start</tt>, its limit

     * will be <tt>end</tt>, and its mark will be undefined.  </p>

     *

     * @param  csq

     *         The character sequence from which the new character buffer is to

     *         be created

     *

     * @param  start

     *         The index of the first character to be used;

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

     *         The new buffer's position will be set to this value.

     *

     * @param  end

     *         The index of the character following the last character to be

     *         used; must be no smaller than <tt>start</tt> and no larger

     *         than <tt>csq.length()</tt>.

     *         The new buffer's limit will be set to this value.

     *

     * @return  The new character buffer

     *

     * @throws  IndexOutOfBoundsException

     *          If the preconditions on the <tt>start</tt> and <tt>end</tt>

     *          parameters do not hold

     */

    public static CharBuffer wrap(CharSequence csq, int start, int end) {

        try {

            return new StringCharBuffer(csq, start, end);

        } catch (IllegalArgumentException x) {

            throw new IndexOutOfBoundsException();

        }

    }

    /**

     * Wraps a character sequence into a buffer.

     *

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

     * <tt>csq.length()</tt>, its position will be zero, and its mark will be

     * undefined.  </p>

     *

     * @param  csq

     *         The character sequence from which the new character buffer is to

     *         be created

     *

     * @return  The new character buffer

     */

    public static CharBuffer wrap(CharSequence csq) {

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

    }

#end[char]

    /**

     * Creates a new $fulltype$ 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 $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.  </p>

     *

     * @return  The new $fulltype$ buffer

     */

    public abstract $Type$Buffer slice();

    /**

     * Creates a new $fulltype$ 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 $fulltype$ buffer

     */

    public abstract $Type$Buffer duplicate();

    /**

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

     * content.

     *

     * <p> The content of the new buffer will be that of this buffer.  Changes