The Math Library: 2 Conversions to Other Types

In many cases, FP numbers will need to be converted to different types for use in different parts of an application. For example, floating point numbers may be involved in a complex function that returns an integer. FP numbers may also need to appear to the user as ASCII text.

Converting Into Other Floats

There are several routines which convert GEOS FP numbers into other float formats, compatible with the C types float and double . Typically in C, this conversion is accomplished by casting the FP numbers into the other type. It is therefore done automatically for you.

If you are working in Assembly or you wish to directly pass floats or doubles to C stubs, consult Direct FP Operations .

Converting ASCII to FP Numbers

 FloatAsciiToFloat()

FloatAsciiToFloat() converts a number represented in an ASCII text format into a FP number. The routine recognizes two flags:

FAF_PUSH_RESULT
Pushes the result onto the FP stack.
FAF_STORE_NUMBER
Stores the result in a specified address.

The routine must also be passed a pointer to the string to convert, the number of characters in the string to convert (starting at the address) and the buffer to store the FP number if passing FAF_STORE_NUMBER.

Converting FP Numbers to ASCII

 FloatFloatToAscii(),  FloatFloatToAscii_StdFormat(),  FloatFloatIEEE64ToAscii_StdFormat()

FloatFloatToAscii() converts an FP number into ASCII text format. The routine must be passed a stack frame, which may be set up by declaring a local variable of type FFA_stackFrame and moving data into the appropriate fields. You should also pass the routine a pointer to a buffer to store the resultant string. This buffer must be declared with a length of either:

FLOAT_FLOAT_TO_ASCII_NORMAL_BUF_LEN: FLOAT_FLOAT_TO_ASCII_HUGE_BUF_LEN

The FFA_stackFrame is a union of two structures: FloatFloatAsciiData or FloatFloatToDateTimeData . You will want to use the FloatFloatToAsciiData structure in most cases; FloatFloatToAsciiDateTimeData is used to format a FP number (representing a date and time) into a date-time format passed in the structure. The routine checks a bit in the structure to see which structure is being passed.

Normal Conversions

TheFloatFloatToAsciiData structure is used most often in formatting FP numbers into ASCII. The structure is rather large and cumbersome to set up. You may wish to use the routine FloatFloatToAscii_StdFormat() which sets up many of these entries automatically. ( FloatFloatToAsciiData Structure lists the entries of the FloatFloatToAsciiData structure.)

Code Display D-4 FloatFloatToAsciiData Structure

typedef struct {

/*
 * FFA_params stores the entries that the caller must set up.
 */
	FloatFloatToAsciiParams			FFA_params;

/*
 * These entries store information returned by FloatFloatToAscii() that may be 
 * examined.
 */
	word			FFA_startNumber;
	word			FFA_decimalPoint;
	word			FFA_endNumber;
	word			FFA_numChars;
	word			FFA_startExponent;

/*
 * The rest of the entries are for internal use only.
 */
	word			FFA_bufSize;
	word			FFA_saveDI;
	word			FFA_numSign;
	byte			FFA_startSigCount;
	byte			FFA_sigCount;
	byte			FFA_noMoreSigInfo;
	byte			FFA_startDecCount;
	byte			FFA_decCount;
	word			FFA_decExponent;
	word			FFA_curExponent;
	byte			FFA_useCommas;
	byte			FFA_charsToComma;
	char			FFA_commaChar;
	char			FFA_decimalChar;
} FloatFloatToAsciiData;

FFA_params is a structure that stores the following entries of its own:

formatFlags: Flags specifying the look and feel of the ASCII text format (see below for allowed flags).
decimalOffset: Integer which specifies the number of decimal places to shift the output. For example, to display a number in terms of millions, a decimalOffset of -6 shifts the decimal point six places to the left; to display in terms of tenths would require a decimalOffset of 1.
totalDigits: Integer which specifies the maximum number of decimal places (integer and decimal portions) that the FP number may exhibit. The ASCII string is truncated if the length of the string is greater than this number.
decimalLimit: Integer which specifies the maximum number of digits to the right of the decimal point. For example a decimalLimit of 2 would print out 123.456789 as 123.46.
preNegative: Characters used to precede a negative number, in the format of a null terminated text string.
postNegative: Characters used to follow a negative number, in the format of a null terminated text string.
prePositive: Characters used to precede a positive number, in the format of a null terminated text string.
postPositive: Characters used to follow a positive number, in the format of a null terminated text string.
header: Characters used to precede the number, in the format of a null terminated text string. For example, a typical header for a currency format might be "$".
trailer: Characters used to follow a FP number, in the format of a null terminated text string.

The formatFlags record is a record of type FloatFloatToAsciiFormatFlags and defines the format of the ASCII output. Set the appropriate flags to get the desired output.

FFAF_FROM_ADDR
Set if routine should take the FP number from a specified address, rather than the FP stack. This pointer (*number) should be passed to FloatFloatToAscii() if this flag is set.
FFAF_DONT_USE_SCIENTIFIC
Set if the result should not be expressed in scientific notation under any condition. If this is set, the number will always be formatted in fixed format.
FFAF_SCIENTIFIC
Set if the result should be expressed in scientific notation even if the number can be expressed in fixed point format. For example, the number `2' will be expressed as "2 x 10 0 ."
FFAF_PERCENT
Set if the result should be expressed as a percentage.
FFAF_USE_COMMAS
Set if the result should use commas to separate thousands.
FFAF_NO_TRAIL_ZEROS
Set if extraneous zeros to the right of the decimal point should be ignored. For example, "123.67000000" will be reduced to "123.67."
FFAF_NO_LEAD_ZEROS
Set to ignore the lead zero for a number less than one. That is, "0.123" is reduced to ".123."
FFAF_HEADER_PRESENT
Set if a header is present; this speeds up conversion.
FFAF_TRAILER_PRESENT
Set if a trailer is present; this speeds up conversion.
FFAF_SIGN_CHAR_TO_FOLLOW_HEADER
Set if sign character(s) should follow the header.
FFAF_SIGN_CHAR_TO_PRECEDE_TRAILER
Set if sign character(s) should precede the trailer.

The rest of the entries in FloatFloatToAsciiData store information filled in by FloatFloatToAscii() . These entries are described below:

FFA_startNumber stores the offset to the start of numeric characters in the ASCII buffer.
FFA_decimalPoint stores the offset to the decimal point character or zero if no decimal point is present.
FFA_endNumber stores the offset to the end of the numeric characters in the ASCII buffer.
FFA_numChars stores the total number of characters in the ASCII buffer (excluding the null terminator). This entry is set to zero if an error is encountered.
FFA_startExponent stores the offset to the "E" character in the ASCII buffer or zero if no exponent is present. Applications can check this to see if the number was expressed in scientific notation using the `E' format.

Date-Time Conversions

FFA_stackFrame may contain FloatFloatToAsciiDateTimeData if FloatFloatToAscii() is being used to convert a FP number into a date-time format. In that case FFA_stackFrame contains the structure FloatFloatToDateTimeData instead of FloatFloatToAsciiData . (FFA_stackFrame is a union.)

FloatFloatToDateTimeData contains one entry, FFA_dateTimeParams . This structure contains several flags which specify how the date-time should be formatted and a number of entries which break down the date-time into its respective parts (year, month, day etc.) If none of these entries are filled in, the date-time is taken from the top of the FP stack.

Date-times are represented by FP numbers in GEOS. The integer portion represents dates as integers counted from Jan 1, 1900, which is designated as 1. The highest date allowed is 73049 (December 31, 2099). The fractional portion represents a fraction of the day between midnight (0.000000) and 11:59:59 p.m. (0.999988). This fractional value is derived from the hour, minute and second of the day.

Code Display D-5 DateTime Parameters

typedef struct {
	FloatFloatToDateTimeFlags				FFA_dateTimeFlags;
	word				FFA_year;
	byte				FFA_month;
	byte				FFA_day;
	byte				FFA_weekday;
	byte				FFA_hours;
	byte				FFA_minutes;
	byte				FFA_seconds;
} FloatFloatToDateTimeParams;

/*
 *	FloatFloatToDateTimeFlags record
 */

typedef WordFlags FloatFloatToDateTimeFlags;
#define		FFDT_DATE_TIME_OP			0x8000
#define		FFDT_FROM_ADDR			0x4000
#define		FFDT_FORMAT			0x3fff

The flag FFDT_DATE_TIME_OP is set to notify the FloatFloatToAscii() routine that this operation is a date-time format, not a normal float to ASCII conversion. This flag must be set if you want to convert the FP number into a date-time format using FloatFloatToAscii() .

FFDT_FROM_ADDR is set if the date-time FP number should not be taken from the FP stack (or passed directly in the FloatFloatToDateTimeParams structure) but should instead be taken from the address passed in FloatFloatToAscii() .

FFDT_FORMAT stores the DateTimeFormat that the routine will use to format the number into a date-time string.

If the date-time is directly passed in, and not taken from an FP date-time number either at a passed address or the top of an FP stack, FloatFloatToAscii() looks at the other passed parameters.

FFA_year specifies the year. The value must be between 1900 and 2099. This is not a one-based year, as it is when presented as a date-time number.

FFA_month is the month of the year, a value between 1 and 12.

FFA_day is the day of a month, a value between 1 and 31.

FFA_hour specifies the hour of the day, a value between 0 and 23. Zero specifies midnight.

FFA_minutes specifies the minute of the hour, a value between 0 and 59.

FFA_seconds specifies the second of the minute, a value between 0 and 59.

Using Standard Formats

FloatFloatToAscii_StdFormat() uses a pre-set stack frame, eliminating the need to set up the variables of the FloatFloatToAsciiData structure manually. The only flags recognized are FFAF_FROM_ADDR, FFAF_SCIENTIFIC, FFAF_PERCENT, FFAF_USE_COMMAS, and FFAF_NO_TRAIL_ZEROS. The developer must pass the number of total digits and the number of decimal digits desired. If the flag FFAF_FROM_ADDR is used, a pointer to a FP number (not on the FP stack) must also be passed.

The standard format sets the following elements of the stack frame to zero: decimalOffset, header, trailer, postNegative, prePositive , and postPositive . The structure element preNegative is set to the minus sign ("-").

FloatFloatIEEE64ToAscii_StdFormat() performs the same operation as FloatFloatToAscii_StdFormat() except that the FP number is passed (in 64 bit format) and is not taken from the stack. The entire FP number (not just a pointer to it) must be passed. All criteria for FloatFloatToAscii_StdFormat() applies to this routine, except that the flag FFAF_FROM_ADDR is not used.

Date and Time Routines

 FloatGetDateNumber(),  FloatDateNumberGetYear(),  FloatDateNumberGetMonthAndDay(),  FloatDateNumberGetWeekday(),  FloatGetTimeNumber(),  FloatTimeNumberGetHour(),  FloatTimeNumberGetMinutes(),  FloatTimeNumberGetSeconds()

FloatGetDateNumber() , when passed the month, day, and year, converts the data into an FP "date number" representation. This format represents dates as integers counted from Jan 1, 1900, which is designated as 1. The highest date allowed is 73050 (December 31, 2099).

FloatDateNumberGetYear(), FloatDateNumberGetMonthAndDay() andFloatDateNumberGetWeekday() all return the appropriate data, either the year, month and day, or weekday, given an FP "date number" as defined above. All data are returned as integers, not as FP numbers, and the original FP "date number" is popped off of the stack. Years are returned as integers between 1900 and 2099. Month and Days are returned as integers between 1 and 12, and 1 and 31, respectively. Weekdays are returned as integers between 1 and 7, where 1 is Sunday, 2 is Monday, etc.

FloatGetTimeNumber() when passed hours, minutes, and seconds returns an FP decimal representation between midnight (0.000000) and 11:59:59 p.m. (0.999988).

FloatTimeNumberGetHour(), FloatTimeNumberGetMinutes() andFloatTimeNumberGetSeconds() return the appropriate data given an FP "time number" as defined above. The original FP "time number" is popped off of the stack.

Note that both "date numbers" and "time numbers" can be added to specify a specific point in time. For example, 73050.999988 would specify December 31, 2099, 11:59:59. Since these formats are in FP format, they can be operated on with all standard functions in the FP library.

Miscellaneous Date Time Routines

 FloatGetDaysInMonth(),  FloatGetNumDigitsInIntegerPart(),  FloatFormatNumber()

FloatGetDaysInMonth() returns the total number of days in a specific month, for a specific year. The routine must be passed the appropriate month and year.

FloatGetNumDigitsInIntegerPart() returns the number of digits in the integer portion of an FP number. Numbers between zero and one will return one as the number of digits.

FloatStringGetDateNumber(), FloatStringGetTimeNumber()

GEOS SDK TechDocs |

1 Basic Math Functions | Next:

3 Float Formats