Java > Open Source Codes > java > nio > ByteBuffer


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
14
15
16 /**
17  * A byte buffer.
18  *
19  * <p> This class defines six categories of operations upon
20  * byte buffers:
21  *
22  * <ul>
23  *
24  * <li><p> Absolute and relative {@link #get() </code><i>get</i><code>} and
25  * {@link #put(byte) </code><i>put</i><code>} methods that read and write
26  * single bytes; </p></li>
27  *
28  * <li><p> Relative {@link #get(byte[]) </code><i>bulk get</i><code>}
29  * methods that transfer contiguous sequences of bytes from this buffer
30  * into an array; </p></li>
31  *
32  * <li><p> Relative {@link #put(byte[]) </code><i>bulk put</i><code>}
33  * methods that transfer contiguous sequences of bytes from a
34  * byte array or some other byte
35  * buffer into this buffer; </p></li>
36  *
37
38  *
39  * <li><p> Absolute and relative {@link #getChar() </code><i>get</i><code>}
40  * and {@link #putChar(char) </code><i>put</i><code>} methods that read and
41  * write values of other primitive types, translating them to and from
42  * sequences of bytes in a particular byte order; </p></li>
43  *
44  * <li><p> Methods for creating <i><a HREF="#views">view buffers</a></i>,
45  * which allow a byte buffer to be viewed as a buffer containing values of
46  * some other primitive type; and </p></li>
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 byte buffer. </p></li>
53  *
54  * </ul>
55  *
56  * <p> Byte 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  * content, or by {@link #wrap(byte[]) </code><i>wrapping</i><code>} an
62  * existing byte array into a buffer.
63  *
64
65
66
67
68
69
70
71  *
72
73  *
74  * <a name="direct">
75  * <h4> Direct <i>vs.</i> non-direct buffers </h4>
76  *
77  * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>. Given a
78  * direct byte buffer, the Java virtual machine will make a best effort to
79  * perform native I/O operations directly upon it. That is, it will attempt to
80  * avoid copying the buffer's content to (or from) an intermediate buffer
81  * before (or after) each invocation of one of the underlying operating
82  * system's native I/O operations.
83  *
84  * <p> A direct byte buffer may be created by invoking the {@link
85  * #allocateDirect(int) allocateDirect} factory method of this class. The
86  * buffers returned by this method typically have somewhat higher allocation
87  * and deallocation costs than non-direct buffers. The contents of direct
88  * buffers may reside outside of the normal garbage-collected heap, and so
89  * their impact upon the memory footprint of an application might not be
90  * obvious. It is therefore recommended that direct buffers be allocated
91  * primarily for large, long-lived buffers that are subject to the underlying
92  * system's native I/O operations. In general it is best to allocate direct
93  * buffers only when they yield a measureable gain in program performance.
94  *
95  * <p> A direct byte buffer may also be created by {@link
96  * java.nio.channels.FileChannel#map </code>mapping<code>} a region of a file
97  * directly into memory. An implementation of the Java platform may optionally
98  * support the creation of direct byte buffers from native code via JNI. If an
99  * instance of one of these kinds of buffers refers to an inaccessible region
100  * of memory then an attempt to access that region will not change the buffer's
101  * content and will cause an unspecified exception to be thrown either at the
102  * time of the access or at some later time.
103  *
104  * <p> Whether a byte buffer is direct or non-direct may be determined by
105  * invoking its {@link #isDirect isDirect} method. This method is provided so
106  * that explicit buffer management can be done in performance-critical code.
107  *
108  *
109  * <a name="bin">
110  * <h4> Access to binary data </h4>
111  *
112  * <p> This class defines methods for reading and writing values of all other
113  * primitive types, except <tt>boolean</tt>. Primitive values are translated
114  * to (or from) sequences of bytes according to the buffer's current byte
115  * order, which may be retrieved and modified via the {@link #order order}
116  * methods. Specific byte orders are represented by instances of the {@link
117  * ByteOrder} class. The initial order of a byte buffer is always {@link
118  * ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
119  *
120  * <p> For access to heterogeneous binary data, that is, sequences of values of
121  * different types, this class defines a family of absolute and relative
122  * <i>get</i> and <i>put</i> methods for each type. For 32-bit floating-point
123  * values, for example, this class defines:
124  *
125  * <blockquote><pre>
126  * float {@link #getFloat()}
127  * float {@link #getFloat(int) getFloat(int index)}
128  * void {@link #putFloat(float) putFloat(float f)}
129  * void {@link #putFloat(int,float) putFloat(int index, float f)}</pre></blockquote>
130  *
131  * <p> Corresponding methods are defined for the types <tt>char</tt>,
132  * <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and <tt>double</tt>. The index
133  * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of
134  * bytes rather than of the type being read or written.
135  *
136  * <a name="views">
137  *
138  * <p> For access to homogeneous binary data, that is, sequences of values of
139  * the same type, this class defines methods that can create <i>views</i> of a
140  * given byte buffer. A <i>view buffer</i> is simply another buffer whose
141  * content is backed by the byte buffer. Changes to the byte buffer's content
142  * will be visible in the view buffer, and vice versa; the two buffers'
143  * position, limit, and mark values are independent. The {@link
144  * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of
145  * the {@link FloatBuffer} class that is backed by the byte buffer upon which
146  * the method is invoked. Corresponding view-creation methods are defined for
147  * the types <tt>char</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and
148  * <tt>double</tt>.
149  *
150  * <p> View buffers have three important advantages over the families of
151  * type-specific <i>get</i> and <i>put</i> methods described above:
152  *
153  * <ul>
154  *
155  * <li><p> A view buffer is indexed not in terms of bytes but rather in terms
156  * of the type-specific size of its values; </p></li>
157  *
158  * <li><p> A view buffer provides relative bulk <i>get</i> and <i>put</i>
159  * methods that can transfer contiguous sequences of values between a buffer
160  * and an array or some other buffer of the same type; and </p></li>
161  *
162  * <li><p> A view buffer is potentially much more efficient because it will
163  * be direct if, and only if, its backing byte buffer is direct. </p></li>
164  *
165  * </ul>
166  *
167  * <p> The byte order of a view buffer is fixed to be that of its byte buffer
168  * at the time that the view is created. </p>
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  * <h4> Invocation chaining </h4>
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  * The sequence of statements
204  *
205  * <blockquote><pre>
206  * bb.putInt(0xCAFEBABE);
207  * bb.putShort(3);
208  * bb.putShort(45);</pre></blockquote>
209  *
210  * can, for example, be replaced by the single statement
211  *
212  * <blockquote><pre>
213  * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote>
214  *
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
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 ByteBuffer
241     extends Buffer
242     implements Comparable <ByteBuffer >
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 byte[] 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 ByteBuffer(int mark, int pos, int lim, int cap, // package-private
257 byte[] 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 ByteBuffer(int mark, int pos, int lim, int cap) { // package-private
267 this(mark, pos, lim, cap, null, 0);
268     }
269
270
271
272     /**
273      * Allocates a new direct byte buffer.
274      *
275      * <p> The new buffer's position will be zero, its limit will be its
276      * capacity, and its mark will be undefined. Whether or not it has a
277      * {@link #hasArray </code>backing array<code>} is unspecified. </p>
278      *
279      * @param capacity
280      * The new buffer's capacity, in bytes
281      *
282      * @return The new byte buffer
283      *
284      * @throws IllegalArgumentException
285      * If the <tt>capacity</tt> is a negative integer
286      */
287     public static ByteBuffer allocateDirect(int capacity) {
288         return new DirectByteBuffer (capacity);
289     }
290
291
292
293     /**
294      * Allocates a new byte 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 bytes
303      *
304      * @return The new byte buffer
305      *
306      * @throws IllegalArgumentException
307      * If the <tt>capacity</tt> is a negative integer
308      */
309     public static ByteBuffer allocate(int capacity) {
310     if (capacity < 0)
311         throw new IllegalArgumentException ();
312     return new HeapByteBuffer (capacity, capacity);
313     }
314
315     /**
316      * Wraps a byte array into a buffer.
317      *
318      * <p> The new buffer will be backed by the given byte 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 byte 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 ByteBuffer wrap(byte[] array,
347                     int offset, int length)
348     {
349     try {
350         return new HeapByteBuffer (array, offset, length);
351     } catch (IllegalArgumentException x) {
352         throw new IndexOutOfBoundsException ();
353     }
354     }
355
356     /**
357      * Wraps a byte array into a buffer.
358      *
359      * <p> The new buffer will be backed by the given byte 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 byte buffer
371      */
372     public static ByteBuffer wrap(byte[] array) {
373     return wrap(array, 0, array.length);
374     }
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468     /**
469      * Creates a new byte 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 bytes 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 byte buffer
484      */
485     public abstract ByteBuffer slice();
486
487     /**
488      * Creates a new byte 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 byte buffer
501      */
502     public abstract ByteBuffer duplicate();
503
504     /**
505      * Creates a new, read-only byte 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 byte buffer
521      */
522     public abstract ByteBuffer asReadOnlyBuffer();
523
524 
525     // -- Singleton get/put methods --
526
527     /**
528      * Relative <i>get</i> method. Reads the byte at this buffer's
529      * current position, and then increments the position. </p>
530      *
531      * @return The byte 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 byte get();
537
538     /**
539      * Relative <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
540      *
541      * <p> Writes the given byte into this buffer at the current
542      * position, and then increments the position. </p>
543      *
544      * @param b
545      * The byte 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 ByteBuffer put(byte b);
556
557     /**
558      * Absolute <i>get</i> method. Reads the byte at the given
559      * index. </p>
560      *
561      * @param index
562      * The index from which the byte will be read
563      *
564      * @return The byte 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 byte get(int index);
571
572     /**
573      * Absolute <i>put</i> method&nbsp;&nbsp;<i>(optional operation)</i>.
574      *
575      * <p> Writes the given byte into this buffer at the given
576      * index. </p>
577      *
578      * @param index
579      * The index at which the byte will be written
580      *
581      * @param b
582      * The byte 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 ByteBuffer put(int index, byte b);
594
595 
596     // -- Bulk get operations --
597
598     /**
599      * Relative bulk <i>get</i> method.
600      *
601      * <p> This method transfers bytes from this buffer into the given
602      * destination array. If there are fewer bytes 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      * bytes are transferred and a {@link BufferUnderflowException} is
606      * thrown.
607      *
608      * <p> Otherwise, this method copies <tt>length</tt> bytes 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 bytes in
622      * this buffer and it is potentially much more efficient. </p>
623      *
624      * @param dst
625      * The array into which bytes are to be written
626      *
627      * @param offset
628      * The offset within the array of the first byte 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 bytes 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> bytes
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 ByteBuffer get(byte[] 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 bytes 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> bytes
671      * remaining in this buffer
672      */
673     public ByteBuffer get(byte[] 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 bytes remaining in the given source
684      * buffer into this buffer. If there are more bytes 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 bytes 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> bytes 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 bytes 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 bytes 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 ByteBuffer put(ByteBuffer 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 bytes into this buffer from the given
736      * source array. If there are more bytes 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      * bytes are transferred and a {@link BufferOverflowException} is
740      * thrown.
741      *
742      * <p> Otherwise, this method copies <tt>length</tt> bytes 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 bytes are to be read
760      *
761      * @param offset
762      * The offset within the array of the first byte to be read;
763      * must be non-negative and no larger than <tt>array.length</tt>
764      *
765      * @param length
766      * The number of bytes 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 ByteBuffer put(byte[] 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      * byte 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 ByteBuffer put(byte[] src) {
812     return put(src, 0, src.length);
813     }
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900 
901     // -- Other stuff --
902
903     /**
904      * Tells whether or not this buffer is backed by an accessible byte
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 byte 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 byte[] 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 bytes between the buffer's current position and its limit,
977      * if any, are copied to the beginning of the buffer. That is, the
978      * byte at index <i>p</i>&nbsp;=&nbsp;<tt>position()</tt> is copied
979      * to index zero, the byte at index <i>p</i>&nbsp;+&nbsp;1 is copied
980      * to index one, and so forth until the byte 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 bytes 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      * <p> Invoke this method after writing data from a buffer in case the
994      * write was incomplete. The following loop, for example, copies bytes
995      * from one channel to another via the buffer <tt>buf</tt>:
996      *
997      * <blockquote><pre>
998      * buf.clear(); // Prepare buffer for use
999      * for (;;) {
1000     * if (in.read(buf) < 0 && !buf.hasRemaining())
1001     * break; // No more bytes to transfer
1002     * buf.flip();
1003     * out.write(buf);
1004     * buf.compact(); // In case of partial write
1005     * }</pre></blockquote>
1006     *
1007
1008     *
1009     * @return This buffer
1010     *
1011     * @throws ReadOnlyBufferException
1012     * If this buffer is read-only
1013     */
1014    public abstract ByteBuffer compact();
1015
1016    /**
1017     * Tells whether or not this byte 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     * Returns a string summarizing the state of this buffer. </p>
1027     *
1028     * @return A summary string
1029     */
1030    public String toString() {
1031    StringBuffer sb = new StringBuffer ();
1032    sb.append(getClass().getName());
1033    sb.append("[pos=");
1034    sb.append(position());
1035    sb.append(" lim=");
1036    sb.append(limit());
1037    sb.append(" cap=");
1038    sb.append(capacity());
1039    sb.append("]");
1040    return sb.toString();
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 byte 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 byte 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 byte 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 ByteBuffer ))
1096        return false;
1097    ByteBuffer that = (ByteBuffer )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        byte v1 = this.get(i);
1103        byte 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 byte 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 byte 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(ByteBuffer 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        byte v1 = this.get(i);
1129        byte 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
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338    // -- Other byte stuff: Access to binary data --
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360    boolean bigEndian // package-private
1361 = true;
1362    boolean nativeByteOrder // package-private
1363 = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN);
1364
1365    /**
1366     * Retrieves this buffer's byte order.
1367     *
1368     * <p> The byte order is used when reading or writing multibyte values, and
1369     * when creating buffers that are views of this byte buffer. The order of
1370     * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN
1371     * BIG_ENDIAN}. </p>
1372     *
1373     * @return This buffer's byte order
1374     */
1375    public final ByteOrder order() {
1376    return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN;
1377    }
1378
1379    /**
1380     * Modifies this buffer's byte order. </p>
1381     *
1382     * @param bo
1383     * The new byte order,
1384     * either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
1385     * or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}
1386     *
1387     * @return This buffer
1388     */
1389    public final ByteBuffer order(ByteOrder bo) {
1390    bigEndian = (bo == ByteOrder.BIG_ENDIAN);
1391    nativeByteOrder =
1392        (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN));
1393    return this;
1394    }
1395
1396    // Unchecked accessors, for use by ByteBufferAs-X-Buffer classes
1397 //
1398 abstract byte _get(int i); // package-private
1399 abstract void _put(int i, byte b); // package-private
1400
1401
1402    /**
1403     * Relative <i>get</i> method for reading a char value.
1404     *
1405     * <p> Reads the next two bytes at this buffer's current position,
1406     * composing them into a char value according to the current byte order,
1407     * and then increments the position by two. </p>
1408     *
1409     * @return The char value at the buffer's current position
1410     *
1411     * @throws BufferUnderflowException
1412     * If there are fewer than two bytes
1413     * remaining in this buffer
1414     */
1415    public abstract char getChar();
1416
1417    /**
1418     * Relative <i>put</i> method for writing a char
1419     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1420     *
1421     * <p> Writes two bytes containing the given char value, in the
1422     * current byte order, into this buffer at the current position, and then
1423     * increments the position by two. </p>
1424     *
1425     * @param value
1426     * The char value to be written
1427     *
1428     * @return This buffer
1429     *
1430     * @throws BufferOverflowException
1431     * If there are fewer than two bytes
1432     * remaining in this buffer
1433     *
1434     * @throws ReadOnlyBufferException
1435     * If this buffer is read-only
1436     */
1437    public abstract ByteBuffer putChar(char value);
1438
1439    /**
1440     * Absolute <i>get</i> method for reading a char value.
1441     *
1442     * <p> Reads two bytes at the given index, composing them into a
1443     * char value according to the current byte order. </p>
1444     *
1445     * @param index
1446     * The index from which the bytes will be read
1447     *
1448     * @return The char value at the given index
1449     *
1450     * @throws IndexOutOfBoundsException
1451     * If <tt>index</tt> is negative
1452     * or not smaller than the buffer's limit,
1453     * minus one
1454     */
1455    public abstract char getChar(int index);
1456
1457    /**
1458     * Absolute <i>put</i> method for writing a char
1459     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1460     *
1461     * <p> Writes two bytes containing the given char value, in the
1462     * current byte order, into this buffer at the given index. </p>
1463     *
1464     * @param index
1465     * The index at which the bytes will be written
1466     *
1467     * @param value
1468     * The char value to be written
1469     *
1470     * @return This buffer
1471     *
1472     * @throws IndexOutOfBoundsException
1473     * If <tt>index</tt> is negative
1474     * or not smaller than the buffer's limit,
1475     * minus one
1476     *
1477     * @throws ReadOnlyBufferException
1478     * If this buffer is read-only
1479     */
1480    public abstract ByteBuffer putChar(int index, char value);
1481
1482    /**
1483     * Creates a view of this byte buffer as a char buffer.
1484     *
1485     * <p> The content of the new buffer will start at this buffer's current
1486     * position. Changes to this buffer's content will be visible in the new
1487     * buffer, and vice versa; the two buffers' position, limit, and mark
1488     * values will be independent.
1489     *
1490     * <p> The new buffer's position will be zero, its capacity and its limit
1491     * will be the number of bytes remaining in this buffer divided by
1492     * two, and its mark will be undefined. The new buffer will be direct
1493     * if, and only if, this buffer is direct, and it will be read-only if, and
1494     * only if, this buffer is read-only. </p>
1495     *
1496     * @return A new char buffer
1497     */
1498    public abstract CharBuffer asCharBuffer();
1499
1500
1501    /**
1502     * Relative <i>get</i> method for reading a short value.
1503     *
1504     * <p> Reads the next two bytes at this buffer's current position,
1505     * composing them into a short value according to the current byte order,
1506     * and then increments the position by two. </p>
1507     *
1508     * @return The short value at the buffer's current position
1509     *
1510     * @throws BufferUnderflowException
1511     * If there are fewer than two bytes
1512     * remaining in this buffer
1513     */
1514    public abstract short getShort();
1515
1516    /**
1517     * Relative <i>put</i> method for writing a short
1518     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1519     *
1520     * <p> Writes two bytes containing the given short value, in the
1521     * current byte order, into this buffer at the current position, and then
1522     * increments the position by two. </p>
1523     *
1524     * @param value
1525     * The short value to be written
1526     *
1527     * @return This buffer
1528     *
1529     * @throws BufferOverflowException
1530     * If there are fewer than two bytes
1531     * remaining in this buffer
1532     *
1533     * @throws ReadOnlyBufferException
1534     * If this buffer is read-only
1535     */
1536    public abstract ByteBuffer putShort(short value);
1537
1538    /**
1539     * Absolute <i>get</i> method for reading a short value.
1540     *
1541     * <p> Reads two bytes at the given index, composing them into a
1542     * short value according to the current byte order. </p>
1543     *
1544     * @param index
1545     * The index from which the bytes will be read
1546     *
1547     * @return The short value at the given index
1548     *
1549     * @throws IndexOutOfBoundsException
1550     * If <tt>index</tt> is negative
1551     * or not smaller than the buffer's limit,
1552     * minus one
1553     */
1554    public abstract short getShort(int index);
1555
1556    /**
1557     * Absolute <i>put</i> method for writing a short
1558     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1559     *
1560     * <p> Writes two bytes containing the given short value, in the
1561     * current byte order, into this buffer at the given index. </p>
1562     *
1563     * @param index
1564     * The index at which the bytes will be written
1565     *
1566     * @param value
1567     * The short value to be written
1568     *
1569     * @return This buffer
1570     *
1571     * @throws IndexOutOfBoundsException
1572     * If <tt>index</tt> is negative
1573     * or not smaller than the buffer's limit,
1574     * minus one
1575     *
1576     * @throws ReadOnlyBufferException
1577     * If this buffer is read-only
1578     */
1579    public abstract ByteBuffer putShort(int index, short value);
1580
1581    /**
1582     * Creates a view of this byte buffer as a short buffer.
1583     *
1584     * <p> The content of the new buffer will start at this buffer's current
1585     * position. Changes to this buffer's content will be visible in the new
1586     * buffer, and vice versa; the two buffers' position, limit, and mark
1587     * values will be independent.
1588     *
1589     * <p> The new buffer's position will be zero, its capacity and its limit
1590     * will be the number of bytes remaining in this buffer divided by
1591     * two, and its mark will be undefined. The new buffer will be direct
1592     * if, and only if, this buffer is direct, and it will be read-only if, and
1593     * only if, this buffer is read-only. </p>
1594     *
1595     * @return A new short buffer
1596     */
1597    public abstract ShortBuffer asShortBuffer();
1598
1599
1600    /**
1601     * Relative <i>get</i> method for reading an int value.
1602     *
1603     * <p> Reads the next four bytes at this buffer's current position,
1604     * composing them into an int value according to the current byte order,
1605     * and then increments the position by four. </p>
1606     *
1607     * @return The int value at the buffer's current position
1608     *
1609     * @throws BufferUnderflowException
1610     * If there are fewer than four bytes
1611     * remaining in this buffer
1612     */
1613    public abstract int getInt();
1614
1615    /**
1616     * Relative <i>put</i> method for writing an int
1617     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1618     *
1619     * <p> Writes four bytes containing the given int value, in the
1620     * current byte order, into this buffer at the current position, and then
1621     * increments the position by four. </p>
1622     *
1623     * @param value
1624     * The int value to be written
1625     *
1626     * @return This buffer
1627     *
1628     * @throws BufferOverflowException
1629     * If there are fewer than four bytes
1630     * remaining in this buffer
1631     *
1632     * @throws ReadOnlyBufferException
1633     * If this buffer is read-only
1634     */
1635    public abstract ByteBuffer putInt(int value);
1636
1637    /**
1638     * Absolute <i>get</i> method for reading an int value.
1639     *
1640     * <p> Reads four bytes at the given index, composing them into a
1641     * int value according to the current byte order. </p>
1642     *
1643     * @param index
1644     * The index from which the bytes will be read
1645     *
1646     * @return The int value at the given index
1647     *
1648     * @throws IndexOutOfBoundsException
1649     * If <tt>index</tt> is negative
1650     * or not smaller than the buffer's limit,
1651     * minus three
1652     */
1653    public abstract int getInt(int index);
1654
1655    /**
1656     * Absolute <i>put</i> method for writing an int
1657     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1658     *
1659     * <p> Writes four bytes containing the given int value, in the
1660     * current byte order, into this buffer at the given index. </p>
1661     *
1662     * @param index
1663     * The index at which the bytes will be written
1664     *
1665     * @param value
1666     * The int value to be written
1667     *
1668     * @return This buffer
1669     *
1670     * @throws IndexOutOfBoundsException
1671     * If <tt>index</tt> is negative
1672     * or not smaller than the buffer's limit,
1673     * minus three
1674     *
1675     * @throws ReadOnlyBufferException
1676     * If this buffer is read-only
1677     */
1678    public abstract ByteBuffer putInt(int index, int value);
1679
1680    /**
1681     * Creates a view of this byte buffer as an int buffer.
1682     *
1683     * <p> The content of the new buffer will start at this buffer's current
1684     * position. Changes to this buffer's content will be visible in the new
1685     * buffer, and vice versa; the two buffers' position, limit, and mark
1686     * values will be independent.
1687     *
1688     * <p> The new buffer's position will be zero, its capacity and its limit
1689     * will be the number of bytes remaining in this buffer divided by
1690     * four, and its mark will be undefined. The new buffer will be direct
1691     * if, and only if, this buffer is direct, and it will be read-only if, and
1692     * only if, this buffer is read-only. </p>
1693     *
1694     * @return A new int buffer
1695     */
1696    public abstract IntBuffer asIntBuffer();
1697
1698
1699    /**
1700     * Relative <i>get</i> method for reading a long value.
1701     *
1702     * <p> Reads the next eight bytes at this buffer's current position,
1703     * composing them into a long value according to the current byte order,
1704     * and then increments the position by eight. </p>
1705     *
1706     * @return The long value at the buffer's current position
1707     *
1708     * @throws BufferUnderflowException
1709     * If there are fewer than eight bytes
1710     * remaining in this buffer
1711     */
1712    public abstract long getLong();
1713
1714    /**
1715     * Relative <i>put</i> method for writing a long
1716     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1717     *
1718     * <p> Writes eight bytes containing the given long value, in the
1719     * current byte order, into this buffer at the current position, and then
1720     * increments the position by eight. </p>
1721     *
1722     * @param value
1723     * The long value to be written
1724     *
1725     * @return This buffer
1726     *
1727     * @throws BufferOverflowException
1728     * If there are fewer than eight bytes
1729     * remaining in this buffer
1730     *
1731     * @throws ReadOnlyBufferException
1732     * If this buffer is read-only
1733     */
1734    public abstract ByteBuffer putLong(long value);
1735
1736    /**
1737     * Absolute <i>get</i> method for reading a long value.
1738     *
1739     * <p> Reads eight bytes at the given index, composing them into a
1740     * long value according to the current byte order. </p>
1741     *
1742     * @param index
1743     * The index from which the bytes will be read
1744     *
1745     * @return The long value at the given index
1746     *
1747     * @throws IndexOutOfBoundsException
1748     * If <tt>index</tt> is negative
1749     * or not smaller than the buffer's limit,
1750     * minus seven
1751     */
1752    public abstract long getLong(int index);
1753
1754    /**
1755     * Absolute <i>put</i> method for writing a long
1756     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1757     *
1758     * <p> Writes eight bytes containing the given long value, in the
1759     * current byte order, into this buffer at the given index. </p>
1760     *
1761     * @param index
1762     * The index at which the bytes will be written
1763     *
1764     * @param value
1765     * The long value to be written
1766     *
1767     * @return This buffer
1768     *
1769     * @throws IndexOutOfBoundsException
1770     * If <tt>index</tt> is negative
1771     * or not smaller than the buffer's limit,
1772     * minus seven
1773     *
1774     * @throws ReadOnlyBufferException
1775     * If this buffer is read-only
1776     */
1777    public abstract ByteBuffer putLong(int index, long value);
1778
1779    /**
1780     * Creates a view of this byte buffer as a long buffer.
1781     *
1782     * <p> The content of the new buffer will start at this buffer's current
1783     * position. Changes to this buffer's content will be visible in the new
1784     * buffer, and vice versa; the two buffers' position, limit, and mark
1785     * values will be independent.
1786     *
1787     * <p> The new buffer's position will be zero, its capacity and its limit
1788     * will be the number of bytes remaining in this buffer divided by
1789     * eight, and its mark will be undefined. The new buffer will be direct
1790     * if, and only if, this buffer is direct, and it will be read-only if, and
1791     * only if, this buffer is read-only. </p>
1792     *
1793     * @return A new long buffer
1794     */
1795    public abstract LongBuffer asLongBuffer();
1796
1797
1798    /**
1799     * Relative <i>get</i> method for reading a float value.
1800     *
1801     * <p> Reads the next four bytes at this buffer's current position,
1802     * composing them into a float value according to the current byte order,
1803     * and then increments the position by four. </p>
1804     *
1805     * @return The float value at the buffer's current position
1806     *
1807     * @throws BufferUnderflowException
1808     * If there are fewer than four bytes
1809     * remaining in this buffer
1810     */
1811    public abstract float getFloat();
1812
1813    /**
1814     * Relative <i>put</i> method for writing a float
1815     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1816     *
1817     * <p> Writes four bytes containing the given float value, in the
1818     * current byte order, into this buffer at the current position, and then
1819     * increments the position by four. </p>
1820     *
1821     * @param value
1822     * The float value to be written
1823     *
1824     * @return This buffer
1825     *
1826     * @throws BufferOverflowException
1827     * If there are fewer than four bytes
1828     * remaining in this buffer
1829     *
1830     * @throws ReadOnlyBufferException
1831     * If this buffer is read-only
1832     */
1833    public abstract ByteBuffer putFloat(float value);
1834
1835    /**
1836     * Absolute <i>get</i> method for reading a float value.
1837     *
1838     * <p> Reads four bytes at the given index, composing them into a
1839     * float value according to the current byte order. </p>
1840     *
1841     * @param index
1842     * The index from which the bytes will be read
1843     *
1844     * @return The float value at the given index
1845     *
1846     * @throws IndexOutOfBoundsException
1847     * If <tt>index</tt> is negative
1848     * or not smaller than the buffer's limit,
1849     * minus three
1850     */
1851    public abstract float getFloat(int index);
1852
1853    /**
1854     * Absolute <i>put</i> method for writing a float
1855     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1856     *
1857     * <p> Writes four bytes containing the given float value, in the
1858     * current byte order, into this buffer at the given index. </p>
1859     *
1860     * @param index
1861     * The index at which the bytes will be written
1862     *
1863     * @param value
1864     * The float value to be written
1865     *
1866     * @return This buffer
1867     *
1868     * @throws IndexOutOfBoundsException
1869     * If <tt>index</tt> is negative
1870     * or not smaller than the buffer's limit,
1871     * minus three
1872     *
1873     * @throws ReadOnlyBufferException
1874     * If this buffer is read-only
1875     */
1876    public abstract ByteBuffer putFloat(int index, float value);
1877
1878    /**
1879     * Creates a view of this byte buffer as a float buffer.
1880     *
1881     * <p> The content of the new buffer will start at this buffer's current
1882     * position. Changes to this buffer's content will be visible in the new
1883     * buffer, and vice versa; the two buffers' position, limit, and mark
1884     * values will be independent.
1885     *
1886     * <p> The new buffer's position will be zero, its capacity and its limit
1887     * will be the number of bytes remaining in this buffer divided by
1888     * four, and its mark will be undefined. The new buffer will be direct
1889     * if, and only if, this buffer is direct, and it will be read-only if, and
1890     * only if, this buffer is read-only. </p>
1891     *
1892     * @return A new float buffer
1893     */
1894    public abstract FloatBuffer asFloatBuffer();
1895
1896
1897    /**
1898     * Relative <i>get</i> method for reading a double value.
1899     *
1900     * <p> Reads the next eight bytes at this buffer's current position,
1901     * composing them into a double value according to the current byte order,
1902     * and then increments the position by eight. </p>
1903     *
1904     * @return The double value at the buffer's current position
1905     *
1906     * @throws BufferUnderflowException
1907     * If there are fewer than eight bytes
1908     * remaining in this buffer
1909     */
1910    public abstract double getDouble();
1911
1912    /**
1913     * Relative <i>put</i> method for writing a double
1914     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1915     *
1916     * <p> Writes eight bytes containing the given double value, in the
1917     * current byte order, into this buffer at the current position, and then
1918     * increments the position by eight. </p>
1919     *
1920     * @param value
1921     * The double value to be written
1922     *
1923     * @return This buffer
1924     *
1925     * @throws BufferOverflowException
1926     * If there are fewer than eight bytes
1927     * remaining in this buffer
1928     *
1929     * @throws ReadOnlyBufferException
1930     * If this buffer is read-only
1931     */
1932    public abstract ByteBuffer putDouble(double value);
1933
1934    /**
1935     * Absolute <i>get</i> method for reading a double value.
1936     *
1937     * <p> Reads eight bytes at the given index, composing them into a
1938     * double value according to the current byte order. </p>
1939     *
1940     * @param index
1941     * The index from which the bytes will be read
1942     *
1943     * @return The double value at the given index
1944     *
1945     * @throws IndexOutOfBoundsException
1946     * If <tt>index</tt> is negative
1947     * or not smaller than the buffer's limit,
1948     * minus seven
1949     */
1950    public abstract double getDouble(int index);
1951
1952    /**
1953     * Absolute <i>put</i> method for writing a double
1954     * value&nbsp;&nbsp;<i>(optional operation)</i>.
1955     *
1956     * <p> Writes eight bytes containing the given double value, in the
1957     * current byte order, into this buffer at the given index. </p>
1958     *
1959     * @param index
1960     * The index at which the bytes will be written
1961     *
1962     * @param value
1963     * The double value to be written
1964     *
1965     * @return This buffer
1966     *
1967     * @throws IndexOutOfBoundsException
1968     * If <tt>index</tt> is negative
1969     * or not smaller than the buffer's limit,
1970     * minus seven
1971     *
1972     * @throws ReadOnlyBufferException
1973     * If this buffer is read-only
1974     */
1975    public abstract ByteBuffer putDouble(int index, double value);
1976
1977    /**
1978     * Creates a view of this byte buffer as a double buffer.
1979     *
1980     * <p> The content of the new buffer will start at this buffer's current
1981     * position. Changes to this buffer's content will be visible in the new
1982     * buffer, and vice versa; the two buffers' position, limit, and mark
1983     * values will be independent.
1984     *
1985     * <p> The new buffer's position will be zero, its capacity and its limit
1986     * will be the number of bytes remaining in this buffer divided by
1987     * eight, and its mark will be undefined. The new buffer will be direct
1988     * if, and only if, this buffer is direct, and it will be read-only if, and
1989     * only if, this buffer is read-only. </p>
1990     *
1991     * @return A new double buffer
1992     */
1993    public abstract DoubleBuffer asDoubleBuffer();
1994
1995}
1996

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags