In Range and Coerce Function

LabVIEW 2011 Help

Edition Date: June 2011

Part Number: 371361H-01

»View Product Info

Owning Palette: Comparison Functions

Requires: Base Package

Determines whether x falls within a range specified by the upper limit and lower limit inputs and optionally coerces the value to fall within the range. The function performs the coercion only in Compare Elements mode. This function accepts time stamp values if all inputs are time stamp values. You can change the comparison mode of this function.

The connector pane displays the default data types for this polymorphic function.

Details Example

	upper limit, x, and lower limit should usually be of the same data type structure, either arrays or clusters, but they can have different numeric representations. For example, if you change one of the data types to an array, you must change the remaining data types to arrays to avoid broken wires. However, you can wire an array to x and two scalars to upper limit and lower limit. You also can wire double-precision, floating-point and integer data.
	coerced(x) returns the coerced or unchanged value of x. If x is within the range set by the upper limit and lower limit inputs or if the function is in Compare Aggregates mode, the value is unchanged. If x is not in range and the function is in Compare Elements mode, the function converts the value to the same value as upper limit or lower limit. If upper limit, x, or lower limit is NaN, coerced(x) is NaN.
	In Range? is a Boolean value in Compare Aggregates mode. In Compare Elements mode, the data type structure of In Range? matches the data type structure of x, with each scalar replaced by a Boolean value. If upper limit, x, or lower limit is NaN, In Range? is FALSE.

In Range and Coerce Details

This function compares the input data values according to the Boolean comparison rules. If the function is in Compare Aggregates mode, it returns the unchanged value of x in coerced(x) rather than a coerced value. The function considers each input array as a single aggregate object, similar to a cluster, where the first element is primary in the comparison. If x is greater than upper limit and the function is in Compare Elements mode (default), the function coerces x to the upper limit value. If x is less than lower limit and the function is in Compare Elements mode, the function coerces x to the lower limit value.

In the case of numeric values, the upper limit, lower limit, and x inputs do not have to be the same data type representation. If you wire a combination of signed and unsigned integers to the upper limit, x, and lower limit inputs of the In Range and Coerce function, the data type of the coerced(x) output must be large enough to represent the full range of possible input values. If the coerced(x) output is an unsigned integer, the signed input values must be positive because an unsigned integer cannot represent a negative number.

By default, In Range And Coerce includes the lower limit value in the range, as indicated by the solid black diamond at the lower limit input. By default, the upper limit value is not included in the range, as indicated by the empty diamond at the upper limit input.

To change whether the function includes the value wired to upper limit or lower limit, right-click the function and select Include upper limit or Include lower limit from the shortcut menu to include or remove the value in the range. These options only affect the result of In Range?. The function always coerces x to the exact values of upper limit or lower limit, regardless of whether you select Include upper limit or Include lower limit from the shortcut menu.

If the lower limit value is greater than the upper limit value, LabVIEW switches the values internally without displaying an error message. If the function is in Compare Elements mode, it still coerces x to either the upper limit or lower limit value. However, In Range? is always FALSE, even if x is between the lower and upper limits.

Example

Refer to the In Range and Coerce VI in the labview\examples\general\functions\Comparison directory for an example of using the In Range and Coerce function.