1 /*
   2  * Copyright (c) 2000, 2018, 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 import jdk.internal.util.ArraysSupport;
  40 
  41 /**
  42  * $A$ $type$ buffer.
  43  *
  44  * <p> This class defines {#if[byte]?six:four} categories of operations upon
  45  * $type$ buffers:
  46  *
  47  * <ul>
  48  *
  49  *   <li><p> Absolute and relative {@link #get() <i>get</i>} and
  50  *   {@link #put($type$) <i>put</i>} methods that read and write
  51  *   single $type$s; </p></li>
  52  *
  53  *   <li><p> Relative {@link #get($type$[]) <i>bulk get</i>}
  54  *   methods that transfer contiguous sequences of $type$s from this buffer
  55  *   into an array; {#if[!byte]?and}</p></li>
  56  *
  57  *   <li><p> Relative {@link #put($type$[]) <i>bulk put</i>}
  58  *   methods that transfer contiguous sequences of $type$s from $a$
  59  *   $type$ array{#if[char]?, a string,} or some other $type$
  60  *   buffer into this buffer;{#if[!byte]? and} </p></li>
  61  *
  62 #if[byte]
  63  *
  64  *   <li><p> Absolute and relative {@link #getChar() <i>get</i>}
  65  *   and {@link #putChar(char) <i>put</i>} methods that read and
  66  *   write values of other primitive types, translating them to and from
  67  *   sequences of bytes in a particular byte order; </p></li>
  68  *
  69  *   <li><p> Methods for creating <i><a href="#views">view buffers</a></i>,
  70  *   which allow a byte buffer to be viewed as a buffer containing values of
  71  *   some other primitive type; and </p></li>
  72  *
  73 #end[byte]
  74  *
  75  *   <li><p> A method for {@link #compact compacting}
  76  *   $a$ $type$ buffer.  </p></li>
  77  *
  78  * </ul>
  79  *
  80  * <p> $Type$ buffers can be created either by {@link #allocate
  81  * <i>allocation</i>}, which allocates space for the buffer's
  82  *
  83 #if[byte]
  84  *
  85  * content, or by {@link #wrap($type$[]) <i>wrapping</i>} an
  86  * existing $type$ array {#if[char]?or string} into a buffer.
  87  *
  88 #else[byte]
  89  *
  90  * content, by {@link #wrap($type$[]) <i>wrapping</i>} an existing
  91  * $type$ array {#if[char]?or string} into a buffer, or by creating a
  92  * <a href="ByteBuffer.html#views"><i>view</i></a> of an existing byte buffer.
  93  *
  94 #end[byte]
  95  *
  96 #if[byte]
  97  *
  98  * <a id="direct"></a>
  99  * <h2> Direct <i>vs.</i> non-direct buffers </h2>
 100  *
 101  * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>.  Given a
 102  * direct byte buffer, the Java virtual machine will make a best effort to
 103  * perform native I/O operations directly upon it.  That is, it will attempt to
 104  * avoid copying the buffer's content to (or from) an intermediate buffer
 105  * before (or after) each invocation of one of the underlying operating
 106  * system's native I/O operations.
 107  *
 108  * <p> A direct byte buffer may be created by invoking the {@link
 109  * #allocateDirect(int) allocateDirect} factory method of this class.  The
 110  * buffers returned by this method typically have somewhat higher allocation
 111  * and deallocation costs than non-direct buffers.  The contents of direct
 112  * buffers may reside outside of the normal garbage-collected heap, and so
 113  * their impact upon the memory footprint of an application might not be
 114  * obvious.  It is therefore recommended that direct buffers be allocated
 115  * primarily for large, long-lived buffers that are subject to the underlying
 116  * system's native I/O operations.  In general it is best to allocate direct
 117  * buffers only when they yield a measureable gain in program performance.
 118  *
 119  * <p> A direct byte buffer may also be created by {@link
 120  * java.nio.channels.FileChannel#map mapping} a region of a file
 121  * directly into memory.  An implementation of the Java platform may optionally
 122  * support the creation of direct byte buffers from native code via JNI.  If an
 123  * instance of one of these kinds of buffers refers to an inaccessible region
 124  * of memory then an attempt to access that region will not change the buffer's
 125  * content and will cause an unspecified exception to be thrown either at the
 126  * time of the access or at some later time.
 127  *
 128  * <p> Whether a byte buffer is direct or non-direct may be determined by
 129  * invoking its {@link #isDirect isDirect} method.  This method is provided so
 130  * that explicit buffer management can be done in performance-critical code.
 131  *
 132  *
 133  * <a id="bin"></a>
 134  * <h2> Access to binary data </h2>
 135  *
 136  * <p> This class defines methods for reading and writing values of all other
 137  * primitive types, except {@code boolean}.  Primitive values are translated
 138  * to (or from) sequences of bytes according to the buffer's current byte
 139  * order, which may be retrieved and modified via the {@link #order order}
 140  * methods.  Specific byte orders are represented by instances of the {@link
 141  * ByteOrder} class.  The initial order of a byte buffer is always {@link
 142  * ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 143  *
 144  * <p> For access to heterogeneous binary data, that is, sequences of values of
 145  * different types, this class defines a family of absolute and relative
 146  * <i>get</i> and <i>put</i> methods for each type.  For 32-bit floating-point
 147  * values, for example, this class defines:
 148  *
 149  * <blockquote><pre>
 150  * float  {@link #getFloat()}
 151  * float  {@link #getFloat(int) getFloat(int index)}
 152  *  void  {@link #putFloat(float) putFloat(float f)}
 153  *  void  {@link #putFloat(int,float) putFloat(int index, float f)}</pre></blockquote>
 154  *
 155  * <p> Corresponding methods are defined for the types {@code char,
 156  * short, int, long}, and {@code double}.  The index
 157  * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of
 158  * bytes rather than of the type being read or written.
 159  *
 160  * <a id="views"></a>
 161  *
 162  * <p> For access to homogeneous binary data, that is, sequences of values of
 163  * the same type, this class defines methods that can create <i>views</i> of a
 164  * given byte buffer.  A <i>view buffer</i> is simply another buffer whose
 165  * content is backed by the byte buffer.  Changes to the byte buffer's content
 166  * will be visible in the view buffer, and vice versa; the two buffers'
 167  * position, limit, and mark values are independent.  The {@link
 168  * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of
 169  * the {@link FloatBuffer} class that is backed by the byte buffer upon which
 170  * the method is invoked.  Corresponding view-creation methods are defined for
 171  * the types {@code char, short, int, long}, and {@code double}.
 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 {@code wrap} 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 {@link java.util.regex}.
 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;
 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     @Override
 293     Object base() {
 294         return hb;
 295     }
 296 
 297 #if[byte]
 298 
 299     /**
 300      * Allocates a new direct $type$ buffer.
 301      *
 302      * <p> The new buffer's position will be zero, its limit will be its
 303      * capacity, its mark will be undefined, each of its elements will be
 304      * initialized to zero, and its byte order will be
 305      * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.  Whether or not it has a
 306      * {@link #hasArray backing array} is unspecified.
 307      *
 308      * @param  capacity
 309      *         The new buffer's capacity, in $type$s
 310      *
 311      * @return  The new $type$ buffer
 312      *
 313      * @throws  IllegalArgumentException
 314      *          If the {@code capacity} is a negative integer
 315      */
 316     public static $Type$Buffer allocateDirect(int capacity) {
 317         return new Direct$Type$Buffer(capacity);
 318     }
 319 
 320 #end[byte]
 321 
 322     /**
 323      * Allocates a new $type$ buffer.
 324      *
 325      * <p> The new buffer's position will be zero, its limit will be its
 326      * capacity, its mark will be undefined, each of its elements will be
 327      * initialized to zero, and its byte order will be
 328 #if[byte]
 329      * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 330 #else[byte]
 331      * the {@link ByteOrder#nativeOrder native order} of the underlying
 332      * hardware.
 333 #end[byte]
 334      * It will have a {@link #array backing array}, and its
 335      * {@link #arrayOffset array offset} will be zero.
 336      *
 337      * @param  capacity
 338      *         The new buffer's capacity, in $type$s
 339      *
 340      * @return  The new $type$ buffer
 341      *
 342      * @throws  IllegalArgumentException
 343      *          If the {@code capacity} is a negative integer
 344      */
 345     public static $Type$Buffer allocate(int capacity) {
 346         if (capacity < 0)
 347             throw createCapacityException(capacity);
 348         return new Heap$Type$Buffer(capacity, capacity);
 349     }
 350 
 351     /**
 352      * Wraps $a$ $type$ array into a buffer.
 353      *
 354      * <p> The new buffer will be backed by the given $type$ array;
 355      * that is, modifications to the buffer will cause the array to be modified
 356      * and vice versa.  The new buffer's capacity will be
 357      * {@code array.length}, its position will be {@code offset}, its limit
 358      * will be {@code offset + length}, its mark will be undefined, and its
 359      * byte order will be
 360 #if[byte]
 361      * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 362 #else[byte]
 363      * the {@link ByteOrder#nativeOrder native order} of the underlying
 364      * hardware.
 365 #end[byte]
 366      * Its {@link #array backing array} will be the given array, and
 367      * its {@link #arrayOffset array offset} will be zero.  </p>
 368      *
 369      * @param  array
 370      *         The array that will back the new buffer
 371      *
 372      * @param  offset
 373      *         The offset of the subarray to be used; must be non-negative and
 374      *         no larger than {@code array.length}.  The new buffer's position
 375      *         will be set to this value.
 376      *
 377      * @param  length
 378      *         The length of the subarray to be used;
 379      *         must be non-negative and no larger than
 380      *         {@code array.length - offset}.
 381      *         The new buffer's limit will be set to {@code offset + length}.
 382      *
 383      * @return  The new $type$ buffer
 384      *
 385      * @throws  IndexOutOfBoundsException
 386      *          If the preconditions on the {@code offset} and {@code length}
 387      *          parameters do not hold
 388      */
 389     public static $Type$Buffer wrap($type$[] array,
 390                                     int offset, int length)
 391     {
 392         try {
 393             return new Heap$Type$Buffer(array, offset, length);
 394         } catch (IllegalArgumentException x) {
 395             throw new IndexOutOfBoundsException();
 396         }
 397     }
 398 
 399     /**
 400      * Wraps $a$ $type$ array into a buffer.
 401      *
 402      * <p> The new buffer will be backed by the given $type$ array;
 403      * that is, modifications to the buffer will cause the array to be modified
 404      * and vice versa.  The new buffer's capacity and limit will be
 405      * {@code array.length}, its position will be zero, its mark will be
 406      * undefined, and its byte order will be
 407 #if[byte]
 408      * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 409 #else[byte]
 410      * the {@link ByteOrder#nativeOrder native order} of the underlying
 411      * hardware.
 412 #end[byte]
 413      * Its {@link #array backing array} will be the given array, and its
 414      * {@link #arrayOffset array offset} will be zero.  </p>
 415      *
 416      * @param  array
 417      *         The array that will back this buffer
 418      *
 419      * @return  The new $type$ buffer
 420      */
 421     public static $Type$Buffer wrap($type$[] array) {
 422         return wrap(array, 0, array.length);
 423     }
 424 
 425 #if[char]
 426 
 427     /**
 428      * Attempts to read characters into the specified character buffer.
 429      * The buffer is used as a repository of characters as-is: the only
 430      * changes made are the results of a put operation. No flipping or
 431      * rewinding of the buffer is performed.
 432      *
 433      * @param target the buffer to read characters into
 434      * @return The number of characters added to the buffer, or
 435      *         -1 if this source of characters is at its end
 436      * @throws IOException if an I/O error occurs
 437      * @throws NullPointerException if target is null
 438      * @throws ReadOnlyBufferException if target is a read only buffer
 439      * @since 1.5
 440      */
 441     public int read(CharBuffer target) throws IOException {
 442         // Determine the number of bytes n that can be transferred
 443         int targetRemaining = target.remaining();
 444         int remaining = remaining();
 445         if (remaining == 0)
 446             return -1;
 447         int n = Math.min(remaining, targetRemaining);
 448         int limit = limit();
 449         // Set source limit to prevent target overflow
 450         if (targetRemaining < remaining)
 451             limit(position() + n);
 452         try {
 453             if (n > 0)
 454                 target.put(this);
 455         } finally {
 456             limit(limit); // restore real limit
 457         }
 458         return n;
 459     }
 460 
 461     /**
 462      * Wraps a character sequence into a buffer.
 463      *
 464      * <p> The content of the new, read-only buffer will be the content of the
 465      * given character sequence.  The buffer's capacity will be
 466      * {@code csq.length()}, its position will be {@code start}, its limit
 467      * will be {@code end}, and its mark will be undefined.  </p>
 468      *
 469      * @param  csq
 470      *         The character sequence from which the new character buffer is to
 471      *         be created
 472      *
 473      * @param  start
 474      *         The index of the first character to be used;
 475      *         must be non-negative and no larger than {@code csq.length()}.
 476      *         The new buffer's position will be set to this value.
 477      *
 478      * @param  end
 479      *         The index of the character following the last character to be
 480      *         used; must be no smaller than {@code start} and no larger
 481      *         than {@code csq.length()}.
 482      *         The new buffer's limit will be set to this value.
 483      *
 484      * @return  The new character buffer
 485      *
 486      * @throws  IndexOutOfBoundsException
 487      *          If the preconditions on the {@code start} and {@code end}
 488      *          parameters do not hold
 489      */
 490     public static CharBuffer wrap(CharSequence csq, int start, int end) {
 491         try {
 492             return new StringCharBuffer(csq, start, end);
 493         } catch (IllegalArgumentException x) {
 494             throw new IndexOutOfBoundsException();
 495         }
 496     }
 497 
 498     /**
 499      * Wraps a character sequence into a buffer.
 500      *
 501      * <p> The content of the new, read-only buffer will be the content of the
 502      * given character sequence.  The new buffer's capacity and limit will be
 503      * {@code csq.length()}, its position will be zero, and its mark will be
 504      * undefined.  </p>
 505      *
 506      * @param  csq
 507      *         The character sequence from which the new character buffer is to
 508      *         be created
 509      *
 510      * @return  The new character buffer
 511      */
 512     public static CharBuffer wrap(CharSequence csq) {
 513         return wrap(csq, 0, csq.length());
 514     }
 515 
 516 #end[char]
 517 
 518     /**
 519      * Creates a new $type$ buffer whose content is a shared subsequence of
 520      * this buffer's content.
 521      *
 522      * <p> The content of the new buffer will start at this buffer's current
 523      * position.  Changes to this buffer's content will be visible in the new
 524      * buffer, and vice versa; the two buffers' position, limit, and mark
 525      * values will be independent.
 526      *
 527      * <p> The new buffer's position will be zero, its capacity and its limit
 528      * will be the number of $type$s remaining in this buffer, its mark will be
 529      * undefined, and its byte order will be
 530 #if[byte]
 531      * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 532 #else[byte]
 533      * identical to that of this buffer.
 534 #end[byte]
 535      * The new buffer will be direct if, and only if, this buffer is direct, and
 536      * it will be read-only if, and only if, this buffer is read-only.  </p>
 537      *
 538      * @return  The new $type$ buffer
 539 #if[byte]
 540      *
 541      * @see #alignedSlice(int)
 542 #end[byte]
 543      */
 544     @Override
 545     public abstract $Type$Buffer slice();
 546 
 547     /**
 548      * Creates a new $type$ buffer that shares this buffer's content.
 549      *
 550      * <p> The content of the new buffer will be that of this buffer.  Changes
 551      * to this buffer's content will be visible in the new buffer, and vice
 552      * versa; the two buffers' position, limit, and mark values will be
 553      * independent.
 554      *
 555      * <p> The new buffer's capacity, limit, position,
 556 #if[byte]
 557      * and mark values will be identical to those of this buffer, and its byte
 558      * order will be {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 559 #else[byte]
 560      * mark values, and byte order will be identical to those of this buffer.
 561 #end[byte]
 562      * The new buffer will be direct if, and only if, this buffer is direct, and
 563      * it will be read-only if, and only if, this buffer is read-only.  </p>
 564      *
 565      * @return  The new $type$ buffer
 566      */
 567     @Override
 568     public abstract $Type$Buffer duplicate();
 569 
 570     /**
 571      * Creates a new, read-only $type$ buffer that shares this buffer's
 572      * content.
 573      *
 574      * <p> The content of the new buffer will be that of this buffer.  Changes
 575      * to this buffer's content will be visible in the new buffer; the new
 576      * buffer itself, however, will be read-only and will not allow the shared
 577      * content to be modified.  The two buffers' position, limit, and mark
 578      * values will be independent.
 579      *
 580      * <p> The new buffer's capacity, limit, position,
 581 #if[byte]
 582      * and mark values will be identical to those of this buffer, and its byte
 583      * order will be {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 584 #else[byte]
 585      * mark values, and byte order will be identical to those of this buffer.
 586 #end[byte]
 587      *
 588      * <p> If this buffer is itself read-only then this method behaves in
 589      * exactly the same way as the {@link #duplicate duplicate} method.  </p>
 590      *
 591      * @return  The new, read-only $type$ buffer
 592      */
 593     public abstract $Type$Buffer asReadOnlyBuffer();
 594 
 595 
 596     // -- Singleton get/put methods --
 597 
 598     /**
 599      * Relative <i>get</i> method.  Reads the $type$ at this buffer's
 600      * current position, and then increments the position.
 601      *
 602      * @return  The $type$ at the buffer's current position
 603      *
 604      * @throws  BufferUnderflowException
 605      *          If the buffer's current position is not smaller than its limit
 606      */
 607     public abstract $type$ get();
 608 
 609     /**
 610      * Relative <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 611      *
 612      * <p> Writes the given $type$ into this buffer at the current
 613      * position, and then increments the position. </p>
 614      *
 615      * @param  $x$
 616      *         The $type$ to be written
 617      *
 618      * @return  This buffer
 619      *
 620      * @throws  BufferOverflowException
 621      *          If this buffer's current position is not smaller than its limit
 622      *
 623      * @throws  ReadOnlyBufferException
 624      *          If this buffer is read-only
 625      */
 626     public abstract $Type$Buffer put($type$ $x$);
 627 
 628     /**
 629      * Absolute <i>get</i> method.  Reads the $type$ at the given
 630      * index.
 631      *
 632      * @param  index
 633      *         The index from which the $type$ will be read
 634      *
 635      * @return  The $type$ at the given index
 636      *
 637      * @throws  IndexOutOfBoundsException
 638      *          If {@code index} is negative
 639      *          or not smaller than the buffer's limit
 640      */
 641     public abstract $type$ get(int index);
 642 
 643 #if[streamableType]
 644     /**
 645      * Absolute <i>get</i> method.  Reads the $type$ at the given
 646      * index without any validation of the index.
 647      *
 648      * @param  index
 649      *         The index from which the $type$ will be read
 650      *
 651      * @return  The $type$ at the given index
 652      */
 653     abstract $type$ getUnchecked(int index);   // package-private
 654 #end[streamableType]
 655 
 656     /**
 657      * Absolute <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 658      *
 659      * <p> Writes the given $type$ into this buffer at the given
 660      * index. </p>
 661      *
 662      * @param  index
 663      *         The index at which the $type$ will be written
 664      *
 665      * @param  $x$
 666      *         The $type$ value to be written
 667      *
 668      * @return  This buffer
 669      *
 670      * @throws  IndexOutOfBoundsException
 671      *          If {@code index} is negative
 672      *          or not smaller than the buffer's limit
 673      *
 674      * @throws  ReadOnlyBufferException
 675      *          If this buffer is read-only
 676      */
 677     public abstract $Type$Buffer put(int index, $type$ $x$);
 678 
 679 
 680     // -- Bulk get operations --
 681 
 682     /**
 683      * Relative bulk <i>get</i> method.
 684      *
 685      * <p> This method transfers $type$s from this buffer into the given
 686      * destination array.  If there are fewer $type$s remaining in the
 687      * buffer than are required to satisfy the request, that is, if
 688      * {@code length}&nbsp;{@code >}&nbsp;{@code remaining()}, then no
 689      * $type$s are transferred and a {@link BufferUnderflowException} is
 690      * thrown.
 691      *
 692      * <p> Otherwise, this method copies {@code length} $type$s from this
 693      * buffer into the given array, starting at the current position of this
 694      * buffer and at the given offset in the array.  The position of this
 695      * buffer is then incremented by {@code length}.
 696      *
 697      * <p> In other words, an invocation of this method of the form
 698      * <code>src.get(dst,&nbsp;off,&nbsp;len)</code> has exactly the same effect as
 699      * the loop
 700      *
 701      * <pre>{@code
 702      *     for (int i = off; i < off + len; i++)
 703      *         dst[i] = src.get():
 704      * }</pre>
 705      *
 706      * except that it first checks that there are sufficient $type$s in
 707      * this buffer and it is potentially much more efficient.
 708      *
 709      * @param  dst
 710      *         The array into which $type$s are to be written
 711      *
 712      * @param  offset
 713      *         The offset within the array of the first $type$ to be
 714      *         written; must be non-negative and no larger than
 715      *         {@code dst.length}
 716      *
 717      * @param  length
 718      *         The maximum number of $type$s to be written to the given
 719      *         array; must be non-negative and no larger than
 720      *         {@code dst.length - offset}
 721      *
 722      * @return  This buffer
 723      *
 724      * @throws  BufferUnderflowException
 725      *          If there are fewer than {@code length} $type$s
 726      *          remaining in this buffer
 727      *
 728      * @throws  IndexOutOfBoundsException
 729      *          If the preconditions on the {@code offset} and {@code length}
 730      *          parameters do not hold
 731      */
 732     public $Type$Buffer get($type$[] dst, int offset, int length) {
 733         checkBounds(offset, length, dst.length);
 734         if (length > remaining())
 735             throw new BufferUnderflowException();
 736         int end = offset + length;
 737         for (int i = offset; i < end; i++)
 738             dst[i] = get();
 739         return this;
 740     }
 741 
 742     /**
 743      * Relative bulk <i>get</i> method.
 744      *
 745      * <p> This method transfers $type$s from this buffer into the given
 746      * destination array.  An invocation of this method of the form
 747      * {@code src.get(a)} behaves in exactly the same way as the invocation
 748      *
 749      * <pre>
 750      *     src.get(a, 0, a.length) </pre>
 751      *
 752      * @param   dst
 753      *          The destination array
 754      *
 755      * @return  This buffer
 756      *
 757      * @throws  BufferUnderflowException
 758      *          If there are fewer than {@code length} $type$s
 759      *          remaining in this buffer
 760      */
 761     public $Type$Buffer get($type$[] dst) {
 762         return get(dst, 0, dst.length);
 763     }
 764 
 765 
 766     // -- Bulk put operations --
 767 
 768     /**
 769      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 770      *
 771      * <p> This method transfers the $type$s remaining in the given source
 772      * buffer into this buffer.  If there are more $type$s remaining in the
 773      * source buffer than in this buffer, that is, if
 774      * {@code src.remaining()}&nbsp;{@code >}&nbsp;{@code remaining()},
 775      * then no $type$s are transferred and a {@link
 776      * BufferOverflowException} is thrown.
 777      *
 778      * <p> Otherwise, this method copies
 779      * <i>n</i>&nbsp;=&nbsp;{@code src.remaining()} $type$s from the given
 780      * buffer into this buffer, starting at each buffer's current position.
 781      * The positions of both buffers are then incremented by <i>n</i>.
 782      *
 783      * <p> In other words, an invocation of this method of the form
 784      * {@code dst.put(src)} has exactly the same effect as the loop
 785      *
 786      * <pre>
 787      *     while (src.hasRemaining())
 788      *         dst.put(src.get()); </pre>
 789      *
 790      * except that it first checks that there is sufficient space in this
 791      * buffer and it is potentially much more efficient.
 792      *
 793      * @param  src
 794      *         The source buffer from which $type$s are to be read;
 795      *         must not be this buffer
 796      *
 797      * @return  This buffer
 798      *
 799      * @throws  BufferOverflowException
 800      *          If there is insufficient space in this buffer
 801      *          for the remaining $type$s in the source buffer
 802      *
 803      * @throws  IllegalArgumentException
 804      *          If the source buffer is this buffer
 805      *
 806      * @throws  ReadOnlyBufferException
 807      *          If this buffer is read-only
 808      */
 809     public $Type$Buffer put($Type$Buffer src) {
 810         if (src == this)
 811             throw createSameBufferException();
 812         if (isReadOnly())
 813             throw new ReadOnlyBufferException();
 814         int n = src.remaining();
 815         if (n > remaining())
 816             throw new BufferOverflowException();
 817         for (int i = 0; i < n; i++)
 818             put(src.get());
 819         return this;
 820     }
 821 
 822     /**
 823      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 824      *
 825      * <p> This method transfers $type$s into this buffer from the given
 826      * source array.  If there are more $type$s to be copied from the array
 827      * than remain in this buffer, that is, if
 828      * {@code length}&nbsp;{@code >}&nbsp;{@code remaining()}, then no
 829      * $type$s are transferred and a {@link BufferOverflowException} is
 830      * thrown.
 831      *
 832      * <p> Otherwise, this method copies {@code length} $type$s from the
 833      * given array into this buffer, starting at the given offset in the array
 834      * and at the current position of this buffer.  The position of this buffer
 835      * is then incremented by {@code length}.
 836      *
 837      * <p> In other words, an invocation of this method of the form
 838      * <code>dst.put(src,&nbsp;off,&nbsp;len)</code> has exactly the same effect as
 839      * the loop
 840      *
 841      * <pre>{@code
 842      *     for (int i = off; i < off + len; i++)
 843      *         dst.put(a[i]);
 844      * }</pre>
 845      *
 846      * except that it first checks that there is sufficient space in this
 847      * buffer and it is potentially much more efficient.
 848      *
 849      * @param  src
 850      *         The array from which $type$s are to be read
 851      *
 852      * @param  offset
 853      *         The offset within the array of the first $type$ to be read;
 854      *         must be non-negative and no larger than {@code array.length}
 855      *
 856      * @param  length
 857      *         The number of $type$s to be read from the given array;
 858      *         must be non-negative and no larger than
 859      *         {@code array.length - offset}
 860      *
 861      * @return  This buffer
 862      *
 863      * @throws  BufferOverflowException
 864      *          If there is insufficient space in this buffer
 865      *
 866      * @throws  IndexOutOfBoundsException
 867      *          If the preconditions on the {@code offset} and {@code length}
 868      *          parameters do not hold
 869      *
 870      * @throws  ReadOnlyBufferException
 871      *          If this buffer is read-only
 872      */
 873     public $Type$Buffer put($type$[] src, int offset, int length) {
 874         checkBounds(offset, length, src.length);
 875         if (length > remaining())
 876             throw new BufferOverflowException();
 877         int end = offset + length;
 878         for (int i = offset; i < end; i++)
 879             this.put(src[i]);
 880         return this;
 881     }
 882 
 883     /**
 884      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 885      *
 886      * <p> This method transfers the entire content of the given source
 887      * $type$ array into this buffer.  An invocation of this method of the
 888      * form {@code dst.put(a)} behaves in exactly the same way as the
 889      * invocation
 890      *
 891      * <pre>
 892      *     dst.put(a, 0, a.length) </pre>
 893      *
 894      * @param   src
 895      *          The source array
 896      *
 897      * @return  This buffer
 898      *
 899      * @throws  BufferOverflowException
 900      *          If there is insufficient space in this buffer
 901      *
 902      * @throws  ReadOnlyBufferException
 903      *          If this buffer is read-only
 904      */
 905     public final $Type$Buffer put($type$[] src) {
 906         return put(src, 0, src.length);
 907     }
 908 
 909 #if[char]
 910 
 911     /**
 912      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 913      *
 914      * <p> This method transfers $type$s from the given string into this
 915      * buffer.  If there are more $type$s to be copied from the string than
 916      * remain in this buffer, that is, if
 917      * <code>end&nbsp;-&nbsp;start</code>&nbsp;{@code >}&nbsp;{@code remaining()},
 918      * then no $type$s are transferred and a {@link
 919      * BufferOverflowException} is thrown.
 920      *
 921      * <p> Otherwise, this method copies
 922      * <i>n</i>&nbsp;=&nbsp;{@code end}&nbsp;-&nbsp;{@code start} $type$s
 923      * from the given string into this buffer, starting at the given
 924      * {@code start} index and at the current position of this buffer.  The
 925      * position of this buffer is then incremented by <i>n</i>.
 926      *
 927      * <p> In other words, an invocation of this method of the form
 928      * <code>dst.put(src,&nbsp;start,&nbsp;end)</code> has exactly the same effect
 929      * as the loop
 930      *
 931      * <pre>{@code
 932      *     for (int i = start; i < end; i++)
 933      *         dst.put(src.charAt(i));
 934      * }</pre>
 935      *
 936      * except that it first checks that there is sufficient space in this
 937      * buffer and it is potentially much more efficient.
 938      *
 939      * @param  src
 940      *         The string from which $type$s are to be read
 941      *
 942      * @param  start
 943      *         The offset within the string of the first $type$ to be read;
 944      *         must be non-negative and no larger than
 945      *         {@code string.length()}
 946      *
 947      * @param  end
 948      *         The offset within the string of the last $type$ to be read,
 949      *         plus one; must be non-negative and no larger than
 950      *         {@code string.length()}
 951      *
 952      * @return  This buffer
 953      *
 954      * @throws  BufferOverflowException
 955      *          If there is insufficient space in this buffer
 956      *
 957      * @throws  IndexOutOfBoundsException
 958      *          If the preconditions on the {@code start} and {@code end}
 959      *          parameters do not hold
 960      *
 961      * @throws  ReadOnlyBufferException
 962      *          If this buffer is read-only
 963      */
 964     public $Type$Buffer put(String src, int start, int end) {
 965         checkBounds(start, end - start, src.length());
 966         if (isReadOnly())
 967             throw new ReadOnlyBufferException();
 968         if (end - start > remaining())
 969             throw new BufferOverflowException();
 970         for (int i = start; i < end; i++)
 971             this.put(src.charAt(i));
 972         return this;
 973     }
 974 
 975     /**
 976      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 977      *
 978      * <p> This method transfers the entire content of the given source string
 979      * into this buffer.  An invocation of this method of the form
 980      * {@code dst.put(s)} behaves in exactly the same way as the invocation
 981      *
 982      * <pre>
 983      *     dst.put(s, 0, s.length()) </pre>
 984      *
 985      * @param   src
 986      *          The source string
 987      *
 988      * @return  This buffer
 989      *
 990      * @throws  BufferOverflowException
 991      *          If there is insufficient space in this buffer
 992      *
 993      * @throws  ReadOnlyBufferException
 994      *          If this buffer is read-only
 995      */
 996     public final $Type$Buffer put(String src) {
 997         return put(src, 0, src.length());
 998     }
 999 
1000 #end[char]
1001 
1002 
1003     // -- Other stuff --
1004 
1005     /**
1006      * Tells whether or not this buffer is backed by an accessible $type$
1007      * array.
1008      *
1009      * <p> If this method returns {@code true} then the {@link #array() array}
1010      * and {@link #arrayOffset() arrayOffset} methods may safely be invoked.
1011      * </p>
1012      *
1013      * @return  {@code true} if, and only if, this buffer
1014      *          is backed by an array and is not read-only
1015      */
1016     public final boolean hasArray() {
1017         return (hb != null) && !isReadOnly;
1018     }
1019 
1020     /**
1021      * Returns the $type$ array that backs this
1022      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1023      *
1024      * <p> Modifications to this buffer's content will cause the returned
1025      * array's content to be modified, and vice versa.
1026      *
1027      * <p> Invoke the {@link #hasArray hasArray} method before invoking this
1028      * method in order to ensure that this buffer has an accessible backing
1029      * array.  </p>
1030      *
1031      * @return  The array that backs this buffer
1032      *
1033      * @throws  ReadOnlyBufferException
1034      *          If this buffer is backed by an array but is read-only
1035      *
1036      * @throws  UnsupportedOperationException
1037      *          If this buffer is not backed by an accessible array
1038      */
1039     public final $type$[] array() {
1040         if (hb == null)
1041             throw new UnsupportedOperationException();
1042         if (isReadOnly)
1043             throw new ReadOnlyBufferException();
1044         return hb;
1045     }
1046 
1047     /**
1048      * Returns the offset within this buffer's backing array of the first
1049      * element of the buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1050      *
1051      * <p> If this buffer is backed by an array then buffer position <i>p</i>
1052      * corresponds to array index <i>p</i>&nbsp;+&nbsp;{@code arrayOffset()}.
1053      *
1054      * <p> Invoke the {@link #hasArray hasArray} method before invoking this
1055      * method in order to ensure that this buffer has an accessible backing
1056      * array.  </p>
1057      *
1058      * @return  The offset within this buffer's array
1059      *          of the first element of the buffer
1060      *
1061      * @throws  ReadOnlyBufferException
1062      *          If this buffer is backed by an array but is read-only
1063      *
1064      * @throws  UnsupportedOperationException
1065      *          If this buffer is not backed by an accessible array
1066      */
1067     public final int arrayOffset() {
1068         if (hb == null)
1069             throw new UnsupportedOperationException();
1070         if (isReadOnly)
1071             throw new ReadOnlyBufferException();
1072         return offset;
1073     }
1074 
1075     // -- Covariant return type overrides
1076 
1077     /**
1078      * {@inheritDoc}
1079      */
1080     @Override
1081     public
1082 #if[!byte]
1083     final
1084 #end[!byte]
1085     $Type$Buffer position(int newPosition) {
1086         super.position(newPosition);
1087         return this;
1088     }
1089     
1090     /**
1091      * {@inheritDoc}
1092      */
1093     @Override
1094     public
1095 #if[!byte]
1096     final
1097 #end[!byte]
1098     $Type$Buffer limit(int newLimit) {
1099         super.limit(newLimit);
1100         return this;
1101     }
1102     
1103     /**
1104      * {@inheritDoc}
1105      */
1106     @Override
1107     public 
1108 #if[!byte]
1109     final
1110 #end[!byte]
1111     $Type$Buffer mark() {
1112         super.mark();
1113         return this;
1114     }
1115 
1116     /**
1117      * {@inheritDoc}
1118      */
1119     @Override
1120     public 
1121 #if[!byte]
1122     final
1123 #end[!byte]
1124     $Type$Buffer reset() {
1125         super.reset();
1126         return this;
1127     }
1128 
1129     /**
1130      * {@inheritDoc}
1131      */
1132     @Override
1133     public 
1134 #if[!byte]
1135     final
1136 #end[!byte]
1137     $Type$Buffer clear() {
1138         super.clear();
1139         return this;
1140     }
1141 
1142     /**
1143      * {@inheritDoc}
1144      */
1145     @Override
1146     public 
1147 #if[!byte]
1148     final
1149 #end[!byte]
1150     $Type$Buffer flip() {
1151         super.flip();
1152         return this;
1153     }
1154 
1155     /**
1156      * {@inheritDoc}
1157      */
1158     @Override
1159     public 
1160 #if[!byte]
1161     final
1162 #end[!byte]
1163     $Type$Buffer rewind() {
1164         super.rewind();
1165         return this;
1166     }
1167 
1168     /**
1169      * Compacts this buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1170      *
1171      * <p> The $type$s between the buffer's current position and its limit,
1172      * if any, are copied to the beginning of the buffer.  That is, the
1173      * $type$ at index <i>p</i>&nbsp;=&nbsp;{@code position()} is copied
1174      * to index zero, the $type$ at index <i>p</i>&nbsp;+&nbsp;1 is copied
1175      * to index one, and so forth until the $type$ at index
1176      * {@code limit()}&nbsp;-&nbsp;1 is copied to index
1177      * <i>n</i>&nbsp;=&nbsp;{@code limit()}&nbsp;-&nbsp;{@code 1}&nbsp;-&nbsp;<i>p</i>.
1178      * The buffer's position is then set to <i>n+1</i> and its limit is set to
1179      * its capacity.  The mark, if defined, is discarded.
1180      *
1181      * <p> The buffer's position is set to the number of $type$s copied,
1182      * rather than to zero, so that an invocation of this method can be
1183      * followed immediately by an invocation of another relative <i>put</i>
1184      * method. </p>
1185      *
1186 #if[byte]
1187      *
1188      * <p> Invoke this method after writing data from a buffer in case the
1189      * write was incomplete.  The following loop, for example, copies bytes
1190      * from one channel to another via the buffer {@code buf}:
1191      *
1192      * <blockquote><pre>{@code
1193      *   buf.clear();          // Prepare buffer for use
1194      *   while (in.read(buf) >= 0 || buf.position != 0) {
1195      *       buf.flip();
1196      *       out.write(buf);
1197      *       buf.compact();    // In case of partial write
1198      *   }
1199      * }</pre></blockquote>
1200      *
1201 #end[byte]
1202      *
1203      * @return  This buffer
1204      *
1205      * @throws  ReadOnlyBufferException
1206      *          If this buffer is read-only
1207      */
1208     public abstract $Type$Buffer compact();
1209 
1210     /**
1211      * Tells whether or not this $type$ buffer is direct.
1212      *
1213      * @return  {@code true} if, and only if, this buffer is direct
1214      */
1215     public abstract boolean isDirect();
1216 
1217 #if[!char]
1218 
1219     /**
1220      * Returns a string summarizing the state of this buffer.
1221      *
1222      * @return  A summary string
1223      */
1224     public String toString() {
1225         StringBuffer sb = new StringBuffer();
1226         sb.append(getClass().getName());
1227         sb.append("[pos=");
1228         sb.append(position());
1229         sb.append(" lim=");
1230         sb.append(limit());
1231         sb.append(" cap=");
1232         sb.append(capacity());
1233         sb.append("]");
1234         return sb.toString();
1235     }
1236 
1237 #end[!char]
1238 
1239 
1240     // ## Should really use unchecked accessors here for speed
1241 
1242     /**
1243      * Returns the current hash code of this buffer.
1244      *
1245      * <p> The hash code of a $type$ buffer depends only upon its remaining
1246      * elements; that is, upon the elements from {@code position()} up to, and
1247      * including, the element at {@code limit()}&nbsp;-&nbsp;{@code 1}.
1248      *
1249      * <p> Because buffer hash codes are content-dependent, it is inadvisable
1250      * to use buffers as keys in hash maps or similar data structures unless it
1251      * is known that their contents will not change.  </p>
1252      *
1253      * @return  The current hash code of this buffer
1254      */
1255     public int hashCode() {
1256         int h = 1;
1257         int p = position();
1258         for (int i = limit() - 1; i >= p; i--)
1259 #if[int]
1260             h = 31 * h + get(i);
1261 #else[int]
1262             h = 31 * h + (int)get(i);
1263 #end[int]
1264         return h;
1265     }
1266 
1267     /**
1268      * Tells whether or not this buffer is equal to another object.
1269      *
1270      * <p> Two $type$ buffers are equal if, and only if,
1271      *
1272      * <ol>
1273      *
1274      *   <li><p> They have the same element type,  </p></li>
1275      *
1276      *   <li><p> They have the same number of remaining elements, and
1277      *   </p></li>
1278      *
1279      *   <li><p> The two sequences of remaining elements, considered
1280      *   independently of their starting positions, are pointwise equal.
1281 #if[floatingPointType]
1282      *   This method considers two $type$ elements {@code a} and {@code b}
1283      *   to be equal if
1284      *   {@code (a == b) || ($Fulltype$.isNaN(a) && $Fulltype$.isNaN(b))}.
1285      *   The values {@code -0.0} and {@code +0.0} are considered to be
1286      *   equal, unlike {@link $Fulltype$#equals(Object)}.
1287 #end[floatingPointType]
1288      *   </p></li>
1289      *
1290      * </ol>
1291      *
1292      * <p> A $type$ buffer is not equal to any other type of object.  </p>
1293      *
1294      * @param  ob  The object to which this buffer is to be compared
1295      *
1296      * @return  {@code true} if, and only if, this buffer is equal to the
1297      *           given object
1298      */
1299     public boolean equals(Object ob) {
1300         if (this == ob)
1301             return true;
1302         if (!(ob instanceof $Type$Buffer))
1303             return false;
1304         $Type$Buffer that = ($Type$Buffer)ob;
1305         if (this.remaining() != that.remaining())
1306             return false;
1307         return BufferMismatch.mismatch(this, this.position(),
1308                                        that, that.position(),
1309                                        this.remaining()) < 0;
1310     }
1311 
1312     /**
1313      * Compares this buffer to another.
1314      *
1315      * <p> Two $type$ buffers are compared by comparing their sequences of
1316      * remaining elements lexicographically, without regard to the starting
1317      * position of each sequence within its corresponding buffer.
1318 #if[floatingPointType]
1319      * Pairs of {@code $type$} elements are compared as if by invoking
1320      * {@link $Fulltype$#compare($type$,$type$)}, except that
1321      * {@code -0.0} and {@code 0.0} are considered to be equal.
1322      * {@code $Fulltype$.NaN} is considered by this method to be equal
1323      * to itself and greater than all other {@code $type$} values
1324      * (including {@code $Fulltype$.POSITIVE_INFINITY}).
1325 #else[floatingPointType]
1326      * Pairs of {@code $type$} elements are compared as if by invoking
1327      * {@link $Fulltype$#compare($type$,$type$)}.
1328 #end[floatingPointType]
1329      *
1330      * <p> A $type$ buffer is not comparable to any other type of object.
1331      *
1332      * @return  A negative integer, zero, or a positive integer as this buffer
1333      *          is less than, equal to, or greater than the given buffer
1334      */
1335     public int compareTo($Type$Buffer that) {
1336         int i = BufferMismatch.mismatch(this, this.position(),
1337                                         that, that.position(),
1338                                         Math.min(this.remaining(), that.remaining()));
1339         if (i >= 0) {
1340             return compare(this.get(this.position() + i), that.get(that.position() + i));
1341         }
1342         return this.remaining() - that.remaining();
1343     }
1344 
1345     private static int compare($type$ x, $type$ y) {
1346 #if[floatingPointType]
1347         return ((x < y)  ? -1 :
1348                 (x > y)  ? +1 :
1349                 (x == y) ?  0 :
1350                 $Fulltype$.isNaN(x) ? ($Fulltype$.isNaN(y) ? 0 : +1) : -1);
1351 #else[floatingPointType]
1352         return $Fulltype$.compare(x, y);
1353 #end[floatingPointType]
1354     }
1355 
1356     // -- Other char stuff --
1357 
1358 #if[char]
1359 
1360     /**
1361      * Returns a string containing the characters in this buffer.
1362      *
1363      * <p> The first character of the resulting string will be the character at
1364      * this buffer's position, while the last character will be the character
1365      * at index {@code limit()}&nbsp;-&nbsp;1.  Invoking this method does not
1366      * change the buffer's position. </p>
1367      *
1368      * @return  The specified string
1369      */
1370     public String toString() {
1371         return toString(position(), limit());
1372     }
1373 
1374     abstract String toString(int start, int end);       // package-private
1375 
1376 
1377     // --- Methods to support CharSequence ---
1378 
1379     /**
1380      * Returns the length of this character buffer.
1381      *
1382      * <p> When viewed as a character sequence, the length of a character
1383      * buffer is simply the number of characters between the position
1384      * (inclusive) and the limit (exclusive); that is, it is equivalent to
1385      * {@code remaining()}. </p>
1386      *
1387      * @return  The length of this character buffer
1388      */
1389     public final int length() {
1390         return remaining();
1391     }
1392 
1393     /**
1394      * Reads the character at the given index relative to the current
1395      * position.
1396      *
1397      * @param  index
1398      *         The index of the character to be read, relative to the position;
1399      *         must be non-negative and smaller than {@code remaining()}
1400      *
1401      * @return  The character at index
1402      *          <code>position()&nbsp;+&nbsp;index</code>
1403      *
1404      * @throws  IndexOutOfBoundsException
1405      *          If the preconditions on {@code index} do not hold
1406      */
1407     public final char charAt(int index) {
1408         return get(position() + checkIndex(index, 1));
1409     }
1410 
1411     /**
1412      * Creates a new character buffer that represents the specified subsequence
1413      * of this buffer, relative to the current position.
1414      *
1415      * <p> The new buffer will share this buffer's content; that is, if the
1416      * content of this buffer is mutable then modifications to one buffer will
1417      * cause the other to be modified.  The new buffer's capacity will be that
1418      * of this buffer, its position will be
1419      * {@code position()}&nbsp;+&nbsp;{@code start}, and its limit will be
1420      * {@code position()}&nbsp;+&nbsp;{@code end}.  The new buffer will be
1421      * direct if, and only if, this buffer is direct, and it will be read-only
1422      * if, and only if, this buffer is read-only.  </p>
1423      *
1424      * @param  start
1425      *         The index, relative to the current position, of the first
1426      *         character in the subsequence; must be non-negative and no larger
1427      *         than {@code remaining()}
1428      *
1429      * @param  end
1430      *         The index, relative to the current position, of the character
1431      *         following the last character in the subsequence; must be no
1432      *         smaller than {@code start} and no larger than
1433      *         {@code remaining()}
1434      *
1435      * @return  The new character buffer
1436      *
1437      * @throws  IndexOutOfBoundsException
1438      *          If the preconditions on {@code start} and {@code end}
1439      *          do not hold
1440      */
1441     public abstract CharBuffer subSequence(int start, int end);
1442 
1443 
1444     // --- Methods to support Appendable ---
1445 
1446     /**
1447      * Appends the specified character sequence  to this
1448      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1449      *
1450      * <p> An invocation of this method of the form {@code dst.append(csq)}
1451      * behaves in exactly the same way as the invocation
1452      *
1453      * <pre>
1454      *     dst.put(csq.toString()) </pre>
1455      *
1456      * <p> Depending on the specification of {@code toString} for the
1457      * character sequence {@code csq}, the entire sequence may not be
1458      * appended.  For instance, invoking the {@link $Type$Buffer#toString()
1459      * toString} method of a character buffer will return a subsequence whose
1460      * content depends upon the buffer's position and limit.
1461      *
1462      * @param  csq
1463      *         The character sequence to append.  If {@code csq} is
1464      *         {@code null}, then the four characters {@code "null"} are
1465      *         appended to this character buffer.
1466      *
1467      * @return  This buffer
1468      *
1469      * @throws  BufferOverflowException
1470      *          If there is insufficient space in this buffer
1471      *
1472      * @throws  ReadOnlyBufferException
1473      *          If this buffer is read-only
1474      *
1475      * @since  1.5
1476      */
1477     public $Type$Buffer append(CharSequence csq) {
1478         if (csq == null)
1479             return put("null");
1480         else
1481             return put(csq.toString());
1482     }
1483 
1484     /**
1485      * Appends a subsequence of the  specified character sequence  to this
1486      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1487      *
1488      * <p> An invocation of this method of the form {@code dst.append(csq, start,
1489      * end)} when {@code csq} is not {@code null}, behaves in exactly the
1490      * same way as the invocation
1491      *
1492      * <pre>
1493      *     dst.put(csq.subSequence(start, end).toString()) </pre>
1494      *
1495      * @param  csq
1496      *         The character sequence from which a subsequence will be
1497      *         appended.  If {@code csq} is {@code null}, then characters
1498      *         will be appended as if {@code csq} contained the four
1499      *         characters {@code "null"}.
1500      *
1501      * @return  This buffer
1502      *
1503      * @throws  BufferOverflowException
1504      *          If there is insufficient space in this buffer
1505      *
1506      * @throws  IndexOutOfBoundsException
1507      *          If {@code start} or {@code end} are negative, {@code start}
1508      *          is greater than {@code end}, or {@code end} is greater than
1509      *          {@code csq.length()}
1510      *
1511      * @throws  ReadOnlyBufferException
1512      *          If this buffer is read-only
1513      *
1514      * @since  1.5
1515      */
1516     public $Type$Buffer append(CharSequence csq, int start, int end) {
1517         CharSequence cs = (csq == null ? "null" : csq);
1518         return put(cs.subSequence(start, end).toString());
1519     }
1520 
1521     /**
1522      * Appends the specified $type$  to this
1523      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1524      *
1525      * <p> An invocation of this method of the form {@code dst.append($x$)}
1526      * behaves in exactly the same way as the invocation
1527      *
1528      * <pre>
1529      *     dst.put($x$) </pre>
1530      *
1531      * @param  $x$
1532      *         The 16-bit $type$ to append
1533      *
1534      * @return  This buffer
1535      *
1536      * @throws  BufferOverflowException
1537      *          If there is insufficient space in this buffer
1538      *
1539      * @throws  ReadOnlyBufferException
1540      *          If this buffer is read-only
1541      *
1542      * @since  1.5
1543      */
1544     public $Type$Buffer append($type$ $x$) {
1545         return put($x$);
1546     }
1547 
1548 #end[char]
1549 
1550 
1551     // -- Other byte stuff: Access to binary data --
1552 
1553 #if[!byte]
1554 
1555     /**
1556      * Retrieves this buffer's byte order.
1557      *
1558      * <p> The byte order of $a$ $type$ buffer created by allocation or by
1559      * wrapping an existing {@code $type$} array is the {@link
1560      * ByteOrder#nativeOrder native order} of the underlying
1561      * hardware.  The byte order of $a$ $type$ buffer created as a <a
1562      * href="ByteBuffer.html#views">view</a> of a byte buffer is that of the
1563      * byte buffer at the moment that the view is created.  </p>
1564      *
1565      * @return  This buffer's byte order
1566      */
1567     public abstract ByteOrder order();
1568 
1569 #end[!byte]
1570 
1571 #if[char]
1572     // The order or null if the buffer does not cover a memory region,
1573     // such as StringCharBuffer
1574     abstract ByteOrder charRegionOrder();
1575 #end[char]
1576 
1577 #if[byte]
1578 
1579     boolean bigEndian                                   // package-private
1580         = true;
1581     boolean nativeByteOrder                             // package-private
1582         = (ByteOrder.nativeOrder() == ByteOrder.BIG_ENDIAN);
1583 
1584     /**
1585      * Retrieves this buffer's byte order.
1586      *
1587      * <p> The byte order is used when reading or writing multibyte values, and
1588      * when creating buffers that are views of this byte buffer.  The order of
1589      * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN
1590      * BIG_ENDIAN}.  </p>
1591      *
1592      * @return  This buffer's byte order
1593      */
1594     public final ByteOrder order() {
1595         return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN;
1596     }
1597 
1598     /**
1599      * Modifies this buffer's byte order.
1600      *
1601      * @param  bo
1602      *         The new byte order,
1603      *         either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
1604      *         or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}
1605      *
1606      * @return  This buffer
1607      */
1608     public final $Type$Buffer order(ByteOrder bo) {
1609         bigEndian = (bo == ByteOrder.BIG_ENDIAN);
1610         nativeByteOrder =
1611             (bigEndian == (ByteOrder.nativeOrder() == ByteOrder.BIG_ENDIAN));
1612         return this;
1613     }
1614 
1615     /**
1616      * Returns the memory address, pointing to the byte at the given index,
1617      * modulus the given unit size.
1618      *
1619      * <p> A return value greater than zero indicates the address of the byte at
1620      * the index is misaligned for the unit size, and the value's quantity
1621      * indicates how much the index should be rounded up or down to locate a
1622      * byte at an aligned address.  Otherwise, a value of {@code 0} indicates
1623      * that the address of the byte at the index is aligned for the unit size.
1624      *
1625      * @apiNote
1626      * This method may be utilized to determine if unit size bytes from an
1627      * index can be accessed atomically, if supported by the native platform.
1628      *
1629      * @implNote
1630      * This implementation throws {@code UnsupportedOperationException} for
1631      * non-direct buffers when the given unit size is greater then {@code 8}.
1632      *
1633      * @param  index
1634      *         The index to query for alignment offset, must be non-negative, no
1635      *         upper bounds check is performed
1636      *
1637      * @param  unitSize
1638      *         The unit size in bytes, must be a power of {@code 2}
1639      *
1640      * @return  The indexed byte's memory address modulus the unit size
1641      *
1642      * @throws IllegalArgumentException
1643      *         If the index is negative or the unit size is not a power of
1644      *         {@code 2}
1645      *
1646      * @throws UnsupportedOperationException
1647      *         If the native platform does not guarantee stable alignment offset
1648      *         values for the given unit size when managing the memory regions
1649      *         of buffers of the same kind as this buffer (direct or
1650      *         non-direct).  For example, if garbage collection would result
1651      *         in the moving of a memory region covered by a non-direct buffer
1652      *         from one location to another and both locations have different
1653      *         alignment characteristics.
1654      *
1655      * @see #alignedSlice(int)
1656      * @since 9
1657      */
1658     public final int alignmentOffset(int index, int unitSize) {
1659         if (index < 0)
1660             throw new IllegalArgumentException("Index less than zero: " + index);
1661         if (unitSize < 1 || (unitSize & (unitSize - 1)) != 0)
1662             throw new IllegalArgumentException("Unit size not a power of two: " + unitSize);
1663         if (unitSize > 8 && !isDirect())
1664             throw new UnsupportedOperationException("Unit size unsupported for non-direct buffers: " + unitSize);
1665 
1666         return (int) ((address + index) % unitSize);
1667     }
1668 
1669     /**
1670      * Creates a new byte buffer whose content is a shared and aligned
1671      * subsequence of this buffer's content.
1672      *
1673      * <p> The content of the new buffer will start at this buffer's current
1674      * position rounded up to the index of the nearest aligned byte for the
1675      * given unit size, and end at this buffer's limit rounded down to the index
1676      * of the nearest aligned byte for the given unit size.
1677      * If rounding results in out-of-bound values then the new buffer's capacity
1678      * and limit will be zero.  If rounding is within bounds the following
1679      * expressions will be true for a new buffer {@code nb} and unit size
1680      * {@code unitSize}:
1681      * <pre>{@code
1682      * nb.alignmentOffset(0, unitSize) == 0
1683      * nb.alignmentOffset(nb.limit(), unitSize) == 0
1684      * }</pre>
1685      *
1686      * <p> Changes to this buffer's content will be visible in the new
1687      * buffer, and vice versa; the two buffers' position, limit, and mark
1688      * values will be independent.
1689      *
1690      * <p> The new buffer's position will be zero, its capacity and its limit
1691      * will be the number of bytes remaining in this buffer or fewer subject to
1692      * alignment, its mark will be undefined, and its byte order will be
1693      * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
1694      *
1695      * The new buffer will be direct if, and only if, this buffer is direct, and
1696      * it will be read-only if, and only if, this buffer is read-only.  </p>
1697      *
1698      * @apiNote
1699      * This method may be utilized to create a new buffer where unit size bytes
1700      * from index, that is a multiple of the unit size, may be accessed
1701      * atomically, if supported by the native platform.
1702      *
1703      * @implNote
1704      * This implementation throws {@code UnsupportedOperationException} for
1705      * non-direct buffers when the given unit size is greater then {@code 8}.
1706      *
1707      * @param  unitSize
1708      *         The unit size in bytes, must be a power of {@code 2}
1709      *
1710      * @return  The new byte buffer
1711      *
1712      * @throws IllegalArgumentException
1713      *         If the unit size not a power of {@code 2}
1714      *
1715      * @throws UnsupportedOperationException
1716      *         If the native platform does not guarantee stable aligned slices
1717      *         for the given unit size when managing the memory regions
1718      *         of buffers of the same kind as this buffer (direct or
1719      *         non-direct).  For example, if garbage collection would result
1720      *         in the moving of a memory region covered by a non-direct buffer
1721      *         from one location to another and both locations have different
1722      *         alignment characteristics.
1723      *
1724      * @see #alignmentOffset(int, int)
1725      * @see #slice()
1726      * @since 9
1727      */
1728     public final ByteBuffer alignedSlice(int unitSize) {
1729         int pos = position();
1730         int lim = limit();
1731 
1732         int pos_mod = alignmentOffset(pos, unitSize);
1733         int lim_mod = alignmentOffset(lim, unitSize);
1734 
1735         // Round up the position to align with unit size
1736         int aligned_pos = (pos_mod > 0)
1737             ? pos + (unitSize - pos_mod)
1738             : pos;
1739 
1740         // Round down the limit to align with unit size
1741         int aligned_lim = lim - lim_mod;
1742 
1743         if (aligned_pos > lim || aligned_lim < pos) {
1744             aligned_pos = aligned_lim = pos;
1745         }
1746 
1747         return slice(aligned_pos, aligned_lim);
1748     }
1749 
1750     abstract ByteBuffer slice(int pos, int lim);
1751 
1752     // #BIN
1753     //
1754     // Binary-data access methods  for short, char, int, long, float,
1755     // and double will be inserted here
1756 
1757 #end[byte]
1758 
1759 #if[streamableType]
1760 
1761 #if[char]
1762     @Override
1763 #end[char]
1764     public $Streamtype$Stream $type$s() {
1765         return StreamSupport.$streamtype$Stream(() -> new $Type$BufferSpliterator(this),
1766             Buffer.SPLITERATOR_CHARACTERISTICS, false);
1767     }
1768 
1769 #end[streamableType]
1770 
1771 }