## nom.tam.fits
Class Header

    java.lang.Object
      nom.tam.fits.Header

public class Header
extends Object

This class describes methods to access and manipulate the header for a FITS HDU.

Constructor Summary
`Header()` Create a Header with no card images.
`Header(BufferedDataInputStream is)` Create a header and populate it from the input stream
`Header(String[] newCards)` Create a header and initialize it with a vector of strings.

Method Summary
`void` `addBooleanValue(String key, boolean val, String comment)` Add or replace a key with the given boolean value and comment.
`void` `addDoubleValue(String key, double val, String comment)` Add or replace a key with the given double value and comment.
`void` `addFloatValue(String key, float val, String comment)` Add or replace a key with the given float value and comment.
`void` `addIntValue(String key, int val, String comment)` Add or replace a key with the given int value and comment.
`protected void` `addLine(HeaderCard fcard)` Add a card image to the header after the mark if set.
`protected void` `addLine(String card)` Add a card image to the header after the mark if set.
`void` `addLongValue(String key, long val, String comment)` Add or replace a key with the given long value and comment.
`void` `addStringValue(String key, String val, String comment)` Add or replace a key with the given string value and comment.
`(package private) void` `checkEnd()` Ensure that the header has exactly one END keyword in the appropriate location.
`boolean` `containsKey(String key)` Tests if the specified keyword is present in this table.
`void` `deleteKey(String key)` Delete the card associated with the given key.
`protected void` `dumpHeader(PrintStream ps)` Dump the header to a given stream.
`protected HeaderCard` `findCard(String key)` Find the card associated with a given key.
`String` `findKey(String key)` Find the card associated with a given key.
`static String` `formatFields(String key, String val, String comment)` Format the key, value and comment fields for the FITS data.
`boolean` `getBooleanValue(String key)` Get the `boolean` value associated with the given key.
`boolean` `getBooleanValue(String key, boolean dft)` Get the `boolean` value associated with the given key.
`String` `getCard(int n)` Get the n'th card image in the header
`double` `getDoubleValue(String key)` Get the `double` value associated with the given key.
`double` `getDoubleValue(String key, double dft)` Get the `double` value associated with the given key.
`float` `getFloatValue(String key)` Get the `float` value associated with the given key.
`float` `getFloatValue(String key, float dft)` Get the `float` value associated with the given key.
`int` `getIntValue(String key)` Get the `int` value associated with the given key.
`int` `getIntValue(String key, int dft)` Get the value associated with the key as an int.
`String` `getKey(int n)` Get the n'th key in the header.
`long` `getLongValue(String key)` Get the `long` value associated with the given key.
`long` `getLongValue(String key, long dft)` Get the `long` value associated with the given key.
`int` `getMark()` Get the current mark.
`String` `getStringValue(String key)` Get the `String` value associated with the given key.
`int` `headerSize()` Return the size of the header data including padding.
`protected boolean` `imageToPrimary()` See if the current header is for an an array and if so turn it into a primary array.
`void` `insertCard(String card)` Insert or add a card to the header.
`void` `insertComment(String value)` Add a COMMENT line.
`void` `insertCommentStyle(String header, String value)` Add a line to the header using the COMMENT style, i.e., no '=' in column 9.
`void` `insertHistory(String value)` Add a HISTORY line.
`boolean` `isValidHeader()` Is this a valid header.
`boolean` `markSet()` Is the mark set?
`(package private) void` `nullImage()` Create a header for a null image.
`int` `paddedDataSize()` Return the size of the data including any needed padding.
`void` `pointToData(Data o)` Create keywords such that this Header describes the given data.
`protected void` `pointToImage(Object o)` Create keywords such that this header describes the given image data.
`protected boolean` `primaryToImage()` See if the current header is an array and if so turn it into an IMAGE extension.
`void` `read(BufferedDataInputStream dis)` Read a stream for header data.
`static Header` `readHeader(BufferedDataInputStream dis)` Create a header by reading the information from the input stream.
`void` `removeCardAt(int i)` Remove the card at the given index.
`void` `replaceCard(String key, String val, String comment)` Add or replace a key using the preformatted value.
`(package private) boolean` `replaceKey(String oldKey, String newKey)` Replace the key with a new key.
`(package private) void` `setBitpix(int val)` Set the BITPIX value for the header.
`(package private) void` `setExtend(boolean val)` Set the EXTEND keyword.
`(package private) void` `setGcount(int val)` Set the group count (GCOUNT) keyword.
`void` `setMark(int newMark)` Set the mark to the given value.
`(package private) void` `setNaxes(int val)` Set the value of the NAXIS keyword
`(package private) void` `setNaxis(int dim, int val)` Set the NAXISn keywords.
`(package private) void` `setPcount(int val)` Set the Parameter count (PCOUNT) keyword.
`(package private) void` `setSimple(boolean val)` Set the SIMPLE keyword to the given value.
`(package private) void` `setXtension(String val)` Set the XTENSION keyword to the given value.
`int` `size()`
`int` `trueDataSize()` Calculate the unpadded size of the data segment from the header information.
`void` `unsetMark()` Unset the mark.
`void` `write(BufferedDataOutputStream dos)` Write the current header (including any needed padding) to the output stream.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Header

    public Header()

  Create a Header with no card images.

### Header

    public Header(BufferedDataInputStream is)
           throws TruncatedFileException,
                  IOException

  Create a header and populate it from the input stream

Parameters:
  `is` - The input stream where header information is expected.

### Header

    public Header(String[] newCards)

  Create a header and initialize it with a vector of strings.

Parameters:
  `newCards` - Card images to be placed in the header.

Method Detail

### size

    public int size()

### trueDataSize

    public int trueDataSize()

  Calculate the unpadded size of the data segment from the header information. Note that this algorithm is not correct for Random Groups format data.

  Returns:
    the unpadded data segment size.

### paddedDataSize

    public int paddedDataSize()

  Return the size of the data including any needed padding.

  Returns:
    the data segment size including any needed padding.

### headerSize

    public int headerSize()

  Return the size of the header data including padding.

  Returns:
    the header size including any needed padding.

### isValidHeader

    public boolean isValidHeader()

  Is this a valid header. This routine provides only minimal checking currently.

  Returns:
    `true` for a valid header, `false` otherwise.

### getCard

    public String getCard(int n)

  Get the n'th card image in the header

  Returns:
    the card image; return `null` if the n'th card does not exist.

### getKey

    public String getKey(int n)

  Get the n'th key in the header.

  Returns:
    the card image; return `null` if the n'th key does not exist.

### getLongValue

    public long getLongValue(String key,
                             long dft)

  Get the `long` value associated with the given key.

  Parameters:
    `key` - The header key.
    `dft` - The default value to be returned if the key cannot be found.
  Returns:
    the associated value.

### getDoubleValue

    public double getDoubleValue(String key,
                                 double dft)

  Get the `double` value associated with the given key.

  Parameters:
    `key` - The header key.
    `dft` - The default value to return if the key cannot be found.
  Returns:
    the associated value.

### getBooleanValue

    public boolean getBooleanValue(String key,
                                   boolean dft)

  Get the `boolean` value associated with the given key.

  Parameters:
    `key` - The header key.
    `dft` - The value to be returned if the key cannot be found or if the parameter does not seem to be a boolean.
  Returns:
    the associated value.

### getLongValue

    public long getLongValue(String key)

  Get the `long` value associated with the given key.

  Parameters:
    `key` - The header key.
  Returns:
    The associated value or 0 if not found.

### getDoubleValue

    public double getDoubleValue(String key)

  Get the `double` value associated with the given key.

  Parameters:
    `key` - The header key.
  Returns:
    The associated value or 0.0 if not found.

### getBooleanValue

    public boolean getBooleanValue(String key)

  Get the `boolean` value associated with the given key.

  Returns:
    The value found, or false if not found or if the keyword is not a logical keyword.

### getIntValue

    public int getIntValue(String key,
                           int dft)

  Get the value associated with the key as an int.

  Parameters:
    `key` - The header key.
    `dft` - The value to be returned if the key is not found.

### getIntValue

    public int getIntValue(String key)

  Get the `int` value associated with the given key.

  Parameters:
    `key` - The header key.
  Returns:
    The associated value or 0 if not found.

### getFloatValue

    public float getFloatValue(String key,
                               float dft)

  Get the `float` value associated with the given key.

  Parameters:
    `key` - The header key.
    `dft` - The value to be returned if the key is not found.

### getFloatValue

    public float getFloatValue(String key)

  Get the `float` value associated with the given key.

  Parameters:
    `key` - The header key.
  Returns:
    The associated value or 0.0 if not found.

### getStringValue

    public String getStringValue(String key)

  Get the `String` value associated with the given key.

  Parameters:
    `key` - The header key.
  Returns:
    The associated value or null if not found or if the value is not a string.

### addLine

    protected void addLine(HeaderCard fcard)

  Add a card image to the header after the mark if set.

  Parameters:
    `fcard` - The card to be added.

### addLine

    protected void addLine(String card)
                    throws HeaderCardException

  Add a card image to the header after the mark if set.

  Parameters:
    `card` - The card to be added.
  Throws:
    `HeaderCardException` - If the card is not valid.

### readHeader

    public static Header readHeader(BufferedDataInputStream dis)
                             throws TruncatedFileException,
                                    IOException

  Create a header by reading the information from the input stream.

  Parameters:
    `dis` - The input stream to read the data from.
  Returns:
    `null` if there was a problem with the header; otherwise return the header read from the input stream.
  Throws:
    `TruncatedFileException`
    `IOException`

### read

    public void read(BufferedDataInputStream dis)
              throws TruncatedFileException,
                     IOException

  Read a stream for header data.

  Parameters:
    `dis` - The input stream to read the data from.
  Returns:
    `null` if there was a problem with the header; otherwise return the header read from the input stream.
  Throws:
    `TruncatedFileException`
    `IOException`

### findCard

    protected HeaderCard findCard(String key)

  Find the card associated with a given key. If found this sets the mark to the card, otherwise it unsets the mark.

  Parameters:
    `key` - The header key.
  Returns:
    `null` if the keyword could not be found; return the HeaderCard object otherwise.

### findKey

    public String findKey(String key)

  Find the card associated with a given key. If found this sets the mark to the card, otherwise it unsets the mark.

  Parameters:
    `key` - The header key.
  Returns:
    `null` if the keyword could not be found; return the card image otherwise.

### replaceKey

    boolean replaceKey(String oldKey,
                       String newKey)
                 throws HeaderCardException

  Replace the key with a new key. Typically this is used when deleting or inserting columns so that TFORMx -> TFORMx-1

  Parameters:
    `oldKey` - The old header keyword.
    `newKey` - the new header keyword.
  Returns:
    `true` if the card was replaced.
  Throws:
    `HeaderCardException` - If `newKey` is not a valid FITS keyword.

### write

    public void write(BufferedDataOutputStream dos)
               throws FitsException

  Write the current header (including any needed padding) to the output stream.

  Parameters:
    `dos` - The output stream to which the data is to be written.
  Throws:
    `FitsException` - if the header could not be written.

### addBooleanValue

    public void addBooleanValue(String key,
                                boolean val,
                                String comment)
                         throws HeaderCardException

  Add or replace a key with the given boolean value and comment.

  Parameters:
    `key` - The header key.
    `val` - The boolean value.
    `comment` - A comment to append to the card.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### addFloatValue

    public void addFloatValue(String key,
                              float val,
                              String comment)
                       throws HeaderCardException

  Add or replace a key with the given float value and comment.

  Parameters:
    `key` - The header key.
    `val` - The float value.
    `comment` - A comment to append to the card.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### addDoubleValue

    public void addDoubleValue(String key,
                               double val,
                               String comment)
                        throws HeaderCardException

  Add or replace a key with the given double value and comment.

  Parameters:
    `key` - The header key.
    `val` - The double value.
    `comment` - A comment to append to the card.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### addStringValue

    public void addStringValue(String key,
                               String val,
                               String comment)
                        throws HeaderCardException

  Add or replace a key with the given string value and comment.

  Parameters:
    `key` - The header key.
    `val` - The string value.
    `comment` - A comment to append to the card.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### replaceCard

    public void replaceCard(String key,
                            String val,
                            String comment)
                     throws HeaderCardException

  Add or replace a key using the preformatted value. If the key is not found, then add the card after the current mark or at the end if the mark is not set.

  Parameters:
    `key` - The header key.
    `val` - The string which will follow the "= " on the card. This routine is called by the various addXXXValue routines after they have formatted the value as a string.
    `comment` - A comment to append to the card.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### addIntValue

    public void addIntValue(String key,
                            int val,
                            String comment)
                     throws HeaderCardException

  Add or replace a key with the given int value and comment.

  Parameters:
    `key` - The header key.
    `val` - The int value.
    `comment` - A comment to append to the card.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### addLongValue

    public void addLongValue(String key,
                             long val,
                             String comment)
                      throws HeaderCardException

  Add or replace a key with the given long value and comment.

  Parameters:
    `key` - The header key.
    `val` - The long value.
    `comment` - A comment to append to the card.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### formatFields

    public static String formatFields(String key,
                                      String val,
                                      String comment)
                               throws HeaderCardException

  Format the key, value and comment fields for the FITS data.

  Parameters:
    `key` - The header keyword.
    `val` - The value associated with the key expressed as a string.
    `comment` - A comment to put on the field.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### insertCard

    public void insertCard(String card)

  Insert or add a card to the header. Insert after the mark if set, or at the end of the header if not set.

  Parameters:
    `card` - The card to be inserted.

### insertCommentStyle

    public void insertCommentStyle(String header,
                                   String value)
                            throws HeaderCardException

  Add a line to the header using the COMMENT style, i.e., no '=' in column 9.

  Parameters:
    `header` - The comment style header.
    `value` - A string to follow the header.
  Throws:
    `HeaderCardException` - If the parameters cannot build a valid FITS card.

### insertComment

    public void insertComment(String value)
                       throws HeaderCardException

  Add a COMMENT line.

  Parameters:
    `value` - The comment.
  Throws:
    `HeaderCardException` - If the parameter is not a valid FITS comment.

### insertHistory

    public void insertHistory(String value)
                       throws HeaderCardException

  Add a HISTORY line.

  Parameters:
    `value` - The history record.
  Throws:
    `HeaderCardException` - If the parameter is not a valid FITS comment.

### markSet

    public boolean markSet()

  Is the mark set?

  Returns:
    `true` if the mark is set.

### getMark

    public int getMark()

  Get the current mark. A value of -2 indicates that the mark is not set and new cards are appended to the end of the header. A value of -1 indicates that the mark is set such that the next card should be inserted at the beginning of the header. Otherwise cards should be inserted after the mark. The mark is typically set to a card whenever an operation (i.e., insert or modify) is made on the card. Thus a series of inserts will result in cards a sequential series of cards in the same order.

  Returns:
    the current mark.

### setMark

    public void setMark(int newMark)

  Set the mark to the given value.

### unsetMark

    public void unsetMark()

  Unset the mark. Inserts should now be done as appends to the end of the header.

### deleteKey

    public void deleteKey(String key)

  Delete the card associated with the given key. Nothing occurs if the key is not found, though this will unset the mark. The mark is left pointing at the following card if successful (or unset if this was the last card).

  Parameters:
    `key` - The header key.

### removeCardAt

    public void removeCardAt(int i)

  Remove the card at the given index. The mark is left pointing at the next card or unset if this was the last card.

  Parameters:
    `i` - The index of the card to be removed.

### containsKey

    public final boolean containsKey(String key)

  Tests if the specified keyword is present in this table.

  Parameters:
    `key` - the keyword to be found.
  Returns:
    `true`if the specified keyword is present in this table; `false`otherwise.````

### pointToData

    public void pointToData(Data o)
                     throws FitsException

  Create keywords such that this Header describes the given data.

  Parameters:
    `o` - The data object to be described.
  Throws:
    `FitsException` - if the data was not valid for this header.

### pointToImage

    protected void pointToImage(Object o)
                         throws FitsException

  Create keywords such that this header describes the given image data.

  Parameters:
    `o` - The image to be described.
  Throws:
    `FitsException` - if the object does not contain valid image data.

### nullImage

    void nullImage()

  Create a header for a null image.

### setSimple

    void setSimple(boolean val)

  Set the SIMPLE keyword to the given value.

  Parameters:
    `val` - The boolean value -- Should be true for FITS data.

### setXtension

    void setXtension(String val)

  Set the XTENSION keyword to the given value.

  Parameters:
    `val` - The name of the extension. "IMAGE" and "BINTABLE" are supported.

### setBitpix

    void setBitpix(int val)

  Set the BITPIX value for the header.

### setNaxes

    void setNaxes(int val)

  Set the value of the NAXIS keyword

  Parameters:
    `val` - The dimensionality of the data.

### checkEnd

    void checkEnd()

  Ensure that the header has exactly one END keyword in the appropriate location.

### setNaxis

    void setNaxis(int dim,
                  int val)

  Set the NAXISn keywords.

  Parameters:
    `dim` - The dimension being set.
    `val` - The length along that dimension.

### setGcount

    void setGcount(int val)

  Set the group count (GCOUNT) keyword. This should be 1 except for the unsupported random-groups data.

  Parameters:
    `val` - the number of groups in the data.

### setPcount

    void setPcount(int val)

  Set the Parameter count (PCOUNT) keyword. This is normally 0 except when random-groups data is used or when the variable length columns convention is used with binary tables.

  Parameters:
    `val` - The number of parameters.

### setExtend

    void setExtend(boolean val)

  Set the EXTEND keyword. This is only placed in the primary header and should always be `true`. Just in case we do provide for setting it to `false`.

  Parameters:
    `val` - the value assigned to the EXTEND keyword.

### primaryToImage

    protected boolean primaryToImage()

  See if the current header is an array and if so turn it into an IMAGE extension.

  Returns:
    whether the transformation could be done.

### imageToPrimary

    protected boolean imageToPrimary()

  See if the current header is for an an array and if so turn it into a primary array.

  Returns:
    whether the transformation could be done.

### dumpHeader

    protected void dumpHeader(PrintStream ps)

  Dump the header to a given stream.

  Parameters:
    `ps` - the stream to which the card images are dumped.