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