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