uk.ac.starlink.util

## Class GenericNioBuffer

- java.lang.Object
- - uk.ac.starlink.util.GenericNioBuffer

-     public class GenericNioBuffer
      extends java.lang.Object

  Convenience class which wraps one of the NIO <Type>Buffer classes to provide generic functionality. Using this class merely allows one to invoke some of the methods which are defined on all the specific buffer types but not on the Buffer superclass itself without a lot of pesky typecasting.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GenericNioBuffer(java.nio.Buffer buf)` Construct a GenericNioBuffer based on an existing `Buffer`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `array()` Returns the primitive array that backs this buffer (optional operation).
    `int` | `arrayOffset()` Returns the offset within this buffer's backing array of the first element of the buffer (optional operation).
    `java.nio.Buffer` | `duplicate()` Creates a new buffer that shares this buffer's content.
    `void` | `get(java.lang.Object dst)` Generic relative bulk get method.
    `void` | `get(java.lang.Object dst, int offset, int length)` Generic relative bulk get method.
    `java.nio.Buffer` | `getBuffer()` Returns the buffer object on which this generic buffer is based.
    `java.lang.Class<?>` | `getElementClass()` Returns the class object of the primitive type that the buffer holds.
    `boolean` | `hasArray()` Tells whether or not this buffer is backed by an accessible primitive array.
    `void` | `put(java.lang.Object src)` Generic relative bulk put method.
    `void` | `put(java.lang.Object src, int offset, int length)` Generic relative bulk put method.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### GenericNioBuffer

          public GenericNioBuffer(java.nio.Buffer buf)

      Construct a GenericNioBuffer based on an existing `Buffer`.
      Parameters:
        `buf` - the NIO buffer

  - ### Method Detail

    - #### getBuffer

          public java.nio.Buffer getBuffer()

      Returns the buffer object on which this generic buffer is based.
      Returns:
        the buffer set at construction

    - #### get

          public void get(java.lang.Object dst)

      Generic relative bulk get method. Fils a given destination array with primitives transferred from this buffer.
      Parameters:
        `dst` - an array of primitives matching the type of the nio Buffer
      See Also:
        `DoubleBuffer.get(double[])`

    - #### get

          public void get(java.lang.Object dst,
                          int offset,
                          int length)

      Generic relative bulk get method. Transfers a given number of primitives from this buffer into the given destination array starting at a given offset into the array.
      Parameters:
        `dst` - an array of primitives matching the type of the nio Buffer
        `offset` - the offset within the array of the first primitive to be written
        `length` - the number of primitives to be transferred
      See Also:
        `DoubleBuffer.get(double[],int,int)`

    - #### put

          public void put(java.lang.Object src)

      Generic relative bulk put method. Transfers the entire content of the given source array into this buffer.
      Parameters:
        `src` - an array of primitives matching the type of the nio Buffer
      See Also:
        `DoubleBuffer.put(double[])`

    - #### put

          public void put(java.lang.Object src,
                          int offset,
                          int length)

      Generic relative bulk put method. Transfers a given number of primitives from the given source array starting at a given point into this buffer.
      Parameters:
        `src` - an array of primitives matching the type of the nio Buffer
        `offset` - the offset within the array of the first primitive to be read
        `length` - the number of primitives to tranfer
      See Also:
        `DoubleBuffer.put(double[],int,int)`

    - #### duplicate

          public java.nio.Buffer duplicate()

      Creates a new buffer that shares this buffer's content.

      The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.

      The new buffer's capacity, limit, position, and mark values will be identical to those of this buffer. The new buffer will be direct if, and only if, this buffer is direct, and it will be read-only if, and only if, this buffer is read-only.

      Returns:
        the new buffer. Note it is a java.nio.Buffer and not a copy of this GenericNioBuffer
      See Also:
        `DoubleBuffer.duplicate()`

    - #### hasArray

          public boolean hasArray()

      Tells whether or not this buffer is backed by an accessible primitive array. If this method returns true then the `array()` and `arrayOffset()` methods may safely be invoked.
      Returns:
        true if, and only if, this buffer is backed by an array and is not read-only
      See Also:
        `DoubleBuffer.hasArray()`

    - #### array

          public java.lang.Object array()

      Returns the primitive array that backs this buffer (optional operation). Modifications to this buffer's content will cause the returned array's content to be modified, and vice versa.

      Invoke the `hasArray()` method before invoking this method in order to ensure that this buffer has an accessible backing array.

      Returns:
        the array that backs this buffer
      Throws:
        `java.nio.ReadOnlyBufferException` - if this buffer is backed by an array but is read-only
        `java.lang.UnsupportedOperationException` - if this buffer is not backed by an accessible array

    - #### arrayOffset

          public int arrayOffset()

      Returns the offset within this buffer's backing array of the first element of the buffer (optional operation). If this buffer is backed by an array then buffer position p corresponds to array index p + arrayOffset().

      Invoke the `hasArray()` method before invoking this method in order to ensure that this buffer has an accessible backing array.

      Returns:
        the offset within this buffer's array of the first element of the buffer
      Throws:
        `java.nio.ReadOnlyBufferException` - if this buffer is backed by an array but is read-only
        `java.lang.UnsupportedOperationException` - if this buffer is not backed by an accessible array

    - #### getElementClass

          public java.lang.Class<?> getElementClass()

      Returns the class object of the primitive type that the buffer holds. Thus `double.class` is returned if the base buffer is a `DoubleBuffer` etc.
      Returns:
        the class of the primitive elements that this buffer holds