Converts and formats a 32-bit floating point number into a string.
Files
lib_str.h/lib_str.c
Prototype
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 + characters
nbr_dp +
1 negative sign +
1 decimal point +
1 NUL terminator)