Introducing High-Precision Math and Big Number Support in BoxLang!

In our latest BoxLang beta, we've rolled out some exciting new features designed to make BoxLang work more naturally out-of-the-box, particularly when dealing with high precision and big numbers. But what does this mean for developers? Let's dive in!

Big Numbers: Handling Large Values with Ease

First up, let's talk about big numbers. As ColdFusion developers, you might not often think about Java’s underlying numeric datatypes, but understanding them can help you appreciate the improvements we've made in BoxLang.

Java offers various numeric types like Integer, Long, and Double, each with its own storage limits. For example, a Double can handle around 17 digits of information. However, when dealing with larger numbers, Java approximates by storing a value like 123123123123123123123123123 as 1.2312312312312312E26, meaning some digits are lost.

This limitation can lead to inaccurate results in math operations, as seen in ColdFusion:

javascriptCopy code
11111111111111111111 + 22222222222222222222

• Windows Calculator: 33333333333333333333
• Lucee 5: 33333333333333330000 ← Data lost
• Adobe CF 2023: 3.33333333333E+019 ← Data lost
• BoxLang: 33333333333333333333
• Lucee 6: 33333333333333333333

As you can see, BoxLang and Lucee 6 handle large numbers seamlessly, ensuring that all digits are preserved without requiring special handling or unsafe precision evaluation.

High-Precision Floating Point: Accurate Math Operations

The phrase "high precision" might sound like jargon, but it's an issue many developers face. Certain decimal values, despite appearing simple, cannot be stored accurately as floating point numbers due to the nature of binary representation. For instance, consider the fraction 1/3 in decimal:

0.3333333333333333...

The same challenge occurs with decimal values like 0.1 when represented in binary. This is why seemingly straightforward calculations like:

(.1 + .2).toString()

Can yield unexpected results:

• Lucee 5: 0.30000000000000004 ← Precision error
• Adobe CF 2023: 0.30000000000000004 ← Precision error
• BoxLang: 0.3
• Lucee 6: 0.3

BoxLang, like Lucee 6, avoids precision loss, providing accurate results for your floating point operations.

BigDecimal: Your New Best Friend for Precision

Enter BigDecimal, a Java class designed to handle both large numbers and high precision floating point values. We've followed Lucee’s lead by introducing automatic type promotion to BigDecimal where necessary, ensuring your math operations "just work" without needing to worry about what’s happening behind the scenes.

Moreover, Java’s BigDecimal allows you to set the level of precision. While Java 21 defaults to "unlimited" precision, we've opted for the IEEE 754-2019 decimal128 format with 34 digits of precision, offering a balance between accuracy and performance.

Smart Parsing: Precision Where It Matters

Unlike Lucee 6, which uses BigDecimal across the board, BoxLang takes a more nuanced approach. Our smart parser stores numbers in the smallest possible type and promotes them only when necessary:

• Integer: For numbers smaller than 10 digits.
• Long: For numbers smaller than 20 digits.
• BigDecimal: For larger numbers and all floating point values.

This approach ensures that your applications remain fast and efficient while still benefiting from the precision of BigDecimal when needed.

Balancing Precision and Performance

While BigDecimal offers significant advantages, it does come with some trade-offs. BigDecimal objects take up more memory and require slightly more time for math operations than primitive types. However, the overhead is minimal and often negligible in modern applications.

For example, one million floating point operations might take 4-6 milliseconds with Double and 5-9 milliseconds with BigDecimal. The impact on performance is minimal, and the accuracy gained is well worth it.

Opting Out: Flexibility for Your Needs

We understand that not every application needs high precision math. That's why we've included a toggle in your boxlang.json:

"useHighPrecisionMath": false

Setting this flag allows you to revert to using Java Double for large numbers and decimals, trading precision for the performance you’re familiar with.

Conclusion

With the latest BoxLang beta, we're excited to offer you more precise and reliable math operations right out-of-the-box. Whether you're dealing with big numbers or floating point math, BoxLang ensures that your calculations are accurate and efficient. And if you ever find you don’t need the extra precision, you have the flexibility to dial it back.

Stay tuned for more updates as we continue to refine and enhance BoxLang to meet your development needs!