[uptime] enhance UptimeToString() and add flags (#12841)

This commit enhances the `UptimeToString()` function by introducing
`UptimeStringFlags` to allow customization of the output string.
Specifically, it adds the following flags:

- `kUptimeStringIncludeMsec`: Includes milliseconds in the string.
- `kUptimeStringSkipHoursIfZero`: Omits the `<hh>:` part when hours
  and days are zero.

The commit also adds a new `UptimeToString()` overload that returns
an `UptimeString` (a `String` object), simplifying usage in logging
and other areas. All existing call sites are updated to use the new
flags and the new overload where appropriate.

src/core/api/instance_api.cpp

@@ -116,7 +116,7 @@ void otInstanceGetUptimeAsString(otInstance *aInstance, char *aBuffer, uint16_t
     {
         StringWriter writer(aBuffer, aSize);
 
-        UptimeToString(AsCoreType(aInstance).Get<UptimeTracker>().GetUptime(), writer, /* aIncludeMsec */ true);
+        UptimeToString(AsCoreType(aInstance).Get<UptimeTracker>().GetUptime(), writer, kUptimeStringIncludeMsec);
     }
 }
 #endif

src/core/api/thread_api.cpp

@@ -533,7 +533,7 @@ void otConvertDurationInSecondsToString(uint32_t aDuration, char *aBuffer, uint1
     StringWriter writer(aBuffer, aSize);
     UptimeMsec   uptime = static_cast<UptimeMsec>(aDuration) * Time::kOneSecondInMsec;
 
-    UptimeToString(uptime, writer, /* aIncludeMsec */ false);
+    UptimeToString(uptime, writer, /* aFlags */ 0);
 }
 #endif
 

src/core/border_router/routing_manager.cpp

@@ -478,10 +478,9 @@ void RoutingManager::ScheduleRoutingPolicyEvaluation(ScheduleMode aMode)
         }
         else
         {
-            String<kUptimeStringSize> string;
-
-            UptimeToString(duration, string, /* aIncludeMsec */ true);
-            LogInfo("Will evaluate routing policy in %s (%lu msec)", string.AsCString() + 3, ToUlong(duration));
+            LogInfo("Will evaluate routing policy in %s (%lu msec)",
+                    UptimeToString(duration, kUptimeStringIncludeMsec | kUptimeStringSkipHoursIfZero).AsCString(),
+                    ToUlong(duration));
         }
     }
 #endif

src/core/common/log.cpp

@@ -133,7 +133,7 @@ void Logger::Log(const char *aModuleName, LogLevel aLogLevel, Error aError, cons
 #else
 #error "OPENTHREAD_CONFIG_LOG_PREPEND_UPTIME requires LOG_INSTANCE_AWARE_API_ENABLE under multi-instance"
 #endif
-        ot::UptimeToString(instance->Get<ot::UptimeTracker>().GetUptime(), logString, /* aInlcudeMsec */ true);
+        ot::UptimeToString(instance->Get<ot::UptimeTracker>().GetUptime(), logString, kUptimeStringIncludeMsec);
         logString.Append(" ");
     }
 #endif

src/core/common/uptime.cpp

@@ -96,7 +96,7 @@ void UptimeTracker::HandleTimer(void)
 static uint16_t DivideAndGetRemainder(uint32_t &aDividend, uint32_t aDivisor)
 {
     // Returns the quotient of division `aDividend / aDivisor` and updates
-    // `aDividend` to returns the remainder
+    // `aDividend` to the remainder
 
     uint32_t quotient = aDividend / aDivisor;
 
@@ -105,7 +105,15 @@ static uint16_t DivideAndGetRemainder(uint32_t &aDividend, uint32_t aDivisor)
     return static_cast<uint16_t>(quotient);
 }
 
-void UptimeToString(UptimeMsec aUptime, StringWriter &aWriter, bool aIncludeMsec)
+UptimeString UptimeToString(UptimeMsec aUptime, UptimeStringFlags aFlags)
+{
+    UptimeString string;
+
+    UptimeToString(aUptime, string, aFlags);
+    return string;
+}
+
+void UptimeToString(UptimeMsec aUptime, StringWriter &aWriter, UptimeStringFlags aFlags)
 {
     uint64_t days = aUptime / Time::kOneDayInMsec;
     uint32_t remainder;
@@ -124,9 +132,14 @@ void UptimeToString(UptimeMsec aUptime, StringWriter &aWriter, bool aIncludeMsec
     minutes   = DivideAndGetRemainder(remainder, Time::kOneMinuteInMsec);
     seconds   = DivideAndGetRemainder(remainder, Time::kOneSecondInMsec);
 
-    aWriter.Append("%02u:%02u:%02u", hours, minutes, seconds);
+    if ((days > 0) || (hours > 0) || !(aFlags & kUptimeStringSkipHoursIfZero))
+    {
+        aWriter.Append("%02u:", hours);
+    }
 
-    if (aIncludeMsec)
+    aWriter.Append("%02u:%02u", minutes, seconds);
+
+    if (aFlags & kUptimeStringIncludeMsec)
     {
         aWriter.Append(".%03u", static_cast<uint16_t>(remainder));
     }

src/core/common/uptime.hpp

@@ -50,11 +50,52 @@
 
 namespace ot {
 
+constexpr uint16_t kUptimeStringSize = OT_UPTIME_STRING_SIZE; ///< Recommended string size to represent uptime.
+
 typedef uint64_t UptimeMsec; ///< Uptime in milliseconds.
 
 typedef uint32_t UptimeSec; ///< Uptime in seconds.
 
-constexpr uint16_t kUptimeStringSize = OT_UPTIME_STRING_SIZE; ///< Recommended string size to represent uptime.
+typedef String<kUptimeStringSize> UptimeString; ///< A string representation of `UptimeMsec`
+
+/**
+ * Represents the flags used by `UptimeToString` to customize the string representation of uptime.
+ */
+enum UptimeStringFlag : uint8_t
+{
+    kUptimeStringIncludeMsec     = 1 << 0, ///< Include `.<mmm>` milliseconds in the string.
+    kUptimeStringSkipHoursIfZero = 1 << 1, ///< Skip the `<hh>:` part if hours (and days) are zero.
+};
+
+/**
+ * Represents a set of `UptimeStringFlag` values.
+ */
+typedef uint8_t UptimeStringFlags;
+
+/**
+ * Converts an uptime value (number of milliseconds) to a human-readable string.
+ *
+ * The string follows the format "<hh>:<mm>:<ss>" or "<dd>d.<hh>:<mm>:<ss>" (if uptime is longer than a day).
+ * @p aFlags can be used to include milliseconds and/or skip the `<hh>:` part if hours/days are zero.
+ *
+ * @param[in]     aUptime  The uptime to convert.
+ * @param[in,out] aWriter  A `StringWriter` to append the converted string to.
+ * @param[in]     aFlags   Flags to customize the string representation.
+ */
+void UptimeToString(UptimeMsec aUptime, StringWriter &aWriter, UptimeStringFlags aFlags);
+
+/**
+ * Converts an uptime value (number of milliseconds) to a human-readable string.
+ *
+ * The string follows the format "<hh>:<mm>:<ss>" or "<dd>d.<hh>:<mm>:<ss>" (if uptime is longer than a day).
+ * @p aFlags can be used to include milliseconds and/or skip the `<hh>:` part if hours/days are zero.
+ *
+ * @param[in]     aUptime  The uptime to convert.
+ * @param[in]     aFlags   Flags to customize the string representation.
+ *
+ * @returns An `UptimeString` containing the human-readable string.
+ */
+UptimeString UptimeToString(UptimeMsec aUptime, UptimeStringFlags aFlags);
 
 /**
  * Implements tracking of device uptime.
@@ -99,19 +140,6 @@ private:
     UptimeTimer mTimer;
 };
 
-/**
- * Converts an uptime value (number of milliseconds) to a human-readable string.
- *
- * The string follows the format "<hh>:<mm>:<ss>.<mmmm>" for hours, minutes, seconds and millisecond (if uptime is
- * shorter than one day) or "<dd>d.<hh>:<mm>:<ss>.<mmmm>" (if longer than a day). @p aIncludeMsec can be used
- * to determine whether `.<mmm>` milliseconds is included or omitted in the resulting string.
- *
- * @param[in]     aUptime        The uptime to convert.
- * @param[in,out] aWriter        A `StringWriter` to append the converted string to.
- * @param[in]     aIncludeMsec   Whether to include `.<mmm>` milliseconds in the string.
- */
-void UptimeToString(UptimeMsec aUptime, StringWriter &aWriter, bool aIncludeMsec);
-
 } // namespace ot
 
 #endif // OPENTHREAD_CONFIG_UPTIME_ENABLE

tests/nexus/platform/nexus_logging.cpp

@@ -45,7 +45,7 @@ static TimestampString GetTimestamp(TimeMilli aNow)
 {
     TimestampString string;
 
-    UptimeToString(aNow.GetValue(), string, /* aIncludeMsec */ true);
+    UptimeToString(aNow.GetValue(), string, kUptimeStringIncludeMsec);
     return string;
 }