Type Conversions

Engines generated by AFC perform all internal computations using a single, user-defined numeric type. At the moment, this can be double, BigDecimal, long, or scaled long. The engine therefore must

• convert all input values obtained from your input methods to its internal type, and
• convert all output values from its internal type to the return type of your output methods.

To convert other value types to those AFC can handle, you should wrap your interfaces to add custom conversion logic. You might also want to do this to keep your interfaces clean of dependencies on AFC specifics (such as the ScaledLong and Milliseconds annotations).

Input Conversions

Here’s the set of supported input types (the ScaledLong annotation works with all supported scales, not just 7, of course):

// Native types
byte getByte();
short getShort();
int getInt();
long getLong();
@ScaledLong( 7 ) long getLong7();
double getDouble();
float getFloat();
boolean getBoolean();

// Boxed native types
Byte getBoxedByte();
Short getBoxedShort();
Integer getBoxedInt();
Long getBoxedLong();
@ScaledLong( 7 ) Long getBoxedLong7();
Double getBoxedDouble();
Float getBoxedFloat();
Boolean getBoxedBoolean();

// Big types
BigDecimal getBigDecimal();
BigInteger getBigInteger();

// Date is converted to a number as in Excel; can also use long value as returned by
// Date.getTime().
// These values are time-zone adjusted.
Date getDate();
@MillisecondsSinceUTC1970 long getDateMs();
@MillisecondsSinceUTC1970 Long getBoxedDateMs();

// With @Milliseconds annotation, long is treated as a time duration in milliseconds for an
// Excel time cell.
// These values or *not* time-zone adjusted.
@Milliseconds long getTime();
@Milliseconds Long getBoxedTime();

// String cannot be used for numbers, but for string-valued cells
String getString();

The rules are:

• Values are silently truncated or reduced in precision to fit the target type (like Java does).
• Dates are converted to local time using the time zone as specified in the factory configuration.
• Pure times must not be passed a java.util.Date – here’s why.
• null values are silently converted to zero (unlike Java).

Warning

The latter rule is different from Excel, which converts empty cells situatively. An empty cell is, for instance, ignored by PRODUCT and string concatenation in Excel. As of this version of AFC, a PRODUCT involving an input value which is null returns zero, not the product of all non-null numbers.
This may change to be more compatible with Excel in a future release of AFC.

Output Conversions

The set of supported output types is the same as that for input types (again, the ScaledLong annotation works with all supported scales, not just 7):

// Native types
byte calcByte();
short calcShort();
int calcInt();
long calcLong();
@ScaledLong( 5 ) long calcLong5();
double calcDouble();
float calcFloat();
boolean calcBoolean();

// Boxed native types
Byte calcBoxedByte();
Short calcBoxedShort();
Integer calcBoxedInt();
Long calcBoxedLong();
@ScaledLong( 5 ) Long calcBoxedLong5();
Double calcBoxedDouble();
Float calcBoxedFloat();
Boolean calcBoxedBoolean();

// Big types
BigDecimal calcBigDecimal();
BigInteger calcBigInteger();

// Date is converted from a number as in Excel; can also use long value as in "new
// Date(long)".
// These values are time-zone adjusted.
Date calcDate();
@MillisecondsSinceUTC1970 long calcDateMs();
@MillisecondsSinceUTC1970 Long calcBoxedDateMs();

// With @Milliseconds annotation, long is converted from an Excel time cell to a time duration
// in milliseconds.
// These values are *not* time-zone adjusted.
@Milliseconds long calcTime();
@Milliseconds Long calcBoxedTime();

// Strings are converted according to Java's settings
String calcString();

The rules are similar, too:

• Values are silently truncated or reduced in precision to fit the target type (like Java does).
• Dates are converted from local time using the time zone as specified in the factory configuration.
• Pure times must not be returned as java.util.Date – here’s why.
• AFC never returns null.

Warning

The latter rule implies that, even if you map an output method to an empty spreadsheet cell, or to one that is mapped to an input method returning null, AFC will return zero, not null.
This may change in a future release of AFC.