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

libcockatrice_network/libcockatrice/network/server/remote/game/server_card.cpp

@@ -26,6 +26,7 @@
 #include <libcockatrice/protocol/pb/event_set_card_attr.pb.h>
 #include <libcockatrice/protocol/pb/event_set_card_counter.pb.h>
 #include <libcockatrice/protocol/pb/serverinfo_card.pb.h>
+#include <libcockatrice/utility/clamped_arithmetic.h>
 #include <libcockatrice/utility/trice_limits.h>
 #include <limits>
 
@@ -114,8 +115,8 @@ QString Server_Card::setAttribute(CardAttribute attribute, const QString &avalue
 
 bool Server_Card::setCounter(int _id, int value, Event_SetCardCounter *event)
 {
-    // Clamp to valid card counter range [0, MAX_COUNTERS_ON_CARD]
-    value = qBound(0, value, MAX_COUNTERS_ON_CARD);
+    // Clamp to valid card counter range [0, MAX_COUNTER_VALUE]
+    value = qBound(0, value, MAX_COUNTER_VALUE);
 
     const int oldValue = counters.value(_id, 0);
     if (value == oldValue) {
@@ -139,10 +140,8 @@ bool Server_Card::setCounter(int _id, int value, Event_SetCardCounter *event)
 bool Server_Card::incrementCounter(int counterId, int delta, Event_SetCardCounter *event)
 {
     const int oldValue = counters.value(counterId, 0);
-    const auto result = static_cast<int64_t>(oldValue) + static_cast<int64_t>(delta);
-    // Clamp to [0, MAX_COUNTERS_ON_CARD] for card counters
-    const int newValue =
-        static_cast<int>(qBound(static_cast<int64_t>(0), result, static_cast<int64_t>(MAX_COUNTERS_ON_CARD)));
+    // Clamp to [0, MAX_COUNTER_VALUE] for card counters
+    const int newValue = addClamped(oldValue, delta, 0, MAX_COUNTER_VALUE);
 
     if (newValue == oldValue) {
         return false;

libcockatrice_network/libcockatrice/network/server/remote/game/server_card.h

@@ -156,7 +156,7 @@ public:
     /**
      * @brief Sets a card counter to an exact value with clamping.
      * @param _id The counter ID.
-     * @param value The desired value (clamped to [0, MAX_COUNTERS_ON_CARD]; 0 removes the counter).
+     * @param value The desired value (clamped to [0, MAX_COUNTER_VALUE]; 0 removes the counter).
      * @param event Optional event to populate with counter state.
      * @return true if the value changed, false otherwise.
      */
@@ -168,7 +168,7 @@ public:
      * @param event Optional event to populate with counter state.
      * @return true if the value changed, false otherwise.
      * @note If counter does not exist, starts from 0. Counter is removed if result is 0.
-     * @note Clamps result to [0, MAX_COUNTERS_ON_CARD].
+     * @note Clamps result to [0, MAX_COUNTER_VALUE].
      */
     [[nodiscard]] bool incrementCounter(int counterId, int delta, Event_SetCardCounter *event = nullptr);
     void setTapped(bool _tapped)

libcockatrice_network/libcockatrice/network/server/remote/game/server_counter.cpp

@@ -1,24 +1,12 @@
 #include "server_counter.h"
 
 #include <libcockatrice/protocol/pb/serverinfo_counter.pb.h>
-#include <limits>
 
 Server_Counter::Server_Counter(int _id, const QString &_name, const color &_counterColor, int _radius, int _count)
     : id(_id), name(_name), counterColor(_counterColor), radius(_radius), count(_count)
 {
 }
 
-//! \todo Extract overflow-safe arithmetic into shared helper.
-//! Duplicated in Server_Card::incrementCounter() - keep in sync if modified.
-bool Server_Counter::incrementCount(int delta)
-{
-    const int oldCount = count;
-    const auto result = static_cast<int64_t>(count) + static_cast<int64_t>(delta);
-    count = static_cast<int>(qBound(static_cast<int64_t>(std::numeric_limits<int>::min()), result,
-                                    static_cast<int64_t>(std::numeric_limits<int>::max())));
-    return count != oldCount;
-}
-
 void Server_Counter::getInfo(ServerInfo_Counter *info)
 {
     info->set_id(id);

libcockatrice_network/libcockatrice/network/server/remote/game/server_counter.h

@@ -22,6 +22,8 @@
 
 #include <QString>
 #include <libcockatrice/protocol/pb/color.pb.h>
+#include <libcockatrice/utility/clamped_arithmetic.h>
+#include <limits>
 
 class ServerInfo_Counter;
 
@@ -92,7 +94,12 @@ public:
      * @return true if the value changed, false otherwise.
      * @note Clamps result to [INT_MIN, INT_MAX] to prevent overflow.
      */
-    [[nodiscard]] bool incrementCount(int delta);
+    [[nodiscard]] bool incrementCount(int delta)
+    {
+        const int oldCount = count;
+        count = addClamped(count, delta, std::numeric_limits<int>::min(), std::numeric_limits<int>::max());
+        return count != oldCount;
+    }
 
     /**
      * @brief Populates info with this counter's current state for network serialization.