uk.ac.starlink.hapi

## Class HapiType<S,A>

- java.lang.Object
- - uk.ac.starlink.hapi.HapiType<S,A>

- Type Parameters:
    `S` - scalar output type
    `A` - array output type

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

  Data type for a HAPI parameter.
  Since:
    11 Jan 2024

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static HapiType<java.lang.Double,double[]>` | `DOUBLE` Floating point type.
    `static HapiType<java.lang.Integer,int[]>` | `INTEGER` Integer type.
    `static HapiType<java.lang.String,java.lang.String[]>` | `ISOTIME` Restricted ISO-8601 timestamp type.
    `static HapiType<java.lang.String,java.lang.String[]>` | `STRING` String type.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `adjustInfo(DefaultValueInfo info)` Performs customisation appropriate to this type on a metadata info object that will represent it.
    `abstract void` | `applyFills(A array, S fill)` Replaces array elements matching a given fill value in place with a suitable blank value representation.
    `static HapiType<?,?>` | `fromText(java.lang.String txt)` Returns a type value given the identifier string as found in the "type" member of a Parameter JSON object.
    `java.lang.Class<A>` | `getArrayClass()` Returns the output class for array values.
    `int` | `getByteCount(int paramLength)` Returns the number of bytes required for a scalar element with this type and the supplied length value.
    `java.lang.String` | `getIdentifier()` Returns the name for this type, which is also the value of the "type" member in a corresponding Parameter JSON object.
    `java.lang.Class<S>` | `getScalarClass()` Returns the output class for scalar values.
    `abstract A` | `readBinaryArray(byte[] buf, int ipos, int elSize, int nel)` Returns an array value of this type from a binary buffer.
    `abstract S` | `readBinaryScalar(byte[] buf, int ipos, int leng)` Returns a scalar value of this type from its binary representation.
    `abstract A` | `readStringArray(java.lang.String[] txts, int ipos, int nel)` Returns an array value of this type from an array of string representations.
    `abstract S` | `readStringScalar(java.lang.String txt)` Returns a scalar value of this type from its text representation.
    `java.lang.String` | `toString()`

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

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

- - ### Field Detail

    - #### STRING

          public static final HapiType<java.lang.String,java.lang.String[]> STRING

      String type.

    - #### ISOTIME

          public static final HapiType<java.lang.String,java.lang.String[]> ISOTIME

      Restricted ISO-8601 timestamp type.

    - #### DOUBLE

          public static final HapiType<java.lang.Double,double[]> DOUBLE

      Floating point type.

    - #### INTEGER

          public static final HapiType<java.lang.Integer,int[]> INTEGER

      Integer type.

  - ### Method Detail

    - #### getIdentifier

          public java.lang.String getIdentifier()

      Returns the name for this type, which is also the value of the "type" member in a corresponding Parameter JSON object.
      Returns:
        type name

    - #### getScalarClass

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

      Returns the output class for scalar values.
      Returns:
        scalar class

    - #### getArrayClass

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

      Returns the output class for array values.
      Returns:
        array class

    - #### getByteCount

          public int getByteCount(int paramLength)

      Returns the number of bytes required for a scalar element with this type and the supplied length value. The `paramLength` is as supplied by `HapiParam.getLength()`.
      Parameters:
        `paramLength` - string length, or -1 for non-string types
      Returns:
        binary byte count for a scalar element of this type

    - #### readStringScalar

          public abstract S readStringScalar(java.lang.String txt)

      Returns a scalar value of this type from its text representation.
      Parameters:
        `txt` - text field as found in CSV
      Returns:
        typed scalar value

    - #### readBinaryScalar

          public abstract S readBinaryScalar(byte[] buf,
                                             int ipos,
                                             int leng)

      Returns a scalar value of this type from its binary representation.
      Parameters:
        `buf` - bytes representing value as found in binary format stream
        `ipos` - starting position of value in buf
        `leng` - length of value in bytes
      Returns:
        typed scalar value

    - #### readStringArray

          public abstract A readStringArray(java.lang.String[] txts,
                                            int ipos,
                                            int nel)

      Returns an array value of this type from an array of string representations.
      Parameters:
        `txts` - text fields as found in CSV, elements may be null
        `ipos` - index of first element in txts to read
        `nel` - number of elements in txts to read
      Returns:
        typed array value, same length as input

    - #### readBinaryArray

          public abstract A readBinaryArray(byte[] buf,
                                            int ipos,
                                            int elSize,
                                            int nel)

      Returns an array value of this type from a binary buffer.
      Parameters:
        `buf` - bytes representing values as found in binary format stream
        `ipos` - starting position of values in buf
        `elSize` - number of bytes per value
        `nel` - number of values to decode
      Returns:
        typed array value with `nel` elements

    - #### applyFills

          public abstract void applyFills(A array,
                                          S fill)

      Replaces array elements matching a given fill value in place with a suitable blank value representation.
      Parameters:
        `array` - array whose elements can be replaced
        `fill` - non-null value for which corresponding array elements should be blanked

    - #### adjustInfo

          public abstract void adjustInfo(DefaultValueInfo info)

      Performs customisation appropriate to this type on a metadata info object that will represent it. This only changes less-essential metadata, basic things like content class will be handled elsewhere. The correct action may be a no-op.
      Parameters:
        `info` - metadata object to modify in place

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### fromText

          public static HapiType<?,?> fromText(java.lang.String txt)

      Returns a type value given the identifier string as found in the "type" member of a Parameter JSON object.
      Parameters:
        `txt` - identifier string
      Returns:
        type instance, or null if no match