Add numeral extraction helpers to Java API (#8978)

New methods:
- Expr.getNumeralDouble(): retrieve any numeral as a double
- IntNum.getUint(): extract numeral as unsigned 32-bit value
- IntNum.getUint64(): extract numeral as unsigned 64-bit value
- RatNum.getSmall(): numerator/denominator as int64 pair
- RatNum.getRationalInt64(): numerator/denominator (returns null on overflow)

Each is a thin wrapper around the existing Native binding.
Added examples to JavaExample.java covering all new methods.

src/api/java/Expr.java

@@ -244,6 +244,15 @@ public class Expr<R extends Sort> extends AST
         return Native.isNumeralAst(getContext().nCtx(), getNativeObject());
     }
 
+    /**
+     * Return the numeral value as a double.
+     * The expression must be a numeral or an algebraic number.
+     **/
+    public double getNumeralDouble()
+    {
+        return Native.getNumeralDouble(getContext().nCtx(), getNativeObject());
+    }
+
     /**
      * Indicates whether the term is well-sorted.
      * 

src/api/java/IntNum.java

@@ -52,6 +52,33 @@ public class IntNum extends IntExpr
         return res.value;
     }
 
+    /**
+     * Retrieve the unsigned 32-bit value.
+     * The returned Java {@code int} holds the raw bit pattern;
+     * use {@code Integer.toUnsignedLong(v)} for unsigned interpretation.
+     **/
+    public int getUint()
+    {
+        Native.IntPtr res = new Native.IntPtr();
+        if (!Native.getNumeralUint(getContext().nCtx(), getNativeObject(), res))
+            throw new Z3Exception("Numeral is not a uint");
+        return res.value;
+    }
+
+    /**
+     * Retrieve the unsigned 64-bit value.
+     * The returned Java {@code long} holds the raw bit pattern;
+     * use {@code Long.toUnsignedString(v)} or {@link #getBigInteger()}
+     * for values exceeding {@code Long.MAX_VALUE}.
+     **/
+    public long getUint64()
+    {
+        Native.LongPtr res = new Native.LongPtr();
+        if (!Native.getNumeralUint64(getContext().nCtx(), getNativeObject(), res))
+            throw new Z3Exception("Numeral is not a uint64");
+        return res.value;
+    }
+
     /**
      * Retrieve the BigInteger value.
      **/

src/api/java/RatNum.java

@@ -60,6 +60,34 @@ public class RatNum extends RealExpr
         return new BigInteger(n.toString());
     }
 
+    /**
+     * Retrieve the numerator and denominator as 64-bit integers.
+     * Throws if the value does not fit in 64-bit integers.
+     * @return a two-element array [numerator, denominator]
+     **/
+    public long[] getSmall()
+    {
+        Native.LongPtr num = new Native.LongPtr();
+        Native.LongPtr den = new Native.LongPtr();
+        if (!Native.getNumeralSmall(getContext().nCtx(), getNativeObject(), num, den))
+            throw new Z3Exception("Numeral does not fit in int64");
+        return new long[] { num.value, den.value };
+    }
+
+    /**
+     * Retrieve the numerator and denominator as 64-bit integers.
+     * Returns null if the value does not fit in 64-bit integers.
+     * @return a two-element array [numerator, denominator], or null
+     **/
+    public long[] getRationalInt64()
+    {
+        Native.LongPtr num = new Native.LongPtr();
+        Native.LongPtr den = new Native.LongPtr();
+        if (!Native.getNumeralRationalInt64(getContext().nCtx(), getNativeObject(), num, den))
+            return null;
+        return new long[] { num.value, den.value };
+    }
+
     /**
      * Returns a string representation in decimal notation.
      * Remarks: The result