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).

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.

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com