20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 #warn This file is preprocessed before being compiled
27
28 package java.nio;
29
30 #if[char]
31 import java.io.IOException;
32 #end[char]
33 #if[streamableType]
34 import java.util.Spliterator;
35 import java.util.stream.StreamSupport;
36 import java.util.stream.$Streamtype$Stream;
37 #end[streamableType]
38
39 import java.util.Objects;
40 import jdk.internal.util.ArraysSupport;
41
42 /**
43 * $A$ $type$ buffer.
44 *
45 * <p> This class defines {#if[byte]?six:four} categories of operations upon
46 * $type$ buffers:
47 *
48 * <ul>
49 *
50 * <li><p> Absolute and relative {@link #get() <i>get</i>} and
51 * {@link #put($type$) <i>put</i>} methods that read and write
52 * single $type$s; </p></li>
53 *
54 * <li><p> Absolute and relative {@link #get($type$[]) <i>bulk get</i>}
55 * methods that transfer contiguous sequences of $type$s from this buffer
56 * into an array; {#if[!byte]?and}</p></li>
57 *
58 * <li><p> Absolute and relative {@link #put($type$[]) <i>bulk put</i>}
59 * methods that transfer contiguous sequences of $type$s from $a$
262 * @since 1.4
263 */
264
265 public abstract class $Type$Buffer
266 extends Buffer
267 implements Comparable<$Type$Buffer>{#if[char]?, Appendable, CharSequence, Readable}
268 {
269
270 // These fields are declared here rather than in Heap-X-Buffer in order to
271 // reduce the number of virtual method invocations needed to access these
272 // values, which is especially costly when coding small buffers.
273 //
274 final $type$[] hb; // Non-null only for heap buffers
275 final int offset;
276 boolean isReadOnly;
277
278 // Creates a new buffer with the given mark, position, limit, capacity,
279 // backing array, and array offset
280 //
281 $Type$Buffer(int mark, int pos, int lim, int cap, // package-private
282 $type$[] hb, int offset)
283 {
284 super(mark, pos, lim, cap);
285 this.hb = hb;
286 this.offset = offset;
287 }
288
289 // Creates a new buffer with the given mark, position, limit, and capacity
290 //
291 $Type$Buffer(int mark, int pos, int lim, int cap) { // package-private
292 this(mark, pos, lim, cap, null, 0);
293 }
294
295 @Override
296 Object base() {
297 return hb;
298 }
299
300 #if[byte]
301
302 /**
303 * Allocates a new direct $type$ buffer.
304 *
305 * <p> The new buffer's position will be zero, its limit will be its
306 * capacity, its mark will be undefined, each of its elements will be
307 * initialized to zero, and its byte order will be
308 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}. Whether or not it has a
309 * {@link #hasArray backing array} is unspecified.
310 *
311 * @param capacity
312 * The new buffer's capacity, in $type$s
331 #if[byte]
332 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
333 #else[byte]
334 * the {@link ByteOrder#nativeOrder native order} of the underlying
335 * hardware.
336 #end[byte]
337 * It will have a {@link #array backing array}, and its
338 * {@link #arrayOffset array offset} will be zero.
339 *
340 * @param capacity
341 * The new buffer's capacity, in $type$s
342 *
343 * @return The new $type$ buffer
344 *
345 * @throws IllegalArgumentException
346 * If the {@code capacity} is a negative integer
347 */
348 public static $Type$Buffer allocate(int capacity) {
349 if (capacity < 0)
350 throw createCapacityException(capacity);
351 return new Heap$Type$Buffer(capacity, capacity);
352 }
353
354 /**
355 * Wraps $a$ $type$ array into a buffer.
356 *
357 * <p> The new buffer will be backed by the given $type$ array;
358 * that is, modifications to the buffer will cause the array to be modified
359 * and vice versa. The new buffer's capacity will be
360 * {@code array.length}, its position will be {@code offset}, its limit
361 * will be {@code offset + length}, its mark will be undefined, and its
362 * byte order will be
363 #if[byte]
364 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
365 #else[byte]
366 * the {@link ByteOrder#nativeOrder native order} of the underlying
367 * hardware.
368 #end[byte]
369 * Its {@link #array backing array} will be the given array, and
370 * its {@link #arrayOffset array offset} will be zero. </p>
371 *
376 * The offset of the subarray to be used; must be non-negative and
377 * no larger than {@code array.length}. The new buffer's position
378 * will be set to this value.
379 *
380 * @param length
381 * The length of the subarray to be used;
382 * must be non-negative and no larger than
383 * {@code array.length - offset}.
384 * The new buffer's limit will be set to {@code offset + length}.
385 *
386 * @return The new $type$ buffer
387 *
388 * @throws IndexOutOfBoundsException
389 * If the preconditions on the {@code offset} and {@code length}
390 * parameters do not hold
391 */
392 public static $Type$Buffer wrap($type$[] array,
393 int offset, int length)
394 {
395 try {
396 return new Heap$Type$Buffer(array, offset, length);
397 } catch (IllegalArgumentException x) {
398 throw new IndexOutOfBoundsException();
399 }
400 }
401
402 /**
403 * Wraps $a$ $type$ array into a buffer.
404 *
405 * <p> The new buffer will be backed by the given $type$ array;
406 * that is, modifications to the buffer will cause the array to be modified
407 * and vice versa. The new buffer's capacity and limit will be
408 * {@code array.length}, its position will be zero, its mark will be
409 * undefined, and its byte order will be
410 #if[byte]
411 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
412 #else[byte]
413 * the {@link ByteOrder#nativeOrder native order} of the underlying
414 * hardware.
415 #end[byte]
416 * Its {@link #array backing array} will be the given array, and its
|
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 #warn This file is preprocessed before being compiled
27
28 package java.nio;
29
30 #if[char]
31 import java.io.IOException;
32 #end[char]
33 #if[streamableType]
34 import java.util.Spliterator;
35 import java.util.stream.StreamSupport;
36 import java.util.stream.$Streamtype$Stream;
37 #end[streamableType]
38
39 import java.util.Objects;
40 import jdk.internal.access.foreign.MemorySegmentProxy;
41 import jdk.internal.util.ArraysSupport;
42
43 /**
44 * $A$ $type$ buffer.
45 *
46 * <p> This class defines {#if[byte]?six:four} categories of operations upon
47 * $type$ buffers:
48 *
49 * <ul>
50 *
51 * <li><p> Absolute and relative {@link #get() <i>get</i>} and
52 * {@link #put($type$) <i>put</i>} methods that read and write
53 * single $type$s; </p></li>
54 *
55 * <li><p> Absolute and relative {@link #get($type$[]) <i>bulk get</i>}
56 * methods that transfer contiguous sequences of $type$s from this buffer
57 * into an array; {#if[!byte]?and}</p></li>
58 *
59 * <li><p> Absolute and relative {@link #put($type$[]) <i>bulk put</i>}
60 * methods that transfer contiguous sequences of $type$s from $a$
263 * @since 1.4
264 */
265
266 public abstract class $Type$Buffer
267 extends Buffer
268 implements Comparable<$Type$Buffer>{#if[char]?, Appendable, CharSequence, Readable}
269 {
270
271 // These fields are declared here rather than in Heap-X-Buffer in order to
272 // reduce the number of virtual method invocations needed to access these
273 // values, which is especially costly when coding small buffers.
274 //
275 final $type$[] hb; // Non-null only for heap buffers
276 final int offset;
277 boolean isReadOnly;
278
279 // Creates a new buffer with the given mark, position, limit, capacity,
280 // backing array, and array offset
281 //
282 $Type$Buffer(int mark, int pos, int lim, int cap, // package-private
283 $type$[] hb, int offset, MemorySegmentProxy segment)
284 {
285 super(mark, pos, lim, cap, segment);
286 this.hb = hb;
287 this.offset = offset;
288 }
289
290 // Creates a new buffer with the given mark, position, limit, and capacity
291 //
292 $Type$Buffer(int mark, int pos, int lim, int cap, MemorySegmentProxy segment) { // package-private
293 this(mark, pos, lim, cap, null, 0, segment);
294 }
295
296 // Creates a new buffer with given base, address and capacity
297 //
298 $Type$Buffer($type$[] hb, long addr, int cap, MemorySegmentProxy segment) { // package-private
299 super(addr, cap, segment);
300 this.hb = hb;
301 this.offset = 0;
302 }
303
304 @Override
305 Object base() {
306 return hb;
307 }
308
309 #if[byte]
310
311 /**
312 * Allocates a new direct $type$ buffer.
313 *
314 * <p> The new buffer's position will be zero, its limit will be its
315 * capacity, its mark will be undefined, each of its elements will be
316 * initialized to zero, and its byte order will be
317 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}. Whether or not it has a
318 * {@link #hasArray backing array} is unspecified.
319 *
320 * @param capacity
321 * The new buffer's capacity, in $type$s
340 #if[byte]
341 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
342 #else[byte]
343 * the {@link ByteOrder#nativeOrder native order} of the underlying
344 * hardware.
345 #end[byte]
346 * It will have a {@link #array backing array}, and its
347 * {@link #arrayOffset array offset} will be zero.
348 *
349 * @param capacity
350 * The new buffer's capacity, in $type$s
351 *
352 * @return The new $type$ buffer
353 *
354 * @throws IllegalArgumentException
355 * If the {@code capacity} is a negative integer
356 */
357 public static $Type$Buffer allocate(int capacity) {
358 if (capacity < 0)
359 throw createCapacityException(capacity);
360 return new Heap$Type$Buffer(capacity, capacity, null);
361 }
362
363 /**
364 * Wraps $a$ $type$ array into a buffer.
365 *
366 * <p> The new buffer will be backed by the given $type$ array;
367 * that is, modifications to the buffer will cause the array to be modified
368 * and vice versa. The new buffer's capacity will be
369 * {@code array.length}, its position will be {@code offset}, its limit
370 * will be {@code offset + length}, its mark will be undefined, and its
371 * byte order will be
372 #if[byte]
373 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
374 #else[byte]
375 * the {@link ByteOrder#nativeOrder native order} of the underlying
376 * hardware.
377 #end[byte]
378 * Its {@link #array backing array} will be the given array, and
379 * its {@link #arrayOffset array offset} will be zero. </p>
380 *
385 * The offset of the subarray to be used; must be non-negative and
386 * no larger than {@code array.length}. The new buffer's position
387 * will be set to this value.
388 *
389 * @param length
390 * The length of the subarray to be used;
391 * must be non-negative and no larger than
392 * {@code array.length - offset}.
393 * The new buffer's limit will be set to {@code offset + length}.
394 *
395 * @return The new $type$ buffer
396 *
397 * @throws IndexOutOfBoundsException
398 * If the preconditions on the {@code offset} and {@code length}
399 * parameters do not hold
400 */
401 public static $Type$Buffer wrap($type$[] array,
402 int offset, int length)
403 {
404 try {
405 return new Heap$Type$Buffer(array, offset, length, null);
406 } catch (IllegalArgumentException x) {
407 throw new IndexOutOfBoundsException();
408 }
409 }
410
411 /**
412 * Wraps $a$ $type$ array into a buffer.
413 *
414 * <p> The new buffer will be backed by the given $type$ array;
415 * that is, modifications to the buffer will cause the array to be modified
416 * and vice versa. The new buffer's capacity and limit will be
417 * {@code array.length}, its position will be zero, its mark will be
418 * undefined, and its byte order will be
419 #if[byte]
420 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}.
421 #else[byte]
422 * the {@link ByteOrder#nativeOrder native order} of the underlying
423 * hardware.
424 #end[byte]
425 * Its {@link #array backing array} will be the given array, and its
|