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 
  34 /**
  35  * $A$ $type$ buffer.
  36  *
  37  * <p> This class defines {#if[byte]?six:four} categories of operations upon
  38  * $type$ buffers:
  39  *
  40  * <ul>
  41  *
  42  *   <li><p> Absolute and relative {@link #get() </code><i>get</i><code>} and
  43  *   {@link #put($type$) </code><i>put</i><code>} methods that read and write
  44  *   single $type$s; </p></li>
  45  *
  46  *   <li><p> Relative {@link #get($type$[]) </code><i>bulk get</i><code>}
  47  *   methods that transfer contiguous sequences of $type$s from this buffer
  48  *   into an array; {#if[!byte]?and}</p></li>
  49  *
  50  *   <li><p> Relative {@link #put($type$[]) </code><i>bulk put</i><code>}
  51  *   methods that transfer contiguous sequences of $type$s from $a$
  52  *   $type$ array{#if[char]?,&#32;a&#32;string,} or some other $type$
  53  *   buffer into this buffer;{#if[!byte]?&#32;and} </p></li>
  54  *
  55 #if[byte]
  56  *
  57  *   <li><p> Absolute and relative {@link #getChar() </code><i>get</i><code>}
  58  *   and {@link #putChar(char) </code><i>put</i><code>} methods that read and
  59  *   write values of other primitive types, translating them to and from
  60  *   sequences of bytes in a particular byte order; </p></li>
  61  *
  62  *   <li><p> Methods for creating <i><a href="#views">view buffers</a></i>,
  63  *   which allow a byte buffer to be viewed as a buffer containing values of
  64  *   some other primitive type; and </p></li>
  65  *
  66 #end[byte]
  67  *
  68  *   <li><p> Methods for {@link #compact </code>compacting<code>}, {@link
  69  *   #duplicate </code>duplicating<code>}, and {@link #slice
  70  *   </code>slicing<code>} $a$ $type$ buffer.  </p></li>
  71  *
  72  * </ul>
  73  *
  74  * <p> $Type$ buffers can be created either by {@link #allocate
  75  * </code><i>allocation</i><code>}, which allocates space for the buffer's
  76  *
  77 #if[byte]
  78  *
  79  * content, or by {@link #wrap($type$[]) </code><i>wrapping</i><code>} an
  80  * existing $type$ array {#if[char]?or&#32;string} into a buffer.
  81  *
  82 #else[byte]
  83  *
  84  * content, by {@link #wrap($type$[]) </code><i>wrapping</i><code>} an existing
  85  * $type$ array {#if[char]?or&#32;string} into a buffer, or by creating a
  86  * <a href="ByteBuffer.html#views"><i>view</i></a> of an existing byte buffer.
  87  *
  88 #end[byte]
  89  *
  90 #if[byte]
  91  *
  92  * <a name="direct">
  93  * <h4> Direct <i>vs.</i> non-direct buffers </h4>
  94  *
  95  * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>.  Given a
  96  * direct byte buffer, the Java virtual machine will make a best effort to
  97  * perform native I/O operations directly upon it.  That is, it will attempt to
  98  * avoid copying the buffer's content to (or from) an intermediate buffer
  99  * before (or after) each invocation of one of the underlying operating
 100  * system's native I/O operations.
 101  *
 102  * <p> A direct byte buffer may be created by invoking the {@link
 103  * #allocateDirect(int) allocateDirect} factory method of this class.  The
 104  * buffers returned by this method typically have somewhat higher allocation
 105  * and deallocation costs than non-direct buffers.  The contents of direct
 106  * buffers may reside outside of the normal garbage-collected heap, and so
 107  * their impact upon the memory footprint of an application might not be
 108  * obvious.  It is therefore recommended that direct buffers be allocated
 109  * primarily for large, long-lived buffers that are subject to the underlying
 110  * system's native I/O operations.  In general it is best to allocate direct
 111  * buffers only when they yield a measureable gain in program performance.
 112  *
 113  * <p> A direct byte buffer may also be created by {@link
 114  * java.nio.channels.FileChannel#map </code>mapping<code>} a region of a file
 115  * directly into memory.  An implementation of the Java platform may optionally
 116  * support the creation of direct byte buffers from native code via JNI.  If an
 117  * instance of one of these kinds of buffers refers to an inaccessible region
 118  * of memory then an attempt to access that region will not change the buffer's
 119  * content and will cause an unspecified exception to be thrown either at the
 120  * time of the access or at some later time.
 121  *
 122  * <p> Whether a byte buffer is direct or non-direct may be determined by
 123  * invoking its {@link #isDirect isDirect} method.  This method is provided so
 124  * that explicit buffer management can be done in performance-critical code.
 125  *
 126  *
 127  * <a name="bin">
 128  * <h4> Access to binary data </h4>
 129  *
 130  * <p> This class defines methods for reading and writing values of all other
 131  * primitive types, except <tt>boolean</tt>.  Primitive values are translated
 132  * to (or from) sequences of bytes according to the buffer's current byte
 133  * order, which may be retrieved and modified via the {@link #order order}
 134  * methods.  Specific byte orders are represented by instances of the {@link
 135  * ByteOrder} class.  The initial order of a byte buffer is always {@link
 136  * ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
 137  *
 138  * <p> For access to heterogeneous binary data, that is, sequences of values of
 139  * different types, this class defines a family of absolute and relative
 140  * <i>get</i> and <i>put</i> methods for each type.  For 32-bit floating-point
 141  * values, for example, this class defines:
 142  *
 143  * <blockquote><pre>
 144  * float  {@link #getFloat()}
 145  * float  {@link #getFloat(int) getFloat(int index)}
 146  *  void  {@link #putFloat(float) putFloat(float f)}
 147  *  void  {@link #putFloat(int,float) putFloat(int index, float f)}</pre></blockquote>
 148  *
 149  * <p> Corresponding methods are defined for the types <tt>char</tt>,
 150  * <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and <tt>double</tt>.  The index
 151  * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of
 152  * bytes rather than of the type being read or written.
 153  *
 154  * <a name="views">
 155  *
 156  * <p> For access to homogeneous binary data, that is, sequences of values of
 157  * the same type, this class defines methods that can create <i>views</i> of a
 158  * given byte buffer.  A <i>view buffer</i> is simply another buffer whose
 159  * content is backed by the byte buffer.  Changes to the byte buffer's content
 160  * will be visible in the view buffer, and vice versa; the two buffers'
 161  * position, limit, and mark values are independent.  The {@link
 162  * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of
 163  * the {@link FloatBuffer} class that is backed by the byte buffer upon which
 164  * the method is invoked.  Corresponding view-creation methods are defined for
 165  * the types <tt>char</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and
 166  * <tt>double</tt>.
 167  *
 168  * <p> View buffers have three important advantages over the families of
 169  * type-specific <i>get</i> and <i>put</i> methods described above:
 170  *
 171  * <ul>
 172  *
 173  *   <li><p> A view buffer is indexed not in terms of bytes but rather in terms
 174  *   of the type-specific size of its values;  </p></li>
 175  *
 176  *   <li><p> A view buffer provides relative bulk <i>get</i> and <i>put</i>
 177  *   methods that can transfer contiguous sequences of values between a buffer
 178  *   and an array or some other buffer of the same type; and  </p></li>
 179  *
 180  *   <li><p> A view buffer is potentially much more efficient because it will
 181  *   be direct if, and only if, its backing byte buffer is direct.  </p></li>
 182  *
 183  * </ul>
 184  *
 185  * <p> The byte order of a view buffer is fixed to be that of its byte buffer
 186  * at the time that the view is created.  </p>
 187  *
 188 #end[byte]
 189 *
 190 #if[!byte]
 191  *
 192  * <p> Like a byte buffer, $a$ $type$ buffer is either <a
 193  * href="ByteBuffer.html#direct"><i>direct</i> or <i>non-direct</i></a>.  A
 194  * $type$ buffer created via the <tt>wrap</tt> methods of this class will
 195  * be non-direct.  $A$ $type$ buffer created as a view of a byte buffer will
 196  * be direct if, and only if, the byte buffer itself is direct.  Whether or not
 197  * $a$ $type$ buffer is direct may be determined by invoking the {@link
 198  * #isDirect isDirect} method.  </p>
 199  *
 200 #end[!byte]
 201 *
 202 #if[char]
 203  *
 204  * <p> This class implements the {@link CharSequence} interface so that
 205  * character buffers may be used wherever character sequences are accepted, for
 206  * example in the regular-expression package <tt>{@link java.util.regex}</tt>.
 207  * </p>
 208  *
 209 #end[char]
 210  *
 211 #if[byte]
 212  * <h4> Invocation chaining </h4>
 213 #end[byte]
 214  *
 215  * <p> Methods in this class that do not otherwise have a value to return are
 216  * specified to return the buffer upon which they are invoked.  This allows
 217  * method invocations to be chained.
 218  *
 219 #if[byte]
 220  *
 221  * The sequence of statements
 222  *
 223  * <blockquote><pre>
 224  * bb.putInt(0xCAFEBABE);
 225  * bb.putShort(3);
 226  * bb.putShort(45);</pre></blockquote>
 227  *
 228  * can, for example, be replaced by the single statement
 229  *
 230  * <blockquote><pre>
 231  * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote>
 232  *
 233 #end[byte]
 234 #if[char]
 235  *
 236  * The sequence of statements
 237  *
 238  * <blockquote><pre>
 239  * cb.put("text/");
 240  * cb.put(subtype);
 241  * cb.put("; charset=");
 242  * cb.put(enc);</pre></blockquote>
 243  *
 244  * can, for example, be replaced by the single statement
 245  *
 246  * <blockquote><pre>
 247  * cb.put("text/").put(subtype).put("; charset=").put(enc);</pre></blockquote>
 248  *
 249 #end[char]
 250  *
 251  *
 252  * @author Mark Reinhold
 253  * @author JSR-51 Expert Group
 254  * @since 1.4
 255  */
 256 
 257 public abstract class $Type$Buffer
 258     extends Buffer
 259     implements Comparable<$Type$Buffer>{#if[char]?, Appendable, CharSequence, Readable}
 260 {
 261 
 262     // These fields are declared here rather than in Heap-X-Buffer in order to
 263     // reduce the number of virtual method invocations needed to access these
 264     // values, which is especially costly when coding small buffers.
 265     //
 266     final $type$[] hb;                  // Non-null only for heap buffers
 267     final int offset;
 268     boolean isReadOnly;                 // Valid only for heap buffers
 269 
 270     // Creates a new buffer with the given mark, position, limit, capacity,
 271     // backing array, and array offset
 272     //
 273     $Type$Buffer(int mark, int pos, int lim, int cap,   // package-private
 274                  $type$[] hb, int offset)
 275     {
 276         super(mark, pos, lim, cap);
 277         this.hb = hb;
 278         this.offset = offset;
 279     }
 280 
 281     // Creates a new buffer with the given mark, position, limit, and capacity
 282     //
 283     $Type$Buffer(int mark, int pos, int lim, int cap) { // package-private
 284         this(mark, pos, lim, cap, null, 0);
 285     }
 286 
 287 #if[byte]
 288 
 289     /**
 290      * Allocates a new direct $type$ buffer.
 291      *
 292      * <p> The new buffer's position will be zero, its limit will be its
 293      * capacity, its mark will be undefined, and each of its elements will be
 294      * initialized to zero.  Whether or not it has a
 295      * {@link #hasArray </code>backing array<code>} is unspecified.
 296      *
 297      * @param  capacity
 298      *         The new buffer's capacity, in $type$s
 299      *
 300      * @return  The new $type$ buffer
 301      *
 302      * @throws  IllegalArgumentException
 303      *          If the <tt>capacity</tt> is a negative integer
 304      */
 305     public static $Type$Buffer allocateDirect(int capacity) {
 306         return new Direct$Type$Buffer(capacity);
 307     }
 308 
 309 #end[byte]
 310 
 311     /**
 312      * Allocates a new $type$ buffer.
 313      *
 314      * <p> The new buffer's position will be zero, its limit will be its
 315      * capacity, its mark will be undefined, and each of its elements will be
 316      * initialized to zero.  It will have a {@link #array
 317      * </code>backing array<code>}, and its {@link #arrayOffset </code>array
 318      * offset<code>} will be zero.
 319      *
 320      * @param  capacity
 321      *         The new buffer's capacity, in $type$s
 322      *
 323      * @return  The new $type$ buffer
 324      *
 325      * @throws  IllegalArgumentException
 326      *          If the <tt>capacity</tt> is a negative integer
 327      */
 328     public static $Type$Buffer allocate(int capacity) {
 329         if (capacity < 0)
 330             throw new IllegalArgumentException();
 331         return new Heap$Type$Buffer(capacity, capacity);
 332     }
 333 
 334     /**
 335      * Wraps $a$ $type$ array into a buffer.
 336      *
 337      * <p> The new buffer will be backed by the given $type$ array;
 338      * that is, modifications to the buffer will cause the array to be modified
 339      * and vice versa.  The new buffer's capacity will be
 340      * <tt>array.length</tt>, its position will be <tt>offset</tt>, its limit
 341      * will be <tt>offset + length</tt>, and its mark will be undefined.  Its
 342      * {@link #array </code>backing array<code>} will be the given array, and
 343      * its {@link #arrayOffset </code>array offset<code>} will be zero.  </p>
 344      *
 345      * @param  array
 346      *         The array that will back the new buffer
 347      *
 348      * @param  offset
 349      *         The offset of the subarray to be used; must be non-negative and
 350      *         no larger than <tt>array.length</tt>.  The new buffer's position
 351      *         will be set to this value.
 352      *
 353      * @param  length
 354      *         The length of the subarray to be used;
 355      *         must be non-negative and no larger than
 356      *         <tt>array.length - offset</tt>.
 357      *         The new buffer's limit will be set to <tt>offset + length</tt>.
 358      *
 359      * @return  The new $type$ buffer
 360      *
 361      * @throws  IndexOutOfBoundsException
 362      *          If the preconditions on the <tt>offset</tt> and <tt>length</tt>
 363      *          parameters do not hold
 364      */
 365     public static $Type$Buffer wrap($type$[] array,
 366                                     int offset, int length)
 367     {
 368         try {
 369             return new Heap$Type$Buffer(array, offset, length);
 370         } catch (IllegalArgumentException x) {
 371             throw new IndexOutOfBoundsException();
 372         }
 373     }
 374 
 375     /**
 376      * Wraps $a$ $type$ array into a buffer.
 377      *
 378      * <p> The new buffer will be backed by the given $type$ array;
 379      * that is, modifications to the buffer will cause the array to be modified
 380      * and vice versa.  The new buffer's capacity and limit will be
 381      * <tt>array.length</tt>, its position will be zero, and its mark will be
 382      * undefined.  Its {@link #array </code>backing array<code>} will be the
 383      * given array, and its {@link #arrayOffset </code>array offset<code>} will
 384      * be zero.  </p>
 385      *
 386      * @param  array
 387      *         The array that will back this buffer
 388      *
 389      * @return  The new $type$ buffer
 390      */
 391     public static $Type$Buffer wrap($type$[] array) {
 392         return wrap(array, 0, array.length);
 393     }
 394 
 395 #if[char]
 396 
 397     /**
 398      * Attempts to read characters into the specified character buffer.
 399      * The buffer is used as a repository of characters as-is: the only
 400      * changes made are the results of a put operation. No flipping or
 401      * rewinding of the buffer is performed.
 402      *
 403      * @param target the buffer to read characters into
 404      * @return The number of characters added to the buffer, or
 405      *         -1 if this source of characters is at its end
 406      * @throws IOException if an I/O error occurs
 407      * @throws NullPointerException if target is null
 408      * @throws ReadOnlyBufferException if target is a read only buffer
 409      * @since 1.5
 410      */
 411     public int read(CharBuffer target) throws IOException {
 412         // Determine the number of bytes n that can be transferred
 413         int targetRemaining = target.remaining();
 414         int remaining = remaining();
 415         if (remaining == 0)
 416             return -1;
 417         int n = Math.min(remaining, targetRemaining);
 418         int limit = limit();
 419         // Set source limit to prevent target overflow
 420         if (targetRemaining < remaining)
 421             limit(position() + n);
 422         try {
 423             if (n > 0)
 424                 target.put(this);
 425         } finally {
 426             limit(limit); // restore real limit
 427         }
 428         return n;
 429     }
 430 
 431     /**
 432      * Wraps a character sequence into a buffer.
 433      *
 434      * <p> The content of the new, read-only buffer will be the content of the
 435      * given character sequence.  The buffer's capacity will be
 436      * <tt>csq.length()</tt>, its position will be <tt>start</tt>, its limit
 437      * will be <tt>end</tt>, and its mark will be undefined.  </p>
 438      *
 439      * @param  csq
 440      *         The character sequence from which the new character buffer is to
 441      *         be created
 442      *
 443      * @param  start
 444      *         The index of the first character to be used;
 445      *         must be non-negative and no larger than <tt>csq.length()</tt>.
 446      *         The new buffer's position will be set to this value.
 447      *
 448      * @param  end
 449      *         The index of the character following the last character to be
 450      *         used; must be no smaller than <tt>start</tt> and no larger
 451      *         than <tt>csq.length()</tt>.
 452      *         The new buffer's limit will be set to this value.
 453      *
 454      * @return  The new character buffer
 455      *
 456      * @throws  IndexOutOfBoundsException
 457      *          If the preconditions on the <tt>start</tt> and <tt>end</tt>
 458      *          parameters do not hold
 459      */
 460     public static CharBuffer wrap(CharSequence csq, int start, int end) {
 461         try {
 462             return new StringCharBuffer(csq, start, end);
 463         } catch (IllegalArgumentException x) {
 464             throw new IndexOutOfBoundsException();
 465         }
 466     }
 467 
 468     /**
 469      * Wraps a character sequence into a buffer.
 470      *
 471      * <p> The content of the new, read-only buffer will be the content of the
 472      * given character sequence.  The new buffer's capacity and limit will be
 473      * <tt>csq.length()</tt>, its position will be zero, and its mark will be
 474      * undefined.  </p>
 475      *
 476      * @param  csq
 477      *         The character sequence from which the new character buffer is to
 478      *         be created
 479      *
 480      * @return  The new character buffer
 481      */
 482     public static CharBuffer wrap(CharSequence csq) {
 483         return wrap(csq, 0, csq.length());
 484     }
 485 
 486 #end[char]
 487 
 488     /**
 489      * Creates a new $type$ buffer whose content is a shared subsequence of
 490      * this buffer's content.
 491      *
 492      * <p> The content of the new buffer will start at this buffer's current
 493      * position.  Changes to this buffer's content will be visible in the new
 494      * buffer, and vice versa; the two buffers' position, limit, and mark
 495      * values will be independent.
 496      *
 497      * <p> The new buffer's position will be zero, its capacity and its limit
 498      * will be the number of $type$s remaining in this buffer, and its mark
 499      * will be undefined.  The new buffer will be direct if, and only if, this
 500      * buffer is direct, and it will be read-only if, and only if, this buffer
 501      * is read-only.  </p>
 502      *
 503      * @return  The new $type$ buffer
 504      */
 505     public abstract $Type$Buffer slice();
 506 
 507     /**
 508      * Creates a new $type$ buffer that shares this buffer's content.
 509      *
 510      * <p> The content of the new buffer will be that of this buffer.  Changes
 511      * to this buffer's content will be visible in the new buffer, and vice
 512      * versa; the two buffers' position, limit, and mark values will be
 513      * independent.
 514      *
 515      * <p> The new buffer's capacity, limit, position, and mark values will be
 516      * identical to those of this buffer.  The new buffer will be direct if,
 517      * and only if, this buffer is direct, and it will be read-only if, and
 518      * only if, this buffer is read-only.  </p>
 519      *
 520      * @return  The new $type$ buffer
 521      */
 522     public abstract $Type$Buffer duplicate();
 523 
 524     /**
 525      * Creates a new, read-only $type$ buffer that shares this buffer's
 526      * content.
 527      *
 528      * <p> The content of the new buffer will be that of this buffer.  Changes
 529      * to this buffer's content will be visible in the new buffer; the new
 530      * buffer itself, however, will be read-only and will not allow the shared
 531      * content to be modified.  The two buffers' position, limit, and mark
 532      * values will be independent.
 533      *
 534      * <p> The new buffer's capacity, limit, position, and mark values will be
 535      * identical to those of this buffer.
 536      *
 537      * <p> If this buffer is itself read-only then this method behaves in
 538      * exactly the same way as the {@link #duplicate duplicate} method.  </p>
 539      *
 540      * @return  The new, read-only $type$ buffer
 541      */
 542     public abstract $Type$Buffer asReadOnlyBuffer();
 543 
 544 
 545     // -- Singleton get/put methods --
 546 
 547     /**
 548      * Relative <i>get</i> method.  Reads the $type$ at this buffer's
 549      * current position, and then increments the position. </p>
 550      *
 551      * @return  The $type$ at the buffer's current position
 552      *
 553      * @throws  BufferUnderflowException
 554      *          If the buffer's current position is not smaller than its limit
 555      */
 556     public abstract $type$ get();
 557 
 558     /**
 559      * Relative <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 560      *
 561      * <p> Writes the given $type$ into this buffer at the current
 562      * position, and then increments the position. </p>
 563      *
 564      * @param  $x$
 565      *         The $type$ to be written
 566      *
 567      * @return  This buffer
 568      *
 569      * @throws  BufferOverflowException
 570      *          If this buffer's current position is not smaller than its limit
 571      *
 572      * @throws  ReadOnlyBufferException
 573      *          If this buffer is read-only
 574      */
 575     public abstract $Type$Buffer put($type$ $x$);
 576 
 577     /**
 578      * Absolute <i>get</i> method.  Reads the $type$ at the given
 579      * index. </p>
 580      *
 581      * @param  index
 582      *         The index from which the $type$ will be read
 583      *
 584      * @return  The $type$ at the given index
 585      *
 586      * @throws  IndexOutOfBoundsException
 587      *          If <tt>index</tt> is negative
 588      *          or not smaller than the buffer's limit
 589      */
 590     public abstract $type$ get(int index);
 591 
 592     /**
 593      * Absolute <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 594      *
 595      * <p> Writes the given $type$ into this buffer at the given
 596      * index. </p>
 597      *
 598      * @param  index
 599      *         The index at which the $type$ will be written
 600      *
 601      * @param  $x$
 602      *         The $type$ value to be written
 603      *
 604      * @return  This buffer
 605      *
 606      * @throws  IndexOutOfBoundsException
 607      *          If <tt>index</tt> is negative
 608      *          or not smaller than the buffer's limit
 609      *
 610      * @throws  ReadOnlyBufferException
 611      *          If this buffer is read-only
 612      */
 613     public abstract $Type$Buffer put(int index, $type$ $x$);
 614 
 615 
 616     // -- Bulk get operations --
 617 
 618     /**
 619      * Relative bulk <i>get</i> method.
 620      *
 621      * <p> This method transfers $type$s from this buffer into the given
 622      * destination array.  If there are fewer $type$s remaining in the
 623      * buffer than are required to satisfy the request, that is, if
 624      * <tt>length</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>, then no
 625      * $type$s are transferred and a {@link BufferUnderflowException} is
 626      * thrown.
 627      *
 628      * <p> Otherwise, this method copies <tt>length</tt> $type$s from this
 629      * buffer into the given array, starting at the current position of this
 630      * buffer and at the given offset in the array.  The position of this
 631      * buffer is then incremented by <tt>length</tt>.
 632      *
 633      * <p> In other words, an invocation of this method of the form
 634      * <tt>src.get(dst,&nbsp;off,&nbsp;len)</tt> has exactly the same effect as
 635      * the loop
 636      *
 637      * <pre>
 638      *     for (int i = off; i < off + len; i++)
 639      *         dst[i] = src.get(); </pre>
 640      *
 641      * except that it first checks that there are sufficient $type$s in
 642      * this buffer and it is potentially much more efficient. </p>
 643      *
 644      * @param  dst
 645      *         The array into which $type$s are to be written
 646      *
 647      * @param  offset
 648      *         The offset within the array of the first $type$ to be
 649      *         written; must be non-negative and no larger than
 650      *         <tt>dst.length</tt>
 651      *
 652      * @param  length
 653      *         The maximum number of $type$s to be written to the given
 654      *         array; must be non-negative and no larger than
 655      *         <tt>dst.length - offset</tt>
 656      *
 657      * @return  This buffer
 658      *
 659      * @throws  BufferUnderflowException
 660      *          If there are fewer than <tt>length</tt> $type$s
 661      *          remaining in this buffer
 662      *
 663      * @throws  IndexOutOfBoundsException
 664      *          If the preconditions on the <tt>offset</tt> and <tt>length</tt>
 665      *          parameters do not hold
 666      */
 667     public $Type$Buffer get($type$[] dst, int offset, int length) {
 668         checkBounds(offset, length, dst.length);
 669         if (length > remaining())
 670             throw new BufferUnderflowException();
 671         int end = offset + length;
 672         for (int i = offset; i < end; i++)
 673             dst[i] = get();
 674         return this;
 675     }
 676 
 677     /**
 678      * Relative bulk <i>get</i> method.
 679      *
 680      * <p> This method transfers $type$s from this buffer into the given
 681      * destination array.  An invocation of this method of the form
 682      * <tt>src.get(a)</tt> behaves in exactly the same way as the invocation
 683      *
 684      * <pre>
 685      *     src.get(a, 0, a.length) </pre>
 686      *
 687      * @return  This buffer
 688      *
 689      * @throws  BufferUnderflowException
 690      *          If there are fewer than <tt>length</tt> $type$s
 691      *          remaining in this buffer
 692      */
 693     public $Type$Buffer get($type$[] dst) {
 694         return get(dst, 0, dst.length);
 695     }
 696 
 697 
 698     // -- Bulk put operations --
 699 
 700     /**
 701      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 702      *
 703      * <p> This method transfers the $type$s remaining in the given source
 704      * buffer into this buffer.  If there are more $type$s remaining in the
 705      * source buffer than in this buffer, that is, if
 706      * <tt>src.remaining()</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>,
 707      * then no $type$s are transferred and a {@link
 708      * BufferOverflowException} is thrown.
 709      *
 710      * <p> Otherwise, this method copies
 711      * <i>n</i>&nbsp;=&nbsp;<tt>src.remaining()</tt> $type$s from the given
 712      * buffer into this buffer, starting at each buffer's current position.
 713      * The positions of both buffers are then incremented by <i>n</i>.
 714      *
 715      * <p> In other words, an invocation of this method of the form
 716      * <tt>dst.put(src)</tt> has exactly the same effect as the loop
 717      *
 718      * <pre>
 719      *     while (src.hasRemaining())
 720      *         dst.put(src.get()); </pre>
 721      *
 722      * except that it first checks that there is sufficient space in this
 723      * buffer and it is potentially much more efficient. </p>
 724      *
 725      * @param  src
 726      *         The source buffer from which $type$s are to be read;
 727      *         must not be this buffer
 728      *
 729      * @return  This buffer
 730      *
 731      * @throws  BufferOverflowException
 732      *          If there is insufficient space in this buffer
 733      *          for the remaining $type$s in the source buffer
 734      *
 735      * @throws  IllegalArgumentException
 736      *          If the source buffer is this buffer
 737      *
 738      * @throws  ReadOnlyBufferException
 739      *          If this buffer is read-only
 740      */
 741     public $Type$Buffer put($Type$Buffer src) {
 742         if (src == this)
 743             throw new IllegalArgumentException();
 744         if (isReadOnly())
 745             throw new ReadOnlyBufferException();
 746         int n = src.remaining();
 747         if (n > remaining())
 748             throw new BufferOverflowException();
 749         for (int i = 0; i < n; i++)
 750             put(src.get());
 751         return this;
 752     }
 753 
 754     /**
 755      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 756      *
 757      * <p> This method transfers $type$s into this buffer from the given
 758      * source array.  If there are more $type$s to be copied from the array
 759      * than remain in this buffer, that is, if
 760      * <tt>length</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>, then no
 761      * $type$s are transferred and a {@link BufferOverflowException} is
 762      * thrown.
 763      *
 764      * <p> Otherwise, this method copies <tt>length</tt> $type$s from the
 765      * given array into this buffer, starting at the given offset in the array
 766      * and at the current position of this buffer.  The position of this buffer
 767      * is then incremented by <tt>length</tt>.
 768      *
 769      * <p> In other words, an invocation of this method of the form
 770      * <tt>dst.put(src,&nbsp;off,&nbsp;len)</tt> has exactly the same effect as
 771      * the loop
 772      *
 773      * <pre>
 774      *     for (int i = off; i < off + len; i++)
 775      *         dst.put(a[i]); </pre>
 776      *
 777      * except that it first checks that there is sufficient space in this
 778      * buffer and it is potentially much more efficient. </p>
 779      *
 780      * @param  src
 781      *         The array from which $type$s are to be read
 782      *
 783      * @param  offset
 784      *         The offset within the array of the first $type$ to be read;
 785      *         must be non-negative and no larger than <tt>array.length</tt>
 786      *
 787      * @param  length
 788      *         The number of $type$s to be read from the given array;
 789      *         must be non-negative and no larger than
 790      *         <tt>array.length - offset</tt>
 791      *
 792      * @return  This buffer
 793      *
 794      * @throws  BufferOverflowException
 795      *          If there is insufficient space in this buffer
 796      *
 797      * @throws  IndexOutOfBoundsException
 798      *          If the preconditions on the <tt>offset</tt> and <tt>length</tt>
 799      *          parameters do not hold
 800      *
 801      * @throws  ReadOnlyBufferException
 802      *          If this buffer is read-only
 803      */
 804     public $Type$Buffer put($type$[] src, int offset, int length) {
 805         checkBounds(offset, length, src.length);
 806         if (length > remaining())
 807             throw new BufferOverflowException();
 808         int end = offset + length;
 809         for (int i = offset; i < end; i++)
 810             this.put(src[i]);
 811         return this;
 812     }
 813 
 814     /**
 815      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 816      *
 817      * <p> This method transfers the entire content of the given source
 818      * $type$ array into this buffer.  An invocation of this method of the
 819      * form <tt>dst.put(a)</tt> behaves in exactly the same way as the
 820      * invocation
 821      *
 822      * <pre>
 823      *     dst.put(a, 0, a.length) </pre>
 824      *
 825      * @return  This buffer
 826      *
 827      * @throws  BufferOverflowException
 828      *          If there is insufficient space in this buffer
 829      *
 830      * @throws  ReadOnlyBufferException
 831      *          If this buffer is read-only
 832      */
 833     public final $Type$Buffer put($type$[] src) {
 834         return put(src, 0, src.length);
 835     }
 836 
 837 #if[char]
 838 
 839     /**
 840      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 841      *
 842      * <p> This method transfers $type$s from the given string into this
 843      * buffer.  If there are more $type$s to be copied from the string than
 844      * remain in this buffer, that is, if
 845      * <tt>end&nbsp;-&nbsp;start</tt>&nbsp;<tt>&gt;</tt>&nbsp;<tt>remaining()</tt>,
 846      * then no $type$s are transferred and a {@link
 847      * BufferOverflowException} is thrown.
 848      *
 849      * <p> Otherwise, this method copies
 850      * <i>n</i>&nbsp;=&nbsp;<tt>end</tt>&nbsp;-&nbsp;<tt>start</tt> $type$s
 851      * from the given string into this buffer, starting at the given
 852      * <tt>start</tt> index and at the current position of this buffer.  The
 853      * position of this buffer is then incremented by <i>n</i>.
 854      *
 855      * <p> In other words, an invocation of this method of the form
 856      * <tt>dst.put(src,&nbsp;start,&nbsp;end)</tt> has exactly the same effect
 857      * as the loop
 858      *
 859      * <pre>
 860      *     for (int i = start; i < end; i++)
 861      *         dst.put(src.charAt(i)); </pre>
 862      *
 863      * except that it first checks that there is sufficient space in this
 864      * buffer and it is potentially much more efficient. </p>
 865      *
 866      * @param  src
 867      *         The string from which $type$s are to be read
 868      *
 869      * @param  start
 870      *         The offset within the string of the first $type$ to be read;
 871      *         must be non-negative and no larger than
 872      *         <tt>string.length()</tt>
 873      *
 874      * @param  end
 875      *         The offset within the string of the last $type$ to be read,
 876      *         plus one; must be non-negative and no larger than
 877      *         <tt>string.length()</tt>
 878      *
 879      * @return  This buffer
 880      *
 881      * @throws  BufferOverflowException
 882      *          If there is insufficient space in this buffer
 883      *
 884      * @throws  IndexOutOfBoundsException
 885      *          If the preconditions on the <tt>start</tt> and <tt>end</tt>
 886      *          parameters do not hold
 887      *
 888      * @throws  ReadOnlyBufferException
 889      *          If this buffer is read-only
 890      */
 891     public $Type$Buffer put(String src, int start, int end) {
 892         checkBounds(start, end - start, src.length());
 893         if (isReadOnly())
 894             throw new ReadOnlyBufferException();
 895         if (end - start > remaining())
 896             throw new BufferOverflowException();
 897         for (int i = start; i < end; i++)
 898             this.put(src.charAt(i));
 899         return this;
 900     }
 901 
 902     /**
 903      * Relative bulk <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
 904      *
 905      * <p> This method transfers the entire content of the given source string
 906      * into this buffer.  An invocation of this method of the form
 907      * <tt>dst.put(s)</tt> behaves in exactly the same way as the invocation
 908      *
 909      * <pre>
 910      *     dst.put(s, 0, s.length()) </pre>
 911      *
 912      * @return  This buffer
 913      *
 914      * @throws  BufferOverflowException
 915      *          If there is insufficient space in this buffer
 916      *
 917      * @throws  ReadOnlyBufferException
 918      *          If this buffer is read-only
 919      */
 920     public final $Type$Buffer put(String src) {
 921         return put(src, 0, src.length());
 922     }
 923 
 924 #end[char]
 925 
 926 
 927     // -- Other stuff --
 928 
 929     /**
 930      * Tells whether or not this buffer is backed by an accessible $type$
 931      * array.
 932      *
 933      * <p> If this method returns <tt>true</tt> then the {@link #array() array}
 934      * and {@link #arrayOffset() arrayOffset} methods may safely be invoked.
 935      * </p>
 936      *
 937      * @return  <tt>true</tt> if, and only if, this buffer
 938      *          is backed by an array and is not read-only
 939      */
 940     public final boolean hasArray() {
 941         return (hb != null) && !isReadOnly;
 942     }
 943 
 944     /**
 945      * Returns the $type$ array that backs this
 946      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
 947      *
 948      * <p> Modifications to this buffer's content will cause the returned
 949      * array's content to be modified, and vice versa.
 950      *
 951      * <p> Invoke the {@link #hasArray hasArray} method before invoking this
 952      * method in order to ensure that this buffer has an accessible backing
 953      * array.  </p>
 954      *
 955      * @return  The array that backs this buffer
 956      *
 957      * @throws  ReadOnlyBufferException
 958      *          If this buffer is backed by an array but is read-only
 959      *
 960      * @throws  UnsupportedOperationException
 961      *          If this buffer is not backed by an accessible array
 962      */
 963     public final $type$[] array() {
 964         if (hb == null)
 965             throw new UnsupportedOperationException();
 966         if (isReadOnly)
 967             throw new ReadOnlyBufferException();
 968         return hb;
 969     }
 970 
 971     /**
 972      * Returns the offset within this buffer's backing array of the first
 973      * element of the buffer&nbsp;&nbsp;<i>(optional operation)</i>.
 974      *
 975      * <p> If this buffer is backed by an array then buffer position <i>p</i>
 976      * corresponds to array index <i>p</i>&nbsp;+&nbsp;<tt>arrayOffset()</tt>.
 977      *
 978      * <p> Invoke the {@link #hasArray hasArray} method before invoking this
 979      * method in order to ensure that this buffer has an accessible backing
 980      * array.  </p>
 981      *
 982      * @return  The offset within this buffer's array
 983      *          of the first element of the buffer
 984      *
 985      * @throws  ReadOnlyBufferException
 986      *          If this buffer is backed by an array but is read-only
 987      *
 988      * @throws  UnsupportedOperationException
 989      *          If this buffer is not backed by an accessible array
 990      */
 991     public final int arrayOffset() {
 992         if (hb == null)
 993             throw new UnsupportedOperationException();
 994         if (isReadOnly)
 995             throw new ReadOnlyBufferException();
 996         return offset;
 997     }
 998 
 999     /**
1000      * Compacts this buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1001      *
1002      * <p> The $type$s between the buffer's current position and its limit,
1003      * if any, are copied to the beginning of the buffer.  That is, the
1004      * $type$ at index <i>p</i>&nbsp;=&nbsp;<tt>position()</tt> is copied
1005      * to index zero, the $type$ at index <i>p</i>&nbsp;+&nbsp;1 is copied
1006      * to index one, and so forth until the $type$ at index
1007      * <tt>limit()</tt>&nbsp;-&nbsp;1 is copied to index
1008      * <i>n</i>&nbsp;=&nbsp;<tt>limit()</tt>&nbsp;-&nbsp;<tt>1</tt>&nbsp;-&nbsp;<i>p</i>.
1009      * The buffer's position is then set to <i>n+1</i> and its limit is set to
1010      * its capacity.  The mark, if defined, is discarded.
1011      *
1012      * <p> The buffer's position is set to the number of $type$s copied,
1013      * rather than to zero, so that an invocation of this method can be
1014      * followed immediately by an invocation of another relative <i>put</i>
1015      * method. </p>
1016      *
1017 #if[byte]
1018      *
1019      * <p> Invoke this method after writing data from a buffer in case the
1020      * write was incomplete.  The following loop, for example, copies bytes
1021      * from one channel to another via the buffer <tt>buf</tt>:
1022      *
1023      * <blockquote><pre>
1024      * buf.clear();          // Prepare buffer for use
1025      * while (in.read(buf) >= 0 || buf.position != 0) {
1026      *     buf.flip();
1027      *     out.write(buf);
1028      *     buf.compact();    // In case of partial write
1029      * }</pre></blockquote>
1030      *
1031 #end[byte]
1032      *
1033      * @return  This buffer
1034      *
1035      * @throws  ReadOnlyBufferException
1036      *          If this buffer is read-only
1037      */
1038     public abstract $Type$Buffer compact();
1039 
1040     /**
1041      * Tells whether or not this $type$ buffer is direct. </p>
1042      *
1043      * @return  <tt>true</tt> if, and only if, this buffer is direct
1044      */
1045     public abstract boolean isDirect();
1046 
1047 #if[!char]
1048 
1049     /**
1050      * Returns a string summarizing the state of this buffer.  </p>
1051      *
1052      * @return  A summary string
1053      */
1054     public String toString() {
1055         StringBuffer sb = new StringBuffer();
1056         sb.append(getClass().getName());
1057         sb.append("[pos=");
1058         sb.append(position());
1059         sb.append(" lim=");
1060         sb.append(limit());
1061         sb.append(" cap=");
1062         sb.append(capacity());
1063         sb.append("]");
1064         return sb.toString();
1065     }
1066 
1067 #end[!char]
1068 
1069 
1070     // ## Should really use unchecked accessors here for speed
1071 
1072     /**
1073      * Returns the current hash code of this buffer.
1074      *
1075      * <p> The hash code of a $type$ buffer depends only upon its remaining
1076      * elements; that is, upon the elements from <tt>position()</tt> up to, and
1077      * including, the element at <tt>limit()</tt>&nbsp;-&nbsp;<tt>1</tt>.
1078      *
1079      * <p> Because buffer hash codes are content-dependent, it is inadvisable
1080      * to use buffers as keys in hash maps or similar data structures unless it
1081      * is known that their contents will not change.  </p>
1082      *
1083      * @return  The current hash code of this buffer
1084      */
1085     public int hashCode() {
1086         int h = 1;
1087         int p = position();
1088         for (int i = limit() - 1; i >= p; i--)
1089 #if[int]
1090             h = 31 * h + get(i);
1091 #else[int]
1092             h = 31 * h + (int)get(i);
1093 #end[int]
1094         return h;
1095     }
1096 
1097     /**
1098      * Tells whether or not this buffer is equal to another object.
1099      *
1100      * <p> Two $type$ buffers are equal if, and only if,
1101      *
1102      * <p><ol>
1103      *
1104      *   <li><p> They have the same element type,  </p></li>
1105      *
1106      *   <li><p> They have the same number of remaining elements, and
1107      *   </p></li>
1108      *
1109      *   <li><p> The two sequences of remaining elements, considered
1110      *   independently of their starting positions, are pointwise equal.
1111 #if[floatingPointType]
1112      *   This method considers two $type$ elements {@code a} and {@code b}
1113      *   to be equal if
1114      *   {@code (a == b) || ($Fulltype$.isNaN(a) && $Fulltype$.isNaN(b))}.
1115      *   The values {@code -0.0} and {@code +0.0} are considered to be
1116      *   equal, unlike {@link $Fulltype$#equals(Object)}.
1117 #end[floatingPointType]
1118      *   </p></li>
1119      *
1120      * </ol>
1121      *
1122      * <p> A $type$ buffer is not equal to any other type of object.  </p>
1123      *
1124      * @param  ob  The object to which this buffer is to be compared
1125      *
1126      * @return  <tt>true</tt> if, and only if, this buffer is equal to the
1127      *           given object
1128      */
1129     public boolean equals(Object ob) {
1130         if (this == ob)
1131             return true;
1132         if (!(ob instanceof $Type$Buffer))
1133             return false;
1134         $Type$Buffer that = ($Type$Buffer)ob;
1135         if (this.remaining() != that.remaining())
1136             return false;
1137         int p = this.position();
1138         for (int i = this.limit() - 1, j = that.limit() - 1; i >= p; i--, j--)
1139             if (!equals(this.get(i), that.get(j)))
1140                 return false;
1141         return true;
1142     }
1143 
1144     private static boolean equals($type$ x, $type$ y) {
1145 #if[floatingPointType]
1146         return (x == y) || ($Fulltype$.isNaN(x) && $Fulltype$.isNaN(y));
1147 #else[floatingPointType]
1148         return x == y;
1149 #end[floatingPointType]
1150     }
1151 
1152     /**
1153      * Compares this buffer to another.
1154      *
1155      * <p> Two $type$ buffers are compared by comparing their sequences of
1156      * remaining elements lexicographically, without regard to the starting
1157      * position of each sequence within its corresponding buffer.
1158 #if[floatingPointType]
1159      * Pairs of {@code $type$} elements are compared as if by invoking
1160      * {@link $Fulltype$#compare($type$,$type$)}, except that
1161      * {@code -0.0} and {@code 0.0} are considered to be equal.
1162      * {@code $Fulltype$.NaN} is considered by this method to be equal
1163      * to itself and greater than all other {@code $type$} values
1164      * (including {@code $Fulltype$.POSITIVE_INFINITY}).
1165 #else[floatingPointType]
1166      * Pairs of {@code $type$} elements are compared as if by invoking
1167      * {@link $Fulltype$#compare($type$,$type$)}.
1168 #end[floatingPointType]
1169      *
1170      * <p> A $type$ buffer is not comparable to any other type of object.
1171      *
1172      * @return  A negative integer, zero, or a positive integer as this buffer
1173      *          is less than, equal to, or greater than the given buffer
1174      */
1175     public int compareTo($Type$Buffer that) {
1176         int n = this.position() + Math.min(this.remaining(), that.remaining());
1177         for (int i = this.position(), j = that.position(); i < n; i++, j++) {
1178             int cmp = compare(this.get(i), that.get(j));
1179             if (cmp != 0)
1180                 return cmp;
1181         }
1182         return this.remaining() - that.remaining();
1183     }
1184 
1185     private static int compare($type$ x, $type$ y) {
1186 #if[floatingPointType]
1187         return ((x < y)  ? -1 :
1188                 (x > y)  ? +1 :
1189                 (x == y) ?  0 :
1190                 $Fulltype$.isNaN(x) ? ($Fulltype$.isNaN(y) ? 0 : +1) : -1);
1191 #else[floatingPointType]
1192         return $Fulltype$.compare(x, y);
1193 #end[floatingPointType]
1194     }
1195 
1196     // -- Other char stuff --
1197 
1198 #if[char]
1199 
1200     /**
1201      * Returns a string containing the characters in this buffer.
1202      *
1203      * <p> The first character of the resulting string will be the character at
1204      * this buffer's position, while the last character will be the character
1205      * at index <tt>limit()</tt>&nbsp;-&nbsp;1.  Invoking this method does not
1206      * change the buffer's position. </p>
1207      *
1208      * @return  The specified string
1209      */
1210     public String toString() {
1211         return toString(position(), limit());
1212     }
1213 
1214     abstract String toString(int start, int end);       // package-private
1215 
1216 
1217     // --- Methods to support CharSequence ---
1218 
1219     /**
1220      * Returns the length of this character buffer.
1221      *
1222      * <p> When viewed as a character sequence, the length of a character
1223      * buffer is simply the number of characters between the position
1224      * (inclusive) and the limit (exclusive); that is, it is equivalent to
1225      * <tt>remaining()</tt>. </p>
1226      *
1227      * @return  The length of this character buffer
1228      */
1229     public final int length() {
1230         return remaining();
1231     }
1232 
1233     /**
1234      * Reads the character at the given index relative to the current
1235      * position. </p>
1236      *
1237      * @param  index
1238      *         The index of the character to be read, relative to the position;
1239      *         must be non-negative and smaller than <tt>remaining()</tt>
1240      *
1241      * @return  The character at index
1242      *          <tt>position()&nbsp;+&nbsp;index</tt>
1243      *
1244      * @throws  IndexOutOfBoundsException
1245      *          If the preconditions on <tt>index</tt> do not hold
1246      */
1247     public final char charAt(int index) {
1248         return get(position() + checkIndex(index, 1));
1249     }
1250 
1251     /**
1252      * Creates a new character buffer that represents the specified subsequence
1253      * of this buffer, relative to the current position.
1254      *
1255      * <p> The new buffer will share this buffer's content; that is, if the
1256      * content of this buffer is mutable then modifications to one buffer will
1257      * cause the other to be modified.  The new buffer's capacity will be that
1258      * of this buffer, its position will be
1259      * <tt>position()</tt>&nbsp;+&nbsp;<tt>start</tt>, and its limit will be
1260      * <tt>position()</tt>&nbsp;+&nbsp;<tt>end</tt>.  The new buffer will be
1261      * direct if, and only if, this buffer is direct, and it will be read-only
1262      * if, and only if, this buffer is read-only.  </p>
1263      *
1264      * @param  start
1265      *         The index, relative to the current position, of the first
1266      *         character in the subsequence; must be non-negative and no larger
1267      *         than <tt>remaining()</tt>
1268      *
1269      * @param  end
1270      *         The index, relative to the current position, of the character
1271      *         following the last character in the subsequence; must be no
1272      *         smaller than <tt>start</tt> and no larger than
1273      *         <tt>remaining()</tt>
1274      *
1275      * @return  The new character buffer
1276      *
1277      * @throws  IndexOutOfBoundsException
1278      *          If the preconditions on <tt>start</tt> and <tt>end</tt>
1279      *          do not hold
1280      */
1281     public abstract CharBuffer subSequence(int start, int end);
1282 
1283 
1284     // --- Methods to support Appendable ---
1285 
1286     /**
1287      * Appends the specified character sequence  to this
1288      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1289      *
1290      * <p> An invocation of this method of the form <tt>dst.append(csq)</tt>
1291      * behaves in exactly the same way as the invocation
1292      *
1293      * <pre>
1294      *     dst.put(csq.toString()) </pre>
1295      *
1296      * <p> Depending on the specification of <tt>toString</tt> for the
1297      * character sequence <tt>csq</tt>, the entire sequence may not be
1298      * appended.  For instance, invoking the {@link $Type$Buffer#toString()
1299      * toString} method of a character buffer will return a subsequence whose
1300      * content depends upon the buffer's position and limit.
1301      *
1302      * @param  csq
1303      *         The character sequence to append.  If <tt>csq</tt> is
1304      *         <tt>null</tt>, then the four characters <tt>"null"</tt> are
1305      *         appended to this character buffer.
1306      *
1307      * @return  This buffer
1308      *
1309      * @throws  BufferOverflowException
1310      *          If there is insufficient space in this buffer
1311      *
1312      * @throws  ReadOnlyBufferException
1313      *          If this buffer is read-only
1314      *
1315      * @since  1.5
1316      */
1317     public $Type$Buffer append(CharSequence csq) {
1318         if (csq == null)
1319             return put("null");
1320         else
1321             return put(csq.toString());
1322     }
1323 
1324     /**
1325      * Appends a subsequence of the  specified character sequence  to this
1326      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1327      *
1328      * <p> An invocation of this method of the form <tt>dst.append(csq, start,
1329      * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in exactly the
1330      * same way as the invocation
1331      *
1332      * <pre>
1333      *     dst.put(csq.subSequence(start, end).toString()) </pre>
1334      *
1335      * @param  csq
1336      *         The character sequence from which a subsequence will be
1337      *         appended.  If <tt>csq</tt> is <tt>null</tt>, then characters
1338      *         will be appended as if <tt>csq</tt> contained the four
1339      *         characters <tt>"null"</tt>.
1340      *
1341      * @return  This buffer
1342      *
1343      * @throws  BufferOverflowException
1344      *          If there is insufficient space in this buffer
1345      *
1346      * @throws  IndexOutOfBoundsException
1347      *          If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
1348      *          is greater than <tt>end</tt>, or <tt>end</tt> is greater than
1349      *          <tt>csq.length()</tt>
1350      *
1351      * @throws  ReadOnlyBufferException
1352      *          If this buffer is read-only
1353      *
1354      * @since  1.5
1355      */
1356     public $Type$Buffer append(CharSequence csq, int start, int end) {
1357         CharSequence cs = (csq == null ? "null" : csq);
1358         return put(cs.subSequence(start, end).toString());
1359     }
1360 
1361     /**
1362      * Appends the specified $type$  to this
1363      * buffer&nbsp;&nbsp;<i>(optional operation)</i>.
1364      *
1365      * <p> An invocation of this method of the form <tt>dst.append($x$)</tt>
1366      * behaves in exactly the same way as the invocation
1367      *
1368      * <pre>
1369      *     dst.put($x$) </pre>
1370      *
1371      * @param  $x$
1372      *         The 16-bit $type$ to append
1373      *
1374      * @return  This buffer
1375      *
1376      * @throws  BufferOverflowException
1377      *          If there is insufficient space in this buffer
1378      *
1379      * @throws  ReadOnlyBufferException
1380      *          If this buffer is read-only
1381      *
1382      * @since  1.5
1383      */
1384     public $Type$Buffer append($type$ $x$) {
1385         return put($x$);
1386     }
1387 
1388 #end[char]
1389 
1390 
1391     // -- Other byte stuff: Access to binary data --
1392 
1393 #if[!byte]
1394 
1395     /**
1396      * Retrieves this buffer's byte order.
1397      *
1398      * <p> The byte order of $a$ $type$ buffer created by allocation or by
1399      * wrapping an existing <tt>$type$</tt> array is the {@link
1400      * ByteOrder#nativeOrder </code>native order<code>} of the underlying
1401      * hardware.  The byte order of $a$ $type$ buffer created as a <a
1402      * href="ByteBuffer.html#views">view</a> of a byte buffer is that of the
1403      * byte buffer at the moment that the view is created.  </p>
1404      *
1405      * @return  This buffer's byte order
1406      */
1407     public abstract ByteOrder order();
1408 
1409 #end[!byte]
1410 
1411 #if[byte]
1412 
1413     boolean bigEndian                                   // package-private
1414         = true;
1415     boolean nativeByteOrder                             // package-private
1416         = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN);
1417 
1418     /**
1419      * Retrieves this buffer's byte order.
1420      *
1421      * <p> The byte order is used when reading or writing multibyte values, and
1422      * when creating buffers that are views of this byte buffer.  The order of
1423      * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN
1424      * BIG_ENDIAN}.  </p>
1425      *
1426      * @return  This buffer's byte order
1427      */
1428     public final ByteOrder order() {
1429         return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN;
1430     }
1431 
1432     /**
1433      * Modifies this buffer's byte order.  </p>
1434      *
1435      * @param  bo
1436      *         The new byte order,
1437      *         either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
1438      *         or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}
1439      *
1440      * @return  This buffer
1441      */
1442     public final $Type$Buffer order(ByteOrder bo) {
1443         bigEndian = (bo == ByteOrder.BIG_ENDIAN);
1444         nativeByteOrder =
1445             (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN));
1446         return this;
1447     }
1448 
1449     // Unchecked accessors, for use by ByteBufferAs-X-Buffer classes
1450     //
1451     abstract byte _get(int i);                          // package-private
1452     abstract void _put(int i, byte b);                  // package-private
1453 
1454     // #BIN
1455     //
1456     // Binary-data access methods  for short, char, int, long, float,
1457     // and double will be inserted here
1458 
1459 #end[byte]
1460 
1461 }