Numeric Methods

CXL provides 8 built-in methods for numeric operations. These methods work on both Integer and Float values (the Numeric receiver type). All return null when the receiver is null.

abs, ceil, floor, round, and round_to also accept an exact decimal receiver and return an exact decimal result — d.round(2) rounds d to two fractional digits using banker’s rounding, staying in the decimal domain rather than converting to a float. The type checker infers decimal for these calls as well, so the result composes with other decimals without a cast: amount.round_to(2) + fee typechecks when both columns are decimal.

abs() -> Numeric

Returns the absolute value. Preserves the original type (Int stays Int, Float stays Float).

$ cxl eval -e 'emit result = (-42).abs()'

{
  "result": 42
}

$ cxl eval -e 'emit result = (-3.14).abs()'

{
  "result": 3.14
}

ceil() -> Int

Rounds up to the nearest integer. Returns the value unchanged for integers.

$ cxl eval -e 'emit result = 3.2.ceil()'

{
  "result": 4
}

$ cxl eval -e 'emit result = (-3.2).ceil()'

{
  "result": -3
}

floor() -> Int

Rounds down to the nearest integer. Returns the value unchanged for integers.

$ cxl eval -e 'emit result = 3.8.floor()'

{
  "result": 3
}

$ cxl eval -e 'emit result = (-3.2).floor()'

{
  "result": -4
}

round([decimals: Int]) -> Float

Rounds to the specified number of decimal places. Default is 0 decimal places. On a decimal receiver the result is a decimal (exact banker’s rounding), not a float.

$ cxl eval -e 'emit result = 3.456.round()'

{
  "result": 3.0
}

$ cxl eval -e 'emit result = 3.456.round(2)'

{
  "result": 3.46
}

round_to(decimals: Int) -> Float

Rounds to the specified number of decimal places. Unlike round(), the decimals argument is required. On a decimal receiver the result is a decimal (exact banker’s rounding), not a float.

$ cxl eval -e 'emit result = 3.14159.round_to(3)'

{
  "result": 3.142
}

Use round_to when you want to be explicit about precision in financial or scientific calculations:

$ cxl eval -e 'emit price = 19.995.round_to(2)'

{
  "price": 20.0
}

clamp(min: Numeric, max: Numeric) -> Numeric

Constrains the value to the given range. Returns min if the value is below it, max if above, or the value itself if within range.

$ cxl eval -e 'emit result = 150.clamp(0, 100)'

{
  "result": 100
}

$ cxl eval -e 'emit result = (-5).clamp(0, 100)'

{
  "result": 0
}

$ cxl eval -e 'emit result = 50.clamp(0, 100)'

{
  "result": 50
}

min(other: Numeric) -> Numeric

Returns the smaller of the receiver and the argument.

$ cxl eval -e 'emit result = 10.min(20)'

{
  "result": 10
}

$ cxl eval -e 'emit result = 10.min(5)'

{
  "result": 5
}

max(other: Numeric) -> Numeric

Returns the larger of the receiver and the argument.

$ cxl eval -e 'emit result = 10.max(20)'

{
  "result": 20
}

$ cxl eval -e 'emit result = 10.max(5)'

{
  "result": 10
}

Practical examples

Clamp a percentage:

emit pct = (completed / total * 100).clamp(0, 100).round_to(1)

Absolute difference:

emit diff = (actual - expected).abs()

Floor division for batch numbering:

emit batch = (row_number / 1000).floor()