Converts and formats a 32-bit unsigned integer into a string.
Files
lib_str.h/lib_str.c
Prototype
Arguments
nbr
Number to format into a string.
nbr_dig
Number of integer digits to format into the number string.
nbr_base
Base of the number 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.
lower_case
Option to format any alphabetic characters (if any) in lower case:
DEF_NO
Format alphabetic characters in upper case.
DEF_YES
Format alphabetic characters in lower case.
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
None.
Notes / Warnings
The following constants may be used to specify the number of digits to format (nbr_dig):
DEF_INT_32U_NBR_DIG_MIN
Minimum number of 32-bit unsigned digits
DEF_INT_32U_NBR_DIG_MAX
Maximumnumber of 32-bit unsigned digits
The number’s base (nbr_base) must be between 2 and 36, inclusive. The following constants may be used to specify the number base:
DEF_NBR_BASE_BIN
Base2
DEF_NBR_BASE_OCT
Base8
DEF_NBR_BASE_DEC
Base 10
DEF_NBR_BASE_HEX
Base 16
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 to format (nbr_dig). Also, whenever an invalid string is formatted for any reason, a NULL pointer is returned.
If the number of digits to format (nbr_dig) is zero; then no formatting is performed except possible NULL-termination of the string. Example:
nbr = 23456
nbr_dig = 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
nbr_dig = 3
pstr = "???"
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 number base digit, with the exception of ‘0’.
For unsigned integers, the number of leading characters is such that the total number of significant integer digits plus the number of leading characters is equal to the requested number of integer digits to format (nbr_dig). Example:
nbr = 23456
nbr_dig = 7
lead_char = ' '
pstr = " 23456"
If the value of the number to format (nbr) is zero and the number of digits to format (nbr_dig) is non-zero, but no leading character (lead_char) available; then one digit of ‘0’ value is formatted. This is not a leading character; but a single integer digit of ‘0’ value. Example:
nbr = 0
nbr_dig = 7
lead_char = '\0'
pstr = "0"
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
1 NUL terminator)