feat: add division configuration system with strategies and precision scales

Author: nguyenphuc22

CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.17] - 2025-01-XX
+
+### Added
+- **Division Configuration System**: New helper objects to make division operations more intuitive and type-safe
+  - `PrecisionScale` object with constants for common decimal place requirements:
+    - `CURRENCY` (2 decimals) - for money calculations
+    - `EXCHANGE_RATE` (4 decimals) - for forex/currency conversion
+    - `PERCENTAGE` (2 decimals) - for percentage calculations
+    - `SCIENTIFIC` (10 decimals) - for scientific computations
+    - `HIGH_PRECISION` (20 decimals) - for very precise calculations
+    - `INTEREST_RATE` (6 decimals) - for interest rate calculations
+    - `CRYPTOCURRENCY` (8 decimals) - for Bitcoin and crypto calculations
+  - `DivisionConfig` data class that combines scale and rounding mode
+  - `DivisionStrategy` object with predefined division strategies:
+    - `CURRENCY` - 2 decimals with HALF_UP rounding
+    - `FINANCIAL` - 2 decimals with HALF_EVEN (banker's) rounding
+    - `EXCHANGE_RATE` - 4 decimals with HALF_UP rounding
+    - `PERCENTAGE` - 2 decimals with HALF_UP rounding
+    - `SCIENTIFIC` - 10 decimals with HALF_UP rounding
+    - `HIGH_PRECISION` - 20 decimals with HALF_UP rounding
+    - `INTEREST_RATE` - 6 decimals with HALF_UP rounding
+    - `CRYPTOCURRENCY` - 8 decimals with HALF_UP rounding
+    - `EXACT` - requires exact result or throws ArithmeticException
+  - New `divide(other: KBigDecimal, config: DivisionConfig)` overload for cleaner division syntax
+
+### Changed
+- **Improved Division API**: Clients can now use predefined strategies instead of manually specifying scale and rounding mode
+
+### Example Usage
+```kotlin
+// Before
+val result = price.divide(quantity, 2, RoundingMode.HALF_UP)
+
+// After - using strategy
+val result = price.divide(quantity, DivisionStrategy.CURRENCY)
+
+// After - using custom config
+val result = price.divide(quantity, DivisionConfig(scale = 4, roundingMode = RoundingMode.HALF_EVEN))
+
+// Using scale constants
+val result = price.divide(quantity, PrecisionScale.CRYPTOCURRENCY, RoundingMode.HALF_UP)
+```
+
+## [0.0.16] - 2025-01-XX
+
+### Fixed
+- Enhanced KBigDecimal division for precision and special cases
+- Added single-parameter divide function with automatic scale determination
+
+### Changed
+- Updated documentation to include new single-parameter divide function
+
+## [0.0.1] - Initial Release
+
+### Added
+- `KBigDecimal` interface for arbitrary precision decimal arithmetic
+- `KBigInteger` interface for arbitrary precision integer arithmetic
+- `KBigMath` utility class for advanced mathematical operations
+- Operator overloading support for natural mathematical syntax
+- Extension functions for easy type conversion
+- Factory methods for creating big numbers from various types
+- Comprehensive test coverage
+- Android and iOS platform support
+- Support for basic arithmetic operations (add, subtract, multiply, divide)
+- Support for advanced operations (sqrt, factorial, gcd, lcm, isPrime, pow)
+- Rounding mode support for decimal operations
+- Platform-optimized implementations using native libraries
+
+[Unreleased]: https://github.com/gatrongdev/kbignum/compare/v0.0.17...HEAD
+[0.0.17]: https://github.com/gatrongdev/kbignum/compare/v0.0.16...v0.0.17
+[0.0.16]: https://github.com/gatrongdev/kbignum/releases/tag/v0.0.16
+[0.0.1]: https://github.com/gatrongdev/kbignum/releases/tag/v0.0.1

README.md

@@ -27,7 +27,7 @@ Add to your `build.gradle.kts`:
 
 ```kotlin
 dependencies {
-    implementation("io.github.gatrongdev:kbignum:0.0.1")
+    implementation("io.github.gatrongdev:kbignum:0.0.17")
 }
 ```
 
@@ -37,7 +37,7 @@ Add to your `build.gradle`:
 
 ```gradle
 dependencies {
-    implementation 'io.github.gatrongdev:kbignum:0.0.1'
+    implementation 'io.github.gatrongdev:kbignum:0.0.17'
 }
 ```
 
@@ -57,8 +57,16 @@ val bigInteger = "12345678901234567890".toKBigInteger()
 val sum = bigDecimal1 + bigDecimal2
 val difference = bigDecimal1 - bigDecimal2
 val product = bigDecimal1 * bigDecimal2
-val quotient = bigDecimal1.divide(bigDecimal2, 10) // 10 decimal places
-val simpleQuotient = bigDecimal1.divide(bigDecimal2) // uses automatic scale
+
+// Division with automatic scale
+val simpleQuotient = bigDecimal1.divide(bigDecimal2)
+
+// Division with predefined strategies (v0.0.17+)
+val currencyResult = bigDecimal1.divide(bigDecimal2, DivisionStrategy.CURRENCY)
+val preciseResult = bigDecimal1.divide(bigDecimal2, DivisionStrategy.SCIENTIFIC)
+
+// Division with custom configuration
+val customResult = bigDecimal1.divide(bigDecimal2, DivisionConfig(scale = 10, roundingMode = RoundingMode.HALF_UP))
 
 // Advanced operations
 val sqrt = KBigMath.sqrt(bigDecimal1, 10)
@@ -92,6 +100,18 @@ val power = KBigMath.pow(bigDecimal1, 5)
 // Precision control
 val scaled = bigDecimal1.setScale(5, RoundingMode.HALF_UP)
 val precision = bigDecimal1.precision()
+
+// Division strategies (v0.0.17+)
+val price = "100.00".toKBigDecimal()
+val quantity = "3".toKBigDecimal()
+
+// Use predefined strategies
+val pricePerItem = price.divide(quantity, DivisionStrategy.CURRENCY)       // 33.33
+val exchangeRate = price.divide(quantity, DivisionStrategy.EXCHANGE_RATE)  // 33.3333
+val cryptoAmount = price.divide(quantity, DivisionStrategy.CRYPTOCURRENCY) // 33.33333333
+
+// Use precision scale constants
+val interestRate = price.divide(quantity, PrecisionScale.INTEREST_RATE, RoundingMode.HALF_UP)
 ```
 
 ## API Reference
@@ -105,10 +125,27 @@ Interface for arbitrary precision decimal numbers:
 - `multiply(other: KBigDecimal): KBigDecimal`
 - `divide(other: KBigDecimal): KBigDecimal`
 - `divide(other: KBigDecimal, scale: Int): KBigDecimal`
+- `divide(other: KBigDecimal, scale: Int, mode: Int): KBigDecimal`
+- `divide(other: KBigDecimal, config: DivisionConfig): KBigDecimal` *(v0.0.17+)*
 - `abs(): KBigDecimal`
 - `signum(): Int`
 - `setScale(scale: Int, roundingMode: Int): KBigDecimal`
 
+### Division Helpers (v0.0.17+)
+
+**PrecisionScale** - Constants for common decimal places:
+- `CURRENCY` (2), `EXCHANGE_RATE` (4), `PERCENTAGE` (2)
+- `SCIENTIFIC` (10), `HIGH_PRECISION` (20), `INTEREST_RATE` (6)
+- `CRYPTOCURRENCY` (8)
+
+**DivisionStrategy** - Predefined strategies:
+- `CURRENCY`, `FINANCIAL`, `EXCHANGE_RATE`, `PERCENTAGE`
+- `SCIENTIFIC`, `HIGH_PRECISION`, `INTEREST_RATE`
+- `CRYPTOCURRENCY`, `EXACT`
+
+**DivisionConfig** - Custom configuration:
+- `DivisionConfig(scale: Int, roundingMode: Int = RoundingMode.HALF_UP)`
+
 ### KBigInteger
 
 Interface for arbitrary precision integers:

shared/build.gradle.kts

@@ -17,7 +17,7 @@ plugins {
 }
 
 group = "io.github.gatrongdev"
-version = "0.0.16"
+version = "0.0.17"
 
 kotlin {
     androidTarget {

shared/src/commonMain/kotlin/io/github/gatrongdev/kbignum/math/KBigDecimal.kt

@@ -60,6 +60,34 @@ interface KBigDecimal : Comparable<KBigDecimal> {
         mode: Int,
     ): KBigDecimal
 
+    /**
+     * Returns a KBigDecimal that is the quotient of this divided by the specified value using a division configuration.
+     * This is a convenient method that accepts a DivisionConfig or DivisionStrategy preset.
+     *
+     * @param other The divisor
+     * @param config The division configuration specifying scale and rounding mode
+     * @return The result of the division with the configured scale and rounding mode
+     * @throws ArithmeticException if other is zero or if rounding is necessary but the rounding mode is UNNECESSARY
+     *
+     * Example usage:
+     * ```
+     * val price = "100.00".toKBigDecimal()
+     * val quantity = "3".toKBigDecimal()
+     *
+     * // Using predefined strategy
+     * val pricePerItem = price.divide(quantity, DivisionStrategy.CURRENCY)
+     * // Result: 33.33
+     *
+     * // Using custom config
+     * val result = price.divide(quantity, DivisionConfig(scale = 4, roundingMode = RoundingMode.HALF_EVEN))
+     * // Result: 33.3333
+     * ```
+     */
+    fun divide(
+        other: KBigDecimal,
+        config: DivisionConfig,
+    ): KBigDecimal = divide(other, config.scale, config.roundingMode)
+
     /**
      * Returns the absolute value of this KBigDecimal.
      * @return The absolute value (always non-negative)

shared/src/commonMain/kotlin/io/github/gatrongdev/kbignum/math/KBigNumberFactory.kt

@@ -117,3 +117,145 @@ object RoundingMode {
     /** Rounding mode to assert that the requested operation has an exact result */
     const val UNNECESSARY = 7
 }
+
+/**
+ * Precision scale constants for common use cases.
+ * These constants define standard decimal places for various types of calculations.
+ */
+object PrecisionScale {
+    /** Scale for currency calculations (2 decimal places) - e.g., $10.99 */
+    const val CURRENCY = 2
+
+    /** Scale for exchange rates (4 decimal places) - e.g., 1.2345 USD/EUR */
+    const val EXCHANGE_RATE = 4
+
+    /** Scale for percentage calculations (2 decimal places) - e.g., 12.34% */
+    const val PERCENTAGE = 2
+
+    /** Scale for high precision scientific calculations (10 decimal places) */
+    const val SCIENTIFIC = 10
+
+    /** Scale for very high precision calculations (20 decimal places) */
+    const val HIGH_PRECISION = 20
+
+    /** Scale for interest rate calculations (6 decimal places) */
+    const val INTEREST_RATE = 6
+
+    /** Scale for cryptocurrency calculations (8 decimal places) - e.g., BTC */
+    const val CRYPTOCURRENCY = 8
+}
+
+/**
+ * Configuration for division operations combining scale and rounding mode.
+ * @property scale Number of digits to the right of the decimal point
+ * @property roundingMode Rounding mode to apply (see RoundingMode constants)
+ */
+data class DivisionConfig(
+    val scale: Int,
+    val roundingMode: Int = RoundingMode.HALF_UP,
+)
+
+/**
+ * Predefined division strategies for common use cases.
+ * Each strategy combines a scale and rounding mode optimized for specific scenarios.
+ */
+object DivisionStrategy {
+    /**
+     * Currency division (2 decimal places, HALF_UP rounding).
+     * Suitable for: money calculations, prices, financial transactions.
+     * Example: $100 / 3 = $33.33
+     */
+    val CURRENCY =
+        DivisionConfig(
+            scale = PrecisionScale.CURRENCY,
+            roundingMode = RoundingMode.HALF_UP,
+        )
+
+    /**
+     * Financial division (2 decimal places, HALF_EVEN rounding).
+     * Suitable for: accounting, banking (banker's rounding for fairness).
+     * Example: reduces cumulative rounding bias in repeated calculations
+     */
+    val FINANCIAL =
+        DivisionConfig(
+            scale = PrecisionScale.CURRENCY,
+            roundingMode = RoundingMode.HALF_EVEN,
+        )
+
+    /**
+     * Exchange rate division (4 decimal places, HALF_UP rounding).
+     * Suitable for: currency conversion, forex calculations.
+     * Example: 100 USD / 1.2345 = 81.0037 EUR
+     */
+    val EXCHANGE_RATE =
+        DivisionConfig(
+            scale = PrecisionScale.EXCHANGE_RATE,
+            roundingMode = RoundingMode.HALF_UP,
+        )
+
+    /**
+     * Percentage division (2 decimal places, HALF_UP rounding).
+     * Suitable for: percentage calculations, ratios.
+     * Example: 50 / 3 = 16.67%
+     */
+    val PERCENTAGE =
+        DivisionConfig(
+            scale = PrecisionScale.PERCENTAGE,
+            roundingMode = RoundingMode.HALF_UP,
+        )
+
+    /**
+     * Scientific division (10 decimal places, HALF_UP rounding).
+     * Suitable for: scientific computations, engineering calculations.
+     * Example: high precision results for research
+     */
+    val SCIENTIFIC =
+        DivisionConfig(
+            scale = PrecisionScale.SCIENTIFIC,
+            roundingMode = RoundingMode.HALF_UP,
+        )
+
+    /**
+     * High precision division (20 decimal places, HALF_UP rounding).
+     * Suitable for: very precise calculations requiring minimal rounding error.
+     * Example: complex mathematical computations
+     */
+    val HIGH_PRECISION =
+        DivisionConfig(
+            scale = PrecisionScale.HIGH_PRECISION,
+            roundingMode = RoundingMode.HALF_UP,
+        )
+
+    /**
+     * Interest rate division (6 decimal places, HALF_UP rounding).
+     * Suitable for: interest calculations, APR/APY computations.
+     * Example: 5% / 12 months = 0.416667% per month
+     */
+    val INTEREST_RATE =
+        DivisionConfig(
+            scale = PrecisionScale.INTEREST_RATE,
+            roundingMode = RoundingMode.HALF_UP,
+        )
+
+    /**
+     * Cryptocurrency division (8 decimal places, HALF_UP rounding).
+     * Suitable for: Bitcoin and other crypto calculations.
+     * Example: 1 BTC / 3 = 0.33333333 BTC
+     */
+    val CRYPTOCURRENCY =
+        DivisionConfig(
+            scale = PrecisionScale.CRYPTOCURRENCY,
+            roundingMode = RoundingMode.HALF_UP,
+        )
+
+    /**
+     * Exact division (requires exact result, no rounding).
+     * Suitable for: divisions that must be exact or throw exception.
+     * Example: 10 / 2 = 5 (exact), but 10 / 3 throws ArithmeticException
+     */
+    val EXACT =
+        DivisionConfig(
+            scale = 0,
+            roundingMode = RoundingMode.UNNECESSARY,
+        )
+}