Package nom.tam.fits

Class HeaderCard

java.lang.Object
nom.tam.fits.HeaderCard
All Implemented Interfaces:
Cloneable, CursorValue<String>
public class HeaderCard extends Object implements CursorValue<String>, Cloneable
An individual entry in the FITS header, such as a key/value pair with an optional comment field, or a comment-style entry without a value field.

  • Field Details

    • FITS_HEADER_CARD_SIZE

      public static final int FITS_HEADER_CARD_SIZE
      The number of characters per header card (line).
      See Also:

    • MAX_KEYWORD_LENGTH

      public static final int MAX_KEYWORD_LENGTH
      Maximum length of a FITS keyword field
      See Also:

    • STRING_QUOTES_LENGTH

      public static final int STRING_QUOTES_LENGTH
      The length of two single quotes that must surround string values.
      See Also:

    • MAX_VALUE_LENGTH

      public static final int MAX_VALUE_LENGTH
      Maximum length of a FITS value field.
      See Also:

    • MAX_COMMENT_CARD_COMMENT_LENGTH

      public static final int MAX_COMMENT_CARD_COMMENT_LENGTH
      Maximum length of a comment-style card comment field.
      See Also:

    • MAX_STRING_VALUE_LENGTH

      public static final int MAX_STRING_VALUE_LENGTH
      Maximum length of a FITS string value field.
      See Also:

    • MAX_LONG_STRING_VALUE_LENGTH

      public static final int MAX_LONG_STRING_VALUE_LENGTH
      Maximum length of a FITS long string value field. the & for the continuation needs one char.
      See Also:

    • MAX_LONG_STRING_VALUE_WITH_COMMENT_LENGTH

      public static final int MAX_LONG_STRING_VALUE_WITH_COMMENT_LENGTH
      if a commend needs the be specified 2 extra chars are needed to start the comment
      See Also:

    • MAX_HIERARCH_KEYWORD_LENGTH

      public static final int MAX_HIERARCH_KEYWORD_LENGTH
      Maximum HIERARCH keyword length (80 chars must fit [<keyword> = '&'] at minimum...
      See Also:

    • MAX_LONG_STRING_CONTINUE_OVERHEAD

      public static final int MAX_LONG_STRING_CONTINUE_OVERHEAD
      The start and end quotes of the string and the ampasant to continue the string.
      See Also:

    • MIN_VALID_CHAR

      public static final char MIN_VALID_CHAR
      The first ASCII character that may be used in header records
      See Also:

    • MAX_VALID_CHAR

      public static final char MAX_VALID_CHAR
      The last ASCII character that may be used in header records
      See Also:

    • EMPTY_KEY

      public static final String EMPTY_KEY
      The default keyword to use instead of null or any number of blanks.
      See Also:

    • DEFAULT_VALUE_CHECK_POLICY

      public static final HeaderCard.ValueCheck DEFAULT_VALUE_CHECK_POLICY
      Default value type checking policy for cards with standardized IFitsHeader keywords.
      Since:
      1.19

  • Constructor Details

  • Method Details

    • cardSize

      public int cardSize()
      Returns the number of 80-character header lines needed to store the data from this card.
      Returns:
      the size of the card in blocks of 80 bytes. So normally every card will return 1. only long stings can return more than one, provided support for long string is enabled.

    • copy

      public HeaderCard copy()
      Returns an independent copy of this card. Both this card and the returned value will have identical content, but modifying one is guaranteed to not affect the other.
      Returns:
      a copy of this carf.

    • getKey

      public final String getKey()
      Returns the keyword component of this card, which may be empty but never null, but it may be an empty string.
      Specified by:
      getKey in interface CursorValue<String>
      Returns:
      the keyword from this card, guaranteed to be not null).
      See Also:

    • getValue

      public final String getValue()
      Returns the serialized value component of this card, which may be null.
      Returns:
      the value from this card
      See Also:

    • getComment

      public final String getComment()
      Returns the comment component of this card, which may be null.
      Returns:
      the comment from this card
      See Also:

    • getHexValue

      @Deprecated public final long getHexValue() throws NumberFormatException
      Deprecated.
      Not supported by the FITS standard, so do not use. It was included due to a misreading of the standard itself.
      Returns:
      the value from this card
      Throws:
      NumberFormatException - if the card's value is null or cannot be parsed as a hexadecimal value.
      See Also:

    • getValue

      public <T> T getValue(Class<T> asType, T defaultValue) throws IllegalArgumentException

      Returns the value cast to the specified type, if possible, or the specified default value if the value is null or if the value is incompatible with the requested type.

      For number types and values, if the requested type has lesser range or precision than the number stored in the FITS header, the value is automatically downcast (i.e. possible rounded and/or truncated) -- the same as if an explicit cast were used in Java. As long as the header value is a proper decimal value, it will be returned as any requested number type.

      Type Parameters:
      T - the generic type of the requested class
      Parameters:
      asType - the requested class of the value
      defaultValue - the value to use if the card has a null value, or a value that cannot be cast to the specified type.
      Returns:
      the value from this card as a specific type, or the specified default value
      Throws:
      IllegalArgumentException - if the specified Java type of not one that is supported for use in FITS headers.

    • isKeyValuePair

      public boolean isKeyValuePair()
      Checks if this card has both a valid keyword and a (non-null) value.
      Returns:
      Is this a key/value card?
      See Also:

    • isStringValue

      public boolean isStringValue()
      Checks if this card has a string value (which may be null).
      Returns:
      true if this card has a string value, otherwise false.
      See Also:

    • isDecimalType

      public boolean isDecimalType()
      Checks if this card has a decimal (floating-point) type value (which may be null).
      Returns:
      true if this card has a decimal (not integer) type number value, otherwise false.
      Since:
      1.16
      See Also:

    • isIntegerType

      public boolean isIntegerType()
      Checks if this card has an integer type value (which may be null).
      Returns:
      true if this card has an integer type value, otherwise false.
      Since:
      1.16
      See Also:

    • isCommentStyleCard

      public final boolean isCommentStyleCard()
      Checks if this card is a comment-style card with no associated value field.
      Returns:
      true if this card is a comment-style card, otherwise false.
      Since:
      1.16
      See Also:

    • hasHierarchKey

      public final boolean hasHierarchKey()
      Checks if this card cas a hierarch style long keyword.
      Returns:
      true if the card has a non-standard HIERARCH style long keyword, with dot-separated components. Otherwise false.
      Since:
      1.16

    • setComment

      public void setComment(String comment)
      Sets a new comment component for this card. The specified comment string will be sanitized to ensure it onlly contains characters suitable for FITS headers. Invalid characters will be replaced with '?'.
      Parameters:
      comment - the new comment text.

    • setValue

      public final HeaderCard setValue(Number update) throws NumberFormatException, LongValueException
      Sets a new number value for this card. The new value will be shown in the integer, fixed-decimal, or format, whichever preserves more digits, or else whichever is the more compact notation. Trailing zeroes will be omitted.
      Parameters:
      update - the new value to set (can be null, in which case the card type defaults to Integer.class)
      Returns:
      the card itself
      Throws:
      NumberFormatException - if the input value is NaN or Infinity.
      LongValueException - if the decimal value cannot be represented in the alotted space
      See Also:

    • setValue

      public HeaderCard setValue(Number update, int decimals) throws NumberFormatException, LongValueException
      Sets a new number value for this card, using scientific (exponential) notation, with up to the specified decimal places showing between the decimal point and the exponent. For example, if decimals is set to 2, then π gets formatted as 3.14E0.
      Parameters:
      update - the new value to set (can be null, in which case the card type defaults to Integer.class)
      decimals - the number of decimal places to show in the scientific notation.
      Returns:
      the card itself
      Throws:
      NumberFormatException - if the input value is NaN or Infinity.
      LongValueException - if the decimal value cannot be represented in the alotted space
      See Also:

    • setValue

      public HeaderCard setValue(Boolean update) throws LongValueException, ValueTypeException
      Sets a new boolean value for this cardvalueType
      Parameters:
      update - the new value to se (can be null).
      Returns:
      the card itself
      Throws:
      LongValueException - if the card has no room even for the single-character 'T' or 'F'. This can never happen with cards created programmatically as they will not allow setting HIERARCH-style keywords long enough to ever trigger this condition. But, it is possible to read cards from a non-standard header, which breaches this limit, by ommitting some required spaces (esp. after the '='), and have a null value. When that happens, we can be left without room for even a single character.
      ValueTypeException - if the card's standard keyword does not support boolean values.

    • setValue

      public final HeaderCard setValue(ComplexValue update) throws NumberFormatException, LongValueException
      Sets a new complex number value for this card. The real and imaginary part will be shown in the integer, fixed-decimal, or format, whichever preserves more digits, or else whichever is the more compact notation. Trailing zeroes will be omitted.
      Parameters:
      update - the new value to set (can be null)
      Returns:
      the card itself
      Throws:
      NumberFormatException - if the input value is NaN or Infinity.
      LongValueException - if the decimal value cannot be represented in the alotted space
      Since:
      1.16
      See Also:

    • setValue

      public HeaderCard setValue(ComplexValue update, int decimals) throws LongValueException
      Sets a new complex number value for this card, using scientific (exponential) notation, with up to the specified number of decimal places showing between the decimal point and the exponent. Trailing zeroes will be omitted. For example, if decimals is set to 2, then (π, 12) gets formatted as (3.14E0,1.2E1).
      Parameters:
      update - the new value to set (can be null)
      decimals - the number of decimal places to show in the scientific notation.
      Returns:
      the HeaderCard itself
      Throws:
      NumberFormatException - if the input value is NaN or Infinity.
      LongValueException - if the decimal value cannot be represented in the alotted space
      Since:
      1.16
      See Also:

    • setHexValue

      @Deprecated public HeaderCard setHexValue(long update) throws LongValueException
      Deprecated.
      Not supported by the FITS standard, so do not use. It was included due to a misreading of the standard itself.
      Parameters:
      update - the new value to set
      Returns:
      the HeaderCard itself
      Throws:
      LongValueException - if the value is too long to fit in the available space.
      Since:
      1.16

    • setValue

      public HeaderCard setValue(String update) throws IllegalArgumentException, LongStringsNotEnabledException
      Sets a new string value for this card.
      Parameters:
      update - the new value to set
      Returns:
      the HeaderCard itself
      Throws:
      IllegalArgumentException - if the new value contains characters that cannot be added to the the FITS header.
      LongStringsNotEnabledException - if the card contains a long string but support for long strings is currently disabled.
      See Also:

    • toString

      public String toString() throws LongValueException, LongStringsNotEnabledException, HierarchNotEnabledException
      Returns the modulo 80 character card image, the toString tries to preserve as much as possible of the comment value by reducing the alignment of the Strings if the comment is longer and if longString is enabled the string can be split into one more card to have more space for the comment.
      Overrides:
      toString in class Object
      Returns:
      the FITS card as one or more 80-character string blocks.
      Throws:
      LongValueException - if the card has a long string value that is too long to contain in the space available after the keyword.
      LongStringsNotEnabledException - if the card contains a long string but support for long strings is currently disabled.
      HierarchNotEnabledException - if the card contains a HIERARCH-style long keyword but support for these is currently disabled.
      See Also:

    • valueType

      public Class<?> valueType()
      Returns the class of the associated value, or null if it's a comment-style card.
      Returns:
      the type of the value.
      See Also:

    • spaceForValue

      public final int spaceForValue()
      Returns the space available for value and/or comment in a single record the keyword.
      Returns:
      the number of characters available in a single 80-character header record for a standard (non long string) value and/or comment.
      Since:
      1.16

    • changeKey

      public void changeKey(String newKey) throws HierarchNotEnabledException, LongValueException, LongStringsNotEnabledException, IllegalArgumentException
      Updates the keyword for this card.
      Parameters:
      newKey - the new FITS header keyword to use for this card.
      Throws:
      HierarchNotEnabledException - if the new key is a HIERARCH-style long key but support for these is not currently enabled.
      IllegalArgumentException - if the keyword contains invalid characters
      LongValueException - if the new keyword does not leave sufficient room for the current non-string value.
      LongStringsNotEnabledException - if the new keyword does not leave sufficient rooom for the current string value without enabling long string support.
      See Also:

    • isBlank

      public boolean isBlank()
      Checks if the card is blank, that is if it contains only empty spaces.
      Returns:
      true if the card contains nothing but blank spaces.

    • getValueCheckingPolicy

      public static HeaderCard.ValueCheck getValueCheckingPolicy()
      Returns the current policy for checking if set values are of the allowed type for cards with standardized IFitsHeader keywords.
      Returns:
      the current value type checking policy
      Since:
      1.19
      See Also:

    • setValueCheckingPolicy

      public static void setValueCheckingPolicy(HeaderCard.ValueCheck policy)
      Sets the policy to used for checking if set values conform to the expected types for cards that use standardized FITS keywords via the IFitsHeader interface.
      Parameters:
      policy - the new polict to use for checking value types.
      Since:
      1.19
      See Also:

    • create

      public static HeaderCard create(String line) throws IllegalArgumentException

      Creates a new FITS header card from a FITS stream representation of it, which is how the key/value and comment are represented inside the FITS file, normally as an 80-character wide entry. The parsing of header 'lines' conforms to all FITS standards, and some optional conventions, such as HIERARCH keywords (if FitsFactory.setUseHierarch(boolean) is enabled), COMMENT and HISTORY entries, and OGIP 1.0 long CONTINUE lines (if FitsFactory.setLongStringsEnabled(boolean) is enabled).

      However, the parsing here is permissive beyond the standards and conventions, and will do its best to support a wide range of FITS files, which may deviate from the standard in subtle (or no so subtle) ways.

      Here is a brief summary of the rules that guide the parsing of keywords, values, and comment 'fields' from the single header line:

      A. Keywords

      • The standard FITS keyword is the first 8 characters of the line, or up to an equal [=] character, whichever comes first, with trailing spaces removed, and always converted to upper-case.
      • If FitsFactory.setUseHierarch(boolean) is enabled, structured longer keywords can be composed after a HIERARCH base key, followed by space (and/or dot ].]) separated parts, up to an equal sign [=]. The library will represent the same components (including HIERARCH) but separated by single dots [.]. For example, the header line starting with [HIERARCH SMA OBS TARGET =], will be referred as [HIERARCH.SMA.OBS.TARGET] withing this library. The keyword parts can be composed of any ASCII characters except dot [.], white spaces, or equal [=].
      • By default, all parts of the key are converted to upper-case. Case sensitive HIERARCH keywords can be retained after enabling IHierarchKeyFormatter.setCaseSensitive(boolean).

      B. Values

      Values are the part of the header line, that is between the keyword and an optional ending comment. Legal header values follow the following parse patterns:

      • Begin with an equal sign [=], or else come after a CONTINUE keyword.
      • Next can be a quoted value such as 'hello', placed inside two single quotes. Or an unquoted value, such as 123.
      • Quoted values must begin with a single quote ['] and and with the next single quote. If there is no end-quote in the line, it is not considered a string value but rather a comment, unless FitsFactory.setAllowHeaderRepairs(boolean) is enabled, in which case the entire remaining line after the opening quote is assumed to be a malformed value.
      • Unquoted values end at the fist [/] character, or else go until the line end.
      • Quoted values have trailing spaces removed, s.t. [' value '] becomes [ value].
      • Unquoted values are trimmed, with both leading and trailing spaces removed, e.g. [ 123 ] becomes [123].

      C. Comments

      The following rules guide the parsing of the values component:

      • If a value is present (see above), the comment is what comes after it. That is, for quoted values, everything that follows the closing quote. For unquoted values, it's what comes after the first [/], with the [/] itself removed.
      • If a value is not present, then everything following the keyword is considered the comment.
      • Comments are trimmed, with both leading and trailing spaces removed.
      Parameters:
      line - the card image (typically 80 characters if in a FITS file).
      Returns:
      a newly created HeaderCard from a FITS card string.
      Throws:
      IllegalArgumentException - if the card was malformed, truncated, or if there was an IO error.
      See Also:

    • create

      public static HeaderCard create(IFitsHeader key, Boolean value) throws IllegalArgumentException
      Creates a new card with a standard or conventional keyword and a boolean value, with the default comment associated with the keyword. Unlike HeaderCard(String, Boolean), this call does not throw an exception, since the keyword and comment should be valid by design.
      Parameters:
      key - The standard or conventional keyword with its associated default comment.
      value - the boolean value associated to the keyword
      Returns:
      A new header card with the speficied standard-style key and comment and the specified value, or null if the standard key itself is malformed or illegal.
      Throws:
      IllegalArgumentException - if the standard key was ill-defined.
      Since:
      1.16

    • create

      public static HeaderCard create(IFitsHeader key, Number value) throws IllegalArgumentException

      Creates a new card with a standard or conventional keyword and a number value, with the default comment associated with the keyword. Unlike HeaderCard(String, Number), this call does not throw a hard HeaderCardException exception, since the keyword and comment should be valid by design. (A runtime IllegalArgumentException may still be thrown in the event that the supplied conventional keywords itself is ill-defined -- but this should not happen unless something was poorly coded in this library, on in an extension of it).

      If the value is not compatible with the convention of the keyword, a warning message is logged but no exception is thrown (at this point).

      Parameters:
      key - The standard or conventional keyword with its associated default comment.
      value - the integer value associated to the keyword.
      Returns:
      A new header card with the speficied standard-style key and comment and the specified value.
      Throws:
      IllegalArgumentException - if the standard key itself was ill-defined.
      Since:
      1.16

    • create

      public static HeaderCard create(IFitsHeader key, ComplexValue value) throws IllegalArgumentException
      Creates a new card with a standard or conventional keyword and a number value, with the default comment associated with the keyword. Unlike HeaderCard(String, Number), this call does not throw an exception, since the keyword and comment should be valid by design.
      Parameters:
      key - The standard or conventional keyword with its associated default comment.
      value - the integer value associated to the keyword.
      Returns:
      A new header card with the speficied standard-style key and comment and the specified value.
      Throws:
      IllegalArgumentException - if the standard key was ill-defined.
      Since:
      1.16

    • create

      public static HeaderCard create(IFitsHeader key, String value) throws IllegalArgumentException
      Creates a new card with a standard or conventional keyword and an integer value, with the default comment associated with the keyword. Unlike HeaderCard(String, Number), this call does not throw a hard exception, since the keyword and comment sohould be valid by design. The string value however will be checked, and an appropriate runtime exception is thrown if it cannot be included in a FITS header.
      Parameters:
      key - The standard or conventional keyword with its associated default comment.
      value - the string associated to the keyword.
      Returns:
      A new header card with the speficied standard-style key and comment and the specified value.
      Throws:
      IllegalArgumentException - if the string value contains characters that are not allowed in FITS headers, that is characters outside of the 0x20 thru 0x7E range, or if the standard key was ill-defined.

    • createCommentStyleCard

      public static HeaderCard createCommentStyleCard(String key, String comment) throws HeaderCardException, LongValueException
      Creates a comment-style card with no associated value field.
      Parameters:
      key - The keyword, or null blank/empty string for an unkeyed comment.
      comment - The comment text.
      Returns:
      a new comment-style header card with the specified key and comment text.
      Throws:
      HeaderCardException - if the key or value were invalid.
      LongValueException - if the comment text is longer than the space available in comment-style cards (71 characters max)
      See Also:

    • createUnkeyedCommentCard

      public static HeaderCard createUnkeyedCommentCard(String text) throws HeaderCardException, LongValueException
      Creates a new unkeyed comment card for th FITS header. These are comment-style cards with no associated value field, and with a blank keyword. They are commonly used to add explanatory notes in the FITS header. Keyed comments are another alternative...
      Parameters:
      text - a concise descriptive entry (max 71 characters).
      Returns:
      a new COMMENT card with the specified key and comment text.
      Throws:
      HeaderCardException - if the text contains invalid charaters.
      LongValueException - if the comment text is longer than the space available in comment-style cards (71 characters max)
      See Also:

    • createCommentCard

      public static HeaderCard createCommentCard(String text) throws HeaderCardException, LongValueException
      Creates a new keyed comment card for th FITS header. These are comment-style cards with no associated value field, and with COMMENT as the keyword. They are commonly used to add explanatory notes in the FITS header. Unkeyed comments are another alternative...
      Parameters:
      text - a concise descriptive entry (max 71 characters).
      Returns:
      a new COMMENT card with the specified key and comment text.
      Throws:
      HeaderCardException - if the text contains invalid charaters.
      LongValueException - if the comment text is longer than the space available in comment-style cards (71 characters max)
      See Also:

    • createHistoryCard

      public static HeaderCard createHistoryCard(String text) throws HeaderCardException, LongValueException
      Creates a new history record for the FITS header. These are comment-style cards with no associated value field, and with HISTORY as the keyword. They are commonly used to document the sequence operations that were performed on the data before it arrived to the state represented by the FITS file. The text field for history entries is limited to 70 characters max per card. However there is no limit to how many such entries are in a FITS header.
      Parameters:
      text - a concise descriptive entry (max 71 characters).
      Returns:
      a new HISTORY card with the specified key and comment text.
      Throws:
      HeaderCardException - if the text contains invalid charaters.
      LongValueException - if the comment text is longer than the space available in comment-style cards (71 characters max)
      See Also:

    • createHexValueCard

      @Deprecated public static HeaderCard createHexValueCard(String key, long value) throws HeaderCardException
      Deprecated.
      Not supported by the FITS standard, so do not use. It was included due to a misreading of the standard itself.
      Parameters:
      key - the keyword
      value - the integer value
      Returns:
      A new header card, with the specified integer in hexadecomal representation.
      Throws:
      HeaderCardException - if the card is invalid (for example the keyword is not valid).
      See Also:

    • createHexValueCard

      @Deprecated public static HeaderCard createHexValueCard(String key, long value, String comment) throws HeaderCardException
      Deprecated.
      Not supported by the FITS standard, so do not use. It was included due to a misreading of the standard itself.
      Parameters:
      key - the keyword
      value - the integer value
      comment - optional comment, or null.
      Returns:
      A new header card, with the specified integer in hexadecomal representation.
      Throws:
      HeaderCardException - if the card is invalid (for example the keyword is not valid).
      See Also:

    • saveNewHeaderCard

      @Deprecated public static HeaderCard saveNewHeaderCard(String key, String comment, boolean hasValue) throws HeaderCardException
      Deprecated.
      This was to be used internally only, without public visibility. It will become unexposed to users in a future release...
      This method was designed for use internally. It is 'safe' (not save!) in the sense that the runtime exception it may throw does not need to be caught.
      Parameters:
      key - keyword
      comment - optional comment, or null
      hasValue - does this card have a (null) value field? If true a null value of type String.class is assumed (for backward compatibility).
      Returns:
      the new HeaderCard
      Throws:
      HeaderCardException - if the card could not be created for some reason (noted as the cause).

    • sanitize

      public static String sanitize(String str)
      Replaces illegal characters in the string ith '?' to be suitable for FITS header records. According to the FITS standard, headers may only contain ASCII characters in the range 0x20 and 0x7E (inclusive).
      Parameters:
      str - the input string.
      Returns:
      the sanitized string for use in a FITS header, with illegal characters replaced by '?'.
      See Also:

    • isValidChar

      public static boolean isValidChar(char c)
      Checks if a character is valid for inclusion in a FITS header record. The FITS standard specifies that only ASCII characters between 0x20 thru 0x7E may be used in FITS headers.
      Parameters:
      c - the character to check
      Returns:
      true if the character is allowed in the FITS header, otherwise false.
      See Also:

    • validateChars

      public static void validateChars(String text) throws IllegalArgumentException
      Checks the specified string for characters that are not allowed in FITS headers, and throws an exception if any are found. According to the FITS standard, headers may only contain ASCII characters in the range 0x20 and 0x7E (inclusive).
      Parameters:
      text - the input string
      Throws:
      IllegalArgumentException - if the unput string contains any characters that cannot be in a FITS header, that is characters outside of the 0x20 to 0x7E range.
      Since:
      1.16
      See Also:

    • validateKey

      public static void validateKey(String key) throws IllegalArgumentException
      Checks if the specified string may be used as a FITS header keyword according to the FITS standard and currently settings for supporting extensions to the standard, such as HIERARCH-style keywords.
      Parameters:
      key - the proposed keyword string
      Throws:
      IllegalArgumentException - if the string cannot be used as a FITS keyword with the current settings. The exception will contain an informative message describing the issue.
      Since:
      1.16
      See Also: