prg_string_double_unit_convert()
Abstract
Converts a number expressed in given units to an equivalent number in different units.
Syntax
prg_string_double_unit_convert (num, old_unit, num_before, new_num_ptr, new_unit_ptr, unit_buf, options)
| Argument | Type | Description |
|---|---|---|
num |
double |
Number to convert. |
old_unit |
PrgT_Units_Type |
Units associated with num. |
num_before |
int |
Maximum number of digits allowed to the left of the decimal point in the converted number. |
new_num_ptr |
double * |
Area to hold the converted number. |
new_unit_ptr |
PrgT_Units_Type * |
Area to hold the units for the converted number. |
unit_buf |
char * |
Area to hold a string representation of the new units. |
options |
int |
Conversion options (see Options in Details) |
Return Type
PrgT_Compcode
PrgC_Compcode_Success if the conversion is successful; PrgC_Compcode_Failure otherwise (see the Details section for Failure Conditions).
Header
prg_string_funcs.h
Details
This function converts a number expressed in given units to an equivalent number in different units (for example, 3600 seconds to 1 hour). You can specify the units to convert to or let the function automatically choose the “best” units for expressing the number (where “best” is based on the num_before argument).
There are five sets of units that can be used:
- time
- distance
- network bandwidth
- network throughput (bits)
- network throughput (bytes)
See Table 7 String Package Symbolic Constants for lists of the units in each set. Generally, units can be converted only within the same set. In the user-specified mode, however, conversion between the two network throughput sets (bits and bytes) is also possible.
Automatic conversion uses these processes:
- When |num| >= 1, repeatedly convert num to a smaller value (with a bigger unit) until the new value has fewer digits before the decimal point than num_before or until the largest unit has been used.
- When |num| < 1, repeatedly convert num to a larger value (with a smaller unit) until the number of digits before the decimal point is less than or equal to num_before or until the smallest unit has been used.
Options
The options argument must be an OR’ed combination of the following symbolic constants:
- PRGC_UNIT_CONVERT_OPT_AUTO—choose the new units automatically, based on num, old_unit, and num_before
- PRGC_UNIT_CONVERT_OPT_USE_NEW_UNIT—use the units specified by new_unit_ptr (if the units are convertible)
- PRGC_UNIT_CONVERT_OPT_FULL_UNIT_STRING—return the full units name in unit_buf instead of an abbreviation (for example, “meters” instead of “m”)
Note: PRGC_UNIT_CONVERT_OPT_USE_NEW_UNIT will be used if both it and PRGC_UNIT_CONVERT_OPT_AUTO are specified together.
Failure Conditions
Three conditions result in a return value of PrgC_Compcode_Failure:
- A null pointer is passed in.
- In automatic conversion, the largest unit has been used and the new value has more than num_before digits.
- In user-specified conversion, the new unit is not compatible with the old unit.