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