# Class CardFactory

java.lang.Object
uk.ac.starlink.fits.CardFactory

public class CardFactory extends Object
Creates FITS CardImages suitable for writing to a FITS header. Different factory instances are available with variant options for header construction.

Attempts to construct illegal FITS headers will generally provoke RuntimeExceptions.

Since:
  4 Mar 2022
Author:
  Mark Taylor

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static interface`
`CardFactory.Config`
CardFactory configuration.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final CardFactory`
`CLASSIC`
Instance with value trimming, bad char replacement, no HIERARCH.
`static final CardFactory`
`DEFAULT`
Default instance (currently `CLASSIC`).
`static final CardImage`
`END_CARD`
CardImage for terminating header ("END").
`static final CardFactory`
`HIERARCH`
Instance with value trimming, bad char replacement, and HIERARCH.
`static final CardFactory`
`STRICT`
Instance with no value trimming, bad char rejection, no HIERARCH.

## Constructor Summary

Constructors
Constructor
Description
`CardFactory(CardFactory.Config config)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`CardImage`
`createCommentCard(String txt)`
Constructs a COMMENT card with the given comment.
`CardImage`
`createIntegerCard(String key, long value, String comment)`
Constructs a key-value card with integer content.
`CardImage`
`createLiteralCard(String key, String literal, String comment)`
Constructs a key-value card with given literal text for the value part.
`CardImage`
`createLogicalCard(String key, boolean value, String comment)`
Constructs a key-value card with logical content.
`CardImage`
`createPlainCard(String txt)`
Constructs a card containing the given exact text.
`CardImage`
`createRealCard(String key, double value, String comment)`
Constructs a key-value card with floating point content.
`CardImage`
`createStringCard(String key, String value, String comment)`
Constructs a key-value card with string content.
`CardFactory.Config`
`getConfig()`
Returns the configuration state of this factory.
`static String`
`sanitiseAsError(String txt)`
Utility string sanitisation function that throws an IllegalArgumentException if any illegal characters are present.
`static String`
`sanitiseByReplacement(String txt, char replaceChar)`
Utility string sanitisation function that replaces illegal characters by a given char.

### Methods inherited from class Object

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

## Field Details

### CLASSIC

public static final CardFactory CLASSIC
Instance with value trimming, bad char replacement, no HIERARCH.

### HIERARCH

public static final CardFactory HIERARCH
Instance with value trimming, bad char replacement, and HIERARCH.

### STRICT

public static final CardFactory STRICT
Instance with no value trimming, bad char rejection, no HIERARCH.

### DEFAULT

public static final CardFactory DEFAULT
Default instance (currently `CLASSIC`).

### END_CARD

public static final CardImage END_CARD
CardImage for terminating header ("END").

## Constructor Details

### CardFactory

public CardFactory(CardFactory.Config config)
Constructor.

Parameters:
  `config` - factory configuration

## Method Details

### getConfig

public CardFactory.Config getConfig()
Returns the configuration state of this factory.

Returns:
  config object

### createPlainCard

public CardImage createPlainCard(String txt)
Constructs a card containing the given exact text. It is padded with spaces if necessary. No sanitisation or trimming is performed.

Parameters:
  `txt` - literal card content, <=80 characters
Returns:
  new card

### createCommentCard

public CardImage createCommentCard(String txt)
Constructs a COMMENT card with the given comment. The text may be sanitised and trimmed if too long according to policy.

Parameters:
  `txt` - comment text
Returns:
  new card

### createStringCard

public CardImage createStringCard(String key, String value, String comment)
Constructs a key-value card with string content. The value and comment may be sanitised and trimmed if too long according to policy.

Parameters:
  `key` - header keyword
  `value` - header value
  `comment` - comment text, or null
Returns:
  new card

### createIntegerCard

public CardImage createIntegerCard(String key, long value, String comment)
Constructs a key-value card with integer content. The comment may be sanitised and trimmed if too long according to policy.

Parameters:
  `key` - header keyword
  `value` - header value
  `comment` - comment text, or null
Returns:
  new card

### createRealCard

public CardImage createRealCard(String key, double value, String comment)
Constructs a key-value card with floating point content. The comment may be sanitised and trimmed if too long according to policy.

Parameters:
  `key` - header keyword
  `value` - header value
  `comment` - comment text, or null
Returns:
  new card

### createLogicalCard

public CardImage createLogicalCard(String key, boolean value, String comment)
Constructs a key-value card with logical content. The comment may be sanitised and trimmed if too long according to policy.

Parameters:
  `key` - header keyword
  `value` - header value
  `comment` - comment text, or null
Returns:
  new card

### createLiteralCard

public CardImage createLiteralCard(String key, String literal, String comment)
Constructs a key-value card with given literal text for the value part. No additional quoting or escaping is performed on the provided string, but both string and comment may be trimmed in a string-sensitive way according to policy.

The key must contain only legal key characters, and the literal and comment must contain only legal header characters.

Parameters:
  `key` - header keyword
  `literal` - formatted value text
  `comment` - comment text, or null
Returns:
  new card
Throws:
  `IllegalArgumentException` - if inputs are not suitable for FITS

### sanitiseByReplacement

public static String sanitiseByReplacement(String txt, char replaceChar)
Utility string sanitisation function that replaces illegal characters by a given char.

Parameters:
  `txt` - input text
  `replaceChar` - character to replace non-FITS characters
Returns:
  same as `txt`, but with non-FITS characters replaced by `replaceChar`

### sanitiseAsError

public static String sanitiseAsError(String txt)
Utility string sanitisation function that throws an IllegalArgumentException if any illegal characters are present.

Parameters:
  `txt` - input text
Returns:
  input text
Throws:
  `IllegalArgumentException` - if non-FITS characters are present