:orphan:

.. index:: pair: group; Unit-conversion
.. _doxid-group__te__tools__te__units:

Unit-conversion
===============

.. toctree::
	:hidden:

	enum_te_unit_prefix.rst
	struct_te_unit.rst
	struct_te_unit_list.rst

Overview
~~~~~~~~

Unit-conversion functions

Copyright (C) 2004-2022 OKTET Labs Ltd. :ref:`More...<details-group__te__tools__te__units>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// typedefs

	typedef enum :ref:`te_unit_prefix<doxid-group__te__tools__te__units_1ga99ff2affa574543d8d5ea0b262a96762>` :ref:`te_unit_prefix<doxid-group__te__tools__te__units_1ga609921513433dcbcaa66bb1e505efa4b>`;
	typedef struct :ref:`te_unit<doxid-structte__unit>` :ref:`te_unit<doxid-group__te__tools__te__units_1gab21ba7f49c0b09a61801a70479b32340>`;
	typedef struct :ref:`te_unit_list<doxid-structte__unit__list>` :ref:`te_unit_list<doxid-group__te__tools__te__units_1ga7936c75f4ca28ef54a6db40fa6dcf3f7>`;

	// enums

	enum :ref:`te_unit_prefix<doxid-group__te__tools__te__units_1ga99ff2affa574543d8d5ea0b262a96762>`;

	// structs

	struct :ref:`te_unit<doxid-structte__unit>`;
	struct :ref:`te_unit_list<doxid-structte__unit__list>`;

	// global functions

	const char* :ref:`te_unit_prefix2str<doxid-group__te__tools__te__units_1gadeed3807465b82523b46e6bb97a868d2>`(:ref:`te_unit_prefix<doxid-group__te__tools__te__units_1ga99ff2affa574543d8d5ea0b262a96762>` unit);
	:ref:`te_unit<doxid-structte__unit>` :ref:`te_unit_pack<doxid-group__te__tools__te__units_1ga811f48ed1e6804bd432268a3b2f69d5a>`(double value);
	double :ref:`te_unit_unpack<doxid-group__te__tools__te__units_1ga72d90c7ef4e17a616a9145107b9aca29>`(:ref:`te_unit<doxid-structte__unit>` value);
	:ref:`te_unit<doxid-structte__unit>` :ref:`te_unit_bin_pack<doxid-group__te__tools__te__units_1ga56ab1e616cf49f6fe3c0b08bef43c1cd>`(double value);
	double :ref:`te_unit_bin_unpack<doxid-group__te__tools__te__units_1ga8417a32ee63492f4cec68b66dfce0a46>`(:ref:`te_unit<doxid-structte__unit>` value);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`te_unit_from_string<doxid-group__te__tools__te__units_1ga2200e6eaa373a9d84efbcf6f9f304c7c>`(const char* str, :ref:`te_unit<doxid-structte__unit>`* value);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`te_unit_list_value_from_string<doxid-group__te__tools__te__units_1ga37b00a14f065a43cf254f2931317d36c>`(const char* str, const :ref:`te_unit_list<doxid-structte__unit__list>`* type, double* value);

	// macros

	#define :target:`TE_UNITS_BIN_G2U<doxid-group__te__tools__te__units_1ga7207fed33e4af2d61b65c2101efe8f3c>`(_val)
	#define :target:`TE_UNITS_BIN_K2U<doxid-group__te__tools__te__units_1ga65086143ea5f22217821a37d83e74d95>`(_val)
	#define :target:`TE_UNITS_BIN_M2U<doxid-group__te__tools__te__units_1gaa64de4fb5b50b9ba8873389e22bcd0e6>`(_val)
	#define :target:`TE_UNITS_BIN_U2G<doxid-group__te__tools__te__units_1ga3672f001b209d351fc3a4fd5d9ec8272>`(_val)
	#define :target:`TE_UNITS_BIN_U2K<doxid-group__te__tools__te__units_1ga5be16deac9706180711b985c4303864f>`(_val)
	#define :target:`TE_UNITS_BIN_U2M<doxid-group__te__tools__te__units_1ga44354bbf5f5cd7cd1401fa7764ca7959>`(_val)
	#define :target:`TE_UNITS_DEC_G2U<doxid-group__te__tools__te__units_1ga5664cc2ae73426344865aa038e92f3ae>`(_val)
	#define :target:`TE_UNITS_DEC_K2U<doxid-group__te__tools__te__units_1ga6ae56872962b8f5117bf5508187abd9c>`(_val)
	#define :target:`TE_UNITS_DEC_M2U<doxid-group__te__tools__te__units_1gac7d3f3a0f9048c2c0635365d50f65ec2>`(_val)
	#define :target:`TE_UNITS_DEC_U2G<doxid-group__te__tools__te__units_1ga0cdcdb260492c50088103f83b6496de2>`(_val)
	#define :target:`TE_UNITS_DEC_U2K<doxid-group__te__tools__te__units_1gafe722b4329233e2a0a28a28554e1ae00>`(_val)
	#define :target:`TE_UNITS_DEC_U2M<doxid-group__te__tools__te__units_1ga40ce2a9c1c9cc1ca3658230d8d5f5fdd>`(_val)

.. _details-group__te__tools__te__units:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Unit-conversion functions

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Typedefs
--------

.. index:: pair: typedef; te_unit_prefix
.. _doxid-group__te__tools__te__units_1ga609921513433dcbcaa66bb1e505efa4b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef enum :ref:`te_unit_prefix<doxid-group__te__tools__te__units_1ga99ff2affa574543d8d5ea0b262a96762>` te_unit_prefix

List of supported unit prefixes

.. index:: pair: typedef; te_unit
.. _doxid-group__te__tools__te__units_1gab21ba7f49c0b09a61801a70479b32340:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`te_unit<doxid-structte__unit>` te_unit

Value-unit pair

.. index:: pair: typedef; te_unit_list
.. _doxid-group__te__tools__te__units_1ga7936c75f4ca28ef54a6db40fa6dcf3f7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`te_unit_list<doxid-structte__unit__list>` te_unit_list

Customizable unit type

Global Functions
----------------

.. index:: pair: function; te_unit_prefix2str
.. _doxid-group__te__tools__te__units_1gadeed3807465b82523b46e6bb97a868d2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	const char* te_unit_prefix2str(:ref:`te_unit_prefix<doxid-group__te__tools__te__units_1ga99ff2affa574543d8d5ea0b262a96762>` unit)

Convert unit prefix to string.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- unit

		- Unit prefix.



.. rubric:: Returns:

String representation of unit prefix, or ``NULL`` if prefix is unknown.

.. index:: pair: function; te_unit_pack
.. _doxid-group__te__tools__te__units_1ga811f48ed1e6804bd432268a3b2f69d5a:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_unit<doxid-structte__unit>` te_unit_pack(double value)

Convert plain value to value-unit.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- value

		- Value to convert.



.. rubric:: Returns:

Converted value with unit prefix.

.. index:: pair: function; te_unit_unpack
.. _doxid-group__te__tools__te__units_1ga72d90c7ef4e17a616a9145107b9aca29:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	double te_unit_unpack(:ref:`te_unit<doxid-structte__unit>` value)

Convert value-unit to plain value.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- value

		- Value to convert.



.. rubric:: Returns:

Plain value.

.. index:: pair: function; te_unit_bin_pack
.. _doxid-group__te__tools__te__units_1ga56ab1e616cf49f6fe3c0b08bef43c1cd:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_unit<doxid-structte__unit>` te_unit_bin_pack(double value)

Convert binary plain value to value-unit.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- value

		- Value to convert.



.. rubric:: Returns:

Converted value with unit prefix.

.. index:: pair: function; te_unit_bin_unpack
.. _doxid-group__te__tools__te__units_1ga8417a32ee63492f4cec68b66dfce0a46:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	double te_unit_bin_unpack(:ref:`te_unit<doxid-structte__unit>` value)

Convert value-unit to binary plain value.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- value

		- Value to convert.



.. rubric:: Returns:

Plain value.

.. index:: pair: function; te_unit_from_string
.. _doxid-group__te__tools__te__units_1ga2200e6eaa373a9d84efbcf6f9f304c7c:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` te_unit_from_string(const char* str, :ref:`te_unit<doxid-structte__unit>`* value)

Read value-unit from the string and store it to ``unit``



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- str

		- String representation of value-unit

	*
		- value

		- Value-unit to store result in



.. rubric:: Returns:

Status code.

.. index:: pair: function; te_unit_list_value_from_string
.. _doxid-group__te__tools__te__units_1ga37b00a14f065a43cf254f2931317d36c:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` te_unit_list_value_from_string(const char* str, const :ref:`te_unit_list<doxid-structte__unit__list>`* type, double* value)

Read value from the string and convert it to double using given unit list

The API is independent and if the returned value is used in te_unit\_\*pack calls, the resulting ``:ref:`te_unit <doxid-structte__unit>``` will not be consistent with ``type``.

Example:

.. ref-code-block:: cpp

	:ref:`te_unit_list <doxid-structte__unit__list>` units = {
	    .:ref:`scale <doxid-structte__unit__list_1a875a3e30e2c17471a9409432672a735a>` = 1000,
	    .start_pow = -1,
	    .units = (const char * const[]){ "mHz", "Hz", "kHz", NULL },
	};

``"300mHz"`` would be converted to ``0.3``.

.. ref-code-block:: cpp

	:ref:`te_unit_list <doxid-structte__unit__list>` units = {
	    .:ref:`non_uniform_scale <doxid-structte__unit__list_1a4eff7afac1f86c061396afee31ff7cd1>` = { 1e-9, 1e-3, 1.0, 60.0, 3600.0 }
	    .units = (const char * const[]){ "ns", "ms", "s", "m", "h", NULL },
	};

``"10h"`` would be converted to ``36000.0`` and ``"10ms"`` to ``0.01``



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- str

		- String representation of value

	*
		- type

		- Unit type

	*
		- value

		- Value to store result in



.. rubric:: Returns:

Status code.