Generic to_string/formatters with format-spec rendering in hertz (1.2.0)

CMakeLists.txt

@@ -7,7 +7,7 @@ if(ESP_PLATFORM)
 endif()
 
 project(frequency
-    VERSION 1.1.2
+    VERSION 1.2.0
     DESCRIPTION "Type-safe frequency handling library modeled after std::chrono"
     HOMEPAGE_URL "https://github.com/cleishm/frequency-cpp"
     LANGUAGES CXX

README.md

@@ -88,6 +88,12 @@ if (kilohertz{1} == hertz{1000}) {
 
 // String conversion
 std::string s = to_string(kilohertz(80));  // "80kHz"
+
+// Formatting: a floating-point format spec renders in hertz, while the
+// default renders the exact stored value.
+millihertz reading{1500};
+std::string disp = std::format("{:.1f}", reading);  // "1.5Hz"
+std::string raw  = std::format("{}", reading);      // "1500mHz" (exact stored value)
 ```
 
 ## Frequency Types

docs/Doxyfile

@@ -6,7 +6,7 @@
 
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "frequency"
-PROJECT_NUMBER         = "1.0.0"
+PROJECT_NUMBER         = "1.2.0"
 PROJECT_BRIEF          = "Type-safe frequency handling library modeled after std::chrono"
 PROJECT_LOGO           =
 OUTPUT_DIRECTORY       = .

idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.1.3"
+version: "1.2.0"
 description: "Type-safe frequency handling library modeled after std::chrono"
 url: "https://github.com/cleishm/frequency-cpp"
 repository: "https://github.com/cleishm/frequency-cpp.git"

include/frequency/frequency.hpp

@@ -1099,28 +1099,75 @@ using terahertz = frequency<int64_t, std::tera>;
 
 /** @} */ // end of FrequencyTypes group
 
-inline std::string to_string(millihertz f) {
-    return std::to_string(f.count()) + "mHz";
-}
-
-inline std::string to_string(hertz f) {
-    return std::to_string(f.count()) + "Hz";
-}
-
-inline std::string to_string(kilohertz f) {
-    return std::to_string(f.count()) + "kHz";
-}
-
-inline std::string to_string(megahertz f) {
-    return std::to_string(f.count()) + "MHz";
-}
-
-inline std::string to_string(gigahertz f) {
-    return std::to_string(f.count()) + "GHz";
+/** @cond INTERNAL */
+// SI prefix for a hertz-per-count ratio; nullptr when unmapped.
+template<typename Ratio>
+struct _si_prefix {
+    static constexpr const char* value = nullptr;
+};
+template<>
+struct _si_prefix<std::femto> {
+    static constexpr const char* value = "f";
+};
+template<>
+struct _si_prefix<std::pico> {
+    static constexpr const char* value = "p";
+};
+template<>
+struct _si_prefix<std::nano> {
+    static constexpr const char* value = "n";
+};
+template<>
+struct _si_prefix<std::micro> {
+    static constexpr const char* value = "µ";
+};
+template<>
+struct _si_prefix<std::milli> {
+    static constexpr const char* value = "m";
+};
+template<>
+struct _si_prefix<std::ratio<1>> {
+    static constexpr const char* value = "";
+};
+template<>
+struct _si_prefix<std::kilo> {
+    static constexpr const char* value = "k";
+};
+template<>
+struct _si_prefix<std::mega> {
+    static constexpr const char* value = "M";
+};
+template<>
+struct _si_prefix<std::giga> {
+    static constexpr const char* value = "G";
+};
+template<>
+struct _si_prefix<std::tera> {
+    static constexpr const char* value = "T";
+};
+template<typename Ratio>
+inline constexpr const char* _si_prefix_v = _si_prefix<typename Ratio::type>::value;
+
+// Appends a NUL-terminated string to a format output iterator.
+template<typename OutputIt>
+constexpr OutputIt _format_append(OutputIt out, const char* s) {
+    for (; *s != '\0'; ++s) {
+        *out++ = *s;
+    }
+    return out;
 }
+/** @endcond */
 
-inline std::string to_string(terahertz f) {
-    return std::to_string(f.count()) + "THz";
+/**
+ * @brief Renders a frequency as its exact count with a precision-qualified
+ * unit, e.g. `to_string(kilohertz(433)) == "433kHz"`.
+ */
+template<typename Rep, typename Precision>
+    requires(!treat_as_inexact_v<Rep>)
+std::string to_string(const frequency<Rep, Precision>& f) {
+    using precision = typename frequency<Rep, Precision>::precision;
+    static_assert(_si_prefix_v<precision> != nullptr, "frequency: precision has no SI prefix");
+    return std::to_string(f.count()) + _si_prefix_v<precision> + "Hz";
 }
 
 } // namespace freq
@@ -1139,46 +1186,41 @@ struct common_type<freq::frequency<Rep1, Precision1>, freq::frequency<Rep2, Prec
 };
 
 #if CONFIG_FREQUENCY_STD_FORMAT
-template<>
-struct formatter<freq::millihertz> {
-    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
-
-    auto format(freq::millihertz f, format_context& ctx) const { return std::format_to(ctx.out(), "{}mHz", f.count()); }
-};
-
-template<>
-struct formatter<freq::hertz> {
-    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
-
-    auto format(freq::hertz f, format_context& ctx) const { return std::format_to(ctx.out(), "{}Hz", f.count()); }
-};
-
-template<>
-struct formatter<freq::kilohertz> {
-    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
-
-    auto format(freq::kilohertz f, format_context& ctx) const { return std::format_to(ctx.out(), "{}kHz", f.count()); }
-};
-
-template<>
-struct formatter<freq::megahertz> {
-    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
-
-    auto format(freq::megahertz f, format_context& ctx) const { return std::format_to(ctx.out(), "{}MHz", f.count()); }
-};
-
-template<>
-struct formatter<freq::gigahertz> {
-    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
-
-    auto format(freq::gigahertz f, format_context& ctx) const { return std::format_to(ctx.out(), "{}GHz", f.count()); }
-};
+// "{}" prints the exact stored count with a precision-qualified unit
+// (kilohertz(433) -> "433kHz"). A non-empty spec is applied to the value in
+// hertz (as double): std::format("{:.1f}", millihertz(1500)) == "1.5Hz".
+template<typename Rep, typename Precision>
+struct formatter<freq::frequency<Rep, Precision>> {
+private:
+    using _precision = typename freq::frequency<Rep, Precision>::precision;
+    static constexpr const char* _prefix = freq::_si_prefix_v<_precision>;
+    std::formatter<double> _num;
+    bool _has_spec = false;
 
-template<>
-struct formatter<freq::terahertz> {
-    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
+public:
+    constexpr auto parse(format_parse_context& ctx) {
+        auto it = ctx.begin();
+        if (it == ctx.end() || *it == '}') {
+            if (_prefix == nullptr) {
+                throw format_error("frequency: precision has no SI prefix; use an explicit format spec");
+            }
+            return it;
+        }
+        _has_spec = true;
+        return _num.parse(ctx);
+    }
 
-    auto format(freq::terahertz f, format_context& ctx) const { return std::format_to(ctx.out(), "{}THz", f.count()); }
+    template<typename FormatContext>
+    auto format(const freq::frequency<Rep, Precision>& f, FormatContext& ctx) const {
+        if (_has_spec) {
+            double hz = static_cast<double>(f.count()) * _precision::num / _precision::den;
+            auto out = _num.format(hz, ctx);
+            return freq::_format_append(out, "Hz");
+        }
+        auto out = std::format_to(ctx.out(), "{}", f.count());
+        out = freq::_format_append(out, _prefix);
+        return freq::_format_append(out, "Hz");
+    }
 };
 #endif
 

tests/frequency_test.cpp

@@ -248,8 +248,32 @@ TEST_CASE("to_string", "[frequency][string]") {
     REQUIRE(to_string(kilohertz(80)) == "80kHz");
     REQUIRE(to_string(megahertz(80)) == "80MHz");
     REQUIRE(to_string(gigahertz(2)) == "2GHz");
+    REQUIRE(to_string(terahertz(5)) == "5THz");
 }
 
+#if CONFIG_FREQUENCY_STD_FORMAT
+TEST_CASE("std::format frequency", "[frequency][string]") {
+    // Empty spec prints the exact stored count with a precision-qualified unit.
+    REQUIRE(std::format("{}", millihertz(1500)) == "1500mHz");
+    REQUIRE(std::format("{}", hertz(440)) == "440Hz");
+    REQUIRE(std::format("{}", kilohertz(433)) == "433kHz");
+    REQUIRE(std::format("{}", megahertz(868)) == "868MHz");
+    REQUIRE(std::format("{}", gigahertz(2)) == "2GHz");
+    REQUIRE(std::format("{}", terahertz(5)) == "5THz");
+}
+
+TEST_CASE("std::format with spec renders in hertz", "[frequency][string]") {
+    // A floating-point format spec renders the value in hertz.
+    REQUIRE(std::format("{:.1f}", millihertz(1500)) == "1.5Hz");
+    REQUIRE(std::format("{:.2f}", millihertz(1534)) == "1.53Hz");
+    REQUIRE(std::format("{:.1f}", hertz(440)) == "440.0Hz");
+    REQUIRE(std::format("{:g}", kilohertz(2)) == "2000Hz");
+
+    // Width and alignment pass through to the numeric part.
+    REQUIRE(std::format("{:7.1f}", millihertz(1500)) == "    1.5Hz");
+}
+#endif
+
 TEST_CASE("frequency period", "[frequency][period]") {
     using namespace std::chrono;
 

vcpkg-port/vcpkg.json

@@ -1,6 +1,6 @@
 {
   "name": "cleishm-frequency-cpp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Type-safe frequency handling library modeled after std::chrono",
   "homepage": "https://github.com/cleishm/frequency-cpp",
   "license": "MIT",