eap.fits
Class FitsCard

java.lang.Object
  eap.fits.FitsCard

public class FitsCard

extends Object

Represents a single header record. It's called a "card" because when FITS was created, FORTRAN was the standard programming language for science and the designers had punchcards in mind. A card consists of 80 ASCII characters containing a key/value pair and a comment. The internal structure of a card is not parsed until needed. You may construct a new card by specifying its raw bytes or by specifying it's component fields. In the former case the bytes are taken without question, and in the latter case, the constructor forces correct FITS format.

Field Summary

static int	CARDS_PER_BLOCK the number of cards in a FITS block = 2880/80
static int	KEY_LENGTH the maximum number of bytes in a keyword = 8
static int	LENGTH the number of bytes in a card = 80
static byte[]	PADDING the value to use for padding out an incomplete block (80 ASCII spaces)

Constructor Summary

FitsCard(byte[] data)
Create a new card initialized with the given data.

FitsCard(byte[] data, int offset)
Create a new card from the bytes in an array, starting at the given offset into the array.

FitsCard(String key)
Create a card by specifying only its keyword.

FitsCard(String key, boolean value, String comment)
construct a card by specifying it's keyword, value and comment.

FitsCard(String key, Boolean value, String comment)
construct a card by specifying it's keyword, value and comment.

FitsCard(String key, double value, String comment)
construct a card by specifying it's keyword, value and comment.

FitsCard(String key, float value, String comment)
construct a card by specifying it's keyword, value and comment.

FitsCard(String key, int value, String comment)
construct a card by specifying it's keyword, value and comment.

FitsCard(String key, long value, String comment)
construct a card by specifying it's keyword, value and comment.

FitsCard(String key, Number value, String comment)
construct a card by specifying it's keyword, value and comment.

FitsCard(String key, String comment)
create a new card which has no value field.

FitsCard(String key, String value, String comment)
construct a card by specifying it's keyword, value and comment.

Method Summary

String	comment() returns the commment field.
byte[]	data() returns the raw 80 bytes of data for this card.
double	doubleValue() returns a double value, if appropriate
static String	formatKeyword(String template) returns a string which is guaranteed to be a legal FITS keyword.
int	intValue() returns an integer value, if appropriate.
String	key() returns a string containing the keyword for this card
String	stringValue() returns the value of the card as a string.
String	toString() returns the raw bytes of the card converted to a string and with trailing white space removed.
Object	value() returns an object representing the value field.

Methods inherited from class java.lang.Object

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

Field Detail

LENGTH

public static final int LENGTH

the number of bytes in a card = 80

See Also:

Constant Field Values

KEY_LENGTH

public static final int KEY_LENGTH

the maximum number of bytes in a keyword = 8

See Also:

Constant Field Values

CARDS_PER_BLOCK

public static final int CARDS_PER_BLOCK

the number of cards in a FITS block = 2880/80

See Also:

Constant Field Values

PADDING

public static final byte[] PADDING

the value to use for padding out an incomplete block (80 ASCII spaces)

Constructor Detail

FitsCard

public FitsCard(byte[] data)

Create a new card initialized with the given data. The values are copied from the array, so the caller may reuse the array.

Parameters:

data - an array of at least 80 bytes

Throws:

ArrayIndexOutOfBoundsException - if the byte array does not have at least 80 bytes in it.

FitsCard

public FitsCard(byte[] data,
                int offset)

Create a new card from the bytes in an array, starting at the given offset into the array.

Parameters:

data - an array of bytes to use for the card data.

offset - the offset into the array at which to start reading data. an offset of "0" means read from the beginning of the array

Throws:

ArrayIndexOutOfBoundsException - if the data array does not contain enough bytes.

FitsCard

public FitsCard(String key)

Create a card by specifying only its keyword. The card will have no value and a blank comment field.

Parameters:

key - the keyword for this card.

FitsCard

public FitsCard(String key,
                String comment)

create a new card which has no value field. Use this constructor for things like HISTORY and COMMENT cards.

Parameters:

key - the keyword for the card

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                String value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for string-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                boolean value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for boolean-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                Boolean value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for boolean-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                int value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for numberical-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                long value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for numberical-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                float value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for numberical-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                double value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for numberical-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

FitsCard

public FitsCard(String key,
                Number value,
                String comment)

construct a card by specifying it's keyword, value and comment. Use this constructor for numberical-valued cards. This method ensures the resulting card will have proper format, possibly truncating values.

Parameters:

key - the keyword for the card

value - the value of the keyword

comment - the comment field for this card.

Method Detail

data

public byte[] data()

returns the raw 80 bytes of data for this card. Note, this returns the actual internal array and not a copy, so it is usually a bad idea to modify the contents of the returned array.

Returns:

the 80 byte array representing this card.

key

public String key()

returns a string containing the keyword for this card

Returns:

the keyword for this card.

value

public Object value()
             throws eap.fits.FitsCardException

returns an object representing the value field. This object may be Boolean, String, Integer, Double, or null if the keyword has no value. Caling this method forces the card to parse its internal structure.

Returns:

the value field of the card or null if the card has no value.

Throws:

FitsCardException - if the raw data are not properly formatted

intValue

public int intValue()
             throws eap.fits.FitsCardException

returns an integer value, if appropriate. If the card contains a floating point number it will be clipped to an integer.

Returns:

the card value clipped to an integer.

Throws:

ClassCastException - if the card does not have a numerical value

NullPointerException - if the card has no value

eap.fits.FitsCardException

doubleValue

public double doubleValue()
                   throws eap.fits.FitsCardException

returns a double value, if appropriate

Returns:

the value field of the card

Throws:

ClassCastException - if the card does not have a numerical value

NullPointerException - if the card has no value

eap.fits.FitsCardException

stringValue

public String stringValue()
                   throws eap.fits.FitsCardException

returns the value of the card as a string. If the value is not actually a string, then the toString() method of the value will be returned. Note that this may be different from the literal value in the raw data - particularly for boolean values.

Throws:

FitsCardException - if the raw data are not properly formatted

comment

public String comment()
               throws eap.fits.FitsCardException

returns the commment field. Calling this method forces the card to parse its internal structure.

Returns:

the comment field of the card.

Throws:

FitsCardException - if the raw data are not properly formatted.

toString

public String toString()

returns the raw bytes of the card converted to a string and with trailing white space removed.

formatKeyword

public static String formatKeyword(String template)

returns a string which is guaranteed to be a legal FITS keyword. Lower case is converted to upper case, white space is trimmed, illegal characters are removed and the string length is truncated to 8 characters or less.

Parameters:

template - the intended keyword

Returns:

a properly formatted FITS keyword as close as possible to the template.