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