STR

Synopsis

HELP:   String representation of an floating point number
TYPE:   OBJECT
SYNTAX: STR(CHRSET=NONE/SYSTEM/ASCII/UCS1/UTF8/EBCDIC/UCS2BE/UTF16BE/UCS2LE/UTF16LE/UCS4BE/UTF32BE/UCS4LE/UTF32LE/LOCAL,SIGN=IFNEGATIVE/SPACEIFPOSITIVE/PLUSIFPOSITIVE,INTDIGITS=num,SEPARATOR=SYSTEM/PERIOD/COMMA/APOSTROPHE,FRACDIGITS=num,ROUNDING[=AWAYFROMZERO/NEAREST/TOWARDZERO/ERROR],FIXEDLENGTH=num,PADDING=NONE/RIGHT/LEFT,PADCHAR='bin'/BINARY-ZERO/ASCII-BLANK/EBCDIC-BLANK/UTF08-BLANK/UTF16BE-BLANK/UTF16LE-BLANK/UTF32BE-BLANK/UTF32LE-BLANK,VALUE='str',NULLTERM,USEEID)

Description

Writes a string representation of a real number, taking an FL5-internal neutral real number representation (produced by a reading counterpart) as input. The resulting string is in decimal format.

By default, the string is written with the minimum number of characters possible to represent the number's value. If the INTDIGITS parameter is set to a non-zero value, the string will always contain exactly the specified number of digits in the integral portion of the number string, even if the integer part could be represented with fewer digits. The integer portion is padded with leading zeros as necessary. If the number to convert requires more integral digits to be representable as string, an error occurs.

Accordingly, the FRACDIGITS parameter sets the length of the fractional portion to a fixed value. It is padded with zeros on the right as necessary. If there are more than FRACDIGITS fractional digits in the number to be converted, the remaining digits are cut off.

With SEPARATOR, the character separating intral and fractional part can be set to either period or comma. The default depends on the system's locale (e.g. environment variable LC_NUMERIC on Linux).

With the SIGN parameter, it is possible to specify if and how a sign character for positive and negative numbers is printed, when converting a real number to a decimal string. The following options are available:

If the output string must have a specific length (e.g. to store it in a fixed-length data field), the FIXEDLENGTH field can be set to the desired number of bytes (not characters!). If the number string is too short, the string is padded with whitespace characters on the left, by default.

The PADDING parameter determines on which side the string is padded. It can be padded at the start or end of the string.

With PADCHAR, the padding character can be changed. The default padding character is the space character in the specified CHRSET. If you specify a custom padding character, the value must be a byte sequence of the padding character in the specified target CHRSET. So, for example, if CHRSET=UTF16BE and the integer string is supposed to be padded with "." characters, PADCHAR must be set to the two bytes sequence of the period character in big endian UTF16. Specified in hex notation, this would be x"002E" (note the x before the quotation marks, which is the marker for hexadecimal notation of a sequence of byte values).

The CHRSET parameter determines the character set of the written string. If no character set is specified, the system's default character set is used. All character sets supported by the character conversion module can be used, including multi-byte charsets.

When using the byte interface (fcbconv()) to convert real numbers to strings, you have to make sure that the output buffer you provide is of sufficient size to hold the output string. If the buffer is too short, the return code is FLMRTC_LEN and the output buffer size is set to the minimum number of bytes required, allowing you to provide a larger buffer and retry the conversion.

You can also activate null termination of the string by activating the NULLTERM switch. The output length returned by the byte interface does not include the null termination character.

The parameter VALUE specifies the default value of a real number. This is always in local charset, decimal base and period is the decimal separator. If the the default value is encountered in the data, an empty string is written.

Additionally, you can activate the parameter USEEID (use empty indication). If a float value in the read data is an empty string, it is written out with the default value. With USEEID, an empty string is written instead of default value. If a default write value is also set, empty string is only written, if the float value is equal to default write value and the read float was an empty string.

Arguments