1 /*

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

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

     4  *

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

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

     7  * published by the Free Software Foundation.  Sun designates this

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

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

    10  *

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

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

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

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

    15  * accompanied this code).

    16  *

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

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

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

    20  *

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

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

    23  * have any questions.

    24  */

    25 

    26 #warn This file is preprocessed before being compiled

    27 

    28 package java.nio;

    29 

    30 #if[char]

    31 import java.io.IOException;

    32 #end[char]

    33 

    34 /**

    35  * $A$ $fulltype$ buffer.

    36  *

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

    38  * $fulltype$ buffers:

    39  *

    40  * <ul>

    41  *

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

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

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

    45  *

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

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

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

    49  *

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

    51  *   methods that transfer contiguous sequences of $fulltype$s from $a$

    52  *   $fulltype$ array{#if[char]?, a string,} or some other $fulltype$

    53  *   buffer into this buffer;{#if[!byte]?&#32;and} </p></li>

    54  *

    55 #if[byte]

    56  *

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

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

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

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

    61  *

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

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

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

    65  *

    66 #end[byte]

    67  *

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

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

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

    71  *

    72  * </ul>

    73  *

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

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

    76  *

    77 #if[byte]

    78  *

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

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

    81  *

    82 #else[byte]

    83  *

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

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

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

    87  *

    88 #end[byte]

    89  *

    90 #if[byte]

    91  *

    92  * <a name="direct">

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

    94  *

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

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

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

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

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

   100  * system's native I/O operations.

   101  *

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

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

   104  * buffers returned by this method typically have somewhat higher allocation

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

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

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

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

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

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

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

   112  *

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

   114  * java.nio.channels.FileChannel#map </code>mapping<code>} a region of a file

   115  * directly into memory.  An implementation of the Java platform may optionally

   116  * support the creation of direct byte buffers from native code via JNI.  If an

   117  * instance of one of these kinds of buffers refers to an inaccessible region

   118  * of memory then an attempt to access that region will not change the buffer's

   119  * content and will cause an unspecified exception to be thrown either at the

   120  * time of the access or at some later time.

   121  *

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

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

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

   125  *

   126  *

   127  * <a name="bin">

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

   129  *

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

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

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

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

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

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

   136  * ByteOrder#BIG_ENDIAN BIG_ENDIAN}.

   137  *

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

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

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

   141  * values, for example, this class defines:

   142  *

   143  * <blockquote><pre>

   144  * float  {@link #getFloat()}

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

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

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

   148  *

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

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

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

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

   153  *

   154  * <a name="views">

   155  *

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

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

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

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

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

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

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

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

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

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

   166  * <tt>double</tt>.

   167  *

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

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

   170  *

   171  * <ul>

   172  *

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

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

   175  *

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

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

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

   179  *

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

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

   182  *

   183  * </ul>

   184  *

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

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

   187  *

   188 #end[byte]

   189 *

   190 #if[!byte]

   191  *

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

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

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

   195  * be non-direct.  $A$ $fulltype$ buffer created as a view of a byte buffer will

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

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

   198  * #isDirect isDirect} method.  </p>

   199  *

   200 #end[!byte]

   201 *

   202 #if[char]

   203  *

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

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

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

   207  * </p>

   208  *

   209 #end[char]

   210  *

   211 #if[byte]

   212  * <h4> Invocation chaining </h4>

   213 #end[byte]

   214  *

   215  * <p> Methods in this class that do not otherwise have a value to return are

   216  * specified to return the buffer upon which they are invoked.  This allows

   217  * method invocations to be chained.

   218  *

   219 #if[byte]

   220  *

   221  * The sequence of statements

   222  *

   223  * <blockquote><pre>

   224  * bb.putInt(0xCAFEBABE);

   225  * bb.putShort(3);

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

   227  *

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

   229  *

   230  * <blockquote><pre>

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

   232  *

   233 #end[byte]

   234 #if[char]

   235  *

   236  * The sequence of statements

   237  *

   238  * <blockquote><pre>

   239  * cb.put("text/");

   240  * cb.put(subtype);

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

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

   243  *

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

   245  *

   246  * <blockquote><pre>

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

   248  *

   249 #end[char]

   250  *

   251  *

   252  * @author Mark Reinhold

   253  * @author JSR-51 Expert Group

   254  * @since 1.4

   255  */

   256 

   257 public abstract class $Type$Buffer

   258     extends Buffer

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

   260 {

   261 

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

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

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

   265     //

   266     final $type$[] hb;                  // Non-null only for heap buffers

   267     final int offset;

   268     boolean isReadOnly;                 // Valid only for heap buffers

   269 

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

   271     // backing array, and array offset

   272     //

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

   274                  $type$[] hb, int offset)

   275     {

   276         super(mark, pos, lim, cap);

   277         this.hb = hb;

   278         this.offset = offset;

   279     }

   280 

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

   282     //

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

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

   285     }

   286 

   287 #if[byte]

   288 

   289     /**

   290      * Allocates a new direct $fulltype$ buffer.

   291      *

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

   293      * capacity, its mark will be undefined, and each of its elements will be

   294      * initialized to zero.  Whether or not it has a

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

   296      *

   297      * @param  capacity

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

   299      *

   300      * @return  The new $fulltype$ buffer

   301      *

   302      * @throws  IllegalArgumentException

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

   304      */

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

   306         return new Direct$Type$Buffer(capacity);

   307     }

   308 

   309 #end[byte]

   310 

   311     /**

   312      * Allocates a new $fulltype$ buffer.

   313      *

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

   315      * capacity, its mark will be undefined, and each of its elements will be

   316      * initialized to zero.  It will have a {@link #array

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

   318      * offset<code>} will be zero.

   319      *

   320      * @param  capacity

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

   322      *

   323      * @return  The new $fulltype$ buffer

   324      *

   325      * @throws  IllegalArgumentException

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

   327      */

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

   329         if (capacity < 0)

   330             throw new IllegalArgumentException();

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

   332     }

   333 

   334     /**

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

   336      *

   337      * <p> The new buffer will be backed by the given $fulltype$ array;

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

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

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

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

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

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

   344      *

   345      * @param  array

   346      *         The array that will back the new buffer

   347      *

   348      * @param  offset

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

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

   351      *         will be set to this value.

   352      *

   353      * @param  length

   354      *         The length of the subarray to be used;

   355      *         must be non-negative and no larger than

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

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

   358      *

   359      * @return  The new $fulltype$ buffer

   360      *

   361      * @throws  IndexOutOfBoundsException

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

   363      *          parameters do not hold

   364      */

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

   366                                     int offset, int length)

   367     {

   368         try {

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

   370         } catch (IllegalArgumentException x) {

   371             throw new IndexOutOfBoundsException();

   372         }

   373     }

   374 

   375     /**

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

   377      *

   378      * <p> The new buffer will be backed by the given $fulltype$ array;

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

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

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

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

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

   384      * be zero.  </p>

   385      *

   386      * @param  array

   387      *         The array that will back this buffer

   388      *

   389      * @return  The new $fulltype$ buffer

   390      */

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

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

   393     }

   394 

   395 #if[char]

   396 

   397     /**

   398      * Attempts to read characters into the specified character buffer.

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

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

   401      * rewinding of the buffer is performed.

   402      *

   403      * @param target the buffer to read characters into

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

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

   406      * @throws IOException if an I/O error occurs

   407      * @throws NullPointerException if target is null

   408      * @throws ReadOnlyBufferException if target is a read only buffer

   409      * @since 1.5

   410      */

   411     public int read(CharBuffer target) throws IOException {

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

   413         int targetRemaining = target.remaining();

   414         int remaining = remaining();

   415         if (remaining == 0)

   416             return -1;

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

   418         int limit = limit();

   419         // Set source limit to prevent target overflow

   420         if (targetRemaining < remaining)

   421             limit(position() + n);

   422         try {

   423             if (n > 0)

   424                 target.put(this);

   425         } finally {

   426             limit(limit); // restore real limit

   427         }

   428         return n;

   429     }

   430 

   431     /**

   432      * Wraps a character sequence into a buffer.

   433      *

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

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

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

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

   438      *

   439      * @param  csq

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

   441      *         be created

   442      *

   443      * @param  start

   444      *         The index of the first character to be used;

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

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

   447      *

   448      * @param  end

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

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

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

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

   453      *

   454      * @return  The new character buffer

   455      *

   456      * @throws  IndexOutOfBoundsException

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

   458      *          parameters do not hold

   459      */

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

   461         try {

   462             return new StringCharBuffer(csq, start, end);

   463         } catch (IllegalArgumentException x) {

   464             throw new IndexOutOfBoundsException();

   465         }

   466     }

   467 

   468     /**

   469      * Wraps a character sequence into a buffer.

   470      *

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

   472      * given character sequence.  The new buffer's capacity and limit will be

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

   474      * undefined.  </p>

   475      *

   476      * @param  csq

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

   478      *         be created

   479      *

   480      * @return  The new character buffer

   481      */

   482     public static CharBuffer wrap(CharSequence csq) {

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

   484     }

   485 

   486 #end[char]

   487 

   488     /**

   489      * Creates a new $fulltype$ buffer whose content is a shared subsequence of

   490      * this buffer's content.

   491      *

   492      * <p> The content of the new buffer will start at this buffer's current

   493      * position.  Changes to this buffer's content will be visible in the new

   494      * buffer, and vice versa; the two buffers' position, limit, and mark

   495      * values will be independent.

   496      *

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

   498      * will be the number of $fulltype$s remaining in this buffer, and its mark

   499      * will be undefined.  The new buffer will be direct if, and only if, this

   500      * buffer is direct, and it will be read-only if, and only if, this buffer

   501      * is read-only.  </p>

   502      *

   503      * @return  The new $fulltype$ buffer

   504      */

   505     public abstract $Type$Buffer slice();

   506 

   507     /**

   508      * Creates a new $fulltype$ buffer that shares this buffer's content.

   509      *

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

   511      * to this buffer's content will be visible in the new buffer, and vice

   512      * versa; the two buffers' position, limit, and mark values will be

   513      * independent.

   514      *

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

   516      * identical to those of this buffer.  The new buffer will be direct if,

   517      * and only if, this buffer is direct, and it will be read-only if, and

   518      * only if, this buffer is read-only.  </p>

   519      *

   520      * @return  The new $fulltype$ buffer

   521      */

   522     public abstract $Type$Buffer duplicate();

   523 

   524     /**

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

   526      * content.

   527      *

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

   529      * to this buffer's content will be visible in the new buffer; the new

   530      * buffer itself, however, will be read-only and will not allow the shared

   531      * content to be modified.  The two buffers' position, limit, and mark

   532      * values will be independent.

   533      *

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

   535      * identical to those of this buffer.

   536      *

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

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

   539      *

   540      * @return  The new, read-only $fulltype$ buffer

   541      */

   542     public abstract $Type$Buffer asReadOnlyBuffer();

   543 

   544 

   545     // -- Singleton get/put methods --

   546 

   547     /**

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

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

   550      *

   551      * @return  The $fulltype$ at the buffer's current position

   552      *

   553      * @throws  BufferUnderflowException

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

   555      */

   556     public abstract $type$ get();

   557 

   558     /**

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

   560      *

   561      * <p> Writes the given $fulltype$ into this buffer at the current

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

   563      *

   564      * @param  $x$

   565      *         The $fulltype$ to be written

   566      *

   567      * @return  This buffer

   568      *

   569      * @throws  BufferOverflowException

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

   571      *

   572      * @throws  ReadOnlyBufferException

   573      *          If this buffer is read-only

   574      */

   575     public abstract $Type$Buffer put($type$ $x$);

   576 

   577     /**

   578      * Absolute <i>get</i> method.  Reads the $fulltype$ at the given

   579      * index. </p>

   580      *

   581      * @param  index

   582      *         The index from which the $fulltype$ will be read

   583      *

   584      * @return  The $fulltype$ at the given index

   585      *

   586      * @throws  IndexOutOfBoundsException

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

   588      *          or not smaller than the buffer's limit

   589      */

   590     public abstract $type$ get(int index);

   591 

   592     /**

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

   594      *

   595      * <p> Writes the given $fulltype$ into this buffer at the given

   596      * index. </p>

   597      *

   598      * @param  index

   599      *         The index at which the $fulltype$ will be written

   600      *

   601      * @param  $x$

   602      *         The $fulltype$ value to be written

   603      *

   604      * @return  This buffer

   605      *

   606      * @throws  IndexOutOfBoundsException

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

   608      *          or not smaller than the buffer's limit

   609      *

   610      * @throws  ReadOnlyBufferException

   611      *          If this buffer is read-only

   612      */

   613     public abstract $Type$Buffer put(int index, $type$ $x$);

   614 

   615 

   616     // -- Bulk get operations --

   617 

   618     /**

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

   620      *

   621      * <p> This method transfers $fulltype$s from this buffer into the given

   622      * destination array.  If there are fewer $fulltype$s remaining in the

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

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

   625      * $fulltype$s are transferred and a {@link BufferUnderflowException} is

   626      * thrown.

   627      *

   628      * <p> Otherwise, this method copies <tt>length</tt> $fulltype$s from this

   629      * buffer into the given array, starting at the current position of this

   630      * buffer and at the given offset in the array.  The position of this

   631      * buffer is then incremented by <tt>length</tt>.

   632      *

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

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

   635      * the loop

   636      *

   637      * <pre>

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

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

   640      *

   641      * except that it first checks that there are sufficient $fulltype$s in

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

   643      *

   644      * @param  dst

   645      *         The array into which $fulltype$s are to be written

   646      *

   647      * @param  offset

   648      *         The offset within the array of the first $fulltype$ to be

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

   650      *         <tt>dst.length</tt>

   651      *

   652      * @param  length

   653      *         The maximum number of $fulltype$s to be written to the given

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

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

   656      *

   657      * @return  This buffer

   658      *

   659      * @throws  BufferUnderflowException

   660      *          If there are fewer than <tt>length</tt> $fulltype$s

   661      *          remaining in this buffer

   662      *

   663      * @throws  IndexOutOfBoundsException

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

   665      *          parameters do not hold

   666      */

   667     public $Type$Buffer get($type$[] dst, int offset, int length) {

   668         checkBounds(offset, length, dst.length);

   669         if (length > remaining())

   670             throw new BufferUnderflowException();

   671         int end = offset + length;

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

   673             dst[i] = get();

   674         return this;

   675     }

   676 

   677     /**

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

   679      *

   680      * <p> This method transfers $fulltype$s from this buffer into the given

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

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

   683      *

   684      * <pre>

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

   686      *

   687      * @return  This buffer

   688      *

   689      * @throws  BufferUnderflowException

   690      *          If there are fewer than <tt>length</tt> $fulltype$s

   691      *          remaining in this buffer

   692      */

   693     public $Type$Buffer get($type$[] dst) {

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

   695     }

   696 

   697 

   698     // -- Bulk put operations --

   699 

   700     /**

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

   702      *

   703      * <p> This method transfers the $fulltype$s remaining in the given source

   704      * buffer into this buffer.  If there are more $fulltype$s remaining in the

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

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

   707      * then no $fulltype$s are transferred and a {@link

   708      * BufferOverflowException} is thrown.

   709      *

   710      * <p> Otherwise, this method copies

   711      * <i>n</i>&nbsp;=&nbsp;<tt>src.remaining()</tt> $fulltype$s from the given

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

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

   714      *

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

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

   717      *

   718      * <pre>

   719      *     while (src.hasRemaining())

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

   721      *

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

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

   724      *

   725      * @param  src

   726      *         The source buffer from which $fulltype$s are to be read;

   727      *         must not be this buffer

   728      *

   729      * @return  This buffer

   730      *

   731      * @throws  BufferOverflowException

   732      *          If there is insufficient space in this buffer

   733      *          for the remaining $fulltype$s in the source buffer

   734      *

   735      * @throws  IllegalArgumentException

   736      *          If the source buffer is this buffer

   737      *

   738      * @throws  ReadOnlyBufferException

   739      *          If this buffer is read-only

   740      */

   741     public $Type$Buffer put($Type$Buffer src) {

   742         if (src == this)

   743             throw new IllegalArgumentException();

   744         int n = src.remaining();

   745         if (n > remaining())

   746             throw new BufferOverflowException();

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

   748             put(src.get());

   749         return this;

   750     }

   751 

   752     /**

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

   754      *

   755      * <p> This method transfers $fulltype$s into this buffer from the given

   756      * source array.  If there are more $fulltype$s to be copied from the array

   757      * than remain in this buffer, that is, if

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

   759      * $fulltype$s are transferred and a {@link BufferOverflowException} is

   760      * thrown.

   761      *

   762      * <p> Otherwise, this method copies <tt>length</tt> $fulltype$s from the

   763      * given array into this buffer, starting at the given offset in the array

   764      * and at the current position of this buffer.  The position of this buffer

   765      * is then incremented by <tt>length</tt>.

   766      *

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

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

   769      * the loop

   770      *

   771      * <pre>

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

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

   774      *

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

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

   777      *

   778      * @param  src

   779      *         The array from which $fulltype$s are to be read

   780      *

   781      * @param  offset

   782      *         The offset within the array of the first $fulltype$ to be read;

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

   784      *

   785      * @param  length

   786      *         The number of $fulltype$s to be read from the given array;

   787      *         must be non-negative and no larger than

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

   789      *

   790      * @return  This buffer

   791      *

   792      * @throws  BufferOverflowException

   793      *          If there is insufficient space in this buffer

   794      *

   795      * @throws  IndexOutOfBoundsException

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

   797      *          parameters do not hold

   798      *

   799      * @throws  ReadOnlyBufferException

   800      *          If this buffer is read-only

   801      */

   802     public $Type$Buffer put($type$[] src, int offset, int length) {

   803         checkBounds(offset, length, src.length);

   804         if (length > remaining())

   805             throw new BufferOverflowException();

   806         int end = offset + length;

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

   808             this.put(src[i]);

   809         return this;

   810     }

   811 

   812     /**

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

   814      *

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

   816      * $fulltype$ array into this buffer.  An invocation of this method of the

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

   818      * invocation

   819      *

   820      * <pre>

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

   822      *

   823      * @return  This buffer

   824      *

   825      * @throws  BufferOverflowException

   826      *          If there is insufficient space in this buffer

   827      *

   828      * @throws  ReadOnlyBufferException

   829      *          If this buffer is read-only

   830      */

   831     public final $Type$Buffer put($type$[] src) {

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

   833     }

   834 

   835 #if[char]

   836 

   837     /**

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

   839      *

   840      * <p> This method transfers $fulltype$s from the given string into this

   841      * buffer.  If there are more $fulltype$s to be copied from the string than

   842      * remain in this buffer, that is, if

   843      * <tt>end&nbsp;-&nbsp;start</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>,

   844      * then no $fulltype$s are transferred and a {@link

   845      * BufferOverflowException} is thrown.

   846      *

   847      * <p> Otherwise, this method copies

   848      * <i>n</i>&nbsp;=&nbsp;<tt>end</tt>&nbsp;-&nbsp;<tt>start</tt> $fulltype$s

   849      * from the given string into this buffer, starting at the given

   850      * <tt>start</tt> index and at the current position of this buffer.  The

   851      * position of this buffer is then incremented by <i>n</i>.

   852      *

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

   854      * <tt>dst.put(src,&nbsp;start,&nbsp;end)</tt> has exactly the same effect

   855      * as the loop

   856      *

   857      * <pre>

   858      *     for (int i = start; i < end; i++)

   859      *         dst.put(src.charAt(i)); </pre>

   860      *

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

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

   863      *

   864      * @param  src

   865      *         The string from which $fulltype$s are to be read

   866      *

   867      * @param  start

   868      *         The offset within the string of the first $fulltype$ to be read;

   869      *         must be non-negative and no larger than

   870      *         <tt>string.length()</tt>

   871      *

   872      * @param  end

   873      *         The offset within the string of the last $fulltype$ to be read,

   874      *         plus one; must be non-negative and no larger than

   875      *         <tt>string.length()</tt>

   876      *

   877      * @return  This buffer

   878      *

   879      * @throws  BufferOverflowException

   880      *          If there is insufficient space in this buffer

   881      *

   882      * @throws  IndexOutOfBoundsException

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

   884      *          parameters do not hold

   885      *

   886      * @throws  ReadOnlyBufferException

   887      *          If this buffer is read-only

   888      */

   889     public $Type$Buffer put(String src, int start, int end) {

   890         checkBounds(start, end - start, src.length());

   891         for (int i = start; i < end; i++)

   892             this.put(src.charAt(i));

   893         return this;

   894     }

   895 

   896     /**

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

   898      *

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

   900      * into this buffer.  An invocation of this method of the form

   901      * <tt>dst.put(s)</tt> behaves in exactly the same way as the invocation

   902      *

   903      * <pre>

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

   905      *

   906      * @return  This buffer

   907      *

   908      * @throws  BufferOverflowException

   909      *          If there is insufficient space in this buffer

   910      *

   911      * @throws  ReadOnlyBufferException

   912      *          If this buffer is read-only

   913      */

   914     public final $Type$Buffer put(String src) {

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

   916     }

   917 

   918 #end[char]

   919 

   920 

   921     // -- Other stuff --

   922 

   923     /**

   924      * Tells whether or not this buffer is backed by an accessible $fulltype$

   925      * array.

   926      *

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

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

   929      * </p>

   930      *

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

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

   933      */

   934     public final boolean hasArray() {

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

   936     }

   937 

   938     /**

   939      * Returns the $fulltype$ array that backs this

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

   941      *

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

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

   944      *

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

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

   947      * array.  </p>

   948      *

   949      * @return  The array that backs this buffer

   950      *

   951      * @throws  ReadOnlyBufferException

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

   953      *

   954      * @throws  UnsupportedOperationException

   955      *          If this buffer is not backed by an accessible array

   956      */

   957     public final $type$[] array() {

   958         if (hb == null)

   959             throw new UnsupportedOperationException();

   960         if (isReadOnly)

   961             throw new ReadOnlyBufferException();

   962         return hb;

   963     }

   964 

   965     /**

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

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

   968      *

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

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

   971      *

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

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

   974      * array.  </p>

   975      *

   976      * @return  The offset within this buffer's array

   977      *          of the first element of the buffer

   978      *

   979      * @throws  ReadOnlyBufferException

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

   981      *

   982      * @throws  UnsupportedOperationException

   983      *          If this buffer is not backed by an accessible array

   984      */

   985     public final int arrayOffset() {

   986         if (hb == null)

   987             throw new UnsupportedOperationException();

   988         if (isReadOnly)

   989             throw new ReadOnlyBufferException();

   990         return offset;

   991     }

   992 

   993     /**

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

   995      *

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

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

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

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

  1000      * to index one, and so forth until the $fulltype$ at index

  1001      * <tt>limit()</tt>&nbsp;-&nbsp;1 is copied to index

  1002      * <i>n</i>&nbsp;=&nbsp;<tt>limit()</tt>&nbsp;-&nbsp;<tt>1</tt>&nbsp;-&nbsp;<i>p</i>.

  1003      * The buffer's position is then set to <i>n+1</i> and its limit is set to

  1004      * its capacity.  The mark, if defined, is discarded.

  1005      *

  1006      * <p> The buffer's position is set to the number of $fulltype$s copied,

  1007      * rather than to zero, so that an invocation of this method can be

  1008      * followed immediately by an invocation of another relative <i>put</i>

  1009      * method. </p>

  1010      *

  1011 #if[byte]

  1012      *

  1013      * <p> Invoke this method after writing data from a buffer in case the

  1014      * write was incomplete.  The following loop, for example, copies bytes

  1015      * from one channel to another via the buffer <tt>buf</tt>:

  1016      *

  1017      * <blockquote><pre>

  1018      * buf.clear();          // Prepare buffer for use

  1019      * while (in.read(buf) >= 0 || buf.position != 0) {

  1020      *     buf.flip();

  1021      *     out.write(buf);

  1022      *     buf.compact();    // In case of partial write

  1023      * }</pre></blockquote>

  1024      *

  1025 #end[byte]

  1026      *

  1027      * @return  This buffer

  1028      *

  1029      * @throws  ReadOnlyBufferException

  1030      *          If this buffer is read-only

  1031      */

  1032     public abstract $Type$Buffer compact();

  1033 

  1034     /**

  1035      * Tells whether or not this $fulltype$ buffer is direct. </p>

  1036      *

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

  1038      */

  1039     public abstract boolean isDirect();

  1040 

  1041 #if[!char]

  1042 

  1043     /**

  1044      * Returns a string summarizing the state of this buffer.  </p>

  1045      *

  1046      * @return  A summary string

  1047      */

  1048     public String toString() {

  1049         StringBuffer sb = new StringBuffer();

  1050         sb.append(getClass().getName());

  1051         sb.append("[pos=");

  1052         sb.append(position());

  1053         sb.append(" lim=");

  1054         sb.append(limit());

  1055         sb.append(" cap=");

  1056         sb.append(capacity());

  1057         sb.append("]");

  1058         return sb.toString();

  1059     }

  1060 

  1061 #end[!char]

  1062 

  1063 

  1064     // ## Should really use unchecked accessors here for speed

  1065 

  1066     /**

  1067      * Returns the current hash code of this buffer.

  1068      *

  1069      * <p> The hash code of a $type$ buffer depends only upon its remaining

  1070      * elements; that is, upon the elements from <tt>position()</tt> up to, and

  1071      * including, the element at <tt>limit()</tt>&nbsp;-&nbsp;<tt>1</tt>.

  1072      *

  1073      * <p> Because buffer hash codes are content-dependent, it is inadvisable

  1074      * to use buffers as keys in hash maps or similar data structures unless it

  1075      * is known that their contents will not change.  </p>

  1076      *

  1077      * @return  The current hash code of this buffer

  1078      */

  1079     public int hashCode() {

  1080         int h = 1;

  1081         int p = position();

  1082         for (int i = limit() - 1; i >= p; i--)

  1083             h = 31 * h + (int)get(i);

  1084         return h;

  1085     }

  1086 

  1087     /**

  1088      * Tells whether or not this buffer is equal to another object.

  1089      *

  1090      * <p> Two $type$ buffers are equal if, and only if,

  1091      *

  1092      * <p><ol>

  1093      *

  1094      *   <li><p> They have the same element type,  </p></li>

  1095      *

  1096      *   <li><p> They have the same number of remaining elements, and

  1097      *   </p></li>

  1098      *

  1099      *   <li><p> The two sequences of remaining elements, considered

  1100      *   independently of their starting positions, are pointwise equal.

  1101      *   </p></li>

  1102      *

  1103      * </ol>

  1104      *

  1105      * <p> A $type$ buffer is not equal to any other type of object.  </p>

  1106      *

  1107      * @param  ob  The object to which this buffer is to be compared

  1108      *

  1109      * @return  <tt>true</tt> if, and only if, this buffer is equal to the

  1110      *           given object

  1111      */

  1112     public boolean equals(Object ob) {

  1113         if (this == ob)

  1114             return true;

  1115         if (!(ob instanceof $Type$Buffer))

  1116             return false;

  1117         $Type$Buffer that = ($Type$Buffer)ob;

  1118         if (this.remaining() != that.remaining())

  1119             return false;

  1120         int p = this.position();

  1121         for (int i = this.limit() - 1, j = that.limit() - 1; i >= p; i--, j--) {

  1122             $type$ v1 = this.get(i);

  1123             $type$ v2 = that.get(j);

  1124             if (v1 != v2) {

  1125                 if ((v1 != v1) && (v2 != v2))   // For float and double

  1126                     continue;

  1127                 return false;

  1128             }

  1129         }

  1130         return true;

  1131     }

  1132 

  1133     /**

  1134      * Compares this buffer to another.