Unify counter clamp arithmetic into shared addClamped() helper (#7009)

* Unify counter clamp arithmetic into shared addClamped() helper

- Add addClamped() in new header clamped_arithmetic.h; uses a 64-bit
  intermediate so the addition cannot overflow int.
- Use it in Server_Card::incrementCounter() (clamps [0, MAX_COUNTERS_ON_CARD])
  and Server_Counter::incrementCount() (clamps [INT_MIN, INT_MAX]), removing
  the duplicated overflow-safe logic and its keep-in-sync TODO.
- Inline incrementCount() into server_counter.h; server_counter.cpp now holds
  only the constructor and getInfo().
- Clarify the card-counter bounds comment in trice_limits.h.

* Rename MAX_COUNTERS_ON_CARD to MAX_COUNTER_VALUE

The constant caps the counter's value, not how many counters can be on the card

* Add direct unit tests for addClamped() helper

* Harden offsetCardCounter() against signed-int overflow

Replace the raw oldValue + offset sum with addClamped(), clamping to [0, MAX_COUNTER_VALUE] without overflow.

* Comment update

* Remove class names from addClamped() docstring

tests/CMakeLists.txt

@@ -4,6 +4,7 @@ enable_testing()
 
 add_test(NAME dummy_test COMMAND dummy_test)
 add_test(NAME expression_test COMMAND expression_test)
+add_test(NAME clamped_arithmetic_test COMMAND clamped_arithmetic_test)
 add_test(NAME test_age_formatting COMMAND test_age_formatting)
 add_test(NAME password_hash_test COMMAND password_hash_test)
 add_test(NAME server_card_counter_test COMMAND server_card_counter_test)
@@ -16,6 +17,7 @@ set_tests_properties(deck_hash_performance_test PROPERTIES TIMEOUT 5)
 
 add_executable(dummy_test dummy_test.cpp)
 add_executable(expression_test expression_test.cpp)
+add_executable(clamped_arithmetic_test clamped_arithmetic_test.cpp)
 add_executable(test_age_formatting test_age_formatting.cpp)
 add_executable(password_hash_test password_hash_test.cpp)
 add_executable(deck_hash_performance_test deck_hash_performance_test.cpp)
@@ -49,6 +51,7 @@ if(NOT GTEST_FOUND)
   set(GTEST_BOTH_LIBRARIES gtest)
   add_dependencies(dummy_test gtest)
   add_dependencies(expression_test gtest)
+  add_dependencies(clamped_arithmetic_test gtest)
   add_dependencies(test_age_formatting gtest)
   add_dependencies(password_hash_test gtest)
   add_dependencies(deck_hash_performance_test gtest)
@@ -59,6 +62,9 @@ endif()
 include_directories(${GTEST_INCLUDE_DIRS})
 target_link_libraries(dummy_test Threads::Threads ${GTEST_BOTH_LIBRARIES})
 target_link_libraries(expression_test libcockatrice_utility Threads::Threads ${GTEST_BOTH_LIBRARIES} ${TEST_QT_MODULES})
+target_link_libraries(
+  clamped_arithmetic_test libcockatrice_utility Threads::Threads ${GTEST_BOTH_LIBRARIES} ${TEST_QT_MODULES}
+)
 target_link_libraries(
   test_age_formatting libcockatrice_utility Threads::Threads ${GTEST_BOTH_LIBRARIES} ${TEST_QT_MODULES}
 )

tests/clamped_arithmetic_test.cpp

@@ -0,0 +1,44 @@
+/** @file clamped_arithmetic_test.cpp
+ *  @brief Tests for shared helpers in clamped_arithmetic.h.
+ *  @ingroup Tests
+ */
+
+#include <gtest/gtest.h>
+#include <libcockatrice/utility/clamped_arithmetic.h>
+#include <limits>
+
+TEST(AddClamped, AddsWithinBounds)
+{
+    EXPECT_EQ(addClamped(5, 3, 0, 100), 8);
+    EXPECT_EQ(addClamped(10, -3, 0, 100), 7);
+}
+
+TEST(AddClamped, ClampsToUpperAndLowerBound)
+{
+    EXPECT_EQ(addClamped(99, 5, 0, 100), 100);  // saturates at max
+    EXPECT_EQ(addClamped(2, -10, 0, 100), 0);   // saturates at min
+    EXPECT_EQ(addClamped(999, 1, 0, 999), 999); // crossing the counter cap holds at the bound
+}
+
+TEST(AddClamped, IntOverflowDoesNotWrap)
+{
+    // The 64-bit intermediate must prevent signed-int overflow UB.
+    constexpr int intMax = std::numeric_limits<int>::max();
+    constexpr int intMin = std::numeric_limits<int>::min();
+    EXPECT_EQ(addClamped(intMax, 1, intMin, intMax), intMax);
+    EXPECT_EQ(addClamped(intMax, intMax, intMin, intMax), intMax);
+}
+
+TEST(AddClamped, IntUnderflowDoesNotWrap)
+{
+    constexpr int intMax = std::numeric_limits<int>::max();
+    constexpr int intMin = std::numeric_limits<int>::min();
+    EXPECT_EQ(addClamped(intMin, -1, intMin, intMax), intMin);
+    EXPECT_EQ(addClamped(intMin, intMin, intMin, intMax), intMin);
+}
+
+int main(int argc, char **argv)
+{
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}

tests/server_card_counter_test.cpp

@@ -28,9 +28,9 @@ TEST(ServerCardCounter, IncrementExistingCounter)
 TEST(ServerCardCounter, IncrementOverflowProtection)
 {
     Server_Card card(CardRef{"TestCard", ""}, 1, 0, 0);
-    ASSERT_TRUE(card.setCounter(1, MAX_COUNTERS_ON_CARD));
+    ASSERT_TRUE(card.setCounter(1, MAX_COUNTER_VALUE));
     EXPECT_FALSE(card.incrementCounter(1, 1));
-    EXPECT_EQ(card.getCounter(1), MAX_COUNTERS_ON_CARD);
+    EXPECT_EQ(card.getCounter(1), MAX_COUNTER_VALUE);
 }
 
 TEST(ServerCardCounter, DecrementUnderflowProtection)
@@ -113,13 +113,13 @@ TEST(ServerCardCounter, IncrementCounterPopulatesEvent)
 TEST(ServerCardCounter, IncrementCounterEventReflectsClampedValue)
 {
     Server_Card card(CardRef{"TestCard", ""}, 1, 0, 0);
-    ASSERT_TRUE(card.setCounter(1, MAX_COUNTERS_ON_CARD - 5));
+    ASSERT_TRUE(card.setCounter(1, MAX_COUNTER_VALUE - 5));
 
     Event_SetCardCounter event;
     EXPECT_TRUE(card.incrementCounter(1, 10, &event));
 
     EXPECT_EQ(event.counter_id(), 1);
-    EXPECT_EQ(event.counter_value(), MAX_COUNTERS_ON_CARD);
+    EXPECT_EQ(event.counter_value(), MAX_COUNTER_VALUE);
 }
 
 TEST(ServerCardCounter, IncrementCounterNoEventWhenNullptr)
@@ -133,7 +133,7 @@ TEST(ServerCardCounter, IncrementCounterNoEventWhenNullptr)
 TEST(ServerCardCounter, IncrementCounterEventNotPopulatedWhenUnchanged)
 {
     Server_Card card(CardRef{"TestCard", ""}, 1, 0, 0);
-    ASSERT_TRUE(card.setCounter(1, MAX_COUNTERS_ON_CARD));
+    ASSERT_TRUE(card.setCounter(1, MAX_COUNTER_VALUE));
 
     Event_SetCardCounter event;
     event.set_counter_id(999);
@@ -156,7 +156,7 @@ TEST(ServerCardCounter, SetCounterClampsAboveMaxToMax)
 {
     Server_Card card(CardRef{"TestCard", ""}, 1, 0, 0);
     EXPECT_TRUE(card.setCounter(1, 1500));
-    EXPECT_EQ(card.getCounter(1), MAX_COUNTERS_ON_CARD);
+    EXPECT_EQ(card.getCounter(1), MAX_COUNTER_VALUE);
 }
 
 TEST(ServerCardCounter, IncrementDoesNotGoBelowZero)
@@ -171,9 +171,9 @@ TEST(ServerCardCounter, IncrementDoesNotGoBelowZero)
 TEST(ServerCardCounter, IncrementDoesNotExceedMax)
 {
     Server_Card card(CardRef{"TestCard", ""}, 1, 0, 0);
-    ASSERT_TRUE(card.setCounter(1, MAX_COUNTERS_ON_CARD - 5));
+    ASSERT_TRUE(card.setCounter(1, MAX_COUNTER_VALUE - 5));
     EXPECT_TRUE(card.incrementCounter(1, 10));
-    EXPECT_EQ(card.getCounter(1), MAX_COUNTERS_ON_CARD);
+    EXPECT_EQ(card.getCounter(1), MAX_COUNTER_VALUE);
 }
 
 int main(int argc, char **argv)