feat(math): add clamp function

[noa-starkware]

Note

Introduces a generic Clamp<T> trait with clamp(min, max) plus unit tests, including panic on invalid bounds.

• Math utils (packages/utils/src/math/utils.cairo)
  • Add Clamp<T> trait with clamp(self, min, max) -> T.
    • Generic over T with PartialOrd, Copy; asserts min <= max and bounds value to [min, max].
  • Tests: add clamp_test covering u64, i64, u256, and clamp_test_panic verifying panic on min > max.

^{Written by Cursor Bugbot for commit 10f6baa. This will update automatically on new commits. Configure here.}

---

This change is 

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@12bc7a6). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
packages/utils/src/math/utils.cairo	90.90%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #138   +/-   ##
=======================================
  Coverage        ?   89.37%           
=======================================
  Files           ?       43           
  Lines           ?     2475           
  Branches        ?        0           
=======================================
  Hits            ?     2212           
  Misses          ?      263           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[NirLevi-starkware]

@NirLevi-starkware reviewed 1 of 1 files at r1, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @noa-starkware)

---

packages/utils/src/math/utils.cairo line 440 at r1 (raw file):

        assert_eq!(10_u64.clamp(0_u64, 20_u64), 10_u64, "clamp failed");
        assert_eq!((-10_i64).clamp(0_i64, 20_i64), 0_i64, "clamp failed");
        assert_eq!(30_i64.clamp(0_i64, 20_i64), 20_i64, "clamp failed");

add one that the min and the max are the same save.

[noa-starkware]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @NirLevi-starkware)

---

packages/utils/src/math/utils.cairo line 440 at r1 (raw file):

Previously, NirLevi-starkware (Nir Levi) wrote…

add one that the min and the max are the same save.

Done.

[NirLevi-starkware]

@NirLevi-starkware reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @noa-starkware)