CharBuffer


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