Automatic Numeric Type Conversion
Code Effects converts numeric types automatically during both rule authoring and rule evaluation. Rule authors can work with compatible numeric values without the exact CLR types matching in the source object.
The compatibility depends on how a value is used in a rule. Rule conditions are permissive, and the parameters of in-rule methods and rule actions, value setters, collections, and arrays are stricter.
NOTE: This article describes the conversion between numeric types only. Nullable compatibility is described separately and can add restrictions. See Nullable Value Support.
Supported Numeric Types
The conversion applies to these numeric types:
byte, sbyte
short, ushort
int, uint
long, ulong
float, double
decimal
Their nullable forms take part as well. Other numeric types, such as Half and Int128, are not supported. See Working Around Unsupported Types.
Numeric Conversion in Rule Conditions
A rule condition can compare numeric fields, properties, and method return values of any numeric types. For example:
int = decimal
short < long
double >= decimal
float = int
When it evaluates a condition, the Evaluator casts both operands to decimal and applies the operator to the two decimals. Every numeric type that Code Effects supports converts to decimal, so rule authors can compare integers and decimals in conditions without matching the types.
Numeric Conversion Outside Conditions
Numeric values used anywhere else follow stricter rules:
- Parameters of in-rule methods
- Parameters of rule actions
- Value setters in execution type rules
- Collections of numeric items
- Arrays
The value that the author gives must be compatible with the target type. The editor does not offer every number for every target.
Every numeric rule element has the AllowDecimals setting, which says whether the value can have a fractional part. With a class as the source object the editor sets it from the CLR type of the member (float, double, and decimal allow decimals, and the integer types do not), so you do not set it in the Field attribute. The editor uses it to avoid a conversion that would drop the fractional part. A value that allows decimals is not offered where an integer is required, because 12.5 cannot become an int, a long, or a short without a loss. An integer value can be used where a decimal is accepted, if the other requirements are met.
Numeric Range Compatibility
Every numeric rule element has a minimum and a maximum that describe its valid range, and the editor checks them everywhere: in conditions, parameters, action parameters, setters, collections, and arrays. It compares the ranges while it builds a menu, and offers only the elements whose range is compatible with the selected one:
using CodeEffects.Rule.Common.Attributes;
using CodeEffects.Rule.Common.Models;
using CodeEffects.Rule.Editor.Client;
// Adaptive Source
var field = new Field
{
Value = "User.UserID",
DisplayName = "User ID",
DataType = DataType.Numeric,
Nullable = true,
Settings = new Settings
{
Min = 0,
Max = 1000000,
AllowDecimals = false
}
};
// Reflection source
[Field(DisplayName = "User ID", Min = 0, Max = 1000000)]
public int? UserID { get; set; }
An int converts to decimal, but a value limited to 0 to 20 is not compatible with one limited to 100 to 200, because no value of the first can satisfy the second.
Two ranges are compatible when they overlap or touch at a boundary. 0–20 and 20–100 are compatible, because they share the value 20.
When a member has no Min and Max, the range is the range of its type. Types wider than a browser can calculate with, long, ulong, float, double, and decimal, get plus and minus 9007199254740992 (2^53), and the unsigned types start at 0.
Evaluation Behavior
The editor checks the metadata of the members to filter its menus while a rule is written. The Evaluator does the actual CLR conversions when it compiles a rule. A conversion that fails at that moment throws the exception that equivalent .NET code throws, such as an OverflowException when a value is outside the range of the target type. The Min and Max properties are used by the editor only, and the engine does not check them.
Important Considerations
The automatic conversion does not make Code Effects loosely typed. The editor prevents invalid choices while a rule is written, as far as it can, and the Evaluator converts only the values that meet the compatibility rules.
When the documentation mentions decimal, read it as "decimal and any numeric type that converts to decimal by the rules in this article". The same is true of every numeric type.
Conditions are permissive because both operands become decimal before the comparison. The other operations are strict because they pass values to specific parameters, assign values to specific fields, or use values of specific collection or array item types.
Summary
- Numeric values in conditions are compared regardless of their types.
- The engine converts both operands of a condition to
decimal.
- Parameters, action parameters, setters, collections, and arrays require compatible numeric types.
- Minimum and maximum ranges apply to every numeric rule element and are compatible when they overlap or touch.
AllowDecimals keeps fractions out of integer targets.
- The
Evaluator does the actual CLR conversions when it compiles a rule, and can throw an OverflowException.