STEP Measure Functions [steptools.com] [Documentation] [STEP Programming]

## Overview

These functions work on STEP measure_with_unit instances. A measure combines a value with a unit, and possibly a subtype for specific value types (lengths, angles, etc). When the measure is part of a representation, it is also combined with representation_item as a complex instance.

These functions are defined in the stix_measure.h header file.

Use stix_measure_get_value() to get the numeric value of a measure, and stix_unit_get_type() to get its unit. Qualified measures may also have an upper limit, lower limit, or precision value.

Use stix_rep_find_measure_item() to search a representation for a specific kind of measure. Versions of these functions specialize in angle, count, linear speed, length, pressure, ratio, rotational speed, and time values.

The stix_measure_make() function creates measures with unit and uses the appropriate subtype or complex instance combinations for the value.

## stix_measure_get_angle()

```double stix_measure_get_angle (
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);

double stix_measure_get_angle (
stp_measure_with_unit * mwu,
RoseUnitSet * uset
);
```

The stix_measure_get_angle() function is a wrapper around stix_measure_get_value() that returns the numeric value of a measure item, possibly converted to a different unit. If no unit parameter is provided, the value is returned as-is. If a RoseUnitSet parameter is given, the value will be converted to the angle unit of the set.

## stix_measure_get_count()

```double stix_measure_get_count (
stp_measure_with_unit * mwu
);  // unitless
```

The stix_measure_get_count() function returns the numeric value of a measure item. Count values never need unit conversion so no additional parameters are required. This is a simple wrapper around stix_measure_get_value() that makes the type of the value clearer in code.

## stix_measure_get_current()

```double stix_measure_get_current(
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);
```

The stix_measure_get_current() function returns the current value of a qualified measure if one is present, and ROSE_NULL_REAL if one is not. The current value is described by the same unit as the main (nominal) value, which is returned by stix_unit_get_type(). You can pass an optional unit parameter if you would like the value converted to a particular unit.

If a measure has a current value, it must be a subtype of qualified_representation_item. See stix_measure_get_lower_limit, stix_measure_get_upper_limit, and stix_measure_get_precision for other qualifiers.

## stix_measure_get_descriptive()

```const char * stix_measure_get_descriptive (
stp_representation * rep,
const char * desired_name = 0
);

const char * stix_measure_get_descriptive (
stp_measure_with_unit * mwu
);
```

The stix_measure_get_descriptive() function returns a string description value. There are two versions of this function. The first version is a wrapper around stix_rep_find_descriptive_item() that searches a representation. The second version operates on a measure with unit. Measures are normally numeric values, but they can hold a descriptve string instead. The function returns a null pointer if no descriptive value can be found.

## stix_measure_get_feedrate()

```double stix_measure_get_feedrate (
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);

double stix_measure_get_feedrate (
stp_measure_with_unit * mwu,
RoseUnitSet * uset
);
```

The stix_measure_get_feedrate() function is a wrapper around stix_measure_get_value() that returns the numeric value of a measure item, possibly converted to a different unit. If no unit parameter is provided, the value is returned as-is. If a RoseUnitSet parameter is given, the value will be converted to the linear speed unit of the set.

## stix_measure_get_length()

```double stix_measure_get_length (
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);

double stix_measure_get_length (
stp_measure_with_unit * mwu,
RoseUnitSet * uset
);
```

The stix_measure_get_length() function is a wrapper around stix_measure_get_value() that returns the numeric value of a measure item, possibly converted to a different unit. If no unit parameter is provided, the value is returned as-is. If a RoseUnitSet parameter is given, the value will be converted to the length unit of the set.

## stix_measure_get_lower_limit()

```double stix_measure_get_lower_limit(
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);
```

The stix_measure_get_lower_limit() function returns the lower limit value of a measure if one is present, and ROSE_NULL_REAL if one is not. The limit value is described by the same unit as the main (nominal) value, which is returned by stix_unit_get_type(). You can pass an optional unit parameter if you would like the value converted to a particular unit. If a measure has a limit value, it must be a subtype of qualified_representation_item. See stix_measure_get_upper_limit and stix_measure_get_precision for other qualifiers.

## stix_measure_get_precision()

```int stix_measure_get_precision(
stp_measure_with_unit * mwu
);
```

The stix_measure_get_precision() function returns the digits of precision for a measure if one is present, and ROSE_NULL_INT if one is not. If a measure has a precision value, it must be a subtype of qualified_representation_item. See stix_measure_get_lower_limit and stix_measure_get_upper_limit for other qualifiers.

## stix_measure_get_pressure()

```double stix_measure_get_pressure (
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);

double stix_measure_get_pressure (
stp_measure_with_unit * mwu,
RoseUnitSet * uset
);
```

The stix_measure_get_pressure() function is a wrapper around stix_measure_get_value() that returns the numeric value of a measure item, possibly converted to a different unit. If no unit parameter is provided, the value is returned as-is. If a RoseUnitSet parameter is given, the value will be converted to the pressure unit of the set.

## stix_measure_get_ratio()

```double stix_measure_get_ratio (
stp_measure_with_unit * mwu
);  // unitless
```

The stix_measure_get_ratio() function returns the numeric value of a measure item. Ratio values never need unit conversion so no additional parameters are required. This is a simple wrapper around stix_measure_get_value() that makes the type of the value clearer in code.

## stix_measure_get_spinrate()

```double stix_measure_get_spinrate (
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);

double stix_measure_get_spinrate (
stp_measure_with_unit * mwu,
RoseUnitSet * uset
);
```

The stix_measure_get_spinrate() function is a wrapper around stix_measure_get_value() that returns the numeric value of a measure item, possibly converted to a different unit. If no unit parameter is provided, the value is returned as-is. If a RoseUnitSet parameter is given, the value will be converted to the rotational speed unit of the set.

## stix_measure_get_std_uncertainty()

```stp_standard_uncertainty * stix_measure_get_std_uncertainty(
stp_qualified_representation_item * qri,
const char * qualname
)

stp_standard_uncertainty * stix_measure_get_std_uncertainty(
stp_measure_with_unit * mwu,
const char * qualname
)
```

The stix_measure_get_std_uncertainty() function searches for a standard_uncertainty instance with a given name in the list of qualifiers in a qualified representation item. The function has several prototypes to simplify programming, but the supplied object must have qualified_representation_item as a type.

## stix_measure_get_time()

```double stix_measure_get_time (
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);

double stix_measure_get_time (
stp_measure_with_unit * mwu,
RoseUnitSet * uset
);
```

## stix_measure_get_upper_limit()

```double stix_measure_get_upper_limit(
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);
```

The stix_measure_get_upper_limit() function returns the lower limit value of a measure if one is present, and ROSE_NULL_REAL if one is not. The limit value is described by the same unit as the main (nominal) value, which is returned by stix_unit_get_type(). You can pass an optional unit parameter if you would like the value converted to a particular unit. If a measure has a limit value, it must be a subtype of qualified_representation_item. See stix_measure_get_lower_limit and stix_measure_get_precision for other qualifiers.

## stix_measure_get_value()

```double stix_measure_get_value(
stp_measure_with_unit * mwu,
RoseUnit u = roseunit_as_is
);
```

The stix_measure_get_value() function returns the numeric value of a measure if one is present, and ROSE_NULL_REAL if the value is null or a descriptive string value. The function takes an optional unit parameter if you would like the value converted to a particular unit. You can find the unit of the value with the stix_unit_get_type() function.

## stix_measure_make()

```stp_measure_with_unit * stix_measure_make(
RoseDesign * design,
double value,
RoseUnit ut
);
```

The stix_measure_make() function creates a new measure instance to describe the given number and with the STEP data for a given RoseUnit in the provided design. The instance will not be a representation_item subtype (use stix_measure_make_item() for that), but the function will create a value-specific subtype if needed.

The stix_measure_make_angle(), stix_measure_make_length(), and stix_measure_make_ratio() wrappers call this function and cast the result for situations that require a more specific pointer type.

## stix_measure_make_angle()

```stp_plane_angle_measure_with_unit * stix_measure_make_angle(
RoseDesign * design,
double value,
RoseUnit ut
);
```

The stix_measure_make_angle() function is just a wrapper around stix_measure_make(). Both functions return the same object, but this version casts the return pointer to the angle-specific subtype for use in places that require the pointer as the more specific type.

## stix_measure_make_angle_item()

```stp_measure_representation_item_and_plane_angle_measure_with_unit * stix_measure_make_angle_item(
RoseDesign * design,
double value,
RoseUnit ut
);
```

The stix_measure_make_angle_item() function is just a wrapper around stix_measure_make_item(). Both functions return the same object, but this version casts the return pointer to the angle-specific representation item subtype for use in places that require the pointer as the more specific type.

## stix_measure_make_item()

```stp_measure_representation_item * stix_measure_make_item(
RoseDesign * design,
double value,
RoseUnit ut
);
```

The stix_measure_make_item() function creates a new measure instance for use in a representation. The instance will describe the given number with the STEP data for a given RoseUnit in the provided design. The function will create instance using any subtypes or complex instance combinations that might be required for type of value.

The stix_measure_make_angle_item(), stix_measure_make_length_item(), and stix_measure_make_ratio_item() wrappers call this function and cast the result for situations that require a more specific pointer type.

```RoseDesign * d;

// Make a 27.3 mm rep item instance
stp_measure_representation_item * box_height =
stix_measure_make_item (d, 27.3, roseunit_mm);
```

## stix_measure_make_length()

```stp_length_measure_with_unit * stix_measure_make_length(
RoseDesign * design,
double value,
RoseUnit ut
);
```

The stix_measure_make_length() function is just a wrapper around stix_measure_make(). Both functions return the same object, but this version casts the return pointer to the length-specific subtype for use in places that require the pointer as the more specific type.

## stix_measure_make_length_item()

```stp_length_measure_with_unit_and_measure_representation_item * stix_measure_make_length_item(
RoseDesign * design,
double value,
RoseUnit ut
);
```

The stix_measure_make_length_item() function is just a wrapper around stix_measure_make_item(). Both functions return the same object, but this version casts the return pointer to the length-specific representation item subtype for use in places that require the pointer as the more specific type.

## stix_measure_make_qualified_item()

```stp_qualified_representation_item * stix_measure_make_qualified_item(
RoseDesign * d,
double value,
RoseUnit ut
);
```

The stix_measure_make_qualified_item() function creates a new measure instance for use in a representation. The result is a complex instance of qualified representation item, measure representation item, and if applicable, a measure with unit subtype. As with stix_measure_make_item(), the resulting object is initialized with the supplied value and unit information.

Use the stix_measure_put_lower_limit(), stix_measure_put_upper_limit(), and stix_measure_put_precision() functions to set additional qualifiers on the result.

## stix_measure_make_ratio()

```stp_ratio_measure_with_unit * stix_measure_make_ratio(
RoseDesign * design,
double value,
RoseUnit ut = roseunit_ratio
);
```

The stix_measure_make_ratio() function is just a wrapper around stix_measure_make(). Both functions return the same object, but this version casts the return pointer to the ratio-specific subtype for use in places that require the pointer as the more specific type.

Since ratio measures normally do not have a specific unit, this function uses a default parameter of roseunit_ratio

## stix_measure_make_ratio_item()

```stp_measure_representation_item_and_ratio_measure_with_unit * stix_measure_make_ratio_item(
RoseDesign * design,
double value,
RoseUnit ut = roseunit_ratio
);
```

The stix_measure_make_ratio_item() function is a wrapper around stix_measure_make_item(). Both functions return the same object, but this version casts the return pointer to the ratio-specific representation item subtype for use in places that require the pointer as the more specific type.

Since ratio measures normally do not have a specific unit, this function uses a default parameter of roseunit_ratio

## stix_measure_make_time()

```stp_time_measure_with_unit * stix_measure_make_time(
RoseDesign * d,
double value,
RoseUnit ut
);
```

The stix_measure_make_time() function is just a wrapper around stix_measure_make(). Both functions return the same object, but this version casts the return pointer to the time-specific subtype for use in places that require the pointer as the more specific type.

## stix_measure_make_time_item()

```stp_measure_representation_item_and_time_measure_with_unit * stix_measure_make_time_item(
RoseDesign * d,
double value,
RoseUnit ut
);
```

The stix_measure_make_time_item() function is a wrapper around stix_measure_make_item(). Both functions return the same object, but this version casts the return pointer to the time-specific representation item subtype for use in places that require the pointer as the more specific type.

## stix_measure_make_value()

```stp_measure_value * stix_measure_make_value(
RoseDesign * design,
double value,
RoseMeasureType mt
);
```

The stix_measure_make_value() function creates a new measure value select type to describe the given number in the provided design. The value type parameter gives the type of quantity (length, angle, etc) described by the number.

## stix_measure_put_lower_limit()

```stp_standard_uncertainty * stix_measure_put_lower_limit(
stp_qualified_representation_item * it,
double limval
);
```

The stix_measure_put_lower_limit() function finds or adds a standard_uncertainty instance with a name of "lower limit" to the list of qualifiers in a qualified representation item. Then the function sets the numeric value to the given number and returns the standard_uncertainty. If the numeric value is ROSE_NULL_REAL, any existing lower limit will be removed and the function will return null.

Use stix_measure_make_qualified_item() to create a measure instance that can hold an upper or lower limit.

## stix_measure_put_precision()

```stp_precision_qualifier * stix_measure_put_precision(
stp_qualified_representation_item * it,
int precval
);
```

The stix_measure_put_precision() function finds or adds a precision_qualifier instance to the list of qualifiers in a qualified representation item. Then the function sets the numeric value to the given number and returns the precision_qualifier.

If the numeric value is ROSE_NULL_INT, any existing precision qualifier will be removed and the function will return null.

## stix_measure_put_std_uncertainty()

```stp_standard_uncertainty * stix_measure_put_std_uncertainty(
stp_qualified_representation_item * qri,
const char * qualname,
double qualval
);
```

The stix_measure_put_std_uncertainty() function finds or adds a standard_uncertainty instance with a given name to the list of qualifiers in a qualified representation item. Then the function sets the numeric value to the given number and returns the standard_uncertainty.

If the numeric value is ROSE_NULL_REAL, any existing standard_uncertainty qualifier with that name name will be removed and the function will return null. This function is the general form of the stix_measure_put_lower_limit() and stix_measure_put_upper_limit() functions.

## stix_measure_put_upper_limit()

```stp_standard_uncertainty * stix_measure_put_upper_limit(
stp_qualified_representation_item * it,
double limval
);
```

The stix_measure_put_upper_limit() function finds or adds a standard_uncertainty instance with a name of "upper limit" to the list of qualifiers in a qualified representation item. Then the function sets the numeric value to the given number and returns the standard_uncertainty. If the numeric value is ROSE_NULL_REAL, any existing upper limit will be removed.

Use stix_measure_make_qualified_item() to create a measure instance that can hold an upper or lower limit.