RoundingRuleEx

You can use the RoundingRuleEx function to round a parameter value according to a rule defined in the Rounding Rule form.

Note: The function returns a RoundingRuleResult object containing the rounded value and operation status.

The RoundingRuleEx function addresses limitations in the error handling of the RoundingRule function. For example, when a parameter is not listed or the rounding rule code is invalid, the function returns 0 instead of an error code. However, 0 can be a valid result in some cases.

When to use

You can use this function to:

  • Apply regulatory rounding rules for nutrition facts labels, such as FDA rounding rules.
  • Round parameter values according to business rules before displaying values to users or in reports.
  • Round calculated values according to defined precision rules in equations.

Syntax

RoundingRuleResult RoundingRuleEx(double wholeValue, string paramCode = "", string ruleCode = "", int additionalIncrements = 0);

Parameters

Parameter Type Required Description
WholeValue double Yes The numeric value to be rounded.
Note: Typically a minimum or a maximum parameter value or calculated result.
ParamCode string Conditional* Parameter name/code to be rounded.
Note: May be omitted in equations but mandatory in workflows.
RuleCode string Yes The rounding rule code that references a rule defined in the Rounding Rule form.
Note:  Function throws exception if not provided.
AdditionalIncrements int No The integer to add extra increments beyond the rules standard rounding logic.
Note: By default, the value is 0.

Return Value

The application returns a RoundingRuleResult object with the following properties:

Property Type Description
RoundedValue double The rounded value.
OriginalValue double The original value passed to the function.
RoundingOperationResult int
  • The operation status code. A value greater than 0 indicates success.
  • A value less than or equal to 0 indicates an error.

Prerequisites

  • The rounding rules must be defined in the Rounding Rule form.
  • The function always returns a RoundingRuleResult object. Check the RoundingOperationResult status before using the rounded value.

Examples

Example 1
Round Parameter Value Using Rounding Rule. 
// Round multiple nutrition parameters using different rules
public int RunRoundingTests()
{
    double dProt = 26.5;
    RoundingRuleResult dRoundProt = RoundingRuleEx(dProt, "PROTEIN", "PVTEST");

    MessageList("Passing test:");
    if (dRoundProt.RoundingOperationResult > 0)
    {
        MessageList("Result is " + dRoundProt.RoundedValue);
    }
    else
    {
        MessageList("Error rounding, leave value as " + dRoundProt.OriginalValue);
    }

    MessageList("Bad Parameter test");
    dRoundProt = RoundingRuleEx(dProt, "PROTEINX", "PVTEST");
    if (dRoundProt.RoundingOperationResult > 0)
    {
        MessageList("Result is " + dRoundProt.RoundedValue);
    }
    else
    {
        MessageList("Error rounding, leave value as " + dRoundProt.OriginalValue);
    }

    MessageList("Bad Rule test");
    RoundingRuleResult dRoundProtBad2 = RoundingRuleEx(dProt, "PROTEIN", "PWTEST");
    if (dRoundProtBad2.RoundingOperationResult > 0)
    {
        MessageList("Result is " + dRoundProtBad2.RoundedValue);
    }
    else
    {
        MessageList("Error rounding, leave value as " + dRoundProtBad2.OriginalValue);
    }

    return 111;
}
Description
This example shows rounding the value of the TEST parameter using the parameter value rounding code of PVTEST.
Related topics