uk.ac.starlink.pds4

## Class FieldReader<S,A>

- java.lang.Object
- - uk.ac.starlink.pds4.FieldReader<S,A>

-     public abstract class FieldReader<S,A>
      extends java.lang.Object

  Adapts a FieldAdapter to return a typed value. The NASA-provided FieldAdapter class does the work of reading bytes or text to turn them into some numeric or string value, but this class augments that to provide an object that knows what type of object should be read. An instance of this class may be used to read either scalar values or (within a Field_Group_*) array values.
  Since:
    24 Nov 2021

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract A` | `createArray(int nel)` Creates a new instance of an array value corresponding to this reader's array type.
    `java.lang.Class<A>` | `getArrayClass()` Returns the type of array value into which this reader can store values.
    `gov.nasa.pds.label.object.FieldType` | `getFieldType()` Returns the field type for this reader.
    `static FieldReader<?,?>` | `getInstance(gov.nasa.pds.label.object.FieldType ftype, java.lang.String[] blankTxts)` Returns a FieldReader instance for a given FieldType.
    `java.lang.Class<S>` | `getScalarClass()` Returns the type of scalar object that this reader will read.
    `abstract void` | `readElement(byte[] buf, int offset, int length, int startBit, int endBit, A array, int iel)` Reads an value from a buffer in accordance with this field type and stores it in one element of a supplied typed array.
    `abstract S` | `readScalar(byte[] buf, int offset, int length, int startBit, int endBit)` Reads a typed scalar value from a buffer in accordance with this field type.

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

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

- - ### Method Detail

    - #### readScalar

          public abstract S readScalar(byte[] buf,
                                       int offset,
                                       int length,
                                       int startBit,
                                       int endBit)

      Reads a typed scalar value from a buffer in accordance with this field type.

      The startBit and endBit arguments reflect their appearence in the corresponding NASA classes, but I don't know what they do.

      Parameters:
        `buf` - byte buffer containing data
        `offset` - index into buf of byte at which data value begins
        `length` - number of bytes over which value is represented
        `startBit` - ??
        `endBit` - ??
      Returns:
        typed data value

    - #### readElement

          public abstract void readElement(byte[] buf,
                                           int offset,
                                           int length,
                                           int startBit,
                                           int endBit,
                                           A array,
                                           int iel)

      Reads an value from a buffer in accordance with this field type and stores it in one element of a supplied typed array. There is a limit to what null handling can be done in this case.

      The startBit and endBit arguments reflect their appearence in the corresponding NASA classes, but I don't know what they do.

      Parameters:
        `buf` - byte buffer containing data
        `offset` - index into buf of byte at which data value begins
        `length` - number of bytes over which value is represented
        `startBit` - ??
        `endBit` - ??
        `array` - array into which read value is stored
        `iel` - index into array a wich value is written

    - #### createArray

          public abstract A createArray(int nel)

      Creates a new instance of an array value corresponding to this reader's array type.
      Parameters:
        `nel` - array size
      Returns:
        new array

    - #### getScalarClass

          public java.lang.Class<S> getScalarClass()

      Returns the type of scalar object that this reader will read.
      Returns:
        scalar content class

    - #### getArrayClass

          public java.lang.Class<A> getArrayClass()

      Returns the type of array value into which this reader can store values.
      Returns:
        array content class

    - #### getFieldType

          public gov.nasa.pds.label.object.FieldType getFieldType()

      Returns the field type for this reader.
      Returns:
        field type

    - #### getInstance

          public static FieldReader<?,?> getInstance(gov.nasa.pds.label.object.FieldType ftype,
                                                     java.lang.String[] blankTxts)

      Returns a FieldReader instance for a given FieldType.
      Parameters:
        `ftype` - field type
        `blankTxts` - array of string values representing field values that are to be mapped to null when read
      Returns:
        field reader