prg_string_double_format()
Abstract
Returns a formatted string representation of a double.
Syntax
prg_string_double_format (num, num_before, num_after, buf, options)
| Argument | Type | Description |
|---|---|---|
num |
double |
Number to be formatted. |
num_before |
int |
Maximum number of characters (counting thousands separators and plus/minus sign) to allow before the decimal point. Must be >= 0. |
num_after |
int |
Number of characters to allow after the decimal point. Must be >= 0. Note: num_before and num_after cannot both be 0. |
buf |
char * |
Area to be filled with the formatted string. This area must be large enough to hold the returned string, which will always be less than or equal to the requested size if the function is successful (returns PrgC_Compcode_Success). The requested size is num_before + num_after (+ 1 [for a decimal point] if num_after > 0). |
options |
int |
Format options for doubles (see Details). |
Return Type
PrgT_Compcode
PrgC_Compcode_Failure if num is too large to fit the num_before constraint or buf is NIL; PrgC_Compcode_Success otherwise.
Header
prg_string_funcs.h
Details
options must be either PRGC_STRING_FROM_DOUBLE_NONE or an OR’ed combination of one or more of the following symbolic constants:
- PRGC_STRING_FROM_DOUBLE_NO_THOUSAND_SEPARATOR—do not include the thousands separator character in the string.
- PRGC_STRING_FROM_DOUBLE_EXCLUDE_MINUS_SIGN—do not include a minus sign for negative numbers.
- PRGC_STRING_FROM_DOUBLE_INCLUDE_PLUS_SIGN—include a plus sign for positive numbers.
- PRGC_STRING_FROM_DOUBLE_PAD_LEAD_SPACES—add leading spaces to make the total number of characters to the left of the decimal point (counting thousands separators and plus/minus sign) equal to num_before.
- PRGC_STRING_FROM_DOUBLE_PAD_TRAIL_SPACES—add trailing spaces to make the total number of characters to the right of the decimal point equal to num_after.
- PRGC_STRING_FROM_DOUBLE_PAD_TRAIL_ZEROS—add trailing zeros to make the total number of characters to the right of the decimal point equal to num_after.
- PRGC_STRING_FROM_DOUBLE_REPRESENT_APPROXIMATED_ZERO—add a tilda (‘~’) in front of numbers that are close to zero (that is, in cases where num is so small that the num_after constraint would result in only zeros in the formatted string). “Close” is defined as num < 0.5 × 10^–num_after.
- PRGC_STRING_FROM_DOUBLE_REMOVE_TRAIL_ZEROS—remove any trailing zeros.
Format Notes
- The formatted number is rounded, if necessary.
- If 0 <= |num| < 1, a zero appears before the decimal point (unless num_before is 0).
- If num_after is 0, the decimal point is not included in the string.
- If num is a symbolic value (such as PRGC_DBL_UNDEF), the symbolic name is returned in buf (“Undefined” in this example). The name string will be padded with spaces (if requested by options) up to the requested string size, which is num_before + num_after (+ 1, if num_after > 0). If both leading and trailing spaces are requested, the name will be centered in the padded string.