1 /*
   2  * Copyright (c) 2000, 2012, 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() </code><i>get</i><code>} and
  48  *   {@link #put($type$) </code><i>put</i><code>} methods that read and write
  49  *   single $type$s; </p></li>
  50  *
  51  *   <li><p> Relative {@link #get($type$[]) </code><i>bulk get</i><code>}
  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$[]) </code><i>bulk put</i><code>}
  56  *   methods that transfer contiguous sequences of $type$s from $a$
  57  *   $type$ array{#if[char]?,&#32;a&#32;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() </code><i>get</i><code>}
  63  *   and {@link #putChar(char) </code><i>put</i><code>} 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 </code>compacting<code>}, {@link
  74  *   #duplicate </code>duplicating<code>}, and {@link #slice
  75  *   </code>slicing<code>} $a$ $type$ buffer.  </p></li>
  76  *
  77  * </ul>
  78  *
  79  * <p> $Type$ buffers can be created either by {@link #allocate
  80  * </code><i>allocation</i><code>}, which allocates space for the buffer's
  81  *
  82 #if[byte]
  83  *
  84  * content, or by {@link #wrap($type$[]) </code><i>wrapping</i><code>} an
  85  * existing $type$ array {#if[char]?or&#32;string} into a buffer.
  86  *
  87 #else[byte]
  88  *
  89  * content, by {@link #wrap($type$[]) </code><i>wrapping</i><code>} an existing
  90  * $type$ array {#if[char]?or&#32;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">
  98  * <h4> Direct <i>vs.</i> non-direct buffers </h4>
  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 </code>mapping<code>} 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">
 133  * <h4> Access to binary data </h4>
 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">
 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  * <h4> Invocation chaining </h4>
 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 </code>backing array<code>} 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
 322      * </code>backing array<code>}, and its {@link #arrayOffset </code>array
 323      * offset<code>} will be zero.
 324      *
 325      * @param  capacity
 326      *         The new buffer's capacity, in $type$s
 327      *
 328      * @return  The new $type$ buffer
 329      *
 330      * @throws  IllegalArgumentException
 331      *          If the <tt>capacity</tt> is a negative integer
 332      */
 333     public static $Type$Buffer allocate(int capacity) {
 334         if (capacity < 0)
 335             throw new IllegalArgumentException();
 336         return new Heap$Type$Buffer(capacity, capacity);
 337     }
 338 
 339     /**
 340      * Wraps $a$ $type$ array into a buffer.
 341      *
 342      * <p> The new buffer will be backed by the given $type$ array;
 343      * that is, modifications to the buffer will cause the array to be modified
 344      * and vice versa.  The new buffer's capacity will be
 345      * <tt>array.length</tt>, its position will be <tt>offset</tt>, its limit
 346      * will be <tt>offset + length</tt>, and its mark will be undefined.  Its
 347      * {@link #array </code>backing array<code>} will be the given array, and
 348      * its {@link #arrayOffset </code>array offset<code>} will be zero.  </p>
 349      *
 350      * @param  array
 351      *         The array that will back the new buffer
 352      *
 353      * @param  offset
 354      *         The offset of the subarray to be used; must be non-negative and
 355      *         no larger than <tt>array.length</tt>.  The new buffer's position
 356      *         will be set to this value.
 357      *
 358      * @param  length
 359      *         The length of the subarray to be used;
 360      *         must be non-negative and no larger than
 361      *         <tt>array.length - offset</tt>.
 362      *         The new buffer's limit will be set to <tt>offset + length</tt>.
 363      *
 364      * @return  The new $type$ buffer
 365      *
 366      * @throws  IndexOutOfBoundsException
 367      *          If the preconditions on the <tt>offset</tt> and <tt>length</tt>
 368      *          parameters do not hold
 369      */
 370     public static $Type$Buffer wrap($type$[] array,
 371                                     int offset, int length)
 372     {
 373         try {
 374             return new Heap$Type$Buffer(array, offset, length);
 375         } catch (IllegalArgumentException x) {
 376             throw new IndexOutOfBoundsException();
 377         }
 378     }
 379 
 380     /**
 381      * Wraps $a$ $type$ array into a buffer.
 382      *
 383      * <p> The new buffer will be backed by the given $type$ array;
 384      * that is, modifications to the buffer will cause the array to be modified
 385      * and vice versa.  The new buffer's capacity and limit will be
 386      * <tt>array.length</tt>, its position will be zero, and its mark will be
 387      * undefined.  Its {@link #array </code>backing array<code>} will be the
 388      * given array, and its {@link #arrayOffset </code>array offset<code>} will
 389      * be zero.  </p>
 390      *
 391      * @param  array
 392      *         The array that will back this buffer
 393      *
 394      * @return  The new $type$ buffer
 395      */
 396     public static $Type$Buffer wrap($type$[] array) {
 397         return wrap(array, 0, array.length);
 398     }
 399 
 400 #if[char]
 401 
 402     /**
 403      * Attempts to read characters into the specified character buffer.
 404      * The buffer is used as a repository of characters as-is: the only
 405      * changes made are the results of a put operation. No flipping or
 406      * rewinding of the buffer is performed.
 407      *
 408      * @param target the buffer to read characters into
 409      * @return The number of characters added to the buffer, or
 410      *         -1 if this source of characters is at its end
 411      * @throws IOException if an I/O error occurs
 412      * @throws NullPointerException if target is null
 413      * @throws ReadOnlyBufferException if target is a read only buffer
 414      * @since 1.5
 415      */
 416     public int read(CharBuffer target) throws IOException {
 417         // Determine the number of bytes n that can be transferred
 418         int targetRemaining = target.remaining();
 419         int remaining = remaining();
 420         if (remaining == 0)
 421             return -1;
 422         int n = Math.min(remaining, targetRemaining);
 423         int limit = limit();
 424         // Set source limit to prevent target overflow
 425         if (targetRemaining < remaining)
 426             limit(position() + n);
 427         try {
 428             if (n > 0)
 429                 target.put(this);
 430         } finally {
 431             limit(limit); // restore real limit
 432         }
 433         return n;
 434     }
 435 
 436     /**
 437      * Wraps a character sequence into a buffer.
 438      *
 439      * <p> The content of the new, read-only buffer will be the content of the
 440      * given character sequence.  The buffer's capacity will be
 441      * <tt>csq.length()</tt>, its position will be <tt>start</tt>, its limit
 442      * will be <tt>end</tt>, and its mark will be undefined.  </p>
 443      *
 444      * @param  csq
 445      *         The character sequence from which the new character buffer is to
 446      *         be created
 447      *
 448      * @param  start
 449      *         The index of the first character to be used;
 450      *         must be non-negative and no larger than <tt>csq.length()</tt>.
 451      *         The new buffer's position will be set to this value.
 452      *
 453      * @param  end
 454      *         The index of the character following the last character to be
 455      *         used; must be no smaller than <tt>start</tt> and no larger
 456      *         than <tt>csq.length()</tt>.
 457      *         The new buffer's limit will be set to this value.
 458      *
 459      * @return  The new character buffer
 460      *
 461      * @throws  IndexOutOfBoundsException
 462      *          If the preconditions on the <tt>start</tt> and <tt>end</tt>
 463      *          parameters do not hold
 464      */
 465     public static CharBuffer wrap(CharSequence csq, int start, int end) {
 466         try {
 467             return new StringCharBuffer(csq, start, end);
 468         } catch (IllegalArgumentException x) {
 469             throw new IndexOutOfBoundsException();
 470         }
 471     }
 472 
 473     /**
 474      * Wraps a character sequence into a buffer.
 475      *
 476      * <p> The content of the new, read-only buffer will be the content of the
 477      * given character sequence.  The new buffer's capacity and limit will be
 478      * <tt>csq.length()</tt>, its position will be zero, and its mark will be
 479      * undefined.  </p>
 480      *
 481      * @param  csq
 482      *         The character sequence from which the new character buffer is to
 483      *         be created
 484      *
 485      * @return  The new character buffer
 486      */
 487     public static CharBuffer wrap(CharSequence csq) {
 488         return wrap(csq, 0, csq.length());
 489     }
 490 
 491 #end[char]
 492 
 493     /**
 494      * Creates a new $type$ buffer whose content is a shared subsequence of
 495      * this buffer's content.
 496      *
 497      * <p> The content of the new buffer will start at this buffer's current
 498      * position.  Changes to this buffer's content will be visible in the new
 499      * buffer, and vice versa; the two buffers' position, limit, and mark
 500      * values will be independent.
 501      *
 502      * <p> The new buffer's position will be zero, its capacity and its limit
 503      * will be the number of $type$s remaining in this buffer, and its mark
 504      * will be undefined.  The new buffer will be direct if, and only if, this
 505      * buffer is direct, and it will be read-only if, and only if, this buffer
 506      * is read-only.  </p>
 507      *
 508      * @return  The new $type$ buffer
 509      */
 510     public abstract $Type$Buffer slice();
 511 
 512     /**
 513      * Creates a new $type$ buffer that shares this buffer's content.
 514      *
 515      * <p> The content of the new buffer will be that of this buffer.  Changes
 516      * to this buffer's content will be visible in the new buffer, and vice
 517      * versa; the two buffers' position, limit, and mark values will be
 518      * independent.
 519      *
 520      * <p> The new buffer's capacity, limit, position, and mark values will be
 521      * identical to those of this buffer.  The new buffer will be direct if,
 522      * and only if, this buffer is direct, and it will be read-only if, and
 523      * only if, this buffer is read-only.  </p>
 524      *
 525      * @return  The new $type$ buffer
 526      */
 527     public abstract $Type$Buffer duplicate();
 528 
 529     /**
 530      * Creates a new, read-only $type$ buffer that shares this buffer's
 531      * content.
 532      *
 533      * <p> The content of the new buffer will be that of this buffer.  Changes
 534      * to this buffer's content will be visible in the new buffer; the new
 535      * buffer itself, however, will be read-only and will not allow the shared
 536      * content to be modified.  The two buffers' position, limit, and mark
 537      * values will be independent.
 538      *
 539      * <p> The new buffer's capacity, limit, position, and mark values will be
 540      * identical to those of this buffer.
 541      *
 542      * <p> If this buffer is itself read-only then this method behaves in
 543      * exactly the same way as the {@link #duplicate duplicate} method.  </p>
 544      *
 545      * @return  The new, read-only $type$ buffer
 546      */
 547     public abstract $Type$Buffer asReadOnlyBuffer();
 548 
 549 
 550     // -- Singleton get/put methods --
 551 
 552     /**
 553      * Relative <i>get</i> method.  Reads the $type$ at this buffer's
 554      * current position, and then increments the position. </p>
 555      *
 556      * @return  The $type$ at the buffer's current position
 557      *
 558      * @throws  BufferUnderflowException
 559      *          If the buffer's current position is not smaller than its limit
 560      */
 561     public abstract $type$ get();
 562 
 563     /**
 564      * Relative <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 565      *
 566      * <p> Writes the given $type$ into this buffer at the current
 567      * position, and then increments the position. </p>
 568      *
 569      * @param  $x$
 570      *         The $type$ to be written
 571      *
 572      * @return  This buffer
 573      *
 574      * @throws  BufferOverflowException
 575      *          If this buffer's current position is not smaller than its limit
 576      *
 577      * @throws  ReadOnlyBufferException
 578      *          If this buffer is read-only
 579      */
 580     public abstract $Type$Buffer put($type$ $x$);
 581 
 582     /**
 583      * Absolute <i>get</i> method.  Reads the $type$ at the given
 584      * index. </p>
 585      *
 586      * @param  index
 587      *         The index from which the $type$ will be read
 588      *
 589      * @return  The $type$ at the given index
 590      *
 591      * @throws  IndexOutOfBoundsException
 592      *          If <tt>index</tt> is negative
 593      *          or not smaller than the buffer's limit
 594      */
 595     public abstract $type$ get(int index);
 596 
 597 #if[streamableType]
 598     /**
 599      * Absolute <i>get</i> method.  Reads the $type$ at the given
 600      * index without any validation of the index.
 601      *
 602      * @param  index
 603      *         The index from which the $type$ will be read
 604      *
 605      * @return  The $type$ at the given index
 606      */
 607     abstract $type$ getUnchecked(int index);   // package-private
 608 #end[streamableType]
 609 
 610     /**
 611      * Absolute <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 612      *
 613      * <p> Writes the given $type$ into this buffer at the given
 614      * index. </p>
 615      *
 616      * @param  index
 617      *         The index at which the $type$ will be written
 618      *
 619      * @param  $x$
 620      *         The $type$ value to be written
 621      *
 622      * @return  This buffer
 623      *
 624      * @throws  IndexOutOfBoundsException
 625      *          If <tt>index</tt> is negative
 626      *          or not smaller than the buffer's limit
 627      *
 628      * @throws  ReadOnlyBufferException
 629      *          If this buffer is read-only
 630      */
 631     public abstract $Type$Buffer put(int index, $type$ $x$);
 632 
 633 
 634     // -- Bulk get operations --
 635 
 636     /**
 637      * Relative bulk <i>get</i> method.
 638      *
 639      * <p> This method transfers $type$s from this buffer into the given
 640      * destination array.  If there are fewer $type$s remaining in the
 641      * buffer than are required to satisfy the request, that is, if
 642      * <tt>length</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>, then no
 643      * $type$s are transferred and a {@link BufferUnderflowException} is
 644      * thrown.
 645      *
 646      * <p> Otherwise, this method copies <tt>length</tt> $type$s from this
 647      * buffer into the given array, starting at the current position of this
 648      * buffer and at the given offset in the array.  The position of this
 649      * buffer is then incremented by <tt>length</tt>.
 650      *
 651      * <p> In other words, an invocation of this method of the form
 652      * <tt>src.get(dst,&nbsp;off,&nbsp;len)</tt> has exactly the same effect as
 653      * the loop
 654      *
 655      * <pre>
 656      *     for (int i = off; i < off + len; i++)
 657      *         dst[i] = src.get(); </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. </p>
 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      * @return  This buffer
 706      *
 707      * @throws  BufferUnderflowException
 708      *          If there are fewer than <tt>length</tt> $type$s
 709      *          remaining in this buffer
 710      */
 711     public $Type$Buffer get($type$[] dst) {
 712         return get(dst, 0, dst.length);
 713     }
 714 
 715 
 716     // -- Bulk put operations --
 717 
 718     /**
 719      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 720      *
 721      * <p> This method transfers the $type$s remaining in the given source
 722      * buffer into this buffer.  If there are more $type$s remaining in the
 723      * source buffer than in this buffer, that is, if
 724      * <tt>src.remaining()</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>,
 725      * then no $type$s are transferred and a {@link
 726      * BufferOverflowException} is thrown.
 727      *
 728      * <p> Otherwise, this method copies
 729      * <i>n</i>&nbsp;=&nbsp;<tt>src.remaining()</tt> $type$s from the given
 730      * buffer into this buffer, starting at each buffer's current position.
 731      * The positions of both buffers are then incremented by <i>n</i>.
 732      *
 733      * <p> In other words, an invocation of this method of the form
 734      * <tt>dst.put(src)</tt> has exactly the same effect as the loop
 735      *
 736      * <pre>
 737      *     while (src.hasRemaining())
 738      *         dst.put(src.get()); </pre>
 739      *
 740      * except that it first checks that there is sufficient space in this
 741      * buffer and it is potentially much more efficient. </p>
 742      *
 743      * @param  src
 744      *         The source buffer from which $type$s are to be read;
 745      *         must not be this buffer
 746      *
 747      * @return  This buffer
 748      *
 749      * @throws  BufferOverflowException
 750      *          If there is insufficient space in this buffer
 751      *          for the remaining $type$s in the source buffer
 752      *
 753      * @throws  IllegalArgumentException
 754      *          If the source buffer is this buffer
 755      *
 756      * @throws  ReadOnlyBufferException
 757      *          If this buffer is read-only
 758      */
 759     public $Type$Buffer put($Type$Buffer src) {
 760         if (src == this)
 761             throw new IllegalArgumentException();
 762         if (isReadOnly())
 763             throw new ReadOnlyBufferException();
 764         int n = src.remaining();
 765         if (n > remaining())
 766             throw new BufferOverflowException();
 767         for (int i = 0; i < n; i++)
 768             put(src.get());
 769         return this;
 770     }
 771 
 772     /**
 773      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 774      *
 775      * <p> This method transfers $type$s into this buffer from the given
 776      * source array.  If there are more $type$s to be copied from the array
 777      * than remain in this buffer, that is, if
 778      * <tt>length</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>, then no
 779      * $type$s are transferred and a {@link BufferOverflowException} is
 780      * thrown.
 781      *
 782      * <p> Otherwise, this method copies <tt>length</tt> $type$s from the
 783      * given array into this buffer, starting at the given offset in the array
 784      * and at the current position of this buffer.  The position of this buffer
 785      * is then incremented by <tt>length</tt>.
 786      *
 787      * <p> In other words, an invocation of this method of the form
 788      * <tt>dst.put(src,&nbsp;off,&nbsp;len)</tt> has exactly the same effect as
 789      * the loop
 790      *
 791      * <pre>
 792      *     for (int i = off; i < off + len; i++)
 793      *         dst.put(a[i]); </pre>
 794      *
 795      * except that it first checks that there is sufficient space in this
 796      * buffer and it is potentially much more efficient. </p>
 797      *
 798      * @param  src
 799      *         The array from which $type$s are to be read
 800      *
 801      * @param  offset
 802      *         The offset within the array of the first $type$ to be read;
 803      *         must be non-negative and no larger than <tt>array.length</tt>
 804      *
 805      * @param  length
 806      *         The number of $type$s to be read from the given array;
 807      *         must be non-negative and no larger than
 808      *         <tt>array.length - offset</tt>
 809      *
 810      * @return  This buffer
 811      *
 812      * @throws  BufferOverflowException
 813      *          If there is insufficient space in this buffer
 814      *
 815      * @throws  IndexOutOfBoundsException
 816      *          If the preconditions on the <tt>offset</tt> and <tt>length</tt>
 817      *          parameters do not hold
 818      *
 819      * @throws  ReadOnlyBufferException
 820      *          If this buffer is read-only
 821      */
 822     public $Type$Buffer put($type$[] src, int offset, int length) {
 823         checkBounds(offset, length, src.length);
 824         if (length > remaining())
 825             throw new BufferOverflowException();
 826         int end = offset + length;
 827         for (int i = offset; i < end; i++)
 828             this.put(src[i]);
 829         return this;
 830     }
 831 
 832     /**
 833      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 834      *
 835      * <p> This method transfers the entire content of the given source
 836      * $type$ array into this buffer.  An invocation of this method of the
 837      * form <tt>dst.put(a)</tt> behaves in exactly the same way as the
 838      * invocation
 839      *
 840      * <pre>
 841      *     dst.put(a, 0, a.length) </pre>
 842      *
 843      * @return  This buffer
 844      *
 845      * @throws  BufferOverflowException
 846      *          If there is insufficient space in this buffer
 847      *
 848      * @throws  ReadOnlyBufferException
 849      *          If this buffer is read-only
 850      */
 851     public final $Type$Buffer put($type$[] src) {
 852         return put(src, 0, src.length);
 853     }
 854 
 855 #if[char]
 856 
 857     /**
 858      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 859      *
 860      * <p> This method transfers $type$s from the given string into this
 861      * buffer.  If there are more $type$s to be copied from the string than
 862      * remain in this buffer, that is, if
 863      * <tt>end&nbsp;-&nbsp;start</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>,
 864      * then no $type$s are transferred and a {@link
 865      * BufferOverflowException} is thrown.
 866      *
 867      * <p> Otherwise, this method copies
 868      * <i>n</i>&nbsp;=&nbsp;<tt>end</tt>&nbsp;-&nbsp;<tt>start</tt> $type$s
 869      * from the given string into this buffer, starting at the given
 870      * <tt>start</tt> index and at the current position of this buffer.  The
 871      * position of this buffer is then incremented by <i>n</i>.
 872      *
 873      * <p> In other words, an invocation of this method of the form
 874      * <tt>dst.put(src,&nbsp;start,&nbsp;end)</tt> has exactly the same effect
 875      * as the loop
 876      *
 877      * <pre>
 878      *     for (int i = start; i < end; i++)
 879      *         dst.put(src.charAt(i)); </pre>
 880      *
 881      * except that it first checks that there is sufficient space in this
 882      * buffer and it is potentially much more efficient. </p>
 883      *
 884      * @param  src
 885      *         The string from which $type$s are to be read
 886      *
 887      * @param  start
 888      *         The offset within the string of the first $type$ to be read;
 889      *         must be non-negative and no larger than
 890      *         <tt>string.length()</tt>
 891      *
 892      * @param  end
 893      *         The offset within the string of the last $type$ to be read,
 894      *         plus one; must be non-negative and no larger than
 895      *         <tt>string.length()</tt>
 896      *
 897      * @return  This buffer
 898      *
 899      * @throws  BufferOverflowException
 900      *          If there is insufficient space in this buffer
 901      *
 902      * @throws  IndexOutOfBoundsException
 903      *          If the preconditions on the <tt>start</tt> and <tt>end</tt>
 904      *          parameters do not hold
 905      *
 906      * @throws  ReadOnlyBufferException
 907      *          If this buffer is read-only
 908      */
 909     public $Type$Buffer put(String src, int start, int end) {
 910         checkBounds(start, end - start, src.length());
 911         if (isReadOnly())
 912             throw new ReadOnlyBufferException();
 913         if (end - start > remaining())
 914             throw new BufferOverflowException();
 915         for (int i = start; i < end; i++)
 916             this.put(src.charAt(i));
 917         return this;
 918     }
 919 
 920     /**
 921      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 922      *
 923      * <p> This method transfers the entire content of the given source string
 924      * into this buffer.  An invocation of this method of the form
 925      * <tt>dst.put(s)</tt> behaves in exactly the same way as the invocation
 926      *
 927      * <pre>
 928      *     dst.put(s, 0, s.length()) </pre>
 929      *
 930      * @return  This buffer
 931      *
 932      * @throws  BufferOverflowException
 933      *          If there is insufficient space in this buffer
 934      *
 935      * @throws  ReadOnlyBufferException
 936      *          If this buffer is read-only
 937      */
 938     public final $Type$Buffer put(String src) {
 939         return put(src, 0, src.length());
 940     }
 941 
 942 #end[char]
 943 
 944 
 945     // -- Other stuff --
 946 
 947     /**
 948      * Tells whether or not this buffer is backed by an accessible $type$
 949      * array.
 950      *
 951      * <p> If this method returns <tt>true</tt> then the {@link #array() array}
 952      * and {@link #arrayOffset() arrayOffset} methods may safely be invoked.
 953      * </p>
 954      *
 955      * @return  <tt>true</tt> if, and only if, this buffer
 956      *          is backed by an array and is not read-only
 957      */
 958     public final boolean hasArray() {
 959         return (hb != null) && !isReadOnly;
 960     }
 961 
 962     /**
 963      * Returns the $type$ array that backs this
 964      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
 965      *
 966      * <p> Modifications to this buffer's content will cause the returned
 967      * array's content to be modified, and vice versa.
 968      *
 969      * <p> Invoke the {@link #hasArray hasArray} method before invoking this
 970      * method in order to ensure that this buffer has an accessible backing
 971      * array.  </p>
 972      *
 973      * @return  The array that backs this buffer
 974      *
 975      * @throws  ReadOnlyBufferException
 976      *          If this buffer is backed by an array but is read-only
 977      *
 978      * @throws  UnsupportedOperationException
 979      *          If this buffer is not backed by an accessible array
 980      */
 981     public final $type$[] array() {
 982         if (hb == null)
 983             throw new UnsupportedOperationException();
 984         if (isReadOnly)
 985             throw new ReadOnlyBufferException();
 986         return hb;
 987     }
 988 
 989     /**
 990      * Returns the offset within this buffer's backing array of the first
 991      * element of the buffer&nbsp;&nbsp;<i>(optional operation)</i>.
 992      *
 993      * <p> If this buffer is backed by an array then buffer position <i>p</i>
 994      * corresponds to array index <i>p</i>&nbsp;+&nbsp;<tt>arrayOffset()</tt>.
 995      *
 996      * <p> Invoke the {@link #hasArray hasArray} method before invoking this
 997      * method in order to ensure that this buffer has an accessible backing
 998      * array.  </p>
 999      *
1000      * @return  The offset within this buffer's array
1001      *          of the first element of the buffer
1002      *
1003      * @throws  ReadOnlyBufferException
1004      *          If this buffer is backed by an array but is read-only
1005      *
1006      * @throws  UnsupportedOperationException
1007      *          If this buffer is not backed by an accessible array
1008      */
1009     public final int arrayOffset() {
1010         if (hb == null)
1011             throw new UnsupportedOperationException();
1012         if (isReadOnly)
1013             throw new ReadOnlyBufferException();
1014         return offset;
1015     }
1016 
1017     /**
1018      * Compacts this buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1019      *
1020      * <p> The $type$s between the buffer's current position and its limit,
1021      * if any, are copied to the beginning of the buffer.  That is, the
1022      * $type$ at index <i>p</i>&nbsp;=&nbsp;<tt>position()</tt> is copied
1023      * to index zero, the $type$ at index <i>p</i>&nbsp;+&nbsp;1 is copied
1024      * to index one, and so forth until the $type$ at index
1025      * <tt>limit()</tt>&nbsp;-&nbsp;1 is copied to index
1026      * <i>n</i>&nbsp;=&nbsp;<tt>limit()</tt>&nbsp;-&nbsp;<tt>1</tt>&nbsp;-&nbsp;<i>p</i>.
1027      * The buffer's position is then set to <i>n+1</i> and its limit is set to
1028      * its capacity.  The mark, if defined, is discarded.
1029      *
1030      * <p> The buffer's position is set to the number of $type$s copied,
1031      * rather than to zero, so that an invocation of this method can be
1032      * followed immediately by an invocation of another relative <i>put</i>
1033      * method. </p>
1034      *
1035 #if[byte]
1036      *
1037      * <p> Invoke this method after writing data from a buffer in case the
1038      * write was incomplete.  The following loop, for example, copies bytes
1039      * from one channel to another via the buffer <tt>buf</tt>:
1040      *
1041      * <blockquote><pre>
1042      * buf.clear();          // Prepare buffer for use
1043      * while (in.read(buf) >= 0 || buf.position != 0) {
1044      *     buf.flip();
1045      *     out.write(buf);
1046      *     buf.compact();    // In case of partial write
1047      * }</pre></blockquote>
1048      *
1049 #end[byte]
1050      *
1051      * @return  This buffer
1052      *
1053      * @throws  ReadOnlyBufferException
1054      *          If this buffer is read-only
1055      */
1056     public abstract $Type$Buffer compact();
1057 
1058     /**
1059      * Tells whether or not this $type$ buffer is direct. </p>
1060      *
1061      * @return  <tt>true</tt> if, and only if, this buffer is direct
1062      */
1063     public abstract boolean isDirect();
1064 
1065 #if[!char]
1066 
1067     /**
1068      * Returns a string summarizing the state of this buffer.  </p>
1069      *
1070      * @return  A summary string
1071      */
1072     public String toString() {
1073         StringBuffer sb = new StringBuffer();
1074         sb.append(getClass().getName());
1075         sb.append("[pos=");
1076         sb.append(position());
1077         sb.append(" lim=");
1078         sb.append(limit());
1079         sb.append(" cap=");
1080         sb.append(capacity());
1081         sb.append("]");
1082         return sb.toString();
1083     }
1084 
1085 #end[!char]
1086 
1087 
1088     // ## Should really use unchecked accessors here for speed
1089 
1090     /**
1091      * Returns the current hash code of this buffer.
1092      *
1093      * <p> The hash code of a $type$ buffer depends only upon its remaining
1094      * elements; that is, upon the elements from <tt>position()</tt> up to, and
1095      * including, the element at <tt>limit()</tt>&nbsp;-&nbsp;<tt>1</tt>.
1096      *
1097      * <p> Because buffer hash codes are content-dependent, it is inadvisable
1098      * to use buffers as keys in hash maps or similar data structures unless it
1099      * is known that their contents will not change.  </p>
1100      *
1101      * @return  The current hash code of this buffer
1102      */
1103     public int hashCode() {
1104         int h = 1;
1105         int p = position();
1106         for (int i = limit() - 1; i >= p; i--)
1107 #if[int]
1108             h = 31 * h + get(i);
1109 #else[int]
1110             h = 31 * h + (int)get(i);
1111 #end[int]
1112         return h;
1113     }
1114 
1115     /**
1116      * Tells whether or not this buffer is equal to another object.
1117      *
1118      * <p> Two $type$ buffers are equal if, and only if,
1119      *
1120      * <p><ol>
1121      *
1122      *   <li><p> They have the same element type,  </p></li>
1123      *
1124      *   <li><p> They have the same number of remaining elements, and
1125      *   </p></li>
1126      *
1127      *   <li><p> The two sequences of remaining elements, considered
1128      *   independently of their starting positions, are pointwise equal.
1129 #if[floatingPointType]
1130      *   This method considers two $type$ elements {@code a} and {@code b}
1131      *   to be equal if
1132      *   {@code (a == b) || ($Fulltype$.isNaN(a) && $Fulltype$.isNaN(b))}.
1133      *   The values {@code -0.0} and {@code +0.0} are considered to be
1134      *   equal, unlike {@link $Fulltype$#equals(Object)}.
1135 #end[floatingPointType]
1136      *   </p></li>
1137      *
1138      * </ol>
1139      *
1140      * <p> A $type$ buffer is not equal to any other type of object.  </p>
1141      *
1142      * @param  ob  The object to which this buffer is to be compared
1143      *
1144      * @return  <tt>true</tt> if, and only if, this buffer is equal to the
1145      *           given object
1146      */
1147     public boolean equals(Object ob) {
1148         if (this == ob)
1149             return true;
1150         if (!(ob instanceof $Type$Buffer))
1151             return false;
1152         $Type$Buffer that = ($Type$Buffer)ob;
1153         if (this.remaining() != that.remaining())
1154             return false;
1155         int p = this.position();
1156         for (int i = this.limit() - 1, j = that.limit() - 1; i >= p; i--, j--)
1157             if (!equals(this.get(i), that.get(j)))
1158                 return false;
1159         return true;
1160     }
1161 
1162     private static boolean equals($type$ x, $type$ y) {
1163 #if[floatingPointType]
1164         return (x == y) || ($Fulltype$.isNaN(x) && $Fulltype$.isNaN(y));
1165 #else[floatingPointType]
1166         return x == y;
1167 #end[floatingPointType]
1168     }
1169 
1170     /**
1171      * Compares this buffer to another.
1172      *
1173      * <p> Two $type$ buffers are compared by comparing their sequences of
1174      * remaining elements lexicographically, without regard to the starting
1175      * position of each sequence within its corresponding buffer.
1176 #if[floatingPointType]
1177      * Pairs of {@code $type$} elements are compared as if by invoking
1178      * {@link $Fulltype$#compare($type$,$type$)}, except that
1179      * {@code -0.0} and {@code 0.0} are considered to be equal.
1180      * {@code $Fulltype$.NaN} is considered by this method to be equal
1181      * to itself and greater than all other {@code $type$} values
1182      * (including {@code $Fulltype$.POSITIVE_INFINITY}).
1183 #else[floatingPointType]
1184      * Pairs of {@code $type$} elements are compared as if by invoking
1185      * {@link $Fulltype$#compare($type$,$type$)}.
1186 #end[floatingPointType]
1187      *
1188      * <p> A $type$ buffer is not comparable to any other type of object.
1189      *
1190      * @return  A negative integer, zero, or a positive integer as this buffer
1191      *          is less than, equal to, or greater than the given buffer
1192      */
1193     public int compareTo($Type$Buffer that) {
1194         int n = this.position() + Math.min(this.remaining(), that.remaining());
1195         for (int i = this.position(), j = that.position(); i < n; i++, j++) {
1196             int cmp = compare(this.get(i), that.get(j));
1197             if (cmp != 0)
1198                 return cmp;
1199         }
1200         return this.remaining() - that.remaining();
1201     }
1202 
1203     private static int compare($type$ x, $type$ y) {
1204 #if[floatingPointType]
1205         return ((x < y)  ? -1 :
1206                 (x > y)  ? +1 :
1207                 (x == y) ?  0 :
1208                 $Fulltype$.isNaN(x) ? ($Fulltype$.isNaN(y) ? 0 : +1) : -1);
1209 #else[floatingPointType]
1210         return $Fulltype$.compare(x, y);
1211 #end[floatingPointType]
1212     }
1213 
1214     // -- Other char stuff --
1215 
1216 #if[char]
1217 
1218     /**
1219      * Returns a string containing the characters in this buffer.
1220      *
1221      * <p> The first character of the resulting string will be the character at
1222      * this buffer's position, while the last character will be the character
1223      * at index <tt>limit()</tt>&nbsp;-&nbsp;1.  Invoking this method does not
1224      * change the buffer's position. </p>
1225      *
1226      * @return  The specified string
1227      */
1228     public String toString() {
1229         return toString(position(), limit());
1230     }
1231 
1232     abstract String toString(int start, int end);       // package-private
1233 
1234 
1235     // --- Methods to support CharSequence ---
1236 
1237     /**
1238      * Returns the length of this character buffer.
1239      *
1240      * <p> When viewed as a character sequence, the length of a character
1241      * buffer is simply the number of characters between the position
1242      * (inclusive) and the limit (exclusive); that is, it is equivalent to
1243      * <tt>remaining()</tt>. </p>
1244      *
1245      * @return  The length of this character buffer
1246      */
1247     public final int length() {
1248         return remaining();
1249     }
1250 
1251     /**
1252      * Reads the character at the given index relative to the current
1253      * position. </p>
1254      *
1255      * @param  index
1256      *         The index of the character to be read, relative to the position;
1257      *         must be non-negative and smaller than <tt>remaining()</tt>
1258      *
1259      * @return  The character at index
1260      *          <tt>position()&nbsp;+&nbsp;index</tt>
1261      *
1262      * @throws  IndexOutOfBoundsException
1263      *          If the preconditions on <tt>index</tt> do not hold
1264      */
1265     public final char charAt(int index) {
1266         return get(position() + checkIndex(index, 1));
1267     }
1268 
1269     /**
1270      * Creates a new character buffer that represents the specified subsequence
1271      * of this buffer, relative to the current position.
1272      *
1273      * <p> The new buffer will share this buffer's content; that is, if the
1274      * content of this buffer is mutable then modifications to one buffer will
1275      * cause the other to be modified.  The new buffer's capacity will be that
1276      * of this buffer, its position will be
1277      * <tt>position()</tt>&nbsp;+&nbsp;<tt>start</tt>, and its limit will be
1278      * <tt>position()</tt>&nbsp;+&nbsp;<tt>end</tt>.  The new buffer will be
1279      * direct if, and only if, this buffer is direct, and it will be read-only
1280      * if, and only if, this buffer is read-only.  </p>
1281      *
1282      * @param  start
1283      *         The index, relative to the current position, of the first
1284      *         character in the subsequence; must be non-negative and no larger
1285      *         than <tt>remaining()</tt>
1286      *
1287      * @param  end
1288      *         The index, relative to the current position, of the character
1289      *         following the last character in the subsequence; must be no
1290      *         smaller than <tt>start</tt> and no larger than
1291      *         <tt>remaining()</tt>
1292      *
1293      * @return  The new character buffer
1294      *
1295      * @throws  IndexOutOfBoundsException
1296      *          If the preconditions on <tt>start</tt> and <tt>end</tt>
1297      *          do not hold
1298      */
1299     public abstract CharBuffer subSequence(int start, int end);
1300 
1301 
1302     // --- Methods to support Appendable ---
1303 
1304     /**
1305      * Appends the specified character sequence  to this
1306      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1307      *
1308      * <p> An invocation of this method of the form <tt>dst.append(csq)</tt>
1309      * behaves in exactly the same way as the invocation
1310      *
1311      * <pre>
1312      *     dst.put(csq.toString()) </pre>
1313      *
1314      * <p> Depending on the specification of <tt>toString</tt> for the
1315      * character sequence <tt>csq</tt>, the entire sequence may not be
1316      * appended.  For instance, invoking the {@link $Type$Buffer#toString()
1317      * toString} method of a character buffer will return a subsequence whose
1318      * content depends upon the buffer's position and limit.
1319      *
1320      * @param  csq
1321      *         The character sequence to append.  If <tt>csq</tt> is
1322      *         <tt>null</tt>, then the four characters <tt>"null"</tt> are
1323      *         appended to this character buffer.
1324      *
1325      * @return  This buffer
1326      *
1327      * @throws  BufferOverflowException
1328      *          If there is insufficient space in this buffer
1329      *
1330      * @throws  ReadOnlyBufferException
1331      *          If this buffer is read-only
1332      *
1333      * @since  1.5
1334      */
1335     public $Type$Buffer append(CharSequence csq) {
1336         if (csq == null)
1337             return put("null");
1338         else
1339             return put(csq.toString());
1340     }
1341 
1342     /**
1343      * Appends a subsequence of the  specified character sequence  to this
1344      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1345      *
1346      * <p> An invocation of this method of the form <tt>dst.append(csq, start,
1347      * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in exactly the
1348      * same way as the invocation
1349      *
1350      * <pre>
1351      *     dst.put(csq.subSequence(start, end).toString()) </pre>
1352      *
1353      * @param  csq
1354      *         The character sequence from which a subsequence will be
1355      *         appended.  If <tt>csq</tt> is <tt>null</tt>, then characters
1356      *         will be appended as if <tt>csq</tt> contained the four
1357      *         characters <tt>"null"</tt>.
1358      *
1359      * @return  This buffer
1360      *
1361      * @throws  BufferOverflowException
1362      *          If there is insufficient space in this buffer
1363      *
1364      * @throws  IndexOutOfBoundsException
1365      *          If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1366      *          is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1367      *          <tt>csq.length()</tt>
1368      *
1369      * @throws  ReadOnlyBufferException
1370      *          If this buffer is read-only
1371      *
1372      * @since  1.5
1373      */
1374     public $Type$Buffer append(CharSequence csq, int start, int end) {
1375         CharSequence cs = (csq == null ? "null" : csq);
1376         return put(cs.subSequence(start, end).toString());
1377     }
1378 
1379     /**
1380      * Appends the specified $type$  to this
1381      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1382      *
1383      * <p> An invocation of this method of the form <tt>dst.append($x$)</tt>
1384      * behaves in exactly the same way as the invocation
1385      *
1386      * <pre>
1387      *     dst.put($x$) </pre>
1388      *
1389      * @param  $x$
1390      *         The 16-bit $type$ to append
1391      *
1392      * @return  This buffer
1393      *
1394      * @throws  BufferOverflowException
1395      *          If there is insufficient space in this buffer
1396      *
1397      * @throws  ReadOnlyBufferException
1398      *          If this buffer is read-only
1399      *
1400      * @since  1.5
1401      */
1402     public $Type$Buffer append($type$ $x$) {
1403         return put($x$);
1404     }
1405 
1406 #end[char]
1407 
1408 
1409     // -- Other byte stuff: Access to binary data --
1410 
1411 #if[!byte]
1412 
1413     /**
1414      * Retrieves this buffer's byte order.
1415      *
1416      * <p> The byte order of $a$ $type$ buffer created by allocation or by
1417      * wrapping an existing <tt>$type$</tt> array is the {@link
1418      * ByteOrder#nativeOrder </code>native order<code>} of the underlying
1419      * hardware.  The byte order of $a$ $type$ buffer created as a <a
1420      * href="ByteBuffer.html#views">view</a> of a byte buffer is that of the
1421      * byte buffer at the moment that the view is created.  </p>
1422      *
1423      * @return  This buffer's byte order
1424      */
1425     public abstract ByteOrder order();
1426 
1427 #end[!byte]
1428 
1429 #if[byte]
1430 
1431     boolean bigEndian                                   // package-private
1432         = true;
1433     boolean nativeByteOrder                             // package-private
1434         = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN);
1435 
1436     /**
1437      * Retrieves this buffer's byte order.
1438      *
1439      * <p> The byte order is used when reading or writing multibyte values, and
1440      * when creating buffers that are views of this byte buffer.  The order of
1441      * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN
1442      * BIG_ENDIAN}.  </p>
1443      *
1444      * @return  This buffer's byte order
1445      */
1446     public final ByteOrder order() {
1447         return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN;
1448     }
1449 
1450     /**
1451      * Modifies this buffer's byte order.  </p>
1452      *
1453      * @param  bo
1454      *         The new byte order,
1455      *         either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
1456      *         or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}
1457      *
1458      * @return  This buffer
1459      */
1460     public final $Type$Buffer order(ByteOrder bo) {
1461         bigEndian = (bo == ByteOrder.BIG_ENDIAN);
1462         nativeByteOrder =
1463             (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN));
1464         return this;
1465     }
1466 
1467     // Unchecked accessors, for use by ByteBufferAs-X-Buffer classes
1468     //
1469     abstract byte _get(int i);                          // package-private
1470     abstract void _put(int i, byte b);                  // package-private
1471 
1472     // #BIN
1473     //
1474     // Binary-data access methods  for short, char, int, long, float,
1475     // and double will be inserted here
1476 
1477 #end[byte]
1478 
1479 #if[streamableType]
1480 
1481 #if[char]
1482     @Override
1483 #end[char]
1484     public $Streamtype$Stream $type$s() {
1485         return StreamSupport.$streamtype$Stream(() -> new $Type$BufferSpliterator(this),
1486             Buffer.SPLITERATOR_CHARACTERISTICS);
1487     }
1488 
1489 #end[streamableType]
1490 
1491 }