1 /*

     2  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. 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.  Oracle designates this

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

     9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * 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 #if[streamableType]

    34 import java.util.Spliterator;

    35 import java.util.stream.StreamSupport;

    36 import java.util.stream.$Streamtype$Stream;

    37 #end[streamableType]

    38 

    39 /**

    40  * $A$ $type$ buffer.

    41  *

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

    43  * $type$ buffers:

    44  *

    45  * <ul>

    46  *

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

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

    49  *   single $type$s; </p></li>

    50  *

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

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

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

    54  *

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

    56  *   methods that transfer contiguous sequences of $type$s from $a$

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

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

    59  *

    60 #if[byte]

    61  *

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

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

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

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

    66  *

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

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

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

    70  *

    71 #end[byte]

    72  *

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

    74  *   #duplicate duplicating}, and {@link #slice slicing}

    75  *   $a$ $type$ buffer.  </p></li>

    76  *

    77  * </ul>

    78  *

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

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

    81  *

    82 #if[byte]

    83  *

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

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

    86  *

    87 #else[byte]

    88  *

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

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

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

    92  *

    93 #end[byte]

    94  *

    95 #if[byte]

    96  *

    97  * <a name="direct"></a>

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

    99  *

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

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

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

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

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

   105  * system's native I/O operations.

   106  *

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

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

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

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

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

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

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

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

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

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

   117  *

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

   119  * java.nio.channels.FileChannel#map mapping} a region of a file

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

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

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

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

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

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

   126  *

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

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

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

   130  *

   131  *

   132  * <a name="bin"></a>

   133  * <h2> Access to binary data </h2>

   134  *

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

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

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

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

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

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

   141  * ByteOrder#BIG_ENDIAN BIG_ENDIAN}.

   142  *

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

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

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

   146  * values, for example, this class defines:

   147  *

   148  * <blockquote><pre>

   149  * float  {@link #getFloat()}

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

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

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

   153  *

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

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

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

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

   158  *

   159  * <a name="views"></a>

   160  *

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

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

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

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

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

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

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

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

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

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

   171  * <tt>double</tt>.

   172  *

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

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

   175  *

   176  * <ul>

   177  *

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

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

   180  *

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

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

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

   184  *

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

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

   187  *

   188  * </ul>

   189  *

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

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

   192  *

   193 #end[byte]

   194 *

   195 #if[!byte]

   196  *

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

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

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

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

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

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

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

   204  *

   205 #end[!byte]

   206 *

   207 #if[char]

   208  *

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

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

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

   212  * </p>

   213  *

   214 #end[char]

   215  *

   216 #if[byte]

   217  * <h2> Invocation chaining </h2>

   218 #end[byte]

   219  *

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

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

   222  * method invocations to be chained.

   223  *

   224 #if[byte]

   225  *

   226  * The sequence of statements

   227  *

   228  * <blockquote><pre>

   229  * bb.putInt(0xCAFEBABE);

   230  * bb.putShort(3);

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

   232  *

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

   234  *

   235  * <blockquote><pre>

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

   237  *

   238 #end[byte]

   239 #if[char]

   240  *

   241  * The sequence of statements

   242  *

   243  * <blockquote><pre>

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

   245  * cb.put(subtype);

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

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

   248  *

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

   250  *

   251  * <blockquote><pre>

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

   253  *

   254 #end[char]

   255  *

   256  *

   257  * @author Mark Reinhold

   258  * @author JSR-51 Expert Group

   259  * @since 1.4

   260  */

   261 

   262 public abstract class $Type$Buffer

   263     extends Buffer

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

   265 {

   266 

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

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

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

   270     //

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

   272     final int offset;

   273     boolean isReadOnly;                 // Valid only for heap buffers

   274 

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

   276     // backing array, and array offset

   277     //

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

   279                  $type$[] hb, int offset)

   280     {

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

   282         this.hb = hb;

   283         this.offset = offset;

   284     }

   285 

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

   287     //

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

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

   290     }

   291 

   292 #if[byte]

   293 

   294     /**

   295      * Allocates a new direct $type$ buffer.

   296      *

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

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

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

   300      * {@link #hasArray backing array} is unspecified.

   301      *

   302      * @param  capacity

   303      *         The new buffer's capacity, in $type$s

   304      *

   305      * @return  The new $type$ buffer

   306      *

   307      * @throws  IllegalArgumentException

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

   309      */

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

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

   312     }

   313 

   314 #end[byte]

   315 

   316     /**

   317      * Allocates a new $type$ buffer.

   318      *

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

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

   321      * initialized to zero.  It will have a {@link #array backing array},

   322      * and its {@link #arrayOffset array offset} will be zero.

   323      *

   324      * @param  capacity

   325      *         The new buffer's capacity, in $type$s

   326      *

   327      * @return  The new $type$ buffer

   328      *

   329      * @throws  IllegalArgumentException

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

   331      */

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

   333         if (capacity < 0)

   334             throw new IllegalArgumentException();

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

   336     }

   337 

   338     /**

   339      * Wraps $a$ $type$ array into a buffer.

   340      *

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

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

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

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

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

   346      * {@link #array backing array} will be the given array, and

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

   348      *

   349      * @param  array

   350      *         The array that will back the new buffer

   351      *

   352      * @param  offset

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

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

   355      *         will be set to this value.

   356      *

   357      * @param  length

   358      *         The length of the subarray to be used;

   359      *         must be non-negative and no larger than

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

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

   362      *

   363      * @return  The new $type$ buffer

   364      *

   365      * @throws  IndexOutOfBoundsException

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

   367      *          parameters do not hold

   368      */

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

   370                                     int offset, int length)

   371     {

   372         try {

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

   374         } catch (IllegalArgumentException x) {

   375             throw new IndexOutOfBoundsException();

   376         }

   377     }

   378 

   379     /**

   380      * Wraps $a$ $type$ array into a buffer.

   381      *

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

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

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

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

   386      * undefined.  Its {@link #array backing array} will be the

   387      * given array, and its {@link #arrayOffset array offset>} will

   388      * be zero.  </p>

   389      *

   390      * @param  array

   391      *         The array that will back this buffer

   392      *

   393      * @return  The new $type$ buffer

   394      */

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

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

   397     }

   398 

   399 #if[char]

   400 

   401     /**

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

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

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

   405      * rewinding of the buffer is performed.

   406      *

   407      * @param target the buffer to read characters into

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

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

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

   411      * @throws NullPointerException if target is null

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

   413      * @since 1.5

   414      */

   415     public int read(CharBuffer target) throws IOException {

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

   417         int targetRemaining = target.remaining();

   418         int remaining = remaining();

   419         if (remaining == 0)

   420             return -1;

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

   422         int limit = limit();

   423         // Set source limit to prevent target overflow

   424         if (targetRemaining < remaining)

   425             limit(position() + n);

   426         try {

   427             if (n > 0)

   428                 target.put(this);

   429         } finally {

   430             limit(limit); // restore real limit

   431         }

   432         return n;

   433     }

   434 

   435     /**

   436      * Wraps a character sequence into a buffer.

   437      *

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

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

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

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

   442      *

   443      * @param  csq

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

   445      *         be created

   446      *

   447      * @param  start

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

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

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

   451      *

   452      * @param  end

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

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

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

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

   457      *

   458      * @return  The new character buffer

   459      *

   460      * @throws  IndexOutOfBoundsException

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

   462      *          parameters do not hold

   463      */

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

   465         try {

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

   467         } catch (IllegalArgumentException x) {

   468             throw new IndexOutOfBoundsException();

   469         }

   470     }

   471 

   472     /**

   473      * Wraps a character sequence into a buffer.

   474      *

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

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

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

   478      * undefined.  </p>

   479      *

   480      * @param  csq

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

   482      *         be created

   483      *

   484      * @return  The new character buffer

   485      */

   486     public static CharBuffer wrap(CharSequence csq) {

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

   488     }

   489 

   490 #end[char]

   491 

   492     /**

   493      * Creates a new $type$ buffer whose content is a shared subsequence of

   494      * this buffer's content.

   495      *

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

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

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

   499      * values will be independent.

   500      *

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

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

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

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

   505      * is read-only.  </p>

   506      *

   507      * @return  The new $type$ buffer

   508      */

   509     public abstract $Type$Buffer slice();

   510 

   511     /**

   512      * Creates a new $type$ buffer that shares this buffer's content.

   513      *

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

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

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

   517      * independent.

   518      *

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

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

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

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

   523      *

   524      * @return  The new $type$ buffer

   525      */

   526     public abstract $Type$Buffer duplicate();

   527 

   528     /**

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

   530      * content.

   531      *

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

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

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

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

   536      * values will be independent.

   537      *

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

   539      * identical to those of this buffer.

   540      *

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

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

   543      *

   544      * @return  The new, read-only $type$ buffer

   545      */

   546     public abstract $Type$Buffer asReadOnlyBuffer();

   547 

   548 

   549     // -- Singleton get/put methods --

   550 

   551     /**

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

   553      * current position, and then increments the position.

   554      *

   555      * @return  The $type$ at the buffer's current position

   556      *

   557      * @throws  BufferUnderflowException

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

   559      */

   560     public abstract $type$ get();

   561 

   562     /**

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

   564      *

   565      * <p> Writes the given $type$ into this buffer at the current

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

   567      *

   568      * @param  $x$

   569      *         The $type$ to be written

   570      *

   571      * @return  This buffer

   572      *

   573      * @throws  BufferOverflowException

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

   575      *

   576      * @throws  ReadOnlyBufferException

   577      *          If this buffer is read-only

   578      */

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

   580 

   581     /**

   582      * Absolute <i>get</i> method.  Reads the $type$ at the given

   583      * index.

   584      *

   585      * @param  index

   586      *         The index from which the $type$ will be read

   587      *

   588      * @return  The $type$ at the given index

   589      *

   590      * @throws  IndexOutOfBoundsException

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

   592      *          or not smaller than the buffer's limit

   593      */

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

   595 

   596 #if[streamableType]

   597     /**

   598      * Absolute <i>get</i> method.  Reads the $type$ at the given

   599      * index without any validation of the index.

   600      *

   601      * @param  index

   602      *         The index from which the $type$ will be read

   603      *

   604      * @return  The $type$ at the given index

   605      */

   606     abstract $type$ getUnchecked(int index);   // package-private

   607 #end[streamableType]

   608 

   609     /**

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

   611      *

   612      * <p> Writes the given $type$ into this buffer at the given

   613      * index. </p>

   614      *

   615      * @param  index

   616      *         The index at which the $type$ will be written

   617      *

   618      * @param  $x$

   619      *         The $type$ value to be written

   620      *

   621      * @return  This buffer

   622      *

   623      * @throws  IndexOutOfBoundsException

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

   625      *          or not smaller than the buffer's limit

   626      *

   627      * @throws  ReadOnlyBufferException

   628      *          If this buffer is read-only

   629      */

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

   631 

   632 

   633     // -- Bulk get operations --

   634 

   635     /**

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

   637      *

   638      * <p> This method transfers $type$s from this buffer into the given

   639      * destination array.  If there are fewer $type$s remaining in the

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

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

   642      * $type$s are transferred and a {@link BufferUnderflowException} is

   643      * thrown.

   644      *

   645      * <p> Otherwise, this method copies <tt>length</tt> $type$s from this

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

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

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

   649      *

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

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

   652      * the loop

   653      *

   654      * <pre>{@code

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

   656      *         dst[i] = src.get():

   657      * }</pre>

   658      *

   659      * except that it first checks that there are sufficient $type$s in

   660      * this buffer and it is potentially much more efficient.

   661      *

   662      * @param  dst

   663      *         The array into which $type$s are to be written

   664      *

   665      * @param  offset

   666      *         The offset within the array of the first $type$ to be

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

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

   669      *

   670      * @param  length

   671      *         The maximum number of $type$s to be written to the given

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

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

   674      *

   675      * @return  This buffer

   676      *

   677      * @throws  BufferUnderflowException

   678      *          If there are fewer than <tt>length</tt> $type$s

   679      *          remaining in this buffer

   680      *

   681      * @throws  IndexOutOfBoundsException

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

   683      *          parameters do not hold

   684      */

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

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

   687         if (length > remaining())

   688             throw new BufferUnderflowException();

   689         int end = offset + length;

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

   691             dst[i] = get();

   692         return this;

   693     }

   694 

   695     /**

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

   697      *

   698      * <p> This method transfers $type$s from this buffer into the given

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

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

   701      *

   702      * <pre>

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

   704      *

   705      * @param   dst

   706      *          The destination array

   707      *

   708      * @return  This buffer

   709      *

   710      * @throws  BufferUnderflowException

   711      *          If there are fewer than <tt>length</tt> $type$s

   712      *          remaining in this buffer

   713      */

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

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

   716     }

   717 

   718 

   719     // -- Bulk put operations --

   720 

   721     /**

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

   723      *

   724      * <p> This method transfers the $type$s remaining in the given source

   725      * buffer into this buffer.  If there are more $type$s remaining in the

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

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

   728      * then no $type$s are transferred and a {@link

   729      * BufferOverflowException} is thrown.

   730      *

   731      * <p> Otherwise, this method copies

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

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

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

   735      *

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

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

   738      *

   739      * <pre>

   740      *     while (src.hasRemaining())

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

   742      *

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

   744      * buffer and it is potentially much more efficient.

   745      *

   746      * @param  src

   747      *         The source buffer from which $type$s are to be read;

   748      *         must not be this buffer

   749      *

   750      * @return  This buffer

   751      *

   752      * @throws  BufferOverflowException

   753      *          If there is insufficient space in this buffer

   754      *          for the remaining $type$s in the source buffer

   755      *

   756      * @throws  IllegalArgumentException

   757      *          If the source buffer is this buffer

   758      *

   759      * @throws  ReadOnlyBufferException

   760      *          If this buffer is read-only

   761      */

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

   763         if (src == this)

   764             throw new IllegalArgumentException();

   765         if (isReadOnly())

   766             throw new ReadOnlyBufferException();

   767         int n = src.remaining();

   768         if (n > remaining())

   769             throw new BufferOverflowException();

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

   771             put(src.get());

   772         return this;

   773     }

   774 

   775     /**

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

   777      *

   778      * <p> This method transfers $type$s into this buffer from the given

   779      * source array.  If there are more $type$s to be copied from the array

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

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

   782      * $type$s are transferred and a {@link BufferOverflowException} is

   783      * thrown.

   784      *

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

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

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

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

   789      *

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

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

   792      * the loop

   793      *

   794      * <pre>{@code

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

   796      *         dst.put(a[i]);

   797      * }</pre>

   798      *

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

   800      * buffer and it is potentially much more efficient.

   801      *

   802      * @param  src

   803      *         The array from which $type$s are to be read

   804      *

   805      * @param  offset

   806      *         The offset within the array of the first $type$ to be read;

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

   808      *

   809      * @param  length

   810      *         The number of $type$s to be read from the given array;

   811      *         must be non-negative and no larger than

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

   813      *

   814      * @return  This buffer

   815      *

   816      * @throws  BufferOverflowException

   817      *          If there is insufficient space in this buffer

   818      *

   819      * @throws  IndexOutOfBoundsException

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

   821      *          parameters do not hold

   822      *

   823      * @throws  ReadOnlyBufferException

   824      *          If this buffer is read-only

   825      */

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

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

   828         if (length > remaining())

   829             throw new BufferOverflowException();

   830         int end = offset + length;

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

   832             this.put(src[i]);

   833         return this;

   834     }

   835 

   836     /**

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

   838      *

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

   840      * $type$ array into this buffer.  An invocation of this method of the

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

   842      * invocation

   843      *

   844      * <pre>

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

   846      *

   847      * @param   src

   848      *          The source array

   849      *

   850      * @return  This buffer

   851      *

   852      * @throws  BufferOverflowException

   853      *          If there is insufficient space in this buffer

   854      *

   855      * @throws  ReadOnlyBufferException

   856      *          If this buffer is read-only

   857      */

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

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

   860     }

   861 

   862 #if[char]

   863 

   864     /**

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

   866      *

   867      * <p> This method transfers $type$s from the given string into this

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

   869      * remain in this buffer, that is, if

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

   871      * then no $type$s are transferred and a {@link

   872      * BufferOverflowException} is thrown.

   873      *

   874      * <p> Otherwise, this method copies

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

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

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

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

   879      *

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

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

   882      * as the loop

   883      *

   884      * <pre>{@code

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

   886      *         dst.put(src.charAt(i));

   887      * }</pre>

   888      *

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

   890      * buffer and it is potentially much more efficient.

   891      *

   892      * @param  src

   893      *         The string from which $type$s are to be read

   894      *

   895      * @param  start

   896      *         The offset within the string of the first $type$ to be read;

   897      *         must be non-negative and no larger than

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

   899      *

   900      * @param  end

   901      *         The offset within the string of the last $type$ to be read,

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

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

   904      *

   905      * @return  This buffer

   906      *

   907      * @throws  BufferOverflowException

   908      *          If there is insufficient space in this buffer

   909      *

   910      * @throws  IndexOutOfBoundsException

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

   912      *          parameters do not hold

   913      *

   914      * @throws  ReadOnlyBufferException

   915      *          If this buffer is read-only

   916      */

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

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

   919         if (isReadOnly())

   920             throw new ReadOnlyBufferException();

   921         if (end - start > remaining())

   922             throw new BufferOverflowException();

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

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

   925         return this;

   926     }

   927 

   928     /**

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

   930      *

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

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

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

   934      *

   935      * <pre>

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

   937      *

   938      * @param   src

   939      *          The source string

   940      *

   941      * @return  This buffer

   942      *

   943      * @throws  BufferOverflowException

   944      *          If there is insufficient space in this buffer

   945      *

   946      * @throws  ReadOnlyBufferException

   947      *          If this buffer is read-only

   948      */

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

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

   951     }

   952 

   953 #end[char]

   954 

   955 

   956     // -- Other stuff --

   957 

   958     /**

   959      * Tells whether or not this buffer is backed by an accessible $type$

   960      * array.

   961      *

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

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

   964      * </p>

   965      *

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

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

   968      */

   969     public final boolean hasArray() {

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

   971     }

   972 

   973     /**

   974      * Returns the $type$ array that backs this

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

   976      *

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

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

   979      *

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

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

   982      * array.  </p>

   983      *

   984      * @return  The array that backs this buffer

   985      *

   986      * @throws  ReadOnlyBufferException

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

   988      *

   989      * @throws  UnsupportedOperationException

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

   991      */

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

   993         if (hb == null)

   994             throw new UnsupportedOperationException();

   995         if (isReadOnly)

   996             throw new ReadOnlyBufferException();

   997         return hb;

   998     }

   999 

  1000     /**

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

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

  1003      *

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

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

  1006      *

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

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

  1009      * array.  </p>

  1010      *

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

  1012      *          of the first element of the buffer

  1013      *

  1014      * @throws  ReadOnlyBufferException

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

  1016      *

  1017      * @throws  UnsupportedOperationException

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

  1019      */

  1020     public final int arrayOffset() {

  1021         if (hb == null)

  1022             throw new UnsupportedOperationException();

  1023         if (isReadOnly)

  1024             throw new ReadOnlyBufferException();

  1025         return offset;

  1026     }

  1027 

  1028     /**

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

  1030      *

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

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

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

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

  1035      * to index one, and so forth until the $type$ at index

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

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

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

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

  1040      *

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

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

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

  1044      * method. </p>

  1045      *

  1046 #if[byte]

  1047      *

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

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

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

  1051      *

  1052      * <blockquote><pre>{@code

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

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

  1055      *       buf.flip();

  1056      *       out.write(buf);

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

  1058      *   }

  1059      * }</pre></blockquote>

  1060      *

  1061 #end[byte]

  1062      *

  1063      * @return  This buffer

  1064      *

  1065      * @throws  ReadOnlyBufferException

  1066      *          If this buffer is read-only

  1067      */

  1068     public abstract $Type$Buffer compact();

  1069 

  1070     /**

  1071      * Tells whether or not this $type$ buffer is direct.

  1072      *

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

  1074      */

  1075     public abstract boolean isDirect();

  1076 

  1077 #if[!char]

  1078 

  1079     /**

  1080      * Returns a string summarizing the state of this buffer.

  1081      *

  1082      * @return  A summary string

  1083      */

  1084     public String toString() {

  1085         StringBuffer sb = new StringBuffer();

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

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

  1088         sb.append(position());

  1089         sb.append(" lim=");

  1090         sb.append(limit());

  1091         sb.append(" cap=");

  1092         sb.append(capacity());

  1093         sb.append("]");

  1094         return sb.toString();

  1095     }

  1096 

  1097 #end[!char]

  1098 

  1099 

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

  1101 

  1102     /**

  1103      * Returns the current hash code of this buffer.

  1104      *

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

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

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

  1108      *

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

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

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

  1112      *

  1113      * @return  The current hash code of this buffer

  1114      */

  1115     public int hashCode() {

  1116         int h = 1;

  1117         int p = position();

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

  1119 #if[int]

  1120             h = 31 * h + get(i);

  1121 #else[int]

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

  1123 #end[int]

  1124         return h;

  1125     }

  1126 

  1127     /**

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

  1129      *

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

  1131      *

  1132      * <ol>

  1133      *

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