[time] add DetermineRemainingDurationFrom() helper (#12608)

This commit introduces `DetermineRemainingDurationFrom(Time aNow)` to
the `Time` class. This method calculates the duration from a given
current time (`aNow`) to the `Time` instance, handling edge cases
where the target time is in the past by returning zero.

Several instances across the codebase (e.g., `Timer::Scheduler`,
`TcatAgent`, `Translator::Mapping`, `Srp::Server`) previously
duplicated this logic using manual checks and subtraction. They have
been updated to use this new centralized helper, improving
readability and reducing the likelihood of wrap-around or negative
duration bugs.

src/core/common/time.hpp

@@ -228,6 +228,18 @@ public:
      */
     Time GetDistantPast(void) const { return Time(mValue - kDistantInterval); }
 
+    /**
+     * Determines the remaining duration from a given current time to this `Time` instance.
+     *
+     * If this `Time` instance is in the past relative to @p aNow, this method returns zero. Otherwise, it returns the
+     * duration from @p aNow to this `Time` instance.
+     *
+     * @param[in] aNow  The current time.
+     *
+     * @returns The remaining duration from @p aNow to this `Time` instance, or zero if this `Time` is in the past.
+     */
+    uint32_t DetermineRemainingDurationFrom(Time aNow) const { return (aNow < *this) ? (*this - aNow) : 0; }
+
     /**
      * Converts a given number of seconds to milliseconds.
      *

src/core/common/timer.cpp

@@ -208,11 +208,10 @@ void Timer::Scheduler::SetAlarm(const AlarmApi &aAlarmApi)
     }
     else
     {
-        Timer   *timer = mTimerList.GetHead();
         Time     now(aAlarmApi.AlarmGetNow());
         uint32_t remaining;
 
-        remaining = (now < timer->mFireTime) ? (timer->mFireTime - now) : 0;
+        remaining = mTimerList.GetHead()->mFireTime.DetermineRemainingDurationFrom(now);
 
         aAlarmApi.AlarmStartAt(&GetInstance(), now.GetValue(), remaining);
     }

src/core/meshcop/tcat_agent.cpp

@@ -1166,7 +1166,9 @@ void TcatAgent::AdaptToExistingActivePeriod(uint32_t &aPeriodDelayMs, uint32_t &
     {
         TimeMilli now = TimerMilli::GetNow();
         uint32_t  remainingMs;
-        remainingMs = (mActiveOrStandbyTimer.GetFireTime() > now) ? mActiveOrStandbyTimer.GetFireTime() - now : 0;
+
+        remainingMs = mActiveOrStandbyTimer.GetFireTime().DetermineRemainingDurationFrom(now);
+
         if (mTimerSetsToActive)
         {
             aPeriodDelayMs    = Min(aPeriodDelayMs, remainingMs);

src/core/net/nat64_translator.cpp

@@ -343,7 +343,7 @@ void Translator::Mapping::CopyTo(AddressMapping &aMapping, TimeMilli aNow) const
     // might become active again before actually removed. Report the
     // mapping to be "just expired" to avoid confusion.
 
-    aMapping.mRemainingTimeMs = (mExpirationTime < aNow) ? 0 : mExpirationTime - aNow;
+    aMapping.mRemainingTimeMs = mExpirationTime.DetermineRemainingDurationFrom(aNow);
 }
 
 void Translator::Mapping::Free(void)

src/core/net/srp_server.cpp

@@ -2026,18 +2026,15 @@ TimeMilli Server::Service::GetKeyExpireTime(void) const { return mUpdateTime + T
 
 void Server::Service::GetLeaseInfo(LeaseInfo &aLeaseInfo) const
 {
-    TimeMilli now           = TimerMilli::GetNow();
-    TimeMilli keyExpireTime = GetKeyExpireTime();
+    TimeMilli now = TimerMilli::GetNow();
 
     aLeaseInfo.mLease             = Time::SecToMsec(GetLease());
     aLeaseInfo.mKeyLease          = Time::SecToMsec(GetKeyLease());
-    aLeaseInfo.mRemainingKeyLease = (now <= keyExpireTime) ? (keyExpireTime - now) : 0;
+    aLeaseInfo.mRemainingKeyLease = GetKeyExpireTime().DetermineRemainingDurationFrom(now);
 
     if (!mIsDeleted)
     {
-        TimeMilli expireTime = GetExpireTime();
-
-        aLeaseInfo.mRemainingLease = (now <= expireTime) ? (expireTime - now) : 0;
+        aLeaseInfo.mRemainingLease = GetExpireTime().DetermineRemainingDurationFrom(now);
     }
     else
     {
@@ -2188,18 +2185,15 @@ TimeMilli Server::Host::GetKeyExpireTime(void) const { return mUpdateTime + Time
 
 void Server::Host::GetLeaseInfo(LeaseInfo &aLeaseInfo) const
 {
-    TimeMilli now           = TimerMilli::GetNow();
-    TimeMilli keyExpireTime = GetKeyExpireTime();
+    TimeMilli now = TimerMilli::GetNow();
 
     aLeaseInfo.mLease             = Time::SecToMsec(GetLease());
     aLeaseInfo.mKeyLease          = Time::SecToMsec(GetKeyLease());
-    aLeaseInfo.mRemainingKeyLease = (now <= keyExpireTime) ? (keyExpireTime - now) : 0;
+    aLeaseInfo.mRemainingKeyLease = GetKeyExpireTime().DetermineRemainingDurationFrom(now);
 
     if (!IsDeleted())
     {
-        TimeMilli expireTime = GetExpireTime();
-
-        aLeaseInfo.mRemainingLease = (now <= expireTime) ? (expireTime - now) : 0;
+        aLeaseInfo.mRemainingLease = GetExpireTime().DetermineRemainingDurationFrom(now);
     }
     else
     {