Str_FmtNbr_Int32S()

Owned by Former user (Deleted)
Last updated: Dec 03, 2020 by WES Admin
5 min read

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

Files

lib_str.h/lib_str.c

Prototype

          CPU_CHAR  *Str_FmtNbr_Int32S (CPU_INT32S    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 uppercase.

DEF_YES

Format alphabetic characters in lowercase.

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_32S_NBR_DIG_MIN + 1

Minimum number of 32-bit signed digits

DEF_INT_32S_NBR_DIG_MAX + 1

Maximum number of 32-bit signed digits
(plus 1 digit for possible negative sign)

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
nbr_base = 10
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
nbr_base = 10
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
nbr_dig = 5
nbr_base = 10
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 signed integers, 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
nbr_dig = 7
nbr_base = 10
lead_char = ' '
pstr = " 23456"
nbr = -23456
nbr_dig = 7
nbr_base = 10
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"

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. Examples:

nbr = -23456
nbr_dig = 8
nbr_base = 10
lead_char = '0'
pstr = "-0023456"
nbr = -43981
nbr_dig = 8
nbr_base = 16
lead_char = '0'
lower_case = DEF_NO
pstr = "-000ABCD"

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. Examples:

nbr = -23456
nbr_dig = 8
nbr_base = 10
lead_char = '#'
pstr = "##-23456"
nbr = -43981
nbr_dig = 8
nbr_base = 16
lead_char = '#'
lower_case = DEF_YES
pstr = "###-abcd"

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

Example Usage

          CPU_CHAR   AppBuf[20];
          CPU_CHAR  *pstr;


          pstr = Str_FmtNbr_Int32S((CPU_INT32S )-12345678,
                                   (CPU_INT08U ) 10,
                                   (CPU_INT08U ) 10,
                                   (CPU_CHAR   ) '0',
                                   (CPU_BOOLEAN) DEF_NO,
                                   (CPU_BOOLEAN) DEF_YES,
                                   (CPU_CHAR  *)&AppBuf[0]);