Package nom.tam.util

Class FlexFormat

java.lang.Object

nom.tam.util.FlexFormat

public class FlexFormat
extends Object

Formatting number values for use in FITS headers.

Since:

1.16

Author:

Attila Kovacs

Field Summary

Fields

Modifier and Type	Field	Description
static final int	AUTO_PRECISION	Constant to specify the precision (number of decimal places shown) should be the natural precision of the number type, or reduced at most to DOUBLE_DECIMALS as necessary to fit in the alotted space.
static final int	DOUBLE_DECIMALS	The maximum number of decimal places to show (after the leading figure) for double-precision (64-bit) values.
static final int	FLOAT_DECIMALS	The maximum number of decimal places to show (after the leading figure) for single-precision (32-bit) values.
static final int	MIN_BIGINT_EFORM_DECIMALS	The minimum number of decimal places to show (after the leading figure) for big-decimal values. 64-bit longs are in the +-1E19 range, so they provide 18 decimals after the leading figure.

Constructor Summary

Constructors

Constructor	Description
FlexFormat()

Method Summary

Modifier and Type	Method	Description
FlexFormat	autoPrecision()	Selects flexible precision formatting of floating point values.
final FlexFormat	forCard(HeaderCard card)	Sets the number of characters that this formatter can use to print number values to the space available for the value field in the specified header card.
String	format(Number value)	Returns a string representation of a decimal number, in the available space, using either fixed decimal format or exponential notitation.
final int	getPrecision()	Returns the maximum number of decimal places that will be shown when formatting floating point values in exponential form, or AUTO_PRECISION if either fixed or exponential form may be used with up to the native precision of the value, or whatever precision can be shown in the space available.
final int	getWidth()	Returns the number of characters that this formatter can use to print number values
FlexFormat	setPrecision(int nDecimals)	Sets the maximum number of decimal places to show after the leading figure (i.e. fractional digits in exponential format).
FlexFormat	setWidth(int nChars)	Sets the number of characters that this formatter can use to print number values.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

AUTO_PRECISION

public static final int AUTO_PRECISION

Constant to specify the precision (number of decimal places shown) should be the natural precision of the number type, or reduced at most to DOUBLE_DECIMALS as necessary to fit in the alotted space.

See Also:

• Constant Field Values

DOUBLE_DECIMALS

public static final int DOUBLE_DECIMALS

The maximum number of decimal places to show (after the leading figure) for double-precision (64-bit) values.

See Also:

• Constant Field Values

FLOAT_DECIMALS

public static final int FLOAT_DECIMALS

The maximum number of decimal places to show (after the leading figure) for single-precision (32-bit) values.

See Also:

• Constant Field Values

MIN_BIGINT_EFORM_DECIMALS

public static final int MIN_BIGINT_EFORM_DECIMALS

The minimum number of decimal places to show (after the leading figure) for big-decimal values. 64-bit longs are in the +-1E19 range, so they provide 18 decimals after the leading figure. We want big integer to provideat least as many decimal places as a long, when in exponential form...

See Also:

• Constant Field Values

Constructor Details

FlexFormat

public FlexFormat()

Method Details

setPrecision

public FlexFormat setPrecision(int nDecimals)

Sets the maximum number of decimal places to show after the leading figure (i.e. fractional digits in exponential format). If the value has more precision than this value it will be rounded to the specified decimal place. The special value AUTO_PRECISION can be used to display as many of the available decimal places as can fit into the space that is available (see setWidth(int).

Parameters:

nDecimals - the requested new number of decimal places to show after the leading figure, or AUTO_PRECISION. If an explicit value is set, all decimal values will be printed in exponential format with up to that many fractional digits showing before the exponent symbol.

Returns:

itself

See Also:

• autoPrecision()
• getPrecision()
• setWidth(int)
• format(Number)

autoPrecision

public FlexFormat autoPrecision()

Selects flexible precision formatting of floating point values. The values will be printed either in fixed format or exponential format, with up to the number of decimal places supported by the underlying value. For BigDecimal and BigInteger types, the precision may be reduced at most down to DOUBLE_DECIMALS to make it fit in the available space.

Returns:

itself

See Also:

• setPrecision(int)
• getPrecision()
• setWidth(int)
• format(Number)

getPrecision

public final int getPrecision()

Returns the maximum number of decimal places that will be shown when formatting floating point values in exponential form, or AUTO_PRECISION if either fixed or exponential form may be used with up to the native precision of the value, or whatever precision can be shown in the space available.

Returns:

the maximum number of decimal places that will be shown when formatting floating point values, or AUTO_PRECISION.

See Also:

• setPrecision(int)
• autoPrecision()
• setWidth(int)

setWidth

public FlexFormat setWidth(int nChars)

Sets the number of characters that this formatter can use to print number values. Subsequent calls to format(Number) will guarantee to return only values that are shorter or equals to the specified width, or else throw an exception.

Parameters:

nChars - the new maximum length for formatted values.

Returns:

itself

See Also:

• getWidth()
• forCard(HeaderCard)
• setPrecision(int)
• format(Number)

forCard

public final FlexFormat forCard(HeaderCard card)

Sets the number of characters that this formatter can use to print number values to the space available for the value field in the specified header card. It is essentially a shorthand for setWidth(card.spaceForValue()).

Parameters:

card - the header card in which the formatted number values must fit.

Returns:

itself

getWidth

public final int getWidth()

Returns the number of characters that this formatter can use to print number values

Returns:

the maximum length for formatted values.

format

public String format(Number value)
              throws LongValueException

Returns a string representation of a decimal number, in the available space, using either fixed decimal format or exponential notitation. It will use the notation that either gets closer to the required fixed precision while filling the available space, or if both notations can fit it will return the more compact one. If neither notation can be accomodated in the space available, then an exception is thrown.

Parameters:

value - the decimal value to print

Returns:

the string representing the value, or an empty string if the value was null.

Throws:

LongValueException - if the decimal value cannot be represented in the alotted space with any precision

See Also:

• setPrecision(int)
• setWidth(int)
• forCard(HeaderCard)