| Up: GEOS SDK TechDocs | Up | Prev: FileTruncate() ... | Next: FoamDBAddFieldToRecord() ...

FloatFloatToAscii()

word	FloatFloatToAscii( /* returns # of chars in ASCII string */
        FFA_stackFrame 		*stackFrame, 
        char 		*resultString,
        FloatNum 		*number);

This routine converts a floating point number to an ASCII string. It uses a complicated data structure, FFA_stackFrame . To convert floating point numbers to ASCII without filling in this structure, use the FloatFloatToAscii_StdFormat() routine instead. Unless a special flag is passed, this routine will convert the top number of the floating point stack and pop it. FloatFloatToAscii() takes the following arguments:

stackFrame
This is an FFA_stackFrame structure. This structure contains a structure of parameters to FloatFloatToAscii() ; also, the routine will return some information in this structure. The structure is discussed in detail below.
resultString
Pointer to a buffer which will hold the generated ASCII string. This buffer must be either FLOAT_TO_ASCII_NORMAL_BUF_LEN or FLOAT_TO_ASCII_HUGE_BUF_LEN bytes, depending on the type of number (see below).
number
Specifies the format of the floating number. If it is FFAF_DONT_USE_SCIENTIFIC then the buffer resultString must be FLOAT_TO_ASCII_HUGE_BUF_LEN bytes long; otherwise, it must be FLOAT_TO_ASCII_NORMAL_BUF_LEN bytes.

If you pass the FFAF_FROM_ADDR flag, then instead of converting the number at the head of the floating-point stack, the routine will convert this number.

The routine explicitly returns the number of characters in the generated string, not counting the null terminator. It will return zero if an error occurred.

Structures: 

typedef union {
	FloatFloatToAsciiData  	 				FFA_float;
        FloatFloatToDateTimeData				FFA_dateTime;
} FFA_stackFrame; 
        
        typedef struct {
        	FloatFloatToAsciiParams FFA_params;
        	word                    FFA_startNumber;
        	word                    FFA_decimalPoint;
        	word                    FFA_endNumber;
        	word                    FFA_numChars;
        	word                    FFA_startExponent;
        	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;

If you're passing a FloatFloatToAsciiData structure, you must fill in the FFA_params field. When FloatFloatToAscii() returns, some of the other fields will have been filled in with potentially useful information:

FFA_startNumber
This is an offset into the returned string, pointing to the start of the numeric characters.
FFA_decimalPoint
This is an offset into the returned string, pointing to the decimal point. If no decimal point appears in the string, this field will be zero.
FFA_endNumber
This is an offset into the returned string, pointing to the end of the numeric characters.
FFA_numChars
This is the number of characters in the returned string, or zero if there was an error. This is the same as FloatFloatToAscii()'s return value.
FFA_startExponent
This is an offset into the returned string, pointing to the "E" character. If there is no such character in the string, this field will be zero.
The other FloatFloatToAsciiData fields are internal.
        typedef struct {
        	FloatFloatToAsciiFormatFlags 						formatFlags;
        	byte    						decimalOffset;
        	byte    						totalDigits;
        	byte    						decimalLimit;
        	char    						preNegative[SIGN_STR_LEN+1];
        	char    						postNegative[SIGN_STR_LEN+1];
        	char    						prePositive[SIGN_STR_LEN+1];
        	char    						postPositive[SIGN_STR_LEN+1];
        	char    						header[PAD_STR_LEN+1];
        	char    						trailer[PAD_STR_LEN+1];
        	byte    						FFTAP_unused;
        } FloatFloatToAsciiParams;

The FloatFloatToAsciiParams structure determines how FloatFloatToAscii() should format its generated string. It contains the following fields:

formatFlags
A FloatFloatToAsciiFormatFlags structure containing flags used to fine-tune the formatting.
decimalOffset
The number of decimal places to offset the decimal point. E.g. an offset of -6 will display numbers in terms of millions.
totalDigits
Maximum number of digits. This is normally MAX_DIGITS_FOR_NORMAL_NUMBERS. If you're using scientific notation, then this is probably MAX_DIGITS_FOR_HUGE_NUMBERS.
decimalLimit
Maximum number of decimal digits; the number will be rounded to meet this limit.
preNegative
The characters which precede a negative number. The string should be null-terminated. Thypical values are "-" and "(".
postNegative
The characters used to terminate a negative number. The string should be null-terminated. Typical values include the empty string and ")".
prePositive
The characters used to precede a postive number. The string should be null-terminated. Typical values include the null string and "+".
postPositive
The character used to terminate a positive number. The string is expected to be null terminated. Typically, this is the empty string.
header
The characters that precede the number. This string should be null terminated. This string might appear before or after the sign character, depending on whether the FFAF_SIGN_CHAR_TO_FOLLOW_HEADER flag is set. Typically, this string is empty; if it isn't, then set the FFAF_HEADER_PRESENT flag.
trailer
The characters that follow the number. This string should be null terminated. Whether this string follows or precedes the sign is determined by the FFAF_SIGN_CHAR_TO_PRECEDE_TRAILER flag. Typically, this string is empty; if it isn't, then set the FFAF_TRAILER_PRESENT flag.
        typedef WordFlags FloatFloatToAsciiFormatFlags;
        #define FFAF_FLOAT_RESERVED 									0x8000
        #define FFAF_FROM_ADDR 									0x4000
        #define FFAF_DONT_USE_SCIENTIFIC 									0x0200
        #define FFAF_SCIENTIFIC 									0x0100
        #define FFAF_PERCENT 									0x0080
        #define FFAF_USE_COMMAS 									0x0040
        #define FFAF_NO_TRAIL_ZEROS 									0x0020
        #define FFAF_NO_LEAD_ZERO 									0x0010
        #define FFAF_HEADER_PRESENT 									0x0008
        #define FFAF_TRAILER_PRESENT 									0x0004
        #define FFAF_SIGN_CHAR_TO_FOLLOW_HEADER 									0x0002
        #define FFAF_SIGN_CHAR_TO_PRECEDE_TRAILER									0x0001

The FloatFloatToAsciiFormatFlags field contains the following flags:

FFAF_FLOAT_RESERVED
This flag must be zero.
FFAF_FROM_ADDR
Normally, FloatFloatToAscii() will convert the number at the top of the floating point stack. By passing this flag, you ask that the routine instead convert the number pointed to by its number argument.
FFAF_DONT_USE_SCIENTIFIC
If set, this flag discourages the use of scientific notation. Zero padding will be used if possible.
FFAF_SCIENTIFIC
Set this flag to enforce scientific notation.
FFAF_PERCENT
Set this flag to display number as a percentage.
FFAF_USE_COMMAS
Set this flag to use comma separators.
FFAF_NO_TRAIL_ZEROS
Set this flag to pad the number with trailing zeros.
FFAF_NO_LEAD_ZERO
Set this flag to make a leading zero appear before fractional values. E.g. ".53" would appear as "0.53" instead.
FFAF_HEADER_PRESENT
If there is no header string, leave this flag clear--this results in a speed optimization.
FFAF_TRAILER_PRESENT
If there is no trailer string, leave this flag clear--this results in a speed optimization.
FFAF_SIGN_CHAR_TO_FOLLOW_HEADER
This flag determines the relative positions of the sign and header strings.
FFAF_SIGN_CHAR_TO_PRECEDE_TRAILER
This flag determines the relative positions of the sign and trailer strings.
        typedef struct {
        	FloatFloatToDateTimeParams      FFA_dateTimeParams;
	} FloatFloatToDateTimeData;
        
        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;

The FloatFloatToDateTime structure is used to pass and return information for the formatting of date and time strings.

FFA_dateTimeFlags
This FloatFloatToDateTimeFlags field fine-tunes the way in which to format the date string.
FFA_year
FFA_month
FFA_day
FFA_weekday
FFA_hours
FFA_minutes
FFA_seconds
These fields will be used to return the various parts of the date/time.
        typedef WordFlags FloatFloatToDateTimeFlags;
        #define FFDT_DATE_TIME_OP 				0x8000
        #define FFDT_FROM_ADDR 				0x4000
        #define FFDT_FORMAT 				0x3fff

The FloatFloatToDateTimeFlags field determines how the date/time should be formated.

FFDTT_DATE_TIME_OP
Set this flag.
FFDTT_FROM_ADDR
Set this flag to convert the number passed as the number argument instead of the top number on the floating point stack.
FFDTT_FORMAT
This is a DateTimeFormat value.

See Also: FloatFloatToAscii_StdFormat().

FloatFloatToAscii_StdFormat()

word FloatFloatToAscii_StdFormat(
        char 					*string, 
        FloatNum 					*number,
        FloatFloatToAsciiFormatFlags 					format,
        word 					numDigits, 
        word 					numFractionalDigits)

This routine formats a floating point number as an ASCII string. It is similar in purpose to FloatFloatToAscii() . However, this routine does not require the use of the daunting FFA_stackFrame data structure. It has the following arguments:

string
Buffer to hold the converted string. This buffer must be at least FLOAT_TO_ASCII_NORMAL_BUF_LEN or FLOAT_TO_ASCII_HUGE_BUF_LEN.
number
If you pass FFAF_FROM_ADDR, this should be a pointer to a number to convert; otherwise the top number on the floating point stack will be popped and converted.
format
This is a flags field of type FloatFloatToAsciiFormatFlags . This data type is discussed under FloatFloatToAscii() . The following flags are permitted: FFAF_FROM_ADDR, FFAF_SCIENTIFIC, FFAFF_PERCENT, FFAF_USE_COMMAS, FFAF_NO_TRAIL_ZEROS.
numDigits
The number of significant digits desired.
numFranctionalDigits
The number of digits which may follow the decimal sign.

The routine returns the number of characters in the resulting string, or zero if there was an error.

See Also: FloatFloatToAscii().

| Up: GEOS SDK TechDocs | Up | Prev: FileTruncate() ... | Next: FoamDBAddFieldToRecord() ...