Allow for retrieving marker labels from the sensor_array.

Author: crowbar27

power_overwhelming/include/visus/pwrowg/sensor_array.h

@@ -1,5 +1,5 @@
 // <copyright file="sensor_array.h" company="Visualisierungsinstitut der Universität Stuttgart">
-// Copyright © 2025 Visualisierungsinstitut der Universität Stuttgart.
+// Copyright © 2025 - 2026 Visualisierungsinstitut der Universität Stuttgart.
 // Licensed under the MIT licence. See LICENCE file for details.
 // </copyright>
 // <author>Christoph Müller</author>
@@ -208,6 +208,44 @@ class POWER_OVERWHELMING_API sensor_array final {
         return this->marker(timestamp::now(), id);
     }
 
+    /// <summary>
+    /// Answer the label of the specified <paramref name="marker" />.
+    /// </summary>
+    /// <param name="dst">If not <see langword="nullptr" />, receives the name
+    /// of the marker provided it exists and fits into <paramref name="cnt" />
+    /// characters.</param>
+    /// <param name="cnt">The size of the <paramref name="dst" /> array.</param>
+    /// <param name="marker">The ID of the marker to retrieve the label for.
+    /// </param>
+    /// <returns>The required buffer size to store the marker (including the
+    /// terminating NUL character), regardless of whether the name has been
+    /// written. If the <paramref name="marker" /> does not exist, the return
+    /// value is zero.</returns>
+    std::size_t marker(_Out_writes_opt_z_(cnt) wchar_t *dst,
+        _In_ const std::size_t cnt, _In_ const unsigned int marker) const;
+
+    /// <summary>
+    /// Answer the label of the specified <paramref name="marker" />.
+    /// </summary>
+    /// <param name="dst">If not <see langword="nullptr" />, receives the name
+    /// of the marker provided it exists and fits into <paramref name="cnt" />
+    /// characters.</param>
+    /// <param name="cnt">The size of the <paramref name="dst" /> array.</param>
+    /// <param name="marker">The ID of the marker to retrieve the label for.
+    /// </param>
+    /// <returns>The required buffer size to store the marker (including the
+    /// terminating NUL character), regardless of whether the name has been
+    /// written. If the <paramref name="marker" /> does not exist, the return
+    /// value is zero.</returns>
+    std::size_t marker(_Out_writes_opt_z_(cnt) char *dst,
+        _In_ const std::size_t cnt, _In_ const unsigned int marker) const;
+
+    /// <summary>
+    /// Answer the number of markers configured in the array.
+    /// </summary>
+    /// <returns>The number of valid markers.</returns>
+    std::size_t markers(void) const noexcept;
+
     /// <summary>
     /// Starts sampling all sensors in the array.
     /// </summary>

power_overwhelming/src/marker_sensor.cpp

@@ -1,5 +1,5 @@
 // <copyright file="marker_sensor.cpp" company="Visualisierungsinstitut der Universität Stuttgart">
-// Copyright © 2025 Visualisierungsinstitut der Universität Stuttgart.
+// Copyright © 2025 - 2026 Visualisierungsinstitut der Universität Stuttgart.
 // Licensed under the MIT licence. See LICENCE file for details.
 // </copyright>
 // <author>Christoph Müller</author>
@@ -44,12 +44,12 @@ bool PWROWG_DETAIL_NAMESPACE::marker_sensor::emit(
         _In_ const timestamp timestamp,
         _In_ const unsigned int id) {
     this->_emitting.store(true, std::memory_order_release);
-    pwrowg_on_exit([this](void) { 
+    pwrowg_on_exit([this](void) {
         this->_emitting.store(false, std::memory_order_release);
     });
 
     const auto retval = (id >= 0)
-        && (id < this->_markers.size())
+        && (id < this->size())
         && this->_state;
 
     if (retval) {
@@ -64,6 +64,30 @@ bool PWROWG_DETAIL_NAMESPACE::marker_sensor::emit(
 }
 
 
+/*
+ * PWROWG_DETAIL_NAMESPACE::marker_sensor::marker
+ */
+std::size_t PWROWG_DETAIL_NAMESPACE::marker_sensor::marker(
+        _Out_writes_opt_z_(cnt) wchar_t *dst,
+        _In_ const std::size_t cnt,
+        _In_ const unsigned int marker) {
+    if ((marker < 0) || (marker >= this->size())) {
+        return 0;
+    }
+
+    const auto retval = this->_markers[marker].size() + 1;
+
+    if ((dst != nullptr) && (cnt >= retval)) {
+        std::copy(this->_markers[marker].begin(),
+            this->_markers[marker].end(),
+            dst);
+        assert(dst[retval - 1] == L'\0');
+    }
+
+    return retval;
+}
+
+
 /*
  * PWROWG_DETAIL_NAMESPACE::marker_sensor::sample
  */

power_overwhelming/src/marker_sensor.h

@@ -1,5 +1,5 @@
 // <copyright file="marker_sensor.h" company="Visualisierungsinstitut der Universität Stuttgart">
-// Copyright © 2025 Visualisierungsinstitut der Universität Stuttgart.
+// Copyright © 2025 - 2026 Visualisierungsinstitut der Universität Stuttgart.
 // Licensed under the MIT licence. See LICENCE file for details.
 // </copyright>
 // <author>Christoph Müller</author>
@@ -137,13 +137,37 @@ class PWROWG_TEST_API marker_sensor final {
     /// otherwise.</returns>
     bool emit(_In_ const timestamp timestamp, _In_ const unsigned int id);
 
+    /// <summary>
+    /// Answer the label of the specified <paramref name="marker" />.
+    /// </summary>
+    /// <param name="dst">If not <see langword="nullptr" />, receives the name
+    /// of the marker provided it exists and fits into <paramref name="cnt" />
+    /// characters.</param>
+    /// <param name="cnt">The size of the <paramref name="dst" /> array.</param>
+    /// <param name="marker">The ID of the marker to retrieve the label for.
+    /// </param>
+    /// <returns>The required buffer size to store the marker (including the
+    /// terminating NUL character), regardless of whether the name has been
+    /// written. If the <paramref name="marker" /> does not exist, the return
+    /// value is zero.</returns>
+    std::size_t marker(_Out_writes_opt_z_(cnt) wchar_t *dst,
+        _In_ const std::size_t cnt, _In_ const unsigned int marker);
+
     /// <summary>
     /// Starts or stops sampling the sensor.
     /// </summary>
     /// <param name="enable"><c>true</c> for enabling the sensor,
     /// <c>false</c> for disabling it.</param>
     void sample(_In_ const bool enable);
 
+    /// <summary>
+    /// Answer the number of markers configured for this sensor.
+    /// </summary>
+    /// <returns>The number of markers.</returns>
+    inline std::size_t size(void) const noexcept {
+        return this->_markers.size();
+    }
+
     marker_sensor& operator =(const marker_sensor& rhs) = delete;
 
 private:

power_overwhelming/src/sensor_array.cpp

@@ -1,5 +1,5 @@
 // <copyright file="sensor_array.cpp" company="Visualisierungsinstitut der Universität Stuttgart">
-// Copyright © 2025 Visualisierungsinstitut der Universität Stuttgart.
+// Copyright © 2025 - 2026 Visualisierungsinstitut der Universität Stuttgart.
 // Licensed under the MIT licence. See LICENCE file for details.
 // </copyright>
 // <author>Christoph Müller</author>
@@ -182,6 +182,64 @@ bool PWROWG_NAMESPACE::sensor_array::marker(_In_ const timestamp timestamp,
 }
 
 
+/*
+ * PWROWG_NAMESPACE::sensor_array::marker
+ */
+std::size_t PWROWG_NAMESPACE::sensor_array::marker(
+        _Out_writes_opt_z_(cnt) wchar_t *dst,
+        _In_ const std::size_t cnt,
+        _In_ const unsigned int marker) const {
+    typedef detail::marker_sensor::list_type type;
+    typedef detail::tuple_types_t<decltype(this->_impl->sensors)> types;
+    typedef detail::type_list_index_of<type, types> index;
+
+    volatile auto impl = this->_impl;  // sic!
+    auto& list = std::get<index::value>(this->_impl->sensors);
+
+    return ((impl != nullptr) && !list.empty())
+        ? list.begin()->marker(dst, cnt, marker)
+        : 0;
+}
+
+
+/*
+ * PWROWG_NAMESPACE::sensor_array::marker
+ */
+std::size_t PWROWG_NAMESPACE::sensor_array::marker(
+        _Out_writes_opt_z_(cnt) char *dst,
+        _In_ const std::size_t cnt,
+        _In_ const unsigned int marker) const {
+    auto retval = this->marker(static_cast<wchar_t *>(nullptr), 0, marker);
+
+    if (retval == 0) {
+        // If the marker does not exist, we can bail out.
+        return retval;
+    }
+
+    // Get the marker and measure the required UTF-8 code units.
+    std::vector<wchar_t> buffer(retval);
+    this->marker(buffer.data(), buffer.size(), marker);
+    retval = detail::convert_string(dst, cnt, buffer.data(), retval);
+
+    return retval;
+}
+
+
+/*
+ * PWROWG_NAMESPACE::sensor_array::markers
+ */
+std::size_t PWROWG_NAMESPACE::sensor_array::markers(void) const noexcept {
+    typedef detail::marker_sensor::list_type type;
+    typedef detail::tuple_types_t<decltype(this->_impl->sensors)> types;
+    typedef detail::type_list_index_of<type, types> index;
+
+    volatile auto impl = this->_impl;  // sic!
+    auto& list = std::get<index::value>(this->_impl->sensors);
+
+    return ((impl != nullptr) && !list.empty()) ? list.begin()->size() : 0;
+}
+
+
 /*
  * PWROWG_NAMESPACE::sensor_array::start
  */

test/marker_test.cpp

@@ -1,5 +1,5 @@
 // <copyright file="marker_test.cpp" company="Visualisierungsinstitut der Universität Stuttgart">
-// Copyright © 2025 Visualisierungsinstitut der Universität Stuttgart.
+// Copyright © 2025 - 2026 Visualisierungsinstitut der Universität Stuttgart.
 // Licensed under the MIT licence. See LICENCE file for details.
 // </copyright>
 // <author>Christoph Müller</author>
@@ -47,6 +47,7 @@ TEST_CLASS(marker_test) {
             .exclude<usb_pd_configuration>();
 
         auto sensors = sensor_array::for_matches(std::move(config), is_marker_sensor);
+        Assert::AreEqual(std::size_t(1), sensors.markers(), L"# of markers", LINE_INFO());
 
         std::vector<sensor_description> descs;
         descs.resize(sensors.descriptions(nullptr, 0));
@@ -64,6 +65,33 @@ TEST_CLASS(marker_test) {
             sensors.stop();
         }
     }
+
+    TEST_METHOD(test_marker_name) {
+        typedef detail::marker_sensor type;
+
+        sensor_array_configuration config;
+        config.configure<marker_configuration>([](marker_configuration &c) { c += L"Erich"; })
+            .exclude<hmc8015_configuration>()
+            .exclude<tinkerforge_configuration>()
+            .exclude<usb_pd_configuration>();
+
+        auto sensors = sensor_array::for_matches(std::move(config), is_marker_sensor);
+
+        {
+            std::vector<wchar_t> name(sensors.marker(static_cast<wchar_t *>(nullptr), 0, 0));
+            Assert::AreEqual(std::size_t(6), sensors.marker(name.data(), name.size(), 0), L"Buffer length", LINE_INFO());
+            Assert::AreEqual(L"Erich", name.data(), L"Marker name", LINE_INFO());
+        }
+
+        {
+            std::vector<char> name(sensors.marker(static_cast<char *>(nullptr), 0, 0));
+            Assert::AreEqual(std::size_t(6), sensors.marker(name.data(), name.size(), 0), L"Buffer length", LINE_INFO());
+            Assert::AreEqual("Erich", name.data(), L"Marker name", LINE_INFO());
+        }
+
+        Assert::AreEqual(std::size_t(0), sensors.marker(static_cast<wchar_t *>(nullptr), 0, 42), L"Inexistent marker", LINE_INFO());
+        Assert::AreEqual(std::size_t(0), sensors.marker(static_cast<char *>(nullptr), 0, 42), L"Inexistent marker", LINE_INFO());
+    }
 };
 
 PWROWG_TEST_NAMESPACE_END