1 /*
2 * Copyright (c) 2000, 2019, 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 java.util.Objects;
40 import jdk.internal.util.ArraysSupport;
41
42 /**
43 * $A$ $type$ buffer.
44 *
45 * <p> This class defines {#if[byte]?six:four} categories of operations upon
46 * $type$ buffers:
47 *
48 * <ul>
49 *
50 * <li><p> Absolute and relative {@link #get() <i>get</i>} and
51 * {@link #put($type$) <i>put</i>} methods that read and write
52 * single $type$s; </p></li>
53 *
54 * <li><p> Absolute and relative {@link #get($type$[]) <i>bulk get</i>}
55 * methods that transfer contiguous sequences of $type$s from this buffer
56 * into an array; {#if[!byte]?and}</p></li>
57 *
58 * <li><p> Absolute and relative {@link #put($type$[]) <i>bulk put</i>}
59 * methods that transfer contiguous sequences of $type$s from $a$
60 * $type$ array{#if[char]?, a string,} or some other $type$
61 * buffer into this buffer;{#if[!byte]? and} </p></li>
62 *
63 #if[byte]
64 *
65 * <li><p> Absolute and relative {@link #getChar() <i>get</i>}
66 * and {@link #putChar(char) <i>put</i>} methods that read and
67 * write values of other primitive types, translating them to and from
68 * sequences of bytes in a particular byte order; </p></li>
69 *
70 * <li><p> Methods for creating <i><a href="#views">view buffers</a></i>,
71 * which allow a byte buffer to be viewed as a buffer containing values of
72 * some other primitive type; and </p></li>
73 *
74 #end[byte]
75 *
76 * <li><p> A method for {@link #compact compacting}
77 * $a$ $type$ buffer. </p></li>
78 *
79 * </ul>
80 *
81 * <p> $Type$ buffers can be created either by {@link #allocate
82 * <i>allocation</i>}, which allocates space for the buffer's
83 *
84 #if[byte]
85 *
86 * content, or by {@link #wrap($type$[]) <i>wrapping</i>} an
87 * existing $type$ array {#if[char]?or string} into a buffer.
88 *
89 #else[byte]
90 *
91 * content, by {@link #wrap($type$[]) <i>wrapping</i>} an existing
92 * $type$ array {#if[char]?or string} into a buffer, or by creating a
93 * <a href="ByteBuffer.html#views"><i>view</i></a> of an existing byte buffer.
94 *
95 #end[byte]
96 *
97 #if[byte]
98 *
99 * <a id="direct"></a>
100 * <h2> Direct <i>vs.</i> non-direct buffers </h2>
101 *
102 * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>. Given a
103 * direct byte buffer, the Java virtual machine will make a best effort to
104 * perform native I/O operations directly upon it. That is, it will attempt to
105 * avoid copying the buffer's content to (or from) an intermediate buffer
106 * before (or after) each invocation of one of the underlying operating
107 * system's native I/O operations.
108 *
109 * <p> A direct byte buffer may be created by invoking the {@link
110 * #allocateDirect(int) allocateDirect} factory method of this class. The
111 * buffers returned by this method typically have somewhat higher allocation
112 * and deallocation costs than non-direct buffers. The contents of direct
113 * buffers may reside outside of the normal garbage-collected heap, and so
114 * their impact upon the memory footprint of an application might not be
115 * obvious. It is therefore recommended that direct buffers be allocated
116 * primarily for large, long-lived buffers that are subject to the underlying
117 * system's native I/O operations. In general it is best to allocate direct
118 * buffers only when they yield a measureable gain in program performance.
119 *
120 * <p> A direct byte buffer may also be created by {@link
121 * java.nio.channels.FileChannel#map mapping} a region of a file
122 * directly into memory. An implementation of the Java platform may optionally
123 * support the creation of direct byte buffers from native code via JNI. If an
124 * instance of one of these kinds of buffers refers to an inaccessible region
125 * of memory then an attempt to access that region will not change the buffer's
126 * content and will cause an unspecified exception to be thrown either at the
127 * time of the access or at some later time.
128 *
129 * <p> Whether a byte buffer is direct or non-direct may be determined by
130 * invoking its {@link #isDirect isDirect} method. This method is provided so
131 * that explicit buffer management can be done in performance-critical code.
132 *
133 *
134 * <a id="bin"></a>
135 * <h2> Access to binary data </h2>
136 *
137 * <p> This class defines methods for reading and writing values of all other
138 * primitive types, except {@code boolean}. Primitive values are translated
139 * to (or from) sequences of bytes according to the buffer's current byte
140 * order, which may be retrieved and modified via the {@link #order order}
141 * methods. Specific byte orders are represented by instances of the {@link
142 * ByteOrder} class. The initial order of a byte buffer is always {@link
143 * ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
144 *
145 * <p> For access to heterogeneous binary data, that is, sequences of values of
146 * different types, this class defines a family of absolute and relative
147 * <i>get</i> and <i>put</i> methods for each type. For 32-bit floating-point
148 * values, for example, this class defines:
149 *
150 * <blockquote><pre>
151 * float {@link #getFloat()}
152 * float {@link #getFloat(int) getFloat(int index)}
153 * void {@link #putFloat(float) putFloat(float f)}
154 * void {@link #putFloat(int,float) putFloat(int index, float f)}</pre></blockquote>
155 *
156 * <p> Corresponding methods are defined for the types {@code char,
157 * short, int, long}, and {@code double}. The index
158 * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of
159 * bytes rather than of the type being read or written.
160 *
161 * <a id="views"></a>
162 *
163 * <p> For access to homogeneous binary data, that is, sequences of values of
164 * the same type, this class defines methods that can create <i>views</i> of a
165 * given byte buffer. A <i>view buffer</i> is simply another buffer whose
166 * content is backed by the byte buffer. Changes to the byte buffer's content
167 * will be visible in the view buffer, and vice versa; the two buffers'
168 * position, limit, and mark values are independent. The {@link
169 * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of
170 * the {@link FloatBuffer} class that is backed by the byte buffer upon which
171 * the method is invoked. Corresponding view-creation methods are defined for
172 * the types {@code char, short, int, long}, and {@code double}.
173 *
174 * <p> View buffers have three important advantages over the families of
175 * type-specific <i>get</i> and <i>put</i> methods described above:
176 *
177 * <ul>
178 *
179 * <li><p> A view buffer is indexed not in terms of bytes but rather in terms
180 * of the type-specific size of its values; </p></li>
181 *
182 * <li><p> A view buffer provides relative bulk <i>get</i> and <i>put</i>
183 * methods that can transfer contiguous sequences of values between a buffer
184 * and an array or some other buffer of the same type; and </p></li>
185 *
186 * <li><p> A view buffer is potentially much more efficient because it will
187 * be direct if, and only if, its backing byte buffer is direct. </p></li>
188 *
189 * </ul>
190 *
191 * <p> The byte order of a view buffer is fixed to be that of its byte buffer
192 * at the time that the view is created. </p>
193 *
194 #end[byte]
195 *
196 #if[!byte]
197 *
198 * <p> Like a byte buffer, $a$ $type$ buffer is either <a
199 * href="ByteBuffer.html#direct"><i>direct</i> or <i>non-direct</i></a>. A
200 * $type$ buffer created via the {@code wrap} methods of this class will
201 * be non-direct. $A$ $type$ buffer created as a view of a byte buffer will
202 * be direct if, and only if, the byte buffer itself is direct. Whether or not
203 * $a$ $type$ buffer is direct may be determined by invoking the {@link
204 * #isDirect isDirect} method. </p>
205 *
206 #end[!byte]
207 *
208 #if[char]
209 *
210 * <p> This class implements the {@link CharSequence} interface so that
211 * character buffers may be used wherever character sequences are accepted, for
212 * example in the regular-expression package {@link java.util.regex}.
213 * </p>
214 *
215 #end[char]
216 *
217 #if[byte]
218 * <h2> Invocation chaining </h2>
219 #end[byte]
220 *
221 * <p> Methods in this class that do not otherwise have a value to return are
222 * specified to return the buffer upon which they are invoked. This allows
223 * method invocations to be chained.
224 *
225 #if[byte]
226 *
227 * The sequence of statements
228 *
229 * <blockquote><pre>
230 * bb.putInt(0xCAFEBABE);
231 * bb.putShort(3);
232 * bb.putShort(45);</pre></blockquote>
233 *
234 * can, for example, be replaced by the single statement
235 *
236 * <blockquote><pre>
237 * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote>
238 *
239 #end[byte]
240 #if[char]
241 *
242 * The sequence of statements
243 *
244 * <blockquote><pre>
245 * cb.put("text/");
246 * cb.put(subtype);
247 * cb.put("; charset=");
248 * cb.put(enc);</pre></blockquote>
249 *
250 * can, for example, be replaced by the single statement
251 *
252 * <blockquote><pre>
253 * cb.put("text/").put(subtype).put("; charset=").put(enc);</pre></blockquote>
254 *
255 #end[char]
256 *
257 *
258 * @author Mark Reinhold
259 * @author JSR-51 Expert Group
260 * @since 1.4
261 */
262
263 public abstract class $Type$Buffer
264 extends Buffer
265 implements Comparable<$Type$Buffer>{#if[char]?, Appendable, CharSequence, Readable}
266 {
267
268 // These fields are declared here rather than in Heap-X-Buffer in order to
269 // reduce the number of virtual method invocations needed to access these
270 // values, which is especially costly when coding small buffers.
271 //
272 final $type$[] hb; // Non-null only for heap buffers
273 final int offset;
274 boolean isReadOnly;
275
276 // Creates a new buffer with the given mark, position, limit, capacity,
277 // backing array, and array offset
278 //
279 $Type$Buffer(int mark, int pos, int lim, int cap, // package-private
280 $type$[] hb, int offset)
281 {
282 super(mark, pos, lim, cap);
283 this.hb = hb;
284 this.offset = offset;
285 }
286
287 // Creates a new buffer with the given mark, position, limit, and capacity
288 //
289 $Type$Buffer(int mark, int pos, int lim, int cap) { // package-private
290 this(mark, pos, lim, cap, null, 0);
291 }
292
293 @Override
294 Object base() {
295 return hb;
296 }
297
298 #if[byte]
299
300 /**
301 * Allocates a new direct $type$ buffer.
302 *
303 * <p> The new buffer's position will be zero, its limit will be its
304 * capacity, its mark will be undefined, each of its elements will be
305 * initialized to zero, and its byte order will be
306 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}. Whether or not it has a
307 * {@link #hasArray backing array} is unspecified.
308 *
309 * @param capacity
310 * The new buffer's capacity, in $type$s
311 *
312 * @return The new $type$ buffer
313 *
314 * @throws IllegalArgumentException
315 * If the {@code capacity} is a negative integer
316 */
317 public static $Type$Buffer allocateDirect(int capacity) {
318 return new Direct$Type$Buffer(capacity);
319 }
320
321 #end[byte]
322
323 /**
324 * Allocates a new $type$ buffer.
325 *
326 * <p> The new buffer's position will be zero, its limit will be its
327 * capacity, its mark will be undefined, each of its elements will be
328 * initialized to zero, and its byte order will be
329 #if[byte]
330 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
331 #else[byte]
332 * the {@link ByteOrder#nativeOrder native order} of the underlying
333 * hardware.
334 #end[byte]
335 * It will have a {@link #array backing array}, and its
336 * {@link #arrayOffset array offset} will be zero.
337 *
338 * @param capacity
339 * The new buffer's capacity, in $type$s
340 *
341 * @return The new $type$ buffer
342 *
343 * @throws IllegalArgumentException
344 * If the {@code capacity} is a negative integer
345 */
346 public static $Type$Buffer allocate(int capacity) {
347 if (capacity < 0)
348 throw createCapacityException(capacity);
349 return new Heap$Type$Buffer(capacity, capacity);
350 }
351
352 /**
353 * Wraps $a$ $type$ array into a buffer.
354 *
355 * <p> The new buffer will be backed by the given $type$ array;
356 * that is, modifications to the buffer will cause the array to be modified
357 * and vice versa. The new buffer's capacity will be
358 * {@code array.length}, its position will be {@code offset}, its limit
359 * will be {@code offset + length}, its mark will be undefined, and its
360 * byte order will be
361 #if[byte]
362 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
363 #else[byte]
364 * the {@link ByteOrder#nativeOrder native order} of the underlying
365 * hardware.
366 #end[byte]
367 * Its {@link #array backing array} will be the given array, and
368 * its {@link #arrayOffset array offset} will be zero. </p>
369 *
370 * @param array
371 * The array that will back the new buffer
372 *
373 * @param offset
374 * The offset of the subarray to be used; must be non-negative and
375 * no larger than {@code array.length}. The new buffer's position
376 * will be set to this value.
377 *
378 * @param length
379 * The length of the subarray to be used;
380 * must be non-negative and no larger than
381 * {@code array.length - offset}.
382 * The new buffer's limit will be set to {@code offset + length}.
383 *
384 * @return The new $type$ buffer
385 *
386 * @throws IndexOutOfBoundsException
387 * If the preconditions on the {@code offset} and {@code length}
388 * parameters do not hold
389 */
390 public static $Type$Buffer wrap($type$[] array,
391 int offset, int length)
392 {
393 try {
394 return new Heap$Type$Buffer(array, offset, length);
395 } catch (IllegalArgumentException x) {
396 throw new IndexOutOfBoundsException();
397 }
398 }
399
400 /**
401 * Wraps $a$ $type$ array into a buffer.
402 *
403 * <p> The new buffer will be backed by the given $type$ array;
404 * that is, modifications to the buffer will cause the array to be modified
405 * and vice versa. The new buffer's capacity and limit will be
406 * {@code array.length}, its position will be zero, its mark will be
407 * undefined, and its byte order will be
408 #if[byte]
409 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
410 #else[byte]
411 * the {@link ByteOrder#nativeOrder native order} of the underlying
412 * hardware.
413 #end[byte]
414 * Its {@link #array backing array} will be the given array, and its
415 * {@link #arrayOffset array offset} will be zero. </p>
416 *
417 * @param array
418 * The array that will back this buffer
419 *
420 * @return The new $type$ buffer
421 */
422 public static $Type$Buffer wrap($type$[] array) {
423 return wrap(array, 0, array.length);
424 }
425
426 #if[char]
427
428 /**
429 * Attempts to read characters into the specified character buffer.
430 * The buffer is used as a repository of characters as-is: the only
431 * changes made are the results of a put operation. No flipping or
432 * rewinding of the buffer is performed.
433 *
434 * @param target the buffer to read characters into
435 * @return The number of characters added to the buffer, or
436 * -1 if this source of characters is at its end
437 * @throws IOException if an I/O error occurs
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 * Absolute bulk <i>get</i> method.
767 *
768 * <p> This method copies {@code length} $type$s from this buffer to a
769 * destination array, starting at the given {@code index} in this buffer
770 * and the given {@code offset} in the array. The position of this buffer
771 * is unchanged.
772 *
773 * <p> An invocation of this method of the form
774 * <code>src.get(index, dst, off, len)</code>
775 * has exactly the same effect as the following loop except that it first
776 * checks the consistency of the supplied parameters and it is potentially
777 * much more efficient:
778 *
779 * <pre>{@code
780 * for (int i = off, j = index; i < off + len; i++, j++)
781 * dst[i] = src.get(j);
782 * }</pre>
783 *
784 * @param index
785 * The index from which the $type$s will be read
786 *
787 * @param dst
788 * The destination array
789 *
790 * @param offset
791 * The offset within the array of the first $type$ to be
792 * written; must be non-negative and no larger than
793 * {@code dst.length}
794 *
795 * @param length
796 * The number of $type$s to be written to the given
797 * array; must be non-negative and no larger than the minimum of
798 * {@code dst.length - offset} and {@code limit() - index}
799 *
800 * @return This buffer
801 *
802 * @throws IndexOutOfBoundsException
803 * If the index is negative, {@code index + length > limit()},
804 * or the preconditions on the {@code offset} and {@code length}
805 * parameters do not hold
806 *
807 * @since 13
808 */
809 public $Type$Buffer get(int index, $type$[] dst, int offset, int length) {
810 //System.out.println("Absolute bulk get");
811 Objects.checkFromIndexSize(index, length, limit());
812 Objects.checkFromIndexSize(offset, length, dst.length);
813 int end = offset + length;
814 for (int i = offset, j = index; i < end; i++, j++)
815 dst[i] = get(j);
816 return this;
817 }
818
819 /**
820 * Absolute bulk <i>get</i> method.
821 *
822 * <p> This method transfers $type$s from this buffer into the given
823 * destination array. The position of this buffer is unchanged. An
824 * invocation of this method of the form
825 * <code>src.get(index, dst)</code> behaves in exactly the same
826 * way as the invocation
827 *
828 * <pre>
829 * src.get(index, dst, 0, dst.length) </pre>
830 *
831 * @param index
832 * The index from which the $type$s will be read
833 *
834 * @param dst
835 * The destination array
836 *
837 * @return This buffer
838 *
839 * @throws IndexOutOfBoundsException
840 * If the index is negative or
841 * {@code index + dst.length > limit()}.
842 *
843 * @since 13
844 */
845 public $Type$Buffer get(int index, $type$[] dst) {
846 return get(index, dst, 0, dst.length);
847 }
848
849
850 // -- Bulk put operations --
851
852 /**
853 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
854 *
855 * <p> This method transfers the $type$s remaining in the given source
856 * buffer into this buffer. If there are more $type$s remaining in the
857 * source buffer than in this buffer, that is, if
858 * {@code src.remaining()} {@code >} {@code remaining()},
859 * then no $type$s are transferred and a {@link
860 * BufferOverflowException} is thrown.
861 *
862 * <p> Otherwise, this method copies
863 * <i>n</i> = {@code src.remaining()} $type$s from the given
864 * buffer into this buffer, starting at each buffer's current position.
865 * The positions of both buffers are then incremented by <i>n</i>.
866 *
867 * <p> In other words, an invocation of this method of the form
868 * {@code dst.put(src)} has exactly the same effect as the loop
869 *
870 * <pre>
871 * while (src.hasRemaining())
872 * dst.put(src.get()); </pre>
873 *
874 * except that it first checks that there is sufficient space in this
875 * buffer and it is potentially much more efficient.
876 *
877 * @param src
878 * The source buffer from which $type$s are to be read;
879 * must not be this buffer
880 *
881 * @return This buffer
882 *
883 * @throws BufferOverflowException
884 * If there is insufficient space in this buffer
885 * for the remaining $type$s in the source buffer
886 *
887 * @throws IllegalArgumentException
888 * If the source buffer is this buffer
889 *
890 * @throws ReadOnlyBufferException
891 * If this buffer is read-only
892 */
893 public $Type$Buffer put($Type$Buffer src) {
894 if (src == this)
895 throw createSameBufferException();
896 if (isReadOnly())
897 throw new ReadOnlyBufferException();
898 int n = src.remaining();
899 if (n > remaining())
900 throw new BufferOverflowException();
901 for (int i = 0; i < n; i++)
902 put(src.get());
903 return this;
904 }
905
906 /**
907 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
908 *
909 * <p> This method transfers $type$s into this buffer from the given
910 * source array. If there are more $type$s to be copied from the array
911 * than remain in this buffer, that is, if
912 * {@code length} {@code >} {@code remaining()}, then no
913 * $type$s are transferred and a {@link BufferOverflowException} is
914 * thrown.
915 *
916 * <p> Otherwise, this method copies {@code length} $type$s from the
917 * given array into this buffer, starting at the given offset in the array
918 * and at the current position of this buffer. The position of this buffer
919 * is then incremented by {@code length}.
920 *
921 * <p> In other words, an invocation of this method of the form
922 * <code>dst.put(src, off, len)</code> has exactly the same effect as
923 * the loop
924 *
925 * <pre>{@code
926 * for (int i = off; i < off + len; i++)
927 * dst.put(src[i]);
928 * }</pre>
929 *
930 * except that it first checks that there is sufficient space in this
931 * buffer and it is potentially much more efficient.
932 *
933 * @param src
934 * The array from which $type$s are to be read
935 *
936 * @param offset
937 * The offset within the array of the first $type$ to be read;
938 * must be non-negative and no larger than {@code array.length}
939 *
940 * @param length
941 * The number of $type$s to be read from the given array;
942 * must be non-negative and no larger than
943 * {@code array.length - offset}
944 *
945 * @return This buffer
946 *
947 * @throws BufferOverflowException
948 * If there is insufficient space in this buffer
949 *
950 * @throws IndexOutOfBoundsException
951 * If the preconditions on the {@code offset} and {@code length}
952 * parameters do not hold
953 *
954 * @throws ReadOnlyBufferException
955 * If this buffer is read-only
956 */
957 public $Type$Buffer put($type$[] src, int offset, int length) {
958 checkBounds(offset, length, src.length);
959 if (length > remaining())
960 throw new BufferOverflowException();
961 int end = offset + length;
962 for (int i = offset; i < end; i++)
963 this.put(src[i]);
964 return this;
965 }
966
967 /**
968 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
969 *
970 * <p> This method transfers the entire content of the given source
971 * $type$ array into this buffer. An invocation of this method of the
972 * form {@code dst.put(a)} behaves in exactly the same way as the
973 * invocation
974 *
975 * <pre>
976 * dst.put(a, 0, a.length) </pre>
977 *
978 * @param src
979 * The source array
980 *
981 * @return This buffer
982 *
983 * @throws BufferOverflowException
984 * If there is insufficient space in this buffer
985 *
986 * @throws ReadOnlyBufferException
987 * If this buffer is read-only
988 */
989 public final $Type$Buffer put($type$[] src) {
990 return put(src, 0, src.length);
991 }
992
993 /**
994 * Absolute bulk <i>put</i> method <i>(optional operation)</i>.
995 *
996 * <p> This method copies {@code length} $type$s into this buffer from a
997 * source array, starting at the given {@code offset} in the array and the
998 * given {@code index} of this buffer. The position of this buffer is
999 * unchanged.
1000 *
1001 * <p> An invocation of this method of the form
1002 * <code>dst.put(index, src, off, len)</code>
1003 * has exactly the same effect as the following loop except that it first
1004 * checks the consistency of the supplied parameters and it is potentially
1005 * much more efficient:
1006 *
1007 * <pre>{@code
1008 * for (int i = off, j = index; i < off + len; i++, j++)
1009 * dst.put(j, src[i]);
1010 * }</pre>
1011 *
1012 * @param index
1013 * The index at which the $type$s will be written
1014 *
1015 * @param src
1016 * The array from which $type$s are to be read
1017 *
1018 * @param offset
1019 * The offset within the array of the first $type$ to be read;
1020 * must be non-negative and no larger than {@code array.length}
1021 *
1022 * @param length
1023 * The number of $type$s to be read from the given array;
1024 * must be non-negative and no larger than the minimum of
1025 * {@code array.length - offset} and {@code limit() - index}
1026 *
1027 * @return This buffer
1028 *
1029 * @throws IndexOutOfBoundsException
1030 * If the index is negative, {@code index + length > limit()},
1031 * or the preconditions on the {@code offset} and {@code length}
1032 * parameters do not hold
1033 *
1034 * @throws ReadOnlyBufferException
1035 * If this buffer is read-only
1036 *
1037 * @since 13
1038 */
1039 public $Type$Buffer put(int index, $type$[] src, int offset, int length) {
1040 //System.out.println("Absolute bulk put array");
1041 if (isReadOnly())
1042 throw new ReadOnlyBufferException();
1043 Objects.checkFromIndexSize(index, length, limit());
1044 Objects.checkFromIndexSize(offset, length, src.length);
1045 int end = offset + length;
1046 for (int i = offset, j = index; i < end; i++, j++)
1047 this.put(j, src[i]);
1048 return this;
1049 }
1050
1051 /**
1052 * Absolute bulk <i>put</i> method <i>(optional operation)</i>.
1053 *
1054 * <p> This method copies $type$s into this buffer from the given source
1055 * array. The position of this buffer is unchanged. An invocation of this
1056 * method of the form <code>dst.put(index, src)</code>
1057 * behaves in exactly the same was as the invocation
1058 *
1059 * <pre>
1060 * dst.put(index, src, 0, src.length); </pre>
1061 *
1062 * @param index
1063 * The index at which the $type$s will be written
1064 *
1065 * @param src
1066 * The array from which $type$s are to be read
1067 *
1068 * @return This buffer
1069 *
1070 * @throws IndexOutOfBoundsException
1071 * If the index is negative, {@code index + length > limit()},
1072 * or the preconditions on the {@code offset} and {@code length}
1073 * parameters do not hold
1074 *
1075 * @throws ReadOnlyBufferException
1076 * If this buffer is read-only
1077 *
1078 * @since 13
1079 */
1080 public $Type$Buffer put(int index, $type$[] src) {
1081 return put(index, src, 0, src.length);
1082 }
1083
1084 /**
1085 * Absolute bulk <i>put</i> method <i>(optional operation)</i>.
1086 *
1087 * <p> This method copies {@code length} $type$s into this buffer from a
1088 * source buffer, starting at the given {@code offset} in the buffer and the
1089 * given {@code index} of this buffer. The positions of both buffers are
1090 * unchanged.
1091 *
1092 * <p> An invocation of this method of the form
1093 * <code>dst.put(index, src, off, len)</code>
1094 * has exactly the same effect as the following loop except that it first
1095 * checks the consistency of the supplied parameters and it is potentially
1096 * much more efficient:
1097 *
1098 * <pre>{@code
1099 * for (int i = off, j = index; i < off + len; i++, j++)
1100 * dst.put(j, src.get(i));
1101 * }</pre>
1102 *
1103 * @param index
1104 * The index at which the $type$s will be written
1105 *
1106 * @param src
1107 * The buffer from which $type$s are to be read
1108 *
1109 * @param offset
1110 * The offset within the buffer of the first $type$ to be read;
1111 * must be non-negative and no larger than {@code src.limit()}
1112 *
1113 * @param length
1114 * The number of $type$s to be read from the given buffer;
1115 * must be non-negative and no larger than the minimum of
1116 * {@code src.limit() - offset} and {@code limit() - index}
1117 *
1118 * @return This buffer
1119 *
1120 * @throws IndexOutOfBoundsException
1121 * If the index is negative, {@code index + length > limit()},
1122 * or the preconditions on the {@code offset} and {@code length}
1123 * parameters do not hold
1124 *
1125 * @throws ReadOnlyBufferException
1126 * If this buffer is read-only
1127 *
1128 * @since 13
1129 */
1130 public $Type$Buffer put(int index, $Type$Buffer src, int offset,
1131 int length) {
1132 //System.out.println("Absolute bulk put buffer");
1133 if (isReadOnly())
1134 throw new ReadOnlyBufferException();
1135 Objects.checkFromIndexSize(index, length, limit());
1136 int n = src.limit();
1137 Objects.checkFromIndexSize(offset, length, n);
1138 for (int i = offset, j = index; i < n; i++, j++)
1139 put(j, src.get(i));
1140 return this;
1141 }
1142
1143 #if[char]
1144
1145 /**
1146 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
1147 *
1148 * <p> This method transfers $type$s from the given string into this
1149 * buffer. If there are more $type$s to be copied from the string than
1150 * remain in this buffer, that is, if
1151 * <code>end - start</code> {@code >} {@code remaining()},
1152 * then no $type$s are transferred and a {@link
1153 * BufferOverflowException} is thrown.
1154 *
1155 * <p> Otherwise, this method copies
1156 * <i>n</i> = {@code end} - {@code start} $type$s
1157 * from the given string into this buffer, starting at the given
1158 * {@code start} index and at the current position of this buffer. The
1159 * position of this buffer is then incremented by <i>n</i>.
1160 *
1161 * <p> In other words, an invocation of this method of the form
1162 * <code>dst.put(src, start, end)</code> has exactly the same effect
1163 * as the loop
1164 *
1165 * <pre>{@code
1166 * for (int i = start; i < end; i++)
1167 * dst.put(src.charAt(i));
1168 * }</pre>
1169 *
1170 * except that it first checks that there is sufficient space in this
1171 * buffer and it is potentially much more efficient.
1172 *
1173 * @param src
1174 * The string from which $type$s are to be read
1175 *
1176 * @param start
1177 * The offset within the string of the first $type$ to be read;
1178 * must be non-negative and no larger than
1179 * {@code string.length()}
1180 *
1181 * @param end
1182 * The offset within the string of the last $type$ to be read,
1183 * plus one; must be non-negative and no larger than
1184 * {@code string.length()}
1185 *
1186 * @return This buffer
1187 *
1188 * @throws BufferOverflowException
1189 * If there is insufficient space in this buffer
1190 *
1191 * @throws IndexOutOfBoundsException
1192 * If the preconditions on the {@code start} and {@code end}
1193 * parameters do not hold
1194 *
1195 * @throws ReadOnlyBufferException
1196 * If this buffer is read-only
1197 */
1198 public $Type$Buffer put(String src, int start, int end) {
1199 checkBounds(start, end - start, src.length());
1200 if (isReadOnly())
1201 throw new ReadOnlyBufferException();
1202 if (end - start > remaining())
1203 throw new BufferOverflowException();
1204 for (int i = start; i < end; i++)
1205 this.put(src.charAt(i));
1206 return this;
1207 }
1208
1209 /**
1210 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
1211 *
1212 * <p> This method transfers the entire content of the given source string
1213 * into this buffer. An invocation of this method of the form
1214 * {@code dst.put(s)} behaves in exactly the same way as the invocation
1215 *
1216 * <pre>
1217 * dst.put(s, 0, s.length()) </pre>
1218 *
1219 * @param src
1220 * The source string
1221 *
1222 * @return This buffer
1223 *
1224 * @throws BufferOverflowException
1225 * If there is insufficient space in this buffer
1226 *
1227 * @throws ReadOnlyBufferException
1228 * If this buffer is read-only
1229 */
1230 public final $Type$Buffer put(String src) {
1231 return put(src, 0, src.length());
1232 }
1233
1234 #end[char]
1235
1236
1237 // -- Other stuff --
1238
1239 /**
1240 * Tells whether or not this buffer is backed by an accessible $type$
1241 * array.
1242 *
1243 * <p> If this method returns {@code true} then the {@link #array() array}
1244 * and {@link #arrayOffset() arrayOffset} methods may safely be invoked.
1245 * </p>
1246 *
1247 * @return {@code true} if, and only if, this buffer
1248 * is backed by an array and is not read-only
1249 */
1250 public final boolean hasArray() {
1251 return (hb != null) && !isReadOnly;
1252 }
1253
1254 /**
1255 * Returns the $type$ array that backs this
1256 * buffer <i>(optional operation)</i>.
1257 *
1258 * <p> Modifications to this buffer's content will cause the returned
1259 * array's content to be modified, and vice versa.
1260 *
1261 * <p> Invoke the {@link #hasArray hasArray} method before invoking this
1262 * method in order to ensure that this buffer has an accessible backing
1263 * array. </p>
1264 *
1265 * @return The array that backs this buffer
1266 *
1267 * @throws ReadOnlyBufferException
1268 * If this buffer is backed by an array but is read-only
1269 *
1270 * @throws UnsupportedOperationException
1271 * If this buffer is not backed by an accessible array
1272 */
1273 public final $type$[] array() {
1274 if (hb == null)
1275 throw new UnsupportedOperationException();
1276 if (isReadOnly)
1277 throw new ReadOnlyBufferException();
1278 return hb;
1279 }
1280
1281 /**
1282 * Returns the offset within this buffer's backing array of the first
1283 * element of the buffer <i>(optional operation)</i>.
1284 *
1285 * <p> If this buffer is backed by an array then buffer position <i>p</i>
1286 * corresponds to array index <i>p</i> + {@code arrayOffset()}.
1287 *
1288 * <p> Invoke the {@link #hasArray hasArray} method before invoking this
1289 * method in order to ensure that this buffer has an accessible backing
1290 * array. </p>
1291 *
1292 * @return The offset within this buffer's array
1293 * of the first element of the buffer
1294 *
1295 * @throws ReadOnlyBufferException
1296 * If this buffer is backed by an array but is read-only
1297 *
1298 * @throws UnsupportedOperationException
1299 * If this buffer is not backed by an accessible array
1300 */
1301 public final int arrayOffset() {
1302 if (hb == null)
1303 throw new UnsupportedOperationException();
1304 if (isReadOnly)
1305 throw new ReadOnlyBufferException();
1306 return offset;
1307 }
1308
1309 // -- Covariant return type overrides
1310
1311 /**
1312 * {@inheritDoc}
1313 */
1314 @Override
1315 public
1316 #if[!byte]
1317 final
1318 #end[!byte]
1319 $Type$Buffer position(int newPosition) {
1320 super.position(newPosition);
1321 return this;
1322 }
1323
1324 /**
1325 * {@inheritDoc}
1326 */
1327 @Override
1328 public
1329 #if[!byte]
1330 final
1331 #end[!byte]
1332 $Type$Buffer limit(int newLimit) {
1333 super.limit(newLimit);
1334 return this;
1335 }
1336
1337 /**
1338 * {@inheritDoc}
1339 */
1340 @Override
1341 public
1342 #if[!byte]
1343 final
1344 #end[!byte]
1345 $Type$Buffer mark() {
1346 super.mark();
1347 return this;
1348 }
1349
1350 /**
1351 * {@inheritDoc}
1352 */
1353 @Override
1354 public
1355 #if[!byte]
1356 final
1357 #end[!byte]
1358 $Type$Buffer reset() {
1359 super.reset();
1360 return this;
1361 }
1362
1363 /**
1364 * {@inheritDoc}
1365 */
1366 @Override
1367 public
1368 #if[!byte]
1369 final
1370 #end[!byte]
1371 $Type$Buffer clear() {
1372 super.clear();
1373 return this;
1374 }
1375
1376 /**
1377 * {@inheritDoc}
1378 */
1379 @Override
1380 public
1381 #if[!byte]
1382 final
1383 #end[!byte]
1384 $Type$Buffer flip() {
1385 super.flip();
1386 return this;
1387 }
1388
1389 /**
1390 * {@inheritDoc}
1391 */
1392 @Override
1393 public
1394 #if[!byte]
1395 final
1396 #end[!byte]
1397 $Type$Buffer rewind() {
1398 super.rewind();
1399 return this;
1400 }
1401
1402 /**
1403 * Compacts this buffer <i>(optional operation)</i>.
1404 *
1405 * <p> The $type$s between the buffer's current position and its limit,
1406 * if any, are copied to the beginning of the buffer. That is, the
1407 * $type$ at index <i>p</i> = {@code position()} is copied
1408 * to index zero, the $type$ at index <i>p</i> + 1 is copied
1409 * to index one, and so forth until the $type$ at index
1410 * {@code limit()} - 1 is copied to index
1411 * <i>n</i> = {@code limit()} - {@code 1} - <i>p</i>.
1412 * The buffer's position is then set to <i>n+1</i> and its limit is set to
1413 * its capacity. The mark, if defined, is discarded.
1414 *
1415 * <p> The buffer's position is set to the number of $type$s copied,
1416 * rather than to zero, so that an invocation of this method can be
1417 * followed immediately by an invocation of another relative <i>put</i>
1418 * method. </p>
1419 *
1420 #if[byte]
1421 *
1422 * <p> Invoke this method after writing data from a buffer in case the
1423 * write was incomplete. The following loop, for example, copies bytes
1424 * from one channel to another via the buffer {@code buf}:
1425 *
1426 * <blockquote><pre>{@code
1427 * buf.clear(); // Prepare buffer for use
1428 * while (in.read(buf) >= 0 || buf.position != 0) {
1429 * buf.flip();
1430 * out.write(buf);
1431 * buf.compact(); // In case of partial write
1432 * }
1433 * }</pre></blockquote>
1434 *
1435 #end[byte]
1436 *
1437 * @return This buffer
1438 *
1439 * @throws ReadOnlyBufferException
1440 * If this buffer is read-only
1441 */
1442 public abstract $Type$Buffer compact();
1443
1444 /**
1445 * Tells whether or not this $type$ buffer is direct.
1446 *
1447 * @return {@code true} if, and only if, this buffer is direct
1448 */
1449 public abstract boolean isDirect();
1450
1451 #if[!char]
1452
1453 /**
1454 * Returns a string summarizing the state of this buffer.
1455 *
1456 * @return A summary string
1457 */
1458 public String toString() {
1459 StringBuffer sb = new StringBuffer();
1460 sb.append(getClass().getName());
1461 sb.append("[pos=");
1462 sb.append(position());
1463 sb.append(" lim=");
1464 sb.append(limit());
1465 sb.append(" cap=");
1466 sb.append(capacity());
1467 sb.append("]");
1468 return sb.toString();
1469 }
1470
1471 #end[!char]
1472
1473
1474 // ## Should really use unchecked accessors here for speed
1475
1476 /**
1477 * Returns the current hash code of this buffer.
1478 *
1479 * <p> The hash code of a $type$ buffer depends only upon its remaining
1480 * elements; that is, upon the elements from {@code position()} up to, and
1481 * including, the element at {@code limit()} - {@code 1}.
1482 *
1483 * <p> Because buffer hash codes are content-dependent, it is inadvisable
1484 * to use buffers as keys in hash maps or similar data structures unless it
1485 * is known that their contents will not change. </p>
1486 *
1487 * @return The current hash code of this buffer
1488 */
1489 public int hashCode() {
1490 int h = 1;
1491 int p = position();
1492 for (int i = limit() - 1; i >= p; i--)
1493 #if[int]
1494 h = 31 * h + get(i);
1495 #else[int]
1496 h = 31 * h + (int)get(i);
1497 #end[int]
1498 return h;
1499 }
1500
1501 /**
1502 * Tells whether or not this buffer is equal to another object.
1503 *
1504 * <p> Two $type$ buffers are equal if, and only if,
1505 *
1506 * <ol>
1507 *
1508 * <li><p> They have the same element type, </p></li>
1509 *
1510 * <li><p> They have the same number of remaining elements, and
1511 * </p></li>
1512 *
1513 * <li><p> The two sequences of remaining elements, considered
1514 * independently of their starting positions, are pointwise equal.
1515 #if[floatingPointType]
1516 * This method considers two $type$ elements {@code a} and {@code b}
1517 * to be equal if
1518 * {@code (a == b) || ($Fulltype$.isNaN(a) && $Fulltype$.isNaN(b))}.
1519 * The values {@code -0.0} and {@code +0.0} are considered to be
1520 * equal, unlike {@link $Fulltype$#equals(Object)}.
1521 #end[floatingPointType]
1522 * </p></li>
1523 *
1524 * </ol>
1525 *
1526 * <p> A $type$ buffer is not equal to any other type of object. </p>
1527 *
1528 * @param ob The object to which this buffer is to be compared
1529 *
1530 * @return {@code true} if, and only if, this buffer is equal to the
1531 * given object
1532 */
1533 public boolean equals(Object ob) {
1534 if (this == ob)
1535 return true;
1536 if (!(ob instanceof $Type$Buffer))
1537 return false;
1538 $Type$Buffer that = ($Type$Buffer)ob;
1539 if (this.remaining() != that.remaining())
1540 return false;
1541 return BufferMismatch.mismatch(this, this.position(),
1542 that, that.position(),
1543 this.remaining()) < 0;
1544 }
1545
1546 /**
1547 * Compares this buffer to another.
1548 *
1549 * <p> Two $type$ buffers are compared by comparing their sequences of
1550 * remaining elements lexicographically, without regard to the starting
1551 * position of each sequence within its corresponding buffer.
1552 #if[floatingPointType]
1553 * Pairs of {@code $type$} elements are compared as if by invoking
1554 * {@link $Fulltype$#compare($type$,$type$)}, except that
1555 * {@code -0.0} and {@code 0.0} are considered to be equal.
1556 * {@code $Fulltype$.NaN} is considered by this method to be equal
1557 * to itself and greater than all other {@code $type$} values
1558 * (including {@code $Fulltype$.POSITIVE_INFINITY}).
1559 #else[floatingPointType]
1560 * Pairs of {@code $type$} elements are compared as if by invoking
1561 * {@link $Fulltype$#compare($type$,$type$)}.
1562 #end[floatingPointType]
1563 *
1564 * <p> A $type$ buffer is not comparable to any other type of object.
1565 *
1566 * @return A negative integer, zero, or a positive integer as this buffer
1567 * is less than, equal to, or greater than the given buffer
1568 */
1569 public int compareTo($Type$Buffer that) {
1570 int i = BufferMismatch.mismatch(this, this.position(),
1571 that, that.position(),
1572 Math.min(this.remaining(), that.remaining()));
1573 if (i >= 0) {
1574 return compare(this.get(this.position() + i), that.get(that.position() + i));
1575 }
1576 return this.remaining() - that.remaining();
1577 }
1578
1579 private static int compare($type$ x, $type$ y) {
1580 #if[floatingPointType]
1581 return ((x < y) ? -1 :
1582 (x > y) ? +1 :
1583 (x == y) ? 0 :
1584 $Fulltype$.isNaN(x) ? ($Fulltype$.isNaN(y) ? 0 : +1) : -1);
1585 #else[floatingPointType]
1586 return $Fulltype$.compare(x, y);
1587 #end[floatingPointType]
1588 }
1589
1590 /**
1591 * Finds and returns the relative index of the first mismatch between this
1592 * buffer and a given buffer. The index is relative to the
1593 * {@link #position() position} of each buffer and will be in the range of
1594 * 0 (inclusive) up to the smaller of the {@link #remaining() remaining}
1595 * elements in each buffer (exclusive).
1596 *
1597 * <p> If the two buffers share a common prefix then the returned index is
1598 * the length of the common prefix and it follows that there is a mismatch
1599 * between the two buffers at that index within the respective buffers.
1600 * If one buffer is a proper prefix of the other then the returned index is
1601 * the smaller of the remaining elements in each buffer, and it follows that
1602 * the index is only valid for the buffer with the larger number of
1603 * remaining elements.
1604 * Otherwise, there is no mismatch.
1605 *
1606 * @param that
1607 * The byte buffer to be tested for a mismatch with this buffer
1608 *
1609 * @return The relative index of the first mismatch between this and the
1610 * given buffer, otherwise -1 if no mismatch.
1611 *
1612 * @since 11
1613 */
1614 public int mismatch($Type$Buffer that) {
1615 int length = Math.min(this.remaining(), that.remaining());
1616 int r = BufferMismatch.mismatch(this, this.position(),
1617 that, that.position(),
1618 length);
1619 return (r == -1 && this.remaining() != that.remaining()) ? length : r;
1620 }
1621
1622 // -- Other char stuff --
1623
1624 #if[char]
1625
1626 /**
1627 * Returns a string containing the characters in this buffer.
1628 *
1629 * <p> The first character of the resulting string will be the character at
1630 * this buffer's position, while the last character will be the character
1631 * at index {@code limit()} - 1. Invoking this method does not
1632 * change the buffer's position. </p>
1633 *
1634 * @return The specified string
1635 */
1636 public String toString() {
1637 return toString(position(), limit());
1638 }
1639
1640 abstract String toString(int start, int end); // package-private
1641
1642
1643 // --- Methods to support CharSequence ---
1644
1645 /**
1646 * Returns the length of this character buffer.
1647 *
1648 * <p> When viewed as a character sequence, the length of a character
1649 * buffer is simply the number of characters between the position
1650 * (inclusive) and the limit (exclusive); that is, it is equivalent to
1651 * {@code remaining()}. </p>
1652 *
1653 * @return The length of this character buffer
1654 */
1655 public final int length() {
1656 return remaining();
1657 }
1658
1659 /**
1660 * Reads the character at the given index relative to the current
1661 * position.
1662 *
1663 * @param index
1664 * The index of the character to be read, relative to the position;
1665 * must be non-negative and smaller than {@code remaining()}
1666 *
1667 * @return The character at index
1668 * <code>position() + index</code>
1669 *
1670 * @throws IndexOutOfBoundsException
1671 * If the preconditions on {@code index} do not hold
1672 */
1673 public final char charAt(int index) {
1674 return get(position() + checkIndex(index, 1));
1675 }
1676
1677 /**
1678 * Creates a new character buffer that represents the specified subsequence
1679 * of this buffer, relative to the current position.
1680 *
1681 * <p> The new buffer will share this buffer's content; that is, if the
1682 * content of this buffer is mutable then modifications to one buffer will
1683 * cause the other to be modified. The new buffer's capacity will be that
1684 * of this buffer, its position will be
1685 * {@code position()} + {@code start}, and its limit will be
1686 * {@code position()} + {@code end}. The new buffer will be
1687 * direct if, and only if, this buffer is direct, and it will be read-only
1688 * if, and only if, this buffer is read-only. </p>
1689 *
1690 * @param start
1691 * The index, relative to the current position, of the first
1692 * character in the subsequence; must be non-negative and no larger
1693 * than {@code remaining()}
1694 *
1695 * @param end
1696 * The index, relative to the current position, of the character
1697 * following the last character in the subsequence; must be no
1698 * smaller than {@code start} and no larger than
1699 * {@code remaining()}
1700 *
1701 * @return The new character buffer
1702 *
1703 * @throws IndexOutOfBoundsException
1704 * If the preconditions on {@code start} and {@code end}
1705 * do not hold
1706 */
1707 public abstract CharBuffer subSequence(int start, int end);
1708
1709
1710 // --- Methods to support Appendable ---
1711
1712 /**
1713 * Appends the specified character sequence to this
1714 * buffer <i>(optional operation)</i>.
1715 *
1716 * <p> An invocation of this method of the form {@code dst.append(csq)}
1717 * behaves in exactly the same way as the invocation
1718 *
1719 * <pre>
1720 * dst.put(csq.toString()) </pre>
1721 *
1722 * <p> Depending on the specification of {@code toString} for the
1723 * character sequence {@code csq}, the entire sequence may not be
1724 * appended. For instance, invoking the {@link $Type$Buffer#toString()
1725 * toString} method of a character buffer will return a subsequence whose
1726 * content depends upon the buffer's position and limit.
1727 *
1728 * @param csq
1729 * The character sequence to append. If {@code csq} is
1730 * {@code null}, then the four characters {@code "null"} are
1731 * appended to this character buffer.
1732 *
1733 * @return This buffer
1734 *
1735 * @throws BufferOverflowException
1736 * If there is insufficient space in this buffer
1737 *
1738 * @throws ReadOnlyBufferException
1739 * If this buffer is read-only
1740 *
1741 * @since 1.5
1742 */
1743 public $Type$Buffer append(CharSequence csq) {
1744 if (csq == null)
1745 return put("null");
1746 else
1747 return put(csq.toString());
1748 }
1749
1750 /**
1751 * Appends a subsequence of the specified character sequence to this
1752 * buffer <i>(optional operation)</i>.
1753 *
1754 * <p> An invocation of this method of the form {@code dst.append(csq, start,
1755 * end)} when {@code csq} is not {@code null}, behaves in exactly the
1756 * same way as the invocation
1757 *
1758 * <pre>
1759 * dst.put(csq.subSequence(start, end).toString()) </pre>
1760 *
1761 * @param csq
1762 * The character sequence from which a subsequence will be
1763 * appended. If {@code csq} is {@code null}, then characters
1764 * will be appended as if {@code csq} contained the four
1765 * characters {@code "null"}.
1766 *
1767 * @return This buffer
1768 *
1769 * @throws BufferOverflowException
1770 * If there is insufficient space in this buffer
1771 *
1772 * @throws IndexOutOfBoundsException
1773 * If {@code start} or {@code end} are negative, {@code start}
1774 * is greater than {@code end}, or {@code end} is greater than
1775 * {@code csq.length()}
1776 *
1777 * @throws ReadOnlyBufferException
1778 * If this buffer is read-only
1779 *
1780 * @since 1.5
1781 */
1782 public $Type$Buffer append(CharSequence csq, int start, int end) {
1783 CharSequence cs = (csq == null ? "null" : csq);
1784 return put(cs.subSequence(start, end).toString());
1785 }
1786
1787 /**
1788 * Appends the specified $type$ to this
1789 * buffer <i>(optional operation)</i>.
1790 *
1791 * <p> An invocation of this method of the form {@code dst.append($x$)}
1792 * behaves in exactly the same way as the invocation
1793 *
1794 * <pre>
1795 * dst.put($x$) </pre>
1796 *
1797 * @param $x$
1798 * The 16-bit $type$ to append
1799 *
1800 * @return This buffer
1801 *
1802 * @throws BufferOverflowException
1803 * If there is insufficient space in this buffer
1804 *
1805 * @throws ReadOnlyBufferException
1806 * If this buffer is read-only
1807 *
1808 * @since 1.5
1809 */
1810 public $Type$Buffer append($type$ $x$) {
1811 return put($x$);
1812 }
1813
1814 #end[char]
1815
1816
1817 // -- Other byte stuff: Access to binary data --
1818
1819 #if[!byte]
1820
1821 /**
1822 * Retrieves this buffer's byte order.
1823 *
1824 * <p> The byte order of $a$ $type$ buffer created by allocation or by
1825 * wrapping an existing {@code $type$} array is the {@link
1826 * ByteOrder#nativeOrder native order} of the underlying
1827 * hardware. The byte order of $a$ $type$ buffer created as a <a
1828 * href="ByteBuffer.html#views">view</a> of a byte buffer is that of the
1829 * byte buffer at the moment that the view is created. </p>
1830 *
1831 * @return This buffer's byte order
1832 */
1833 public abstract ByteOrder order();
1834
1835 #end[!byte]
1836
1837 #if[char]
1838 // The order or null if the buffer does not cover a memory region,
1839 // such as StringCharBuffer
1840 abstract ByteOrder charRegionOrder();
1841 #end[char]
1842
1843 #if[byte]
1844
1845 boolean bigEndian // package-private
1846 = true;
1847 boolean nativeByteOrder // package-private
1848 = (ByteOrder.nativeOrder() == ByteOrder.BIG_ENDIAN);
1849
1850 /**
1851 * Retrieves this buffer's byte order.
1852 *
1853 * <p> The byte order is used when reading or writing multibyte values, and
1854 * when creating buffers that are views of this byte buffer. The order of
1855 * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN
1856 * BIG_ENDIAN}. </p>
1857 *
1858 * @return This buffer's byte order
1859 */
1860 public final ByteOrder order() {
1861 return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN;
1862 }
1863
1864 /**
1865 * Modifies this buffer's byte order.
1866 *
1867 * @param bo
1868 * The new byte order,
1869 * either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
1870 * or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}
1871 *
1872 * @return This buffer
1873 */
1874 public final $Type$Buffer order(ByteOrder bo) {
1875 bigEndian = (bo == ByteOrder.BIG_ENDIAN);
1876 nativeByteOrder =
1877 (bigEndian == (ByteOrder.nativeOrder() == ByteOrder.BIG_ENDIAN));
1878 return this;
1879 }
1880
1881 /**
1882 * Returns the memory address, pointing to the byte at the given index,
1883 * modulus the given unit size.
1884 *
1885 * <p> A return value greater than zero indicates the address of the byte at
1886 * the index is misaligned for the unit size, and the value's quantity
1887 * indicates how much the index should be rounded up or down to locate a
1888 * byte at an aligned address. Otherwise, a value of {@code 0} indicates
1889 * that the address of the byte at the index is aligned for the unit size.
1890 *
1891 * @apiNote
1892 * This method may be utilized to determine if unit size bytes from an
1893 * index can be accessed atomically, if supported by the native platform.
1894 *
1895 * @implNote
1896 * This implementation throws {@code UnsupportedOperationException} for
1897 * non-direct buffers when the given unit size is greater then {@code 8}.
1898 *
1899 * @param index
1900 * The index to query for alignment offset, must be non-negative, no
1901 * upper bounds check is performed
1902 *
1903 * @param unitSize
1904 * The unit size in bytes, must be a power of {@code 2}
1905 *
1906 * @return The indexed byte's memory address modulus the unit size
1907 *
1908 * @throws IllegalArgumentException
1909 * If the index is negative or the unit size is not a power of
1910 * {@code 2}
1911 *
1912 * @throws UnsupportedOperationException
1913 * If the native platform does not guarantee stable alignment offset
1914 * values for the given unit size when managing the memory regions
1915 * of buffers of the same kind as this buffer (direct or
1916 * non-direct). For example, if garbage collection would result
1917 * in the moving of a memory region covered by a non-direct buffer
1918 * from one location to another and both locations have different
1919 * alignment characteristics.
1920 *
1921 * @see #alignedSlice(int)
1922 * @since 9
1923 */
1924 public final int alignmentOffset(int index, int unitSize) {
1925 if (index < 0)
1926 throw new IllegalArgumentException("Index less than zero: " + index);
1927 if (unitSize < 1 || (unitSize & (unitSize - 1)) != 0)
1928 throw new IllegalArgumentException("Unit size not a power of two: " + unitSize);
1929 if (unitSize > 8 && !isDirect())
1930 throw new UnsupportedOperationException("Unit size unsupported for non-direct buffers: " + unitSize);
1931
1932 return (int) ((address + index) % unitSize);
1933 }
1934
1935 /**
1936 * Creates a new byte buffer whose content is a shared and aligned
1937 * subsequence of this buffer's content.
1938 *
1939 * <p> The content of the new buffer will start at this buffer's current
1940 * position rounded up to the index of the nearest aligned byte for the
1941 * given unit size, and end at this buffer's limit rounded down to the index
1942 * of the nearest aligned byte for the given unit size.
1943 * If rounding results in out-of-bound values then the new buffer's capacity
1944 * and limit will be zero. If rounding is within bounds the following
1945 * expressions will be true for a new buffer {@code nb} and unit size
1946 * {@code unitSize}:
1947 * <pre>{@code
1948 * nb.alignmentOffset(0, unitSize) == 0
1949 * nb.alignmentOffset(nb.limit(), unitSize) == 0
1950 * }</pre>
1951 *
1952 * <p> Changes to this buffer's content will be visible in the new
1953 * buffer, and vice versa; the two buffers' position, limit, and mark
1954 * values will be independent.
1955 *
1956 * <p> The new buffer's position will be zero, its capacity and its limit
1957 * will be the number of bytes remaining in this buffer or fewer subject to
1958 * alignment, its mark will be undefined, and its byte order will be
1959 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
1960 *
1961 * The new buffer will be direct if, and only if, this buffer is direct, and
1962 * it will be read-only if, and only if, this buffer is read-only. </p>
1963 *
1964 * @apiNote
1965 * This method may be utilized to create a new buffer where unit size bytes
1966 * from index, that is a multiple of the unit size, may be accessed
1967 * atomically, if supported by the native platform.
1968 *
1969 * @implNote
1970 * This implementation throws {@code UnsupportedOperationException} for
1971 * non-direct buffers when the given unit size is greater then {@code 8}.
1972 *
1973 * @param unitSize
1974 * The unit size in bytes, must be a power of {@code 2}
1975 *
1976 * @return The new byte buffer
1977 *
1978 * @throws IllegalArgumentException
1979 * If the unit size not a power of {@code 2}
1980 *
1981 * @throws UnsupportedOperationException
1982 * If the native platform does not guarantee stable aligned slices
1983 * for the given unit size when managing the memory regions
1984 * of buffers of the same kind as this buffer (direct or
1985 * non-direct). For example, if garbage collection would result
1986 * in the moving of a memory region covered by a non-direct buffer
1987 * from one location to another and both locations have different
1988 * alignment characteristics.
1989 *
1990 * @see #alignmentOffset(int, int)
1991 * @see #slice()
1992 * @since 9
1993 */
1994 public final ByteBuffer alignedSlice(int unitSize) {
1995 int pos = position();
1996 int lim = limit();
1997
1998 int pos_mod = alignmentOffset(pos, unitSize);
1999 int lim_mod = alignmentOffset(lim, unitSize);
2000
2001 // Round up the position to align with unit size
2002 int aligned_pos = (pos_mod > 0)
2003 ? pos + (unitSize - pos_mod)
2004 : pos;
2005
2006 // Round down the limit to align with unit size
2007 int aligned_lim = lim - lim_mod;
2008
2009 if (aligned_pos > lim || aligned_lim < pos) {
2010 aligned_pos = aligned_lim = pos;
2011 }
2012
2013 return slice(aligned_pos, aligned_lim);
2014 }
2015
2016 abstract ByteBuffer slice(int pos, int lim);
2017
2018 // #BIN
2019 //
2020 // Binary-data access methods for short, char, int, long, float,
2021 // and double will be inserted here
2022
2023 #end[byte]
2024
2025 #if[streamableType]
2026
2027 #if[char]
2028 @Override
2029 #end[char]
2030 public $Streamtype$Stream $type$s() {
2031 return StreamSupport.$streamtype$Stream(() -> new $Type$BufferSpliterator(this),
2032 Buffer.SPLITERATOR_CHARACTERISTICS, false);
2033 }
2034
2035 #end[streamableType]
2036
2037 }