Add Moneta.toLongOrNull() convertor

.github/workflows/test.yaml

@@ -19,24 +19,24 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up JDK 21
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: "21"
           cache: gradle
 
       - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v5
 
       - name: Build (all modules) with tests
         run: ./gradlew --no-daemon clean build
 
       - name: Publish test reports (always)
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: test-reports
           path: |

moneta/src/commonMain/kotlin/dev/voir/moneta/Moneta.kt

@@ -11,7 +11,7 @@ import dev.voir.moneta.Moneta.Companion.fromInt
  *  2. the currency code (`code`) — e.g. "USD", "EUR"
  *  3. the currency scale/decimals (`decimals`) — number of fractional digits (e.g. 2 for USD cents)
  *
- * Internally the amount is stored as a high-precision [`Decimal`] instance. `Moneta` is
+ * Internally the amount is stored as a high-precision [Decimal] instance. `Moneta` is
  * **decimal-based** and intended to be exact for fiat and crypto usage when combined with
  * the correct `decimals` for the currency.
  *
@@ -420,6 +420,18 @@ class Moneta private constructor(
         return shifted.toIntegerString()
     }
 
+    /**
+     * Convert this Moneta into atomic smallest-units as a Long (cents/sats/wei...).
+     *
+     * - Rounds to currency decimals (HALF_UP by default), then shifts right by `decimals`
+     * - Returns null if the result doesn't fit in a Long
+     */
+    fun toAtomicLongOrNull(rounding: Rounding = Rounding.HALF_UP): Long? {
+        val atomicStr = this.toAtomicString(rounding) // already scaled + shifted + integer string
+        return atomicStr.toLongOrNull()
+    }
+
+
     /**
      * Human-friendly textual representation of the monetary value using the underlying decimal.
      *