Str_FmtNbr_Int32U()

Converts and formats a 32-bit unsigned integer into a string.

Files

lib_str.h/lib_str.c

Prototype

          CPU_CHAR  *Str_FmtNbr_Int32U (CPU_INT32U    nbr,
                                        CPU_INT08U    nbr_dig,
                                        CPU_INT08U    nbr_base,
                                        CPU_CHAR      lead_char,
                                        CPU_BOOLEAN   lower_case,
                                        CPU_BOOLEAN   nul,
                                        CPU_CHAR     *pstr);

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 +
1 NUL terminator) characters

Example Usage

          CPU_CHAR   AppBuf[20];
          CPU_CHAR  *pstr;
           
          pstr = Str_FmtNbr_Int32U((CPU_INT32U ) 12345678u,
                                   (CPU_INT08U ) 10,
                                   (CPU_INT08U ) 10,
                                   (CPU_CHAR   ) </code>'0'<code >,
                                   (CPU_BOOLEAN) DEF_NO,
                                   (CPU_BOOLEAN) DEF_YES,
                                   (CPU_CHAR  *)&AppBuf[0]);