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 * The methods defined by {@code CharSequence} operate relative to the current
214 * position of the buffer when they are invoked.
215 * </p>
216 *
217 #end[char]
218 *
219 #if[byte]
220 * <h2> Invocation chaining </h2>
221 #end[byte]
222 *
223 * <p> Methods in this class that do not otherwise have a value to return are
224 * specified to return the buffer upon which they are invoked. This allows
225 * method invocations to be chained.
226 *
227 #if[byte]
228 *
229 * The sequence of statements
230 *
231 * <blockquote><pre>
232 * bb.putInt(0xCAFEBABE);
233 * bb.putShort(3);
234 * bb.putShort(45);</pre></blockquote>
235 *
236 * can, for example, be replaced by the single statement
237 *
238 * <blockquote><pre>
239 * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote>
240 *
241 #end[byte]
242 #if[char]
243 *
244 * The sequence of statements
245 *
246 * <blockquote><pre>
247 * cb.put("text/");
248 * cb.put(subtype);
249 * cb.put("; charset=");
250 * cb.put(enc);</pre></blockquote>
251 *
252 * can, for example, be replaced by the single statement
253 *
254 * <blockquote><pre>
255 * cb.put("text/").put(subtype).put("; charset=").put(enc);</pre></blockquote>
256 *
257 #end[char]
258 *
259 *
260 * @author Mark Reinhold
261 * @author JSR-51 Expert Group
262 * @since 1.4
263 */
264
265 public abstract class $Type$Buffer
266 extends Buffer
267 implements Comparable<$Type$Buffer>{#if[char]?, Appendable, CharSequence, Readable}
268 {
269
270 // These fields are declared here rather than in Heap-X-Buffer in order to
271 // reduce the number of virtual method invocations needed to access these
272 // values, which is especially costly when coding small buffers.
273 //
274 final $type$[] hb; // Non-null only for heap buffers
275 final int offset;
276 boolean isReadOnly;
277
278 // Creates a new buffer with the given mark, position, limit, capacity,
279 // backing array, and array offset
280 //
281 $Type$Buffer(int mark, int pos, int lim, int cap, // package-private
282 $type$[] hb, int offset)
283 {
284 super(mark, pos, lim, cap);
285 this.hb = hb;
286 this.offset = offset;
287 }
288
289 // Creates a new buffer with the given mark, position, limit, and capacity
290 //
291 $Type$Buffer(int mark, int pos, int lim, int cap) { // package-private
292 this(mark, pos, lim, cap, null, 0);
293 }
294
295 @Override
296 Object base() {
297 return hb;
298 }
299
300 #if[byte]
301
302 /**
303 * Allocates a new direct $type$ buffer.
304 *
305 * <p> The new buffer's position will be zero, its limit will be its
306 * capacity, its mark will be undefined, each of its elements will be
307 * initialized to zero, and its byte order will be
308 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}. Whether or not it has a
309 * {@link #hasArray backing array} is unspecified.
310 *
311 * @param capacity
312 * The new buffer's capacity, in $type$s
313 *
314 * @return The new $type$ buffer
315 *
316 * @throws IllegalArgumentException
317 * If the {@code capacity} is a negative integer
318 */
319 public static $Type$Buffer allocateDirect(int capacity) {
320 return new Direct$Type$Buffer(capacity);
321 }
322
323 #end[byte]
324
325 /**
326 * Allocates a new $type$ buffer.
327 *
328 * <p> The new buffer's position will be zero, its limit will be its
329 * capacity, its mark will be undefined, each of its elements will be
330 * initialized to zero, and its byte order will be
331 #if[byte]
332 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
333 #else[byte]
334 * the {@link ByteOrder#nativeOrder native order} of the underlying
335 * hardware.
336 #end[byte]
337 * It will have a {@link #array backing array}, and its
338 * {@link #arrayOffset array offset} will be zero.
339 *
340 * @param capacity
341 * The new buffer's capacity, in $type$s
342 *
343 * @return The new $type$ buffer
344 *
345 * @throws IllegalArgumentException
346 * If the {@code capacity} is a negative integer
347 */
348 public static $Type$Buffer allocate(int capacity) {
349 if (capacity < 0)
350 throw createCapacityException(capacity);
351 return new Heap$Type$Buffer(capacity, capacity);
352 }
353
354 /**
355 * Wraps $a$ $type$ array into a buffer.
356 *
357 * <p> The new buffer will be backed by the given $type$ array;
358 * that is, modifications to the buffer will cause the array to be modified
359 * and vice versa. The new buffer's capacity will be
360 * {@code array.length}, its position will be {@code offset}, its limit
361 * will be {@code offset + length}, its mark will be undefined, and its
362 * byte order will be
363 #if[byte]
364 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
365 #else[byte]
366 * the {@link ByteOrder#nativeOrder native order} of the underlying
367 * hardware.
368 #end[byte]
369 * Its {@link #array backing array} will be the given array, and
370 * its {@link #arrayOffset array offset} will be zero. </p>
371 *
372 * @param array
373 * The array that will back the new buffer
374 *
375 * @param offset
376 * The offset of the subarray to be used; must be non-negative and
377 * no larger than {@code array.length}. The new buffer's position
378 * will be set to this value.
379 *
380 * @param length
381 * The length of the subarray to be used;
382 * must be non-negative and no larger than
383 * {@code array.length - offset}.
384 * The new buffer's limit will be set to {@code offset + length}.
385 *
386 * @return The new $type$ buffer
387 *
388 * @throws IndexOutOfBoundsException
389 * If the preconditions on the {@code offset} and {@code length}
390 * parameters do not hold
391 */
392 public static $Type$Buffer wrap($type$[] array,
393 int offset, int length)
394 {
395 try {
396 return new Heap$Type$Buffer(array, offset, length);
397 } catch (IllegalArgumentException x) {
398 throw new IndexOutOfBoundsException();
399 }
400 }
401
402 /**
403 * Wraps $a$ $type$ array into a buffer.
404 *
405 * <p> The new buffer will be backed by the given $type$ array;
406 * that is, modifications to the buffer will cause the array to be modified
407 * and vice versa. The new buffer's capacity and limit will be
408 * {@code array.length}, its position will be zero, its mark will be
409 * undefined, and its byte order will be
410 #if[byte]
411 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
412 #else[byte]
413 * the {@link ByteOrder#nativeOrder native order} of the underlying
414 * hardware.
415 #end[byte]
416 * Its {@link #array backing array} will be the given array, and its
417 * {@link #arrayOffset array offset} will be zero. </p>
418 *
419 * @param array
420 * The array that will back this buffer
421 *
422 * @return The new $type$ buffer
423 */
424 public static $Type$Buffer wrap($type$[] array) {
425 return wrap(array, 0, array.length);
426 }
427
428 #if[char]
429
430 /**
431 * Attempts to read characters into the specified character buffer.
432 * The buffer is used as a repository of characters as-is: the only
433 * changes made are the results of a put operation. No flipping or
434 * rewinding of the buffer is performed.
435 *
436 * @param target the buffer to read characters into
437 * @return The number of characters added to the buffer, or
438 * -1 if this source of characters is at its end
439 * @throws IOException if an I/O error occurs
440 * @throws ReadOnlyBufferException if target is a read only buffer
441 * @since 1.5
442 */
443 public int read(CharBuffer target) throws IOException {
444 // Determine the number of bytes n that can be transferred
445 int targetRemaining = target.remaining();
446 int remaining = remaining();
447 if (remaining == 0)
448 return -1;
449 int n = Math.min(remaining, targetRemaining);
450 int limit = limit();
451 // Set source limit to prevent target overflow
452 if (targetRemaining < remaining)
453 limit(position() + n);
454 try {
455 if (n > 0)
456 target.put(this);
457 } finally {
458 limit(limit); // restore real limit
459 }
460 return n;
461 }
462
463 /**
464 * Wraps a character sequence into a buffer.
465 *
466 * <p> The content of the new, read-only buffer will be the content of the
467 * given character sequence. The buffer's capacity will be
468 * {@code csq.length()}, its position will be {@code start}, its limit
469 * will be {@code end}, and its mark will be undefined. </p>
470 *
471 * @param csq
472 * The character sequence from which the new character buffer is to
473 * be created
474 *
475 * @param start
476 * The index of the first character to be used;
477 * must be non-negative and no larger than {@code csq.length()}.
478 * The new buffer's position will be set to this value.
479 *
480 * @param end
481 * The index of the character following the last character to be
482 * used; must be no smaller than {@code start} and no larger
483 * than {@code csq.length()}.
484 * The new buffer's limit will be set to this value.
485 *
486 * @return The new character buffer
487 *
488 * @throws IndexOutOfBoundsException
489 * If the preconditions on the {@code start} and {@code end}
490 * parameters do not hold
491 */
492 public static CharBuffer wrap(CharSequence csq, int start, int end) {
493 try {
494 return new StringCharBuffer(csq, start, end);
495 } catch (IllegalArgumentException x) {
496 throw new IndexOutOfBoundsException();
497 }
498 }
499
500 /**
501 * Wraps a character sequence into a buffer.
502 *
503 * <p> The content of the new, read-only buffer will be the content of the
504 * given character sequence. The new buffer's capacity and limit will be
505 * {@code csq.length()}, its position will be zero, and its mark will be
506 * undefined. </p>
507 *
508 * @param csq
509 * The character sequence from which the new character buffer is to
510 * be created
511 *
512 * @return The new character buffer
513 */
514 public static CharBuffer wrap(CharSequence csq) {
515 return wrap(csq, 0, csq.length());
516 }
517
518 #end[char]
519
520 /**
521 * Creates a new $type$ buffer whose content is a shared subsequence of
522 * this buffer's content.
523 *
524 * <p> The content of the new buffer will start at this buffer's current
525 * position. Changes to this buffer's content will be visible in the new
526 * buffer, and vice versa; the two buffers' position, limit, and mark
527 * values will be independent.
528 *
529 * <p> The new buffer's position will be zero, its capacity and its limit
530 * will be the number of $type$s remaining in this buffer, its mark will be
531 * undefined, and its byte order will be
532 #if[byte]
533 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
534 #else[byte]
535 * identical to that of this buffer.
536 #end[byte]
537 * The new buffer will be direct if, and only if, this buffer is direct, and
538 * it will be read-only if, and only if, this buffer is read-only. </p>
539 *
540 * @return The new $type$ buffer
541 #if[byte]
542 *
543 * @see #alignedSlice(int)
544 #end[byte]
545 */
546 @Override
547 public abstract $Type$Buffer slice();
548
549 /**
550 * Creates a new $type$ buffer whose content is a shared subsequence of
551 * this buffer's content.
552 *
553 * <p> The new buffer will start at position {@code index} in this buffer
554 * and will contain {@code length} elements. Changes to this buffer's
555 * content will be visible in the new buffer, and vice versa; the two
556 * buffers' position, limit, and mark values will be independent.
557 *
558 * <p> The new buffer's position will be zero, its capacity and its limit
559 * will be {@code length}, its mark will be undefined, and its byte order
560 * will be
561 #if[byte]
562 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
563 #else[byte]
564 * identical to that of this buffer.
565 #end[byte]
566 * The new buffer will be direct if, and only if, this buffer is direct,
567 * and it will be read-only if, and only if, this buffer is read-only. </p>
568 *
569 * @param index
570 * The position in this buffer at which the content of the new
571 * buffer will start; must be non-negative and less than
572 * {@link #limit() limit()}
573 *
574 * @param length
575 * The number of elements the new buffer will contain; must be
576 * non-negative and no larger than {@code limit() - index}
577 *
578 * @return The new buffer
579 *
580 * @throws IndexOutOfBoundsException
581 * If {@code index} is negative or not less than {@code limit()},
582 * {@code length} is negative, or {@code length > limit() - index}
583 *
584 * @since 13
585 */
586 @Override
587 public abstract $Type$Buffer slice(int index, int length);
588
589 /**
590 * Creates a new $type$ buffer that shares this buffer's content.
591 *
592 * <p> The content of the new buffer will be that of this buffer. Changes
593 * to this buffer's content will be visible in the new buffer, and vice
594 * versa; the two buffers' position, limit, and mark values will be
595 * independent.
596 *
597 * <p> The new buffer's capacity, limit, position,
598 #if[byte]
599 * and mark values will be identical to those of this buffer, and its byte
600 * order will be {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
601 #else[byte]
602 * mark values, and byte order will be identical to those of this buffer.
603 #end[byte]
604 * The new buffer will be direct if, and only if, this buffer is direct, and
605 * it will be read-only if, and only if, this buffer is read-only. </p>
606 *
607 * @return The new $type$ buffer
608 */
609 @Override
610 public abstract $Type$Buffer duplicate();
611
612 /**
613 * Creates a new, read-only $type$ buffer that shares this buffer's
614 * content.
615 *
616 * <p> The content of the new buffer will be that of this buffer. Changes
617 * to this buffer's content will be visible in the new buffer; the new
618 * buffer itself, however, will be read-only and will not allow the shared
619 * content to be modified. The two buffers' position, limit, and mark
620 * values will be independent.
621 *
622 * <p> The new buffer's capacity, limit, position,
623 #if[byte]
624 * and mark values will be identical to those of this buffer, and its byte
625 * order will be {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
626 #else[byte]
627 * mark values, and byte order will be identical to those of this buffer.
628 #end[byte]
629 *
630 * <p> If this buffer is itself read-only then this method behaves in
631 * exactly the same way as the {@link #duplicate duplicate} method. </p>
632 *
633 * @return The new, read-only $type$ buffer
634 */
635 public abstract $Type$Buffer asReadOnlyBuffer();
636
637
638 // -- Singleton get/put methods --
639
640 /**
641 * Relative <i>get</i> method. Reads the $type$ at this buffer's
642 * current position, and then increments the position.
643 *
644 * @return The $type$ at the buffer's current position
645 *
646 * @throws BufferUnderflowException
647 * If the buffer's current position is not smaller than its limit
648 */
649 public abstract $type$ get();
650
651 /**
652 * Relative <i>put</i> method <i>(optional operation)</i>.
653 *
654 * <p> Writes the given $type$ into this buffer at the current
655 * position, and then increments the position. </p>
656 *
657 * @param $x$
658 * The $type$ to be written
659 *
660 * @return This buffer
661 *
662 * @throws BufferOverflowException
663 * If this buffer's current position is not smaller than its limit
664 *
665 * @throws ReadOnlyBufferException
666 * If this buffer is read-only
667 */
668 public abstract $Type$Buffer put($type$ $x$);
669
670 /**
671 * Absolute <i>get</i> method. Reads the $type$ at the given
672 * index.
673 *
674 * @param index
675 * The index from which the $type$ will be read
676 *
677 * @return The $type$ at the given index
678 *
679 * @throws IndexOutOfBoundsException
680 * If {@code index} is negative
681 * or not smaller than the buffer's limit
682 */
683 public abstract $type$ get(int index);
684
685 #if[streamableType]
686 /**
687 * Absolute <i>get</i> method. Reads the $type$ at the given
688 * index without any validation of the index.
689 *
690 * @param index
691 * The index from which the $type$ will be read
692 *
693 * @return The $type$ at the given index
694 */
695 abstract $type$ getUnchecked(int index); // package-private
696 #end[streamableType]
697
698 /**
699 * Absolute <i>put</i> method <i>(optional operation)</i>.
700 *
701 * <p> Writes the given $type$ into this buffer at the given
702 * index. </p>
703 *
704 * @param index
705 * The index at which the $type$ will be written
706 *
707 * @param $x$
708 * The $type$ value to be written
709 *
710 * @return This buffer
711 *
712 * @throws IndexOutOfBoundsException
713 * If {@code index} is negative
714 * or not smaller than the buffer's limit
715 *
716 * @throws ReadOnlyBufferException
717 * If this buffer is read-only
718 */
719 public abstract $Type$Buffer put(int index, $type$ $x$);
720
721
722 // -- Bulk get operations --
723
724 /**
725 * Relative bulk <i>get</i> method.
726 *
727 * <p> This method transfers $type$s from this buffer into the given
728 * destination array. If there are fewer $type$s remaining in the
729 * buffer than are required to satisfy the request, that is, if
730 * {@code length} {@code >} {@code remaining()}, then no
731 * $type$s are transferred and a {@link BufferUnderflowException} is
732 * thrown.
733 *
734 * <p> Otherwise, this method copies {@code length} $type$s from this
735 * buffer into the given array, starting at the current position of this
736 * buffer and at the given offset in the array. The position of this
737 * buffer is then incremented by {@code length}.
738 *
739 * <p> In other words, an invocation of this method of the form
740 * <code>src.get(dst, off, len)</code> has exactly the same effect as
741 * the loop
742 *
743 * <pre>{@code
744 * for (int i = off; i < off + len; i++)
745 * dst[i] = src.get();
746 * }</pre>
747 *
748 * except that it first checks that there are sufficient $type$s in
749 * this buffer and it is potentially much more efficient.
750 *
751 * @param dst
752 * The array into which $type$s are to be written
753 *
754 * @param offset
755 * The offset within the array of the first $type$ to be
756 * written; must be non-negative and no larger than
757 * {@code dst.length}
758 *
759 * @param length
760 * The maximum number of $type$s to be written to the given
761 * array; must be non-negative and no larger than
762 * {@code dst.length - offset}
763 *
764 * @return This buffer
765 *
766 * @throws BufferUnderflowException
767 * If there are fewer than {@code length} $type$s
768 * remaining in this buffer
769 *
770 * @throws IndexOutOfBoundsException
771 * If the preconditions on the {@code offset} and {@code length}
772 * parameters do not hold
773 */
774 public $Type$Buffer get($type$[] dst, int offset, int length) {
775 checkBounds(offset, length, dst.length);
776 if (length > remaining())
777 throw new BufferUnderflowException();
778 int end = offset + length;
779 for (int i = offset; i < end; i++)
780 dst[i] = get();
781 return this;
782 }
783
784 /**
785 * Relative bulk <i>get</i> method.
786 *
787 * <p> This method transfers $type$s from this buffer into the given
788 * destination array. An invocation of this method of the form
789 * {@code src.get(a)} behaves in exactly the same way as the invocation
790 *
791 * <pre>
792 * src.get(a, 0, a.length) </pre>
793 *
794 * @param dst
795 * The destination array
796 *
797 * @return This buffer
798 *
799 * @throws BufferUnderflowException
800 * If there are fewer than {@code length} $type$s
801 * remaining in this buffer
802 */
803 public $Type$Buffer get($type$[] dst) {
804 return get(dst, 0, dst.length);
805 }
806
807 /**
808 * Absolute bulk <i>get</i> method.
809 *
810 * <p> This method transfers {@code length} $type$s from this
811 * buffer into the given array, starting at the given index in this
812 * buffer and at the given offset in the array. The position of this
813 * buffer is unchanged.
814 *
815 * <p> An invocation of this method of the form
816 * <code>src.get(index, dst, offset, length)</code>
817 * has exactly the same effect as the following loop except that it first
818 * checks the consistency of the supplied parameters and it is potentially
819 * much more efficient:
820 *
821 * <pre>{@code
822 * for (int i = offset, j = index; i < offset + length; i++, j++)
823 * dst[i] = src.get(j);
824 * }</pre>
825 *
826 * @param index
827 * The index in this buffer from which the first $type$ will be
828 * read; must be non-negative and less than {@code limit()}
829 *
830 * @param dst
831 * The destination array
832 *
833 * @param offset
834 * The offset within the array of the first $type$ to be
835 * written; must be non-negative and less than
836 * {@code dst.length}
837 *
838 * @param length
839 * The number of $type$s to be written to the given array;
840 * must be non-negative and no larger than the smaller of
841 * {@code limit() - index} and {@code dst.length - offset}
842 *
843 * @return This buffer
844 *
845 * @throws IndexOutOfBoundsException
846 * If the preconditions on the {@code index}, {@code offset}, and
847 * {@code length} parameters do not hold
848 *
849 * @since 13
850 */
851 public $Type$Buffer get(int index, $type$[] dst, int offset, int length) {
852 Objects.checkFromIndexSize(index, length, limit());
853 Objects.checkFromIndexSize(offset, length, dst.length);
854 int end = offset + length;
855 for (int i = offset, j = index; i < end; i++, j++)
856 dst[i] = get(j);
857 return this;
858 }
859
860 /**
861 * Absolute bulk <i>get</i> method.
862 *
863 * <p> This method transfers $type$s from this buffer into the given
864 * destination array. The position of this buffer is unchanged. An
865 * invocation of this method of the form
866 * <code>src.get(index, dst)</code> behaves in exactly the same
867 * way as the invocation:
868 *
869 * <pre>
870 * src.get(index, dst, 0, dst.length) </pre>
871 *
872 * @param index
873 * The index in this buffer from which the first $type$ will be
874 * read; must be non-negative and less than {@code limit()}
875 *
876 * @param dst
877 * The destination array
878 *
879 * @return This buffer
880 *
881 * @throws IndexOutOfBoundsException
882 * If {@code index} is negative, not smaller than {@code limit()},
883 * or {@code limit() - index < dst.length}
884 *
885 * @since 13
886 */
887 public $Type$Buffer get(int index, $type$[] dst) {
888 return get(index, dst, 0, dst.length);
889 }
890
891 // -- Bulk put operations --
892
893 /**
894 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
895 *
896 * <p> This method transfers the $type$s remaining in the given source
897 * buffer into this buffer. If there are more $type$s remaining in the
898 * source buffer than in this buffer, that is, if
899 * {@code src.remaining()} {@code >} {@code remaining()},
900 * then no $type$s are transferred and a {@link
901 * BufferOverflowException} is thrown.
902 *
903 * <p> Otherwise, this method copies
904 * <i>n</i> = {@code src.remaining()} $type$s from the given
905 * buffer into this buffer, starting at each buffer's current position.
906 * The positions of both buffers are then incremented by <i>n</i>.
907 *
908 * <p> In other words, an invocation of this method of the form
909 * {@code dst.put(src)} has exactly the same effect as the loop
910 *
911 * <pre>
912 * while (src.hasRemaining())
913 * dst.put(src.get()); </pre>
914 *
915 * except that it first checks that there is sufficient space in this
916 * buffer and it is potentially much more efficient.
917 *
918 * @param src
919 * The source buffer from which $type$s are to be read;
920 * must not be this buffer
921 *
922 * @return This buffer
923 *
924 * @throws BufferOverflowException
925 * If there is insufficient space in this buffer
926 * for the remaining $type$s in the source buffer
927 *
928 * @throws IllegalArgumentException
929 * If the source buffer is this buffer
930 *
931 * @throws ReadOnlyBufferException
932 * If this buffer is read-only
933 */
934 public $Type$Buffer put($Type$Buffer src) {
935 if (src == this)
936 throw createSameBufferException();
937 if (isReadOnly())
938 throw new ReadOnlyBufferException();
939 int n = src.remaining();
940 if (n > remaining())
941 throw new BufferOverflowException();
942 for (int i = 0; i < n; i++)
943 put(src.get());
944 return this;
945 }
946
947 /**
948 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
949 *
950 * <p> This method transfers $type$s into this buffer from the given
951 * source array. If there are more $type$s to be copied from the array
952 * than remain in this buffer, that is, if
953 * {@code length} {@code >} {@code remaining()}, then no
954 * $type$s are transferred and a {@link BufferOverflowException} is
955 * thrown.
956 *
957 * <p> Otherwise, this method copies {@code length} $type$s from the
958 * given array into this buffer, starting at the given offset in the array
959 * and at the current position of this buffer. The position of this buffer
960 * is then incremented by {@code length}.
961 *
962 * <p> In other words, an invocation of this method of the form
963 * <code>dst.put(src, off, len)</code> has exactly the same effect as
964 * the loop
965 *
966 * <pre>{@code
967 * for (int i = off; i < off + len; i++)
968 * dst.put(src[i]);
969 * }</pre>
970 *
971 * except that it first checks that there is sufficient space in this
972 * buffer and it is potentially much more efficient.
973 *
974 * @param src
975 * The array from which $type$s are to be read
976 *
977 * @param offset
978 * The offset within the array of the first $type$ to be read;
979 * must be non-negative and no larger than {@code src.length}
980 *
981 * @param length
982 * The number of $type$s to be read from the given array;
983 * must be non-negative and no larger than
984 * {@code src.length - offset}
985 *
986 * @return This buffer
987 *
988 * @throws BufferOverflowException
989 * If there is insufficient space in this buffer
990 *
991 * @throws IndexOutOfBoundsException
992 * If the preconditions on the {@code offset} and {@code length}
993 * parameters do not hold
994 *
995 * @throws ReadOnlyBufferException
996 * If this buffer is read-only
997 */
998 public $Type$Buffer put($type$[] src, int offset, int length) {
999 checkBounds(offset, length, src.length);
1000 if (length > remaining())
1001 throw new BufferOverflowException();
1002 int end = offset + length;
1003 for (int i = offset; i < end; i++)
1004 this.put(src[i]);
1005 return this;
1006 }
1007
1008 /**
1009 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
1010 *
1011 * <p> This method transfers the entire content of the given source
1012 * $type$ array into this buffer. An invocation of this method of the
1013 * form {@code dst.put(a)} behaves in exactly the same way as the
1014 * invocation
1015 *
1016 * <pre>
1017 * dst.put(a, 0, a.length) </pre>
1018 *
1019 * @param src
1020 * The source array
1021 *
1022 * @return This buffer
1023 *
1024 * @throws BufferOverflowException
1025 * If there is insufficient space in this buffer
1026 *
1027 * @throws ReadOnlyBufferException
1028 * If this buffer is read-only
1029 */
1030 public final $Type$Buffer put($type$[] src) {
1031 return put(src, 0, src.length);
1032 }
1033
1034 /**
1035 * Absolute bulk <i>put</i> method <i>(optional operation)</i>.
1036 *
1037 * <p> This method transfers {@code length} $type$s from the given
1038 * array, starting at the given offset in the array and at the given index
1039 * in this buffer. The position of this buffer is unchanged.
1040 *
1041 * <p> An invocation of this method of the form
1042 * <code>dst.put(index, src, offset, length)</code>
1043 * has exactly the same effect as the following loop except that it first
1044 * checks the consistency of the supplied parameters and it is potentially
1045 * much more efficient:
1046 *
1047 * <pre>{@code
1048 * for (int i = offset, j = index; i < offset + length; i++, j++)
1049 * dst.put(j, src[i]);
1050 * }</pre>
1051 *
1052 * @param index
1053 * The index in this buffer at which the first $type$ will be
1054 * written; must be non-negative and less than {@code limit()}
1055 *
1056 * @param src
1057 * The array from which $type$s are to be read
1058 *
1059 * @param offset
1060 * The offset within the array of the first $type$ to be read;
1061 * must be non-negative and less than {@code src.length}
1062 *
1063 * @param length
1064 * The number of $type$s to be read from the given array;
1065 * must be non-negative and no larger than the smaller of
1066 * {@code limit() - index} and {@code src.length - offset}
1067 *
1068 * @return This buffer
1069 *
1070 * @throws IndexOutOfBoundsException
1071 * If the preconditions on the {@code index}, {@code offset}, and
1072 * {@code length} parameters do not hold
1073 *
1074 * @throws ReadOnlyBufferException
1075 * If this buffer is read-only
1076 *
1077 * @since 13
1078 */
1079 public $Type$Buffer put(int index, $type$[] src, int offset, int length) {
1080 if (isReadOnly())
1081 throw new ReadOnlyBufferException();
1082 Objects.checkFromIndexSize(index, length, limit());
1083 Objects.checkFromIndexSize(offset, length, src.length);
1084 int end = offset + length;
1085 for (int i = offset, j = index; i < end; i++, j++)
1086 this.put(j, src[i]);
1087 return this;
1088 }
1089
1090 /**
1091 * Absolute bulk <i>put</i> method <i>(optional operation)</i>.
1092 *
1093 * <p> This method copies $type$s into this buffer from the given source
1094 * array. The position of this buffer is unchanged. An invocation of this
1095 * method of the form <code>dst.put(index, src)</code>
1096 * behaves in exactly the same way as the invocation:
1097 *
1098 * <pre>
1099 * dst.put(index, src, 0, src.length); </pre>
1100 *
1101 * @param index
1102 * The index in this buffer at which the first $type$ will be
1103 * written; must be non-negative and less than {@code limit()}
1104 *
1105 * @param src
1106 * The array from which $type$s are to be read
1107 *
1108 * @return This buffer
1109 *
1110 * @throws IndexOutOfBoundsException
1111 * If {@code index} is negative, not smaller than {@code limit()},
1112 * or {@code limit() - index < src.length}
1113 *
1114 * @throws ReadOnlyBufferException
1115 * If this buffer is read-only
1116 *
1117 * @since 13
1118 */
1119 public $Type$Buffer put(int index, $type$[] src) {
1120 return put(index, src, 0, src.length);
1121 }
1122
1123 #if[char]
1124
1125 /**
1126 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
1127 *
1128 * <p> This method transfers $type$s from the given string into this
1129 * buffer. If there are more $type$s to be copied from the string than
1130 * remain in this buffer, that is, if
1131 * <code>end - start</code> {@code >} {@code remaining()},
1132 * then no $type$s are transferred and a {@link
1133 * BufferOverflowException} is thrown.
1134 *
1135 * <p> Otherwise, this method copies
1136 * <i>n</i> = {@code end} - {@code start} $type$s
1137 * from the given string into this buffer, starting at the given
1138 * {@code start} index and at the current position of this buffer. The
1139 * position of this buffer is then incremented by <i>n</i>.
1140 *
1141 * <p> In other words, an invocation of this method of the form
1142 * <code>dst.put(src, start, end)</code> has exactly the same effect
1143 * as the loop
1144 *
1145 * <pre>{@code
1146 * for (int i = start; i < end; i++)
1147 * dst.put(src.charAt(i));
1148 * }</pre>
1149 *
1150 * except that it first checks that there is sufficient space in this
1151 * buffer and it is potentially much more efficient.
1152 *
1153 * @param src
1154 * The string from which $type$s are to be read
1155 *
1156 * @param start
1157 * The offset within the string of the first $type$ to be read;
1158 * must be non-negative and no larger than
1159 * {@code string.length()}
1160 *
1161 * @param end
1162 * The offset within the string of the last $type$ to be read,
1163 * plus one; must be non-negative and no larger than
1164 * {@code string.length()}
1165 *
1166 * @return This buffer
1167 *
1168 * @throws BufferOverflowException
1169 * If there is insufficient space in this buffer
1170 *
1171 * @throws IndexOutOfBoundsException
1172 * If the preconditions on the {@code start} and {@code end}
1173 * parameters do not hold
1174 *
1175 * @throws ReadOnlyBufferException
1176 * If this buffer is read-only
1177 */
1178 public $Type$Buffer put(String src, int start, int end) {
1179 checkBounds(start, end - start, src.length());
1180 if (isReadOnly())
1181 throw new ReadOnlyBufferException();
1182 if (end - start > remaining())
1183 throw new BufferOverflowException();
1184 for (int i = start; i < end; i++)
1185 this.put(src.charAt(i));
1186 return this;
1187 }
1188
1189 /**
1190 * Relative bulk <i>put</i> method <i>(optional operation)</i>.
1191 *
1192 * <p> This method transfers the entire content of the given source string
1193 * into this buffer. An invocation of this method of the form
1194 * {@code dst.put(s)} behaves in exactly the same way as the invocation
1195 *
1196 * <pre>
1197 * dst.put(s, 0, s.length()) </pre>
1198 *
1199 * @param src
1200 * The source string
1201 *
1202 * @return This buffer
1203 *
1204 * @throws BufferOverflowException
1205 * If there is insufficient space in this buffer
1206 *
1207 * @throws ReadOnlyBufferException
1208 * If this buffer is read-only
1209 */
1210 public final $Type$Buffer put(String src) {
1211 return put(src, 0, src.length());
1212 }
1213
1214 #end[char]
1215
1216
1217 // -- Other stuff --
1218
1219 /**
1220 * Tells whether or not this buffer is backed by an accessible $type$
1221 * array.
1222 *
1223 * <p> If this method returns {@code true} then the {@link #array() array}
1224 * and {@link #arrayOffset() arrayOffset} methods may safely be invoked.
1225 * </p>
1226 *
1227 * @return {@code true} if, and only if, this buffer
1228 * is backed by an array and is not read-only
1229 */
1230 public final boolean hasArray() {
1231 return (hb != null) && !isReadOnly;
1232 }
1233
1234 /**
1235 * Returns the $type$ array that backs this
1236 * buffer <i>(optional operation)</i>.
1237 *
1238 * <p> Modifications to this buffer's content will cause the returned
1239 * array's content to be modified, and vice versa.
1240 *
1241 * <p> Invoke the {@link #hasArray hasArray} method before invoking this
1242 * method in order to ensure that this buffer has an accessible backing
1243 * array. </p>
1244 *
1245 * @return The array that backs this buffer
1246 *
1247 * @throws ReadOnlyBufferException
1248 * If this buffer is backed by an array but is read-only
1249 *
1250 * @throws UnsupportedOperationException
1251 * If this buffer is not backed by an accessible array
1252 */
1253 public final $type$[] array() {
1254 if (hb == null)
1255 throw new UnsupportedOperationException();
1256 if (isReadOnly)
1257 throw new ReadOnlyBufferException();
1258 return hb;
1259 }
1260
1261 /**
1262 * Returns the offset within this buffer's backing array of the first
1263 * element of the buffer <i>(optional operation)</i>.
1264 *
1265 * <p> If this buffer is backed by an array then buffer position <i>p</i>
1266 * corresponds to array index <i>p</i> + {@code arrayOffset()}.
1267 *
1268 * <p> Invoke the {@link #hasArray hasArray} method before invoking this
1269 * method in order to ensure that this buffer has an accessible backing
1270 * array. </p>
1271 *
1272 * @return The offset within this buffer's array
1273 * of the first element of the buffer
1274 *
1275 * @throws ReadOnlyBufferException
1276 * If this buffer is backed by an array but is read-only
1277 *
1278 * @throws UnsupportedOperationException
1279 * If this buffer is not backed by an accessible array
1280 */
1281 public final int arrayOffset() {
1282 if (hb == null)
1283 throw new UnsupportedOperationException();
1284 if (isReadOnly)
1285 throw new ReadOnlyBufferException();
1286 return offset;
1287 }
1288
1289 // -- Covariant return type overrides
1290
1291 /**
1292 * {@inheritDoc}
1293 */
1294 @Override
1295 public
1296 #if[!byte]
1297 final
1298 #end[!byte]
1299 $Type$Buffer position(int newPosition) {
1300 super.position(newPosition);
1301 return this;
1302 }
1303
1304 /**
1305 * {@inheritDoc}
1306 */
1307 @Override
1308 public
1309 #if[!byte]
1310 final
1311 #end[!byte]
1312 $Type$Buffer limit(int newLimit) {
1313 super.limit(newLimit);
1314 return this;
1315 }
1316
1317 /**
1318 * {@inheritDoc}
1319 */
1320 @Override
1321 public
1322 #if[!byte]
1323 final
1324 #end[!byte]
1325 $Type$Buffer mark() {
1326 super.mark();
1327 return this;
1328 }
1329
1330 /**
1331 * {@inheritDoc}
1332 */
1333 @Override
1334 public
1335 #if[!byte]
1336 final
1337 #end[!byte]
1338 $Type$Buffer reset() {
1339 super.reset();
1340 return this;
1341 }
1342
1343 /**
1344 * {@inheritDoc}
1345 */
1346 @Override
1347 public
1348 #if[!byte]
1349 final
1350 #end[!byte]
1351 $Type$Buffer clear() {
1352 super.clear();
1353 return this;
1354 }
1355
1356 /**
1357 * {@inheritDoc}
1358 */
1359 @Override
1360 public
1361 #if[!byte]
1362 final
1363 #end[!byte]
1364 $Type$Buffer flip() {
1365 super.flip();
1366 return this;
1367 }
1368
1369 /**
1370 * {@inheritDoc}
1371 */
1372 @Override
1373 public
1374 #if[!byte]
1375 final
1376 #end[!byte]
1377 $Type$Buffer rewind() {
1378 super.rewind();
1379 return this;
1380 }
1381
1382 /**
1383 * Compacts this buffer <i>(optional operation)</i>.
1384 *
1385 * <p> The $type$s between the buffer's current position and its limit,
1386 * if any, are copied to the beginning of the buffer. That is, the
1387 * $type$ at index <i>p</i> = {@code position()} is copied
1388 * to index zero, the $type$ at index <i>p</i> + 1 is copied
1389 * to index one, and so forth until the $type$ at index
1390 * {@code limit()} - 1 is copied to index
1391 * <i>n</i> = {@code limit()} - {@code 1} - <i>p</i>.
1392 * The buffer's position is then set to <i>n+1</i> and its limit is set to
1393 * its capacity. The mark, if defined, is discarded.
1394 *
1395 * <p> The buffer's position is set to the number of $type$s copied,
1396 * rather than to zero, so that an invocation of this method can be
1397 * followed immediately by an invocation of another relative <i>put</i>
1398 * method. </p>
1399 *
1400 #if[byte]
1401 *
1402 * <p> Invoke this method after writing data from a buffer in case the
1403 * write was incomplete. The following loop, for example, copies bytes
1404 * from one channel to another via the buffer {@code buf}:
1405 *
1406 * <blockquote><pre>{@code
1407 * buf.clear(); // Prepare buffer for use
1408 * while (in.read(buf) >= 0 || buf.position != 0) {
1409 * buf.flip();
1410 * out.write(buf);
1411 * buf.compact(); // In case of partial write
1412 * }
1413 * }</pre></blockquote>
1414 *
1415 #end[byte]
1416 *
1417 * @return This buffer
1418 *
1419 * @throws ReadOnlyBufferException
1420 * If this buffer is read-only
1421 */
1422 public abstract $Type$Buffer compact();
1423
1424 /**
1425 * Tells whether or not this $type$ buffer is direct.
1426 *
1427 * @return {@code true} if, and only if, this buffer is direct
1428 */
1429 public abstract boolean isDirect();
1430
1431 #if[!char]
1432
1433 /**
1434 * Returns a string summarizing the state of this buffer.
1435 *
1436 * @return A summary string
1437 */
1438 public String toString() {
1439 StringBuffer sb = new StringBuffer();
1440 sb.append(getClass().getName());
1441 sb.append("[pos=");
1442 sb.append(position());
1443 sb.append(" lim=");
1444 sb.append(limit());
1445 sb.append(" cap=");
1446 sb.append(capacity());
1447 sb.append("]");
1448 return sb.toString();
1449 }
1450
1451 #end[!char]
1452
1453
1454 // ## Should really use unchecked accessors here for speed
1455
1456 /**
1457 * Returns the current hash code of this buffer.
1458 *
1459 * <p> The hash code of a $type$ buffer depends only upon its remaining
1460 * elements; that is, upon the elements from {@code position()} up to, and
1461 * including, the element at {@code limit()} - {@code 1}.
1462 *
1463 * <p> Because buffer hash codes are content-dependent, it is inadvisable
1464 * to use buffers as keys in hash maps or similar data structures unless it
1465 * is known that their contents will not change. </p>
1466 *
1467 * @return The current hash code of this buffer
1468 */
1469 public int hashCode() {
1470 int h = 1;
1471 int p = position();
1472 for (int i = limit() - 1; i >= p; i--)
1473 #if[int]
1474 h = 31 * h + get(i);
1475 #else[int]
1476 h = 31 * h + (int)get(i);
1477 #end[int]
1478 return h;
1479 }
1480
1481 /**
1482 * Tells whether or not this buffer is equal to another object.
1483 *
1484 * <p> Two $type$ buffers are equal if, and only if,
1485 *
1486 * <ol>
1487 *
1488 * <li><p> They have the same element type, </p></li>
1489 *
1490 * <li><p> They have the same number of remaining elements, and
1491 * </p></li>
1492 *
1493 * <li><p> The two sequences of remaining elements, considered
1494 * independently of their starting positions, are pointwise equal.
1495 #if[floatingPointType]
1496 * This method considers two $type$ elements {@code a} and {@code b}
1497 * to be equal if
1498 * {@code (a == b) || ($Fulltype$.isNaN(a) && $Fulltype$.isNaN(b))}.
1499 * The values {@code -0.0} and {@code +0.0} are considered to be
1500 * equal, unlike {@link $Fulltype$#equals(Object)}.
1501 #end[floatingPointType]
1502 * </p></li>
1503 *
1504 * </ol>
1505 *
1506 * <p> A $type$ buffer is not equal to any other type of object. </p>
1507 *
1508 * @param ob The object to which this buffer is to be compared
1509 *
1510 * @return {@code true} if, and only if, this buffer is equal to the
1511 * given object
1512 */
1513 public boolean equals(Object ob) {
1514 if (this == ob)
1515 return true;
1516 if (!(ob instanceof $Type$Buffer))
1517 return false;
1518 $Type$Buffer that = ($Type$Buffer)ob;
1519 if (this.remaining() != that.remaining())
1520 return false;
1521 return BufferMismatch.mismatch(this, this.position(),
1522 that, that.position(),
1523 this.remaining()) < 0;
1524 }
1525
1526 /**
1527 * Compares this buffer to another.
1528 *
1529 * <p> Two $type$ buffers are compared by comparing their sequences of
1530 * remaining elements lexicographically, without regard to the starting
1531 * position of each sequence within its corresponding buffer.
1532 #if[floatingPointType]
1533 * Pairs of {@code $type$} elements are compared as if by invoking
1534 * {@link $Fulltype$#compare($type$,$type$)}, except that
1535 * {@code -0.0} and {@code 0.0} are considered to be equal.
1536 * {@code $Fulltype$.NaN} is considered by this method to be equal
1537 * to itself and greater than all other {@code $type$} values
1538 * (including {@code $Fulltype$.POSITIVE_INFINITY}).
1539 #else[floatingPointType]
1540 * Pairs of {@code $type$} elements are compared as if by invoking
1541 * {@link $Fulltype$#compare($type$,$type$)}.
1542 #end[floatingPointType]
1543 *
1544 * <p> A $type$ buffer is not comparable to any other type of object.
1545 *
1546 * @return A negative integer, zero, or a positive integer as this buffer
1547 * is less than, equal to, or greater than the given buffer
1548 */
1549 public int compareTo($Type$Buffer that) {
1550 int i = BufferMismatch.mismatch(this, this.position(),
1551 that, that.position(),
1552 Math.min(this.remaining(), that.remaining()));
1553 if (i >= 0) {
1554 return compare(this.get(this.position() + i), that.get(that.position() + i));
1555 }
1556 return this.remaining() - that.remaining();
1557 }
1558
1559 private static int compare($type$ x, $type$ y) {
1560 #if[floatingPointType]
1561 return ((x < y) ? -1 :
1562 (x > y) ? +1 :
1563 (x == y) ? 0 :
1564 $Fulltype$.isNaN(x) ? ($Fulltype$.isNaN(y) ? 0 : +1) : -1);
1565 #else[floatingPointType]
1566 return $Fulltype$.compare(x, y);
1567 #end[floatingPointType]
1568 }
1569
1570 /**
1571 * Finds and returns the relative index of the first mismatch between this
1572 * buffer and a given buffer. The index is relative to the
1573 * {@link #position() position} of each buffer and will be in the range of
1574 * 0 (inclusive) up to the smaller of the {@link #remaining() remaining}
1575 * elements in each buffer (exclusive).
1576 *
1577 * <p> If the two buffers share a common prefix then the returned index is
1578 * the length of the common prefix and it follows that there is a mismatch
1579 * between the two buffers at that index within the respective buffers.
1580 * If one buffer is a proper prefix of the other then the returned index is
1581 * the smaller of the remaining elements in each buffer, and it follows that
1582 * the index is only valid for the buffer with the larger number of
1583 * remaining elements.
1584 * Otherwise, there is no mismatch.
1585 *
1586 * @param that
1587 * The byte buffer to be tested for a mismatch with this buffer
1588 *
1589 * @return The relative index of the first mismatch between this and the
1590 * given buffer, otherwise -1 if no mismatch.
1591 *
1592 * @since 11
1593 */
1594 public int mismatch($Type$Buffer that) {
1595 int length = Math.min(this.remaining(), that.remaining());
1596 int r = BufferMismatch.mismatch(this, this.position(),
1597 that, that.position(),
1598 length);
1599 return (r == -1 && this.remaining() != that.remaining()) ? length : r;
1600 }
1601
1602 // -- Other char stuff --
1603
1604 #if[char]
1605
1606 /**
1607 * Returns a string containing the characters in this buffer.
1608 *
1609 * <p> The first character of the resulting string will be the character at
1610 * this buffer's position, while the last character will be the character
1611 * at index {@code limit()} - 1. Invoking this method does not
1612 * change the buffer's position. </p>
1613 *
1614 * @return The specified string
1615 */
1616 public String toString() {
1617 return toString(position(), limit());
1618 }
1619
1620 abstract String toString(int start, int end); // package-private
1621
1622
1623 // --- Methods to support CharSequence ---
1624
1625 /**
1626 * Returns the length of this character buffer.
1627 *
1628 * <p> When viewed as a character sequence, the length of a character
1629 * buffer is simply the number of characters between the position
1630 * (inclusive) and the limit (exclusive); that is, it is equivalent to
1631 * {@code remaining()}. </p>
1632 *
1633 * @return The length of this character buffer
1634 */
1635 public final int length() {
1636 return remaining();
1637 }
1638
1639 /**
1640 * Reads the character at the given index relative to the current
1641 * position.
1642 *
1643 * @param index
1644 * The index of the character to be read, relative to the position;
1645 * must be non-negative and smaller than {@code remaining()}
1646 *
1647 * @return The character at index
1648 * <code>position() + index</code>
1649 *
1650 * @throws IndexOutOfBoundsException
1651 * If the preconditions on {@code index} do not hold
1652 */
1653 public final char charAt(int index) {
1654 return get(position() + checkIndex(index, 1));
1655 }
1656
1657 /**
1658 * Creates a new character buffer that represents the specified subsequence
1659 * of this buffer, relative to the current position.
1660 *
1661 * <p> The new buffer will share this buffer's content; that is, if the
1662 * content of this buffer is mutable then modifications to one buffer will
1663 * cause the other to be modified. The new buffer's capacity will be that
1664 * of this buffer, its position will be
1665 * {@code position()} + {@code start}, and its limit will be
1666 * {@code position()} + {@code end}. The new buffer will be
1667 * direct if, and only if, this buffer is direct, and it will be read-only
1668 * if, and only if, this buffer is read-only. </p>
1669 *
1670 * @param start
1671 * The index, relative to the current position, of the first
1672 * character in the subsequence; must be non-negative and no larger
1673 * than {@code remaining()}
1674 *
1675 * @param end
1676 * The index, relative to the current position, of the character
1677 * following the last character in the subsequence; must be no
1678 * smaller than {@code start} and no larger than
1679 * {@code remaining()}
1680 *
1681 * @return The new character buffer
1682 *
1683 * @throws IndexOutOfBoundsException
1684 * If the preconditions on {@code start} and {@code end}
1685 * do not hold
1686 */
1687 public abstract CharBuffer subSequence(int start, int end);
1688
1689
1690 // --- Methods to support Appendable ---
1691
1692 /**
1693 * Appends the specified character sequence to this
1694 * buffer <i>(optional operation)</i>.
1695 *
1696 * <p> An invocation of this method of the form {@code dst.append(csq)}
1697 * behaves in exactly the same way as the invocation
1698 *
1699 * <pre>
1700 * dst.put(csq.toString()) </pre>
1701 *
1702 * <p> Depending on the specification of {@code toString} for the
1703 * character sequence {@code csq}, the entire sequence may not be
1704 * appended. For instance, invoking the {@link $Type$Buffer#toString()
1705 * toString} method of a character buffer will return a subsequence whose
1706 * content depends upon the buffer's position and limit.
1707 *
1708 * @param csq
1709 * The character sequence to append. If {@code csq} is
1710 * {@code null}, then the four characters {@code "null"} are
1711 * appended to this character buffer.
1712 *
1713 * @return This buffer
1714 *
1715 * @throws BufferOverflowException
1716 * If there is insufficient space in this buffer
1717 *
1718 * @throws ReadOnlyBufferException
1719 * If this buffer is read-only
1720 *
1721 * @since 1.5
1722 */
1723 public $Type$Buffer append(CharSequence csq) {
1724 if (csq == null)
1725 return put("null");
1726 else
1727 return put(csq.toString());
1728 }
1729
1730 /**
1731 * Appends a subsequence of the specified character sequence to this
1732 * buffer <i>(optional operation)</i>.
1733 *
1734 * <p> An invocation of this method of the form {@code dst.append(csq, start,
1735 * end)} when {@code csq} is not {@code null}, behaves in exactly the
1736 * same way as the invocation
1737 *
1738 * <pre>
1739 * dst.put(csq.subSequence(start, end).toString()) </pre>
1740 *
1741 * @param csq
1742 * The character sequence from which a subsequence will be
1743 * appended. If {@code csq} is {@code null}, then characters
1744 * will be appended as if {@code csq} contained the four
1745 * characters {@code "null"}.
1746 *
1747 * @return This buffer
1748 *
1749 * @throws BufferOverflowException
1750 * If there is insufficient space in this buffer
1751 *
1752 * @throws IndexOutOfBoundsException
1753 * If {@code start} or {@code end} are negative, {@code start}
1754 * is greater than {@code end}, or {@code end} is greater than
1755 * {@code csq.length()}
1756 *
1757 * @throws ReadOnlyBufferException
1758 * If this buffer is read-only
1759 *
1760 * @since 1.5
1761 */
1762 public $Type$Buffer append(CharSequence csq, int start, int end) {
1763 CharSequence cs = (csq == null ? "null" : csq);
1764 return put(cs.subSequence(start, end).toString());
1765 }
1766
1767 /**
1768 * Appends the specified $type$ to this
1769 * buffer <i>(optional operation)</i>.
1770 *
1771 * <p> An invocation of this method of the form {@code dst.append($x$)}
1772 * behaves in exactly the same way as the invocation
1773 *
1774 * <pre>
1775 * dst.put($x$) </pre>
1776 *
1777 * @param $x$
1778 * The 16-bit $type$ to append
1779 *
1780 * @return This buffer
1781 *
1782 * @throws BufferOverflowException
1783 * If there is insufficient space in this buffer
1784 *
1785 * @throws ReadOnlyBufferException
1786 * If this buffer is read-only
1787 *
1788 * @since 1.5
1789 */
1790 public $Type$Buffer append($type$ $x$) {
1791 return put($x$);
1792 }
1793
1794 #end[char]
1795
1796
1797 // -- Other byte stuff: Access to binary data --
1798
1799 #if[!byte]
1800
1801 /**
1802 * Retrieves this buffer's byte order.
1803 *
1804 * <p> The byte order of $a$ $type$ buffer created by allocation or by
1805 * wrapping an existing {@code $type$} array is the {@link
1806 * ByteOrder#nativeOrder native order} of the underlying
1807 * hardware. The byte order of $a$ $type$ buffer created as a <a
1808 * href="ByteBuffer.html#views">view</a> of a byte buffer is that of the
1809 * byte buffer at the moment that the view is created. </p>
1810 *
1811 * @return This buffer's byte order
1812 */
1813 public abstract ByteOrder order();
1814
1815 #end[!byte]
1816
1817 #if[char]
1818 // The order or null if the buffer does not cover a memory region,
1819 // such as StringCharBuffer
1820 abstract ByteOrder charRegionOrder();
1821 #end[char]
1822
1823 #if[byte]
1824
1825 boolean bigEndian // package-private
1826 = true;
1827 boolean nativeByteOrder // package-private
1828 = (ByteOrder.nativeOrder() == ByteOrder.BIG_ENDIAN);
1829
1830 /**
1831 * Retrieves this buffer's byte order.
1832 *
1833 * <p> The byte order is used when reading or writing multibyte values, and
1834 * when creating buffers that are views of this byte buffer. The order of
1835 * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN
1836 * BIG_ENDIAN}. </p>
1837 *
1838 * @return This buffer's byte order
1839 */
1840 public final ByteOrder order() {
1841 return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN;
1842 }
1843
1844 /**
1845 * Modifies this buffer's byte order.
1846 *
1847 * @param bo
1848 * The new byte order,
1849 * either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
1850 * or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}
1851 *
1852 * @return This buffer
1853 */
1854 public final $Type$Buffer order(ByteOrder bo) {
1855 bigEndian = (bo == ByteOrder.BIG_ENDIAN);
1856 nativeByteOrder =
1857 (bigEndian == (ByteOrder.nativeOrder() == ByteOrder.BIG_ENDIAN));
1858 return this;
1859 }
1860
1861 /**
1862 * Returns the memory address, pointing to the byte at the given index,
1863 * modulus the given unit size.
1864 *
1865 * <p> A return value greater than zero indicates the address of the byte at
1866 * the index is misaligned for the unit size, and the value's quantity
1867 * indicates how much the index should be rounded up or down to locate a
1868 * byte at an aligned address. Otherwise, a value of {@code 0} indicates
1869 * that the address of the byte at the index is aligned for the unit size.
1870 *
1871 * @apiNote
1872 * This method may be utilized to determine if unit size bytes from an
1873 * index can be accessed atomically, if supported by the native platform.
1874 *
1875 * @implNote
1876 * This implementation throws {@code UnsupportedOperationException} for
1877 * non-direct buffers when the given unit size is greater then {@code 8}.
1878 *
1879 * @param index
1880 * The index to query for alignment offset, must be non-negative, no
1881 * upper bounds check is performed
1882 *
1883 * @param unitSize
1884 * The unit size in bytes, must be a power of {@code 2}
1885 *
1886 * @return The indexed byte's memory address modulus the unit size
1887 *
1888 * @throws IllegalArgumentException
1889 * If the index is negative or the unit size is not a power of
1890 * {@code 2}
1891 *
1892 * @throws UnsupportedOperationException
1893 * If the native platform does not guarantee stable alignment offset
1894 * values for the given unit size when managing the memory regions
1895 * of buffers of the same kind as this buffer (direct or
1896 * non-direct). For example, if garbage collection would result
1897 * in the moving of a memory region covered by a non-direct buffer
1898 * from one location to another and both locations have different
1899 * alignment characteristics.
1900 *
1901 * @see #alignedSlice(int)
1902 * @since 9
1903 */
1904 public final int alignmentOffset(int index, int unitSize) {
1905 if (index < 0)
1906 throw new IllegalArgumentException("Index less than zero: " + index);
1907 if (unitSize < 1 || (unitSize & (unitSize - 1)) != 0)
1908 throw new IllegalArgumentException("Unit size not a power of two: " + unitSize);
1909 if (unitSize > 8 && !isDirect())
1910 throw new UnsupportedOperationException("Unit size unsupported for non-direct buffers: " + unitSize);
1911
1912 return (int) ((address + index) % unitSize);
1913 }
1914
1915 /**
1916 * Creates a new byte buffer whose content is a shared and aligned
1917 * subsequence of this buffer's content.
1918 *
1919 * <p> The content of the new buffer will start at this buffer's current
1920 * position rounded up to the index of the nearest aligned byte for the
1921 * given unit size, and end at this buffer's limit rounded down to the index
1922 * of the nearest aligned byte for the given unit size.
1923 * If rounding results in out-of-bound values then the new buffer's capacity
1924 * and limit will be zero. If rounding is within bounds the following
1925 * expressions will be true for a new buffer {@code nb} and unit size
1926 * {@code unitSize}:
1927 * <pre>{@code
1928 * nb.alignmentOffset(0, unitSize) == 0
1929 * nb.alignmentOffset(nb.limit(), unitSize) == 0
1930 * }</pre>
1931 *
1932 * <p> Changes to this buffer's content will be visible in the new
1933 * buffer, and vice versa; the two buffers' position, limit, and mark
1934 * values will be independent.
1935 *
1936 * <p> The new buffer's position will be zero, its capacity and its limit
1937 * will be the number of bytes remaining in this buffer or fewer subject to
1938 * alignment, its mark will be undefined, and its byte order will be
1939 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
1940 *
1941 * The new buffer will be direct if, and only if, this buffer is direct, and
1942 * it will be read-only if, and only if, this buffer is read-only. </p>
1943 *
1944 * @apiNote
1945 * This method may be utilized to create a new buffer where unit size bytes
1946 * from index, that is a multiple of the unit size, may be accessed
1947 * atomically, if supported by the native platform.
1948 *
1949 * @implNote
1950 * This implementation throws {@code UnsupportedOperationException} for
1951 * non-direct buffers when the given unit size is greater then {@code 8}.
1952 *
1953 * @param unitSize
1954 * The unit size in bytes, must be a power of {@code 2}
1955 *
1956 * @return The new byte buffer
1957 *
1958 * @throws IllegalArgumentException
1959 * If the unit size not a power of {@code 2}
1960 *
1961 * @throws UnsupportedOperationException
1962 * If the native platform does not guarantee stable aligned slices
1963 * for the given unit size when managing the memory regions
1964 * of buffers of the same kind as this buffer (direct or
1965 * non-direct). For example, if garbage collection would result
1966 * in the moving of a memory region covered by a non-direct buffer
1967 * from one location to another and both locations have different
1968 * alignment characteristics.
1969 *
1970 * @see #alignmentOffset(int, int)
1971 * @see #slice()
1972 * @since 9
1973 */
1974 public final ByteBuffer alignedSlice(int unitSize) {
1975 int pos = position();
1976 int lim = limit();
1977
1978 int pos_mod = alignmentOffset(pos, unitSize);
1979 int lim_mod = alignmentOffset(lim, unitSize);
1980
1981 // Round up the position to align with unit size
1982 int aligned_pos = (pos_mod > 0)
1983 ? pos + (unitSize - pos_mod)
1984 : pos;
1985
1986 // Round down the limit to align with unit size
1987 int aligned_lim = lim - lim_mod;
1988
1989 if (aligned_pos > lim || aligned_lim < pos) {
1990 aligned_pos = aligned_lim = pos;
1991 }
1992
1993 return slice(aligned_pos, aligned_lim - aligned_pos);
1994 }
1995
1996 // #BIN
1997 //
1998 // Binary-data access methods for short, char, int, long, float,
1999 // and double will be inserted here
2000
2001 #end[byte]
2002
2003 #if[streamableType]
2004
2005 #if[char]
2006 @Override
2007 #end[char]
2008 public $Streamtype$Stream $type$s() {
2009 return StreamSupport.$streamtype$Stream(() -> new $Type$BufferSpliterator(this),
2010 Buffer.SPLITERATOR_CHARACTERISTICS, false);
2011 }
2012
2013 #end[streamableType]
2014
2015 }