prg_string_double_unit_convert()
摘要
将以指定单位表示的数值转换为以不同单位表示的等效数值。
语法
prg_string_double_unit_convert (num, old_unit, num_before, new_num_ptr, new_unit_ptr, unit_buf, options)
| 参数 | 类型 | 说明 |
|---|---|---|
num |
double |
要转换的数值。 |
old_unit |
PrgT_Units_Type |
与 num 关联的单位。 |
num_before |
int |
转换后数值小数点左侧允许的最大位数。 |
new_num_ptr |
double * |
用于存放转换后数值的区域。 |
new_unit_ptr |
PrgT_Units_Type * |
用于存放转换后数值单位的区域。 |
unit_buf |
char * |
用于存放新单位字符串表示的区域。 |
options |
int |
转换选项(见 Details 小节中的 选项) |
返回类型
PrgT_Compcode
转换成功时返回 PrgC_Compcode_Success;否则返回 PrgC_Compcode_Failure(见 Details 小节中的失败条件)。
头文件
prg_string_funcs.h
详情
该函数将以指定单位表示的数值转换为以不同单位表示的等效数值(例如,3600 秒转换为 1 小时)。你可以指定要转换到的单位,也可以让函数自动选择表达该数值的“最佳”单位(“最佳”的判定基于 num_before 参数)。
可以使用的单位共有五组:
- 时间
- 距离
- 网络带宽
- 网络吞吐量(比特)
- 网络吞吐量(字节)
各组单位的列表参见 表 7 字符串包符号常量。通常,单位只能在同一组内转换;但在用户指定模式下,两个网络吞吐量组(比特与字节)之间也可以转换。
自动转换遵循以下过程:
- 当 |num| >= 1 时,反复将 num 转换为更小的值(使用更大的单位),直到新值小数点前的位数少于 num_before,或已用到最大单位为止。
- 当 |num| < 1 时,反复将 num 转换为更大的值(使用更小的单位),直到小数点前的位数小于或等于 num_before,或已用到最小单位为止。
选项
options 参数必须是以下符号常量的 OR 组合:
- PRGC_UNIT_CONVERT_OPT_AUTO—基于 num、old_unit 和 num_before 自动选择新单位
- PRGC_UNIT_CONVERT_OPT_USE_NEW_UNIT—使用 new_unit_ptr 指定的单位(若单位可转换)
- PRGC_UNIT_CONVERT_OPT_FULL_UNIT_STRING—在 unit_buf 中返回完整的单位名称而非缩写(例如返回 “meters” 而不是 “m”)
注意: 若同时指定 PRGC_UNIT_CONVERT_OPT_USE_NEW_UNIT 和 PRGC_UNIT_CONVERT_OPT_AUTO,将使用前者。
失败条件
以下三种情况会返回 PrgC_Compcode_Failure:
- 传入了空指针。
- 自动转换时,已用到最大单位且新值的位数超过 num_before。
- 用户指定转换时,新单位与旧单位不兼容。