uk.ac.starlink.fits

## Class AbstractWideFits

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

- All Implemented Interfaces:
    WideFits

      public abstract class AbstractWideFits
      extends java.lang.Object
      implements WideFits

  Implementations of the WideFits interface. This class fills in the details of the general idea defined in WideFits. Static methods provide concrete implementations.

  The Wide FITS convention is defined in the file (fits/src/docs/)wide-fits.txt

  Since:
    27 Jul 2017

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `KEY_ICOL_CONTAINER` Index of container column hosting extended column data.
    `static java.lang.String` | `KEY_NCOL_EXT` Header key for extended column count - includes standard ones.

    - ### Fields inherited from interface uk.ac.starlink.fits.WideFits

      `DEFAULT, MAX_NCOLSTD`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractWideFits(int icolContainer, int extColMax, java.lang.String implName)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addContainerColumnHeader(nom.tam.fits.Header hdr, long nbyteExt, long nslice)` Adds the per-HDU header cards that describe the single container column (with index icolContainer) used to implement this convention in a BINTABLE HDU.
    `void` | `addExtensionHeader(nom.tam.fits.Header hdr, int ncolExt)` Adds the per-HDU header cards that announce the operation of this convention in a BINTABLE HDU.
    `static WideFits` | `createAlphaWideFits(int icolContainer)` Returns a WideFits instance that uses normal TFORMaaa headers where aaa is a 3-digit base-26 integer (each digit is [A-Z]).
    `static WideFits` | `createHierarchWideFits(int icolContainer)` Returns a WideFits instance that uses headers of the form HIERARCH XT TFORMnnnnn, using the ESO HIERARCH convention.
    `int` | `getContainerColumnIndex()` Returns the index of the column used (if any) by this specification for extended column data.
    `int` | `getExtColumnMax()` Maximum extended number of columns that can be represented by this convention.
    `int` | `getExtendedColumnCount(HeaderCards cards, int ncolStd)` Returns the total number of columns, including extended ones, described by a FITS header according to this convention.
    `static void` | `logWideRead(java.util.logging.Logger logger, int nStdcol, int nAllcol)` Utility method to write a log message indicating that this convention is being used to read a FITS file.
    `static void` | `logWideWrite(java.util.logging.Logger logger, int nStdcol, int nAllcol)` Utility method to write a log message indicating that this convention is being used to write a FITS file.
    `java.lang.String` | `toString()`

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

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

    - ### Methods inherited from interface uk.ac.starlink.fits.WideFits

      `createExtendedHeader`

- - ### Field Detail

    - #### KEY_ICOL_CONTAINER

          public static final java.lang.String KEY_ICOL_CONTAINER

      Index of container column hosting extended column data.
      See Also:
        Constant Field Values

    - #### KEY_NCOL_EXT

          public static final java.lang.String KEY_NCOL_EXT

      Header key for extended column count - includes standard ones.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AbstractWideFits

          protected AbstractWideFits(int icolContainer,
                                     int extColMax,
                                     java.lang.String implName)

      Constructor.
      Parameters:
        `icolContainer` - 1-based index of container column used for storing extended column data; usually 999
        `extColMax` - maximum number of extended columns (including standard columns) that can be represented by this convention
        `implName` - base name of this implementation

  - ### Method Detail

    - #### getContainerColumnIndex

          public int getContainerColumnIndex()

      Description copied from interface: `WideFits`
      Returns the index of the column used (if any) by this specification for extended column data. The result is the FITS column index, so the first column in the table is 1. This value is equal to the number of standard columns if extended columns are included.

      Under normal circumstances, this returns 999 (`WideFits.MAX_NCOLSTD`).

      Specified by:
        `getContainerColumnIndex` in interface `WideFits`
      Returns:
        1-based index of container column

    - #### getExtColumnMax

          public int getExtColumnMax()

      Description copied from interface: `WideFits`
      Maximum extended number of columns that can be represented by this convention. This value includes the standard columns.
      Specified by:
        `getExtColumnMax` in interface `WideFits`
      Returns:
        maximum extended column count

    - #### addContainerColumnHeader

          public void addContainerColumnHeader(nom.tam.fits.Header hdr,
                                               long nbyteExt,
                                               long nslice)

      Description copied from interface: `WideFits`
      Adds the per-HDU header cards that describe the single container column (with index icolContainer) used to implement this convention in a BINTABLE HDU.
      Specified by:
        `addContainerColumnHeader` in interface `WideFits`
      Parameters:
        `hdr` - header to append to
        `nbyteExt` - number of bytes per row in container column
        `nslice` - if >0 this will result in a TDIMnnn header that gives a 2-element shape, with the supplied value being the second element; if you don't want TDIMnnn, use 0

    - #### addExtensionHeader

          public void addExtensionHeader(nom.tam.fits.Header hdr,
                                         int ncolExt)

      Description copied from interface: `WideFits`
      Adds the per-HDU header cards that announce the operation of this convention in a BINTABLE HDU.
      Specified by:
        `addExtensionHeader` in interface `WideFits`
      Parameters:
        `hdr` - header to append to
        `ncolExt` - total column count including extended

    - #### getExtendedColumnCount

          public int getExtendedColumnCount(HeaderCards cards,
                                            int ncolStd)

      Description copied from interface: `WideFits`
      Returns the total number of columns, including extended ones, described by a FITS header according to this convention.
      Specified by:
        `getExtendedColumnCount` in interface `WideFits`
      Parameters:
        `cards` - FITS header
        `ncolStd` - number of 'standard' BINTABLE columns, got from TFIELDS header
      Returns:
        extended number of columns, includes standard ones

    - #### toString

          public java.lang.String toString()

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

    - #### createAlphaWideFits

          public static WideFits createAlphaWideFits(int icolContainer)

      Returns a WideFits instance that uses normal TFORMaaa headers where aaa is a 3-digit base-26 integer (each digit is [A-Z]).

      Note: this implementation is a historical relic. It could be removed if its maintenance becomes problematic.

      Parameters:
        `icolContainer` - 1-based index of container column used for storing extended column data; usually 999
      Returns:
        WideFits implementation

    - #### createHierarchWideFits

          public static WideFits createHierarchWideFits(int icolContainer)

      Returns a WideFits instance that uses headers of the form HIERARCH XT TFORMnnnnn, using the ESO HIERARCH convention.
      Parameters:
        `icolContainer` - 1-based index of container column used for storing extended column data; usually 999
      Returns:
        WideFits implementation

    - #### logWideWrite

          public static void logWideWrite(java.util.logging.Logger logger,
                                          int nStdcol,
                                          int nAllcol)

      Utility method to write a log message indicating that this convention is being used to write a FITS file.
      Parameters:
        `logger` - logger
        `nStdcol` - number of standard FITS columns
        `nAllcol` - total number of columns including extended

    - #### logWideRead

          public static void logWideRead(java.util.logging.Logger logger,
                                         int nStdcol,
                                         int nAllcol)

      Utility method to write a log message indicating that this convention is being used to read a FITS file.
      Parameters:
        `logger` - logger
        `nStdcol` - number of standard FITS columns
        `nAllcol` - total number of columns including extended