In Range and Coerce Function

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.

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.

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


icon

Inputs/Outputs

  • cdbl.png upper limit —

    upper limit of the range.

  • cdbl.png x —

    x is the value to check and/or coerce.

  • cdbl.png lower limit —

    lower limit of the range.

  • idbl.png coerced(x) —

    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.

  • ibool.png In Range? —

    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.

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

    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, all of the inputs will be coerced to the same unsigned integer type. This can lead to unexpected results for negative input values. For example, wiring an unsigned integer to upper limit and a negative signed integer to lower limit may cause LabVIEW to interpret the lower limit input as larger than the upper limit input. To avoid this issue, convert integer inputs to the same type before you wire them to the In Range and Coerce function.

    If the lower limit value is greater than the upper limit value, In Range? is always FALSE and LabVIEW switches the lower limit value and the upper limit value internally before computing coerced(x).

    FPGA Module Details

    The following details apply when you use this object in an FPGA VI.

    Note The following details are subject to change with each version of the LabVIEW FPGA Module.
    Single-Cycle Timed Loop Supported.
    Usage

    If the value of lower limit is greater than the value of upper limit, LabVIEW does not swap the values of lower limit and upper limit. You must change the values of lower limit and upper limit manually if you do not want the value of lower limit to be greater than the value of upper limit.

    You cannot wire an array or cluster to this function in a single-cycle Timed Loop.

    If you use this function with the single-precision floating-point data type, refer to the Using the Single-Precision Floating-Point Data Type and Deciding Which Data Type to Use in FPGA Designs topics for resource use, latency, and single-cycle Timed Loop support implications.
    Timing

    Inside single-cycle Timed Loop--When you use Comparison functions inside a single-cycle Timed Loop, the combinatorial logic delay is proportional to the width of the data types you compare.

    Outside single-cycle Timed Loop--When you use Comparison functions outside a single-cycle Timed Loop, each Comparison function takes one clock cycle.

    If you use the Comparison functions with the fixed-point data type, the overflow and rounding modes might impact timing.

    Resources The Comparison functions use FPGA resources in proportion to the width of the data types you compare.

    Examples

    Refer to the following example files included with LabVIEW.

    • labview\examples\Comparison\In Range and Coerce.vi