uf_unit.html

/*

uf_unit.h
File description:

This the Open API interface to units specifications used by e.g. expressions and user attributes.

In NX a units specification consists of two parts, the measure and the unit types.
The measure defines what type of value is being considered.
Examples of measures are:

Measure Measure Type
---------------------------------
Length UF_MEASURE_LENGTH
Area UF_MEASURE_AREA
Thermal Energy UF_MEASURE_THERMAL_ENERGY

The OOTB (pre-installed) measures are enumerated as listed in uf_unit_types.h.
Those types are valid only for the pre-installed measures.
If custom measures are added either via an XML file (globally) or the Units Manager (globally or in a part),
they cannot be identified by this fixed enumeration. For such measures we recommend that you
instead use APIs that identify the measures by their internal (untranslated) names.

For each measure, NX supports a number of unit types. The unit type is the actual units
that are used to express the given value.
Examples of unit types are:

Units Unit Type Name
----------------------------------
'millimeters' UF_UNIT_LENGTH_mm
'inches squared' UF_UNIT_AREA_in2
'Btu' UF_UNIT_ENERGY_btu

The names of the OOTB (pre-installed) unit types are defined uf_unit_types.h.

Using the UF_UNIT subroutines, you can:

. Find the tag of a unit type using the unit name.
. Find the name of a unit specification using the unit type tag.
. Convert a value from one unit type to another.

*/
#ifndef UF_UNIT_INCLUDED
#define UF_UNIT_INCLUDED

/******************************************************************************

***************************************************************************/

#include <uf_defs.h>
#include <uf_error_bases.h>
#include <uf_unit_types.h>
#include <libufun_exports.h>

/*****************************************************************************
* UF_UNIT_ask_unit_tag_from_unit_name
*
* Given a unit type name and the associated measure type, return the tag of the unit type
*
* The given name is the name of the units as defined in uf_unit_types.h
* To properly select the units, an object in the part as well as the measure type
* must be provided.
*
* For example, the name for millimeters is "MilliMeter", defined in uf_unit_types.h as 'UF_UNIT_LENGTH_mm
*
* NOTE: The measure type is persistent and listed in uf_unit_types.h only for
* OOTB measures. This function is supported only for such measures.
*
* Environment: Internal and External
* History: NX8.5.3
*****************************************************************************/
extern UFUNEXPORT int UF_UNIT_ask_unit_tag_from_unit_name
(
tag_t object, /* The units context (an object in the part where the units are used) */
UF_UNIT_MEASURE_TYPE_t unit_measure_type, /* The measure type of the units (see uf_unit_types.h) */
const char * name, /* The name of the unit type (see uf_unit_types.h) */
tag_t *unit /* <O> The tag of the unit type */
);

/*****************************************************************************
* UF_UNIT_ask_system_unit_tag_from_measure
*
* Given a unit type name and the associated measure type, return the tag of the system unit type.
* The system units is that used to store values in the part file (as opposed to display units).
*
* To properly select the units, an object in the part as well as the measure type
* must be provided.
*
* NOTE: The measure type is persistent and listed in uf_unit_types.h only for
* OOTB measures. This function is supported only for such measures.
*
* Environment: Internal and External
* History: NX8.5.3
*****************************************************************************/
extern UFUNEXPORT int UF_UNIT_ask_system_unit_tag_from_measure
(
tag_t object, /* The units context (an object in the part where the units are used) */
UF_UNIT_MEASURE_TYPE_t unit_measure_type, /* The measure type of the units (see uf_unit_types.h) */
tag_t *unit /* <O> The tag of the unit type */
);

/******************************************************************************
* UF_UNIT_ask_unit_name_from_unit_tag
*
* Given a unit tag, return the unit name of the units
*
* For example, the name for millimeters is "MilliMeter", defined in uf_unit_types.h as 'UF_UNIT_LENGTH_mm
* The returned string must be freed after use.
*
* Environment: Internal and External
* History: NX8.5.3
*****************************************************************************/
extern UFUNEXPORT int UF_UNIT_ask_unit_name_from_unit_tag
(
tag_t unit, /* The tag of the unit type */
char ** name /* <OF> The unit name of the units (see uf_unit_types.h) */
);

/******************************************************************************
* UF_UNIT_ask_measure_type_from_unit_tag
*
* Given a unit tag, return the measure type
*
* NOTE: The measure type is persistent and listed in uf_unit_types.h only for
* OOTB measures. This function is supported only for such measures.
*
* Environment: Internal and External
* History: NX8.5.3
******************************************************************************/
extern UFUNEXPORT int UF_UNIT_ask_measure_type_from_unit_tag
(
tag_t unit, /* The tag of the unit type */
UF_UNIT_MEASURE_TYPE_p_t measure_type /* <O> The measure type associated with the given units (see uf_unit_types.h) */
);

/******************************************************************************
* UF_UNIT_convert_value
*
* Given a value with a given unit type, convert it to a value in a new unit type.
*
* The dimensions of the new units must be the same as those of the initial units
*
* Environment: Internal and External
* History: NX8.5.3
******************************************************************************/
extern UFUNEXPORT int UF_UNIT_convert_value
(
double initial_value, /* The value to be converted */
tag_t initial_units, /* The tag of the unit type of the initial value */
tag_t new_units, /* The tag of the unit type of the new units */
double *converted_value /* <O> The value expressed in the new units */
);

#undef EXPORTLIBRARY
#endif