Numbers

Integers and floats to rule the world!

There are two basic kinds of numbers in BoxLang: integers (whole numbers) and floats (have a decimal point). BoxLang provides sophisticated number handling with automatic type promotion and high-precision arithmetic.

🔢 Number Types

BoxLang uses Java's numeric types internally:

Type	Size (bits)	Range	Usage
Integer	32	-2,147,483,648 to 2,147,483,647	Whole numbers
Long	64	-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807	Large whole numbers
Double	64	±4.9E-324 to ±1.7976931348623157E308	Decimal numbers (15-16 digits precision)
BigDecimal	Arbitrary	Unlimited precision	High-precision calculations, currency
BigInteger	Arbitrary	Unlimited size	Very large whole numbers

🎯 Type Promotion & Type Contagion

BoxLang is smart enough to automatically promote numeric types at runtime with no need for explicit casting. This is called type contagion - when you mix different numeric types in an operation, BoxLang automatically promotes to the most appropriate type:

// Integer operations stay as integers
result = 10 + 5  // Integer: 15

// Mixing integer and decimal promotes to decimal
result = 10 + 5.5  // Double: 15.5

// Large numbers automatically become BigDecimal/BigInteger
result = 111111111111111111111111111 + 222222222222222222222222222
// BigInteger: 333333333333333333333333333

// Decimal operations use BigDecimal for precision
result = 0.1 + 0.2  // BigDecimal: 0.3 (not 0.30000000000000004!)

// Mixed operations promote to the highest precision type
intVal = 10
doubleVal = 5.5
bigDecVal = 100.123456789
result = intVal + doubleVal + bigDecVal  // BigDecimal

No Precision Loss! BoxLang automatically uses BigDecimal for decimal operations to avoid floating-point precision issues. For example, (0.1 + 0.2) correctly returns 0.3, not 0.30000000000000004 like in other languages.

⚡ High Precision Math

High precision math is enabled by default in BoxLang! This means BoxLang automatically uses BigDecimal for decimal arithmetic to maintain precision:

// Automatic high precision
result = 1.0 / 3.0  // BigDecimal with full precision

// No precision loss in calculations
total = 0.1 + 0.2 + 0.3  // Exactly 0.6

// Currency calculations are safe
price = 19.99
quantity = 3
total = price * quantity  // Exactly 59.97

You can configure high precision math in your boxlang.json configuration:

{
    // By default BoxLang uses high-precision mathematics via BigDecimal operations
    // You can turn this off here for all applications
    "useHighPrecisionMath": true,
}

Configuration Options:

• highPrecisionMath - Enable/disable automatic BigDecimal usage (default: true)

• mathPrecision - Number of significant digits (default: 128)

• mathRoundingMode - Rounding strategy: HALF_UP, HALF_DOWN, CEILING, FLOOR, etc.

• Use the ortus.boxlang.runtime.types.util.MathUtil to change other parameters for high precision math.

💰 PrecisionEvaluate for Complex Expressions

For string-based math expressions requiring guaranteed precision, use precisionEvaluate(), or if you disable high precision math:

// Evaluate complex expressions with full precision
result = precisionEvaluate("1/3 + 2/3")  // Exactly 1.0
result = precisionEvaluate("(10.5 * 3) + (7.2 / 4)")  // Precise calculation

precisionEvaluate() works with +, -, *, /, (), and MOD operators. Other operators (^, %, \) will use standard precision.

Learn more about precisionEvaluate()

🧮 Basic Arithmetic

a = 1
b = 50.1
writeOutput( a * b )  // 50.1 (automatic type promotion)

// All basic operations
sum = 10 + 5        // 15
diff = 10 - 5       // 5
product = 10 * 5    // 50
quotient = 10 / 5   // 2
power = 10 ^ 2      // 100
modulo = 10 % 3     // 1

Try it online!

🏷️ The numeric Type

When typing function arguments and return values, use the numeric type instead of specific types like integer or double. This allows BoxLang's type promotion to work naturally:

numeric function add( numeric a, numeric b ) {
    return a + b
}

// Works with any numeric type
result = add(10, 5)           // Integer inputs
result = add(10.5, 5.2)       // Double inputs
result = add(10, 5.5)         // Mixed inputs - automatic promotion

Try it online!

📚 Mathematical Built-In Functions (BIFs)

BoxLang provides comprehensive mathematical functions organized by category:

🔢 Basic Math Operations

Function	Purpose	Example
abs()	Absolute value	abs(-5) → 5
ceiling()	Round up to integer	ceiling(4.3) → 5
floor()	Round down to integer	floor(4.7) → 4
round()	Round to nearest integer/decimal	round(4.567, 2) → 4.57
fix()	Convert to integer (truncate)	fix(4.7) → 4
int()	Closest smaller integer	int(4.7) → 4
sgn()	Sign of number (-1, 0, 1)	sgn(-5) → -1
max()	Maximum of two numbers	max(10, 20) → 20
min()	Minimum of two numbers	min(10, 20) → 10

📐 Trigonometric Functions

Function	Purpose	Example
sin()	Sine (radians)	sin(pi()/2) → 1
cos()	Cosine (radians)	cos(0) → 1
tan()	Tangent (radians)	tan(pi()/4) → 1
asin()	Arc sine (inverse)	asin(1) → 1.5708
acos()	Arc cosine (inverse)	acos(1) → 0
atn()	Arc tangent (inverse)	atn(1) → 0.7854
pi()	Value of π	pi() → 3.14159...

📊 Exponential & Logarithmic

Function	Purpose	Example
exp()	Exponential (e^x)	exp(1) → 2.71828
log()	Natural logarithm	log(10) → 2.302585
log10()	Base-10 logarithm	log10(100) → 2
sqr()	Square root	sqr(16) → 4

🎲 Random Number Generation

Function	Purpose	Example
rand()	Random float (0 to 1)	rand() → 0.742351
randRange()	Random integer in range	randRange(1, 100) → 42
randomize()	Seed random generator	randomize(12345)

🔧 Number Manipulation

Function	Purpose	Example
incrementValue()	Increment integer part	incrementValue(4.7) → 5.7
decrementValue()	Decrement integer part	decrementValue(4.7) → 3.7
formatBaseN()	Convert to base-N string	formatBaseN(255, 16) → \"FF\"
inputBaseN()	Parse base-N string	inputBaseN(\"FF\", 16) → 255

🔨 Bitwise Operations

Function	Purpose	Example
bitAnd()	Bitwise AND	bitAnd(12, 10) → 8
bitOr()	Bitwise OR	bitOr(12, 10) → 14
bitXor()	Bitwise XOR	bitXor(12, 10) → 6
bitNot()	Bitwise NOT	bitNot(12) → -13
bitSHLN()	Shift left	bitSHLN(5, 2) → 20
bitSHRN()	Shift right	bitSHRN(20, 2) → 5
bitMaskSet()	Set bits in mask	bitMaskSet(0, 0, 3) → 7
bitMaskClear()	Clear bits in mask	bitMaskClear(7, 0, 2) → 4
bitMaskRead()	Read bits from mask	bitMaskRead(7, 0, 2) → 3

🎯 High Precision

Function	Purpose	Example
precisionEvaluate()	Evaluate with BigDecimal	precisionEvaluate(\"1/3 + 2/3\") → 1.0

Complete Reference: For detailed documentation of each function, visit the Math BIF Reference.

⚙️ Member Functions

All numeric BIFs can be called as member functions on number variables:

num = 42.7

// Basic math
num.abs()           // 42.7
num.ceiling()       // 43
num.floor()         // 42
num.round()         // 43
num.round(1)        // 42.7
num.sgn()           // 1

// Trigonometric
angle = 1.5708
angle.sin()         // 1.0
angle.cos()         // 0.0
angle.tan()         // Infinity

// Logarithmic
num.log()           // Natural log
num.log10()         // Base-10 log
num.exp()           // e^num
num.sqr()           // Square root

// Comparison
num.max(50)         // 50
num.min(50)         // 42.7

// Manipulation
num.incrementValue() // 43.7
num.decrementValue() // 41.7
num.fix()           // 42
num.int()           // 42

Java Number Methods

Since BoxLang numbers are Java objects, you also have access to Java methods:

import java.lang.Math
import java.math.BigDecimal

// Integer/Long methods
num = 42
num.toString()              // "42"
num.longValue()             // 42L
num.doubleValue()           // 42.0
Math.abs(num)              // 42

// BigDecimal methods (when using high precision)
bigNum = 123.456789
bigNum.scale()              // Number of decimal places
bigNum.precision()          // Total significant digits
bigNum.add(10)             // 133.456789
bigNum.subtract(3)         // 120.456789
bigNum.multiply(2)         // 246.913578
bigNum.divide(3, 10)       // Divide with scale
bigNum.setScale(2)         // Round to 2 decimals

// Math class methods
Math.sqrt(16)              // 4.0
Math.pow(2, 8)             // 256.0
Math.random()              // Random 0.0-1.0
Math.ceil(4.3)             // 5.0
Math.floor(4.7)            // 4.0
Math.round(4.5)            // 5

🔄 Casting/Parsing

While BoxLang automatically handles type promotion, you can explicitly convert values to numbers:

// Basic conversion
toNumeric("29.5")                // 29.5
toNumeric("42")                  // 42

// Different radix/base conversions
toNumeric("FF", "hex")          // 255 (hexadecimal)
toNumeric("1010", "bin")        // 10 (binary)
toNumeric("77", "oct")          // 63 (octal)

// Parse with radix
val("123abc")                    // 123 (extracts leading number)
inputBaseN("FF", 16)            // 255 (hex to decimal)
formatBaseN(255, 16)            // "FF" (decimal to hex)

The parseNumber() function converts strings to numbers in different numeral systems:

parseNumber("1,234.56", "en")   // 1234.56
parseNumber("1.234,56", "de")   // 1234.56 (German format)

Learn more about parseNumber()

Radix/Base Systems: A radix (or base) is the number of unique digits used to represent numbers. Common systems: decimal (base 10: 0-9), binary (base 2: 0-1), octal (base 8: 0-7), hexadecimal (base 16: 0-9, A-F).

Try it online!

✅ Is it a number?

Use isNumeric() to check if a value can be converted to a number:

isNumeric(23)           // true
isNumeric("42")         // true
isNumeric("42.5")       // true
isNumeric("twenty")     // false
isNumeric(5e2)          // true (scientific notation)
isNumeric("0xFF")       // true (hex literal)
isNumeric("1,234.56")   // false (contains comma)
isNumeric(true)         // true (true = 1, false = 0)

Try it online!

🔁 Looping with Numbers

Numbers are commonly used in loops for repetition and iteration:

// For loop
for (var i = 1; i <= 10; i++) {
    writeOutput("Day #i#")
}

// While loop
i = 1
while (i <= 10) {
    writeOutput("Day #i#")
    i++
}

// Loop construct
loop from="1" to="10" index="i" {
    writeOutput("Day #i#")
}

// Times helper
10.times((i) => {
    writeOutput("Iteration #i#")
})

BoxLang provides multiple looping constructs. You can also iterate over arrays, structures, queries, and objects. See the Loop component reference for details.

Try it online!

🔗 Related Documentation

• Math BIF Reference - Complete list of mathematical functions

• Numeric Type Reference - Member function documentation

• Operators - Arithmetic and bitwise operators

• Java Number API - Native Java methods

• Java BigDecimal API - High precision arithmetic

• Java Math API - Java Math class methods