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