Str_FmtNbr_32()

Owned by Former user (Deleted)
Last updated: Jul 19, 2021 by WES Admin
6 min read

Converts and formats a 32-bit floating point number into a string.

Files

lib_str.h/lib_str.c

Prototype

          CPU_CHAR  *Str_FmtNbr_32 (CPU_FP32      nbr,
                                    CPU_INT08U    nbr_dig,
                                    CPU_INT08U    nbr_dp,
                                    CPU_CHAR      lead_char,
                                    CPU_BOOLEAN   nul,
                                    CPU_CHAR     *pstr);

Arguments

nbr

Number to format into a string.

nbr_dig

Number of integerdigits to format into the number string.

nbr_dp

Number of decimaldigits to format into the number string.

lead_char

Option to prepend a leading character into the formatted number string:

'\0'

Do not prepend leading character to string.

Printable character

Prepend leading character to string.

Unprintable character

Format invalid string.

nul

Option to NULL-terminate the formatted number string:

DEF_NO

Do not append terminating NULL-character to string.

DEF_YES

Append terminating NULL-character to string.

pstr

Pointer to the string memory buffer to return the formatted number string.

Returned Value

Pointer to formatted number string, if no errors;

Pointer to NULL, otherwise.

Required Configuration

Available only if LIB_STR_CFG_FP_EN is DEF_ENABLED in lib_cfg.h (see section 5-1).

Notes / Warnings

For any unsuccessful string format or errors, an invalid string of question marks ('?') will be formatted, where the number of question marks is determined by the number of digits (nbr_dig) and number of decimal point digits (nbr_dp) to format. Also, whenever an invalid string is formatted for any reason, a NULL pointer is returned.

If the total number of digits to format (nbr_dig + nbr_dp) is zero; then no formatting is performed except possible NULL-termination of the string. Example:

nbr = -23456.789
nbr_dig = 0
nbr_dp = 0
pstr = ""

If the number of digits to format (nbr_dig) is less than the number of significant integer digits of the number to format (nbr); then an invalid string is formatted instead of truncating any significant integer digits. Example:

nbr = 23456.789
nbr_dig = 3
nbr_dp = 2
pstr = "??????"

If the number to format (nbr) is negative but the number of digits to format (nbr_dig) is equal to the number of significant integer digits of the number to format (nbr); then an invalid string is formatted instead of truncating the negative sign. Example:

nbr = -23456.789
nbr_dig = 5
nbr_dp = 2
pstr = "????????"

If the number to format (nbr) is negative but the number of significant integer digits is zero, and the number of digits to format (nbr_dig) is zero but the number of decimal point digits to format (nbr_dp) is non-zero; then the negative sign immediately prefixes the decimal point—with no decimal digits formatted, not even a single decimal digit of ‘0’. Example:

nbr = -0.7895
nbr_dig = 0
nbr_dp = 2
pstr = "-.78"

If the number to format (nbr) is positive but the number of significant integer digits is zero, and the number of digits to format (nbr_dig) is zero but the number of decimal point digits to format (nbr_dp) is non-zero; then a single decimal digit of ‘0’ prefixes the decimal point. This ‘0’ digit is used whenever a negative sign is not formatted so that the formatted string’s decimal point is not floating, but fixed in the string as the 2nd character. Example:

nbr = 0.7895
nbr_dig = 0
nbr_dp = 2
pstr = "0.78"

If the total number of digits to format (nbr_dig + nbr_dp) is greater than the configured maximum accuracy (LIB_STR_CFG_FP_MAX_NBR_DIG_SIG), all digits or decimal places following all significantly-accurate digits of the number to format (nbr) will be replaced and formatted with zeros (‘0’). Example:

nbr = 123456789.012345
nbr_dig = 9
nbr_dp = 6
LIB_STR_CFG_FP_MAX_NBR_DIG_SIG = 7
pstr = "123456700.000000"

Also, if the total number of digits to format (nbr_dig + nbr_dp) is greater than the maximum accuracy of the CPU’s and/or compiler’s 32-bit floating-point numbers, digits following all significantly-accurate digits of the number to format (nbr) will be inaccurate. Therefore, one or more least-significant digits of the number to format (nbr) may be rounded and not necessarily truncated due to the inaccuracy of the CPU’s and/or compiler’s floating-point implementation.

Leading character option (lead_char) prepends leading characters prior to the first non-zero significant digit. Leading character must be a printable ASCII character; but must not be a base-10 digit, with the exception of ‘0’.

For floating point numbers, the number of leading characters is such that the total number of significant integer digits plus the number of leading characters plus possible negative sign character is equal to the requested number of integer digits to format (nbr_dig). Examples:

nbr = 23456.789
nbr_dig = 7
nbr_dp = 2
lead_char = ' '
pstr = " 23456.78"
nbr = -23456.789
nbr_dig = 7
nbr_dp = 2
lead_char = ' '
pstr = " -23456.78"

If the integer value of the number to format (nbr) is zero and the number of digits to format (nbr_dig) is greater than one OR the number is not negative; but no leading character (lead_char) available; then one digit of ‘0’ value is formatted preceding the decimal point. This is not a leading character; but a single integer digit of ‘0’ value. Examples:

nbr = 0.789
nbr_dig = 7
nbr_dp = 2
lead_char = '\0'
pstr = "0.78"
nbr = 0.789
nbr_dig = 0
nbr_dp = 2
lead_char = '\0'
pstr = "0.78"

If the number to format (nbr) is negative and the leading character (lead_char) is a ‘0’ digit; then the negative sign character prefixes all leading characters prior to the formatted number. Example:

nbr = -23456.789
nbr_dig = 8
nbr_dp = 2
lead_char = '0'
pstr = "-0023456.78"

If the number to format (nbr) is negative and the leading character (lead_char) is not a ‘0’ digit; then the negative sign character immediately prefixes the most significant digit of the formatted number. Example:

nbr = -23456.789
nbr_dig = 8
nbr_dp = 2
lead_char = '#'
pstr = "##-23456.78"

When NULL-character terminate option (nul) is disabled, it prevents overwriting previous character array formatting. Warning: Unless pstr character array is pre-/post-terminated, if NULL-character terminate option is disabled, it will cause character string run-on.

Format buffer size not validated; buffer overruns must be prevented by caller. To prevent character buffer overrun:

Character array size must be >= (nbr_dig +
nbr_dp +
1 negative sign +
1 decimal point +
1 NUL terminator) characters

Example Usage

          CPU_CHAR   AppBuf[20];
          CPU_CHAR  *pstr;


          pstr = Str_FmtNbr_32((CPU_FP32   )-1234.5678,
                               (CPU_INT08U ) 5,
                               (CPU_INT08U ) 2,
                               (CPU_CHAR   ) ' ',
                               (CPU_BOOLEAN) DEF_NO,
                               (CPU_BOOLEAN) DEF_YES,
                               (CPU_CHAR  *)&AppBuf[0]);