uk.ac.starlink.fits

## Class FitsHeader

- java.lang.Object
- - uk.ac.starlink.fits.FitsHeader

-     public class FitsHeader
      extends java.lang.Object

  Represents the header part of a FITS HDU that has been read. It is composed of a number of ParsedCards.

  The FITS 4.0 long-string syntax is supported.

  Since:
    4 Mar 2022

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `java.lang.String[]` | `BORING_KEYS` Keywords which are never used as table parameters.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FitsHeader(ParsedCard<?>[] cards)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Boolean` | `getBooleanValue(java.lang.String key)` Returns the boolean value for a card with a given key, if one exists.
    `ParsedCard<?>[]` | `getCards()` Returns the header cards of which this header is composed.
    `long` | `getDataBlockCount()` Returns the number of FITS blocks occupied by the Data part of the HDU described by this header.
    `long` | `getDataByteCount()` Returns the number of bytes occupied by the Data part of the HDU described by this header, rounded up to an integer number of blocks.
    `DescribedValue` | `getDescribedValue(java.lang.String key)` Returns the content of a card with a given key as a DescribedValue, if such a key exists.
    `java.lang.Double` | `getDoubleValue(java.lang.String key)` Returns the double value for a card with a given key, if one exists.
    `long` | `getHeaderBlockCount()` Returns the number of FITS blocks occupied by this header.
    `long` | `getHeaderByteCount()` Returns the number of bytes occupied by this header, rounded up to an integer number of blocks.
    `java.lang.Integer` | `getIntValue(java.lang.String key)` Returns the integer value for a card with a given key, if one exists.
    `java.lang.Long` | `getLongValue(java.lang.String key)` Returns the long value for a card with a given key, if one exists.
    `java.lang.Number` | `getNumberValue(java.lang.String key)` Returns a numeric value for a card with a given key, if one exists.
    `int` | `getRequiredIntValue(java.lang.String key)` Returns an integer value for a card with a given key, or throws an exception if none exists.
    `long` | `getRequiredLongValue(java.lang.String key)` Returns a long value for a card with a given key, or throws an exception if none exists.
    `java.lang.String` | `getRequiredStringValue(java.lang.String key)` Returns a long value for a card with a given key, or throws an exception if none exists.
    `java.lang.String` | `getStringValue(java.lang.String key)` Returns the string value for a card with a given key, if one exists.
    `DescribedValue[]` | `getUnusedParams()` Returns an array of DescribedValue objects suitable for use as items of per-table metadata derived from this FITS header.
    `java.lang.Object` | `getValue(java.lang.String key)` Returns the untyped value for a card with a given key, if one exists.
    `void` | `useKey(java.lang.String key)` Marks a given keyword as used.

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

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

- - ### Field Detail

    - #### BORING_KEYS

          public final java.lang.String[] BORING_KEYS

      Keywords which are never used as table parameters.

  - ### Constructor Detail

    - #### FitsHeader

          public FitsHeader(ParsedCard<?>[] cards)

      Constructor. All the header cards composing the header must be included so that the header knows its length in bytes.
      Parameters:
        `cards` - header cards composing the header

  - ### Method Detail

    - #### getCards

          public ParsedCard<?>[] getCards()

      Returns the header cards of which this header is composed.
      Returns:
        ordered sequence of parsed header cards

    - #### getValue

          public java.lang.Object getValue(java.lang.String key)

      Returns the untyped value for a card with a given key, if one exists.
      Parameters:
        `key` - header keyword
      Returns:
        value, or null

    - #### getDescribedValue

          public DescribedValue getDescribedValue(java.lang.String key)

      Returns the content of a card with a given key as a DescribedValue, if such a key exists. Any comment text is provided as the `ValueInfo.getDescription()`.
      Parameters:
        `key` - header keyword
      Returns:
        described value, or null

    - #### getIntValue

          public java.lang.Integer getIntValue(java.lang.String key)

      Returns the integer value for a card with a given key, if one exists.
      Parameters:
        `key` - header keyword
      Returns:
        integer value, or null

    - #### getLongValue

          public java.lang.Long getLongValue(java.lang.String key)

      Returns the long value for a card with a given key, if one exists.
      Parameters:
        `key` - header keyword
      Returns:
        long value, or null

    - #### getDoubleValue

          public java.lang.Double getDoubleValue(java.lang.String key)

      Returns the double value for a card with a given key, if one exists.
      Parameters:
        `key` - header keyword
      Returns:
        double value, or null

    - #### getNumberValue

          public java.lang.Number getNumberValue(java.lang.String key)

      Returns a numeric value for a card with a given key, if one exists. This may be a BigInteger or BigDecimal if no other Number class can represent the serialized value.
      Parameters:
        `key` - header keyword
      Returns:
        numeric value, or null

    - #### getBooleanValue

          public java.lang.Boolean getBooleanValue(java.lang.String key)

      Returns the boolean value for a card with a given key, if one exists.
      Parameters:
        `key` - header keyword
      Returns:
        boolean value, or null

    - #### getStringValue

          public java.lang.String getStringValue(java.lang.String key)

      Returns the string value for a card with a given key, if one exists.
      Parameters:
        `key` - header keyword
      Returns:
        string value, or null

    - #### getRequiredIntValue

          public int getRequiredIntValue(java.lang.String key)
                                  throws HeaderValueException

      Returns an integer value for a card with a given key, or throws an exception if none exists.
      Parameters:
        `key` - header keyword
      Returns:
        integer value
      Throws:
        `HeaderValueException` - if no suitable card exists

    - #### getRequiredLongValue

          public long getRequiredLongValue(java.lang.String key)
                                    throws HeaderValueException

      Returns a long value for a card with a given key, or throws an exception if none exists.
      Parameters:
        `key` - header keyword
      Returns:
        long value
      Throws:
        `HeaderValueException` - if no suitable card exists

    - #### getRequiredStringValue

          public java.lang.String getRequiredStringValue(java.lang.String key)
                                                  throws HeaderValueException

      Returns a long value for a card with a given key, or throws an exception if none exists.
      Parameters:
        `key` - header keyword
      Returns:
        long value
      Throws:
        `HeaderValueException` - if no suitable card exists

    - #### useKey

          public void useKey(java.lang.String key)

      Marks a given keyword as used. This is invoked by all the `get*Value` methods.
      Parameters:
        `key` - header keyword

    - #### getHeaderBlockCount

          public long getHeaderBlockCount()

      Returns the number of FITS blocks occupied by this header.
      Returns:
        number of 2880-byte blocks in header

    - #### getDataBlockCount

          public long getDataBlockCount()
                                 throws HeaderValueException

      Returns the number of FITS blocks occupied by the Data part of the HDU described by this header.
      Returns:
        number of 2880-byte blocks in data part of HDU
      Throws:
        `HeaderValueException`

    - #### getHeaderByteCount

          public long getHeaderByteCount()

      Returns the number of bytes occupied by this header, rounded up to an integer number of blocks.
      Returns:
        `getHeaderBlockCount()` * 2880

    - #### getDataByteCount

          public long getDataByteCount()
                                throws HeaderValueException

      Returns the number of bytes occupied by the Data part of the HDU described by this header, rounded up to an integer number of blocks.
      Returns:
        `getDataBlockCount()` * 2880
      Throws:
        `HeaderValueException`

    - #### getUnusedParams

          public DescribedValue[] getUnusedParams()

      Returns an array of DescribedValue objects suitable for use as items of per-table metadata derived from this FITS header. This contains entries for every card which has not already been queried within this object (for which `useKey(java.lang.String)` has not been explicitly or implicitly called. Certain standard structural FITS keywords (`BORING_KEYS`) are ignored as well.

      The idea is that keywords which have already been read to determine table structure do not need to be recorded separately since their meaning is implicitly included in the table metadata already.

      Returns:
        array of table parameters relating to this object