wireforge 0.1.0__py3-none-any.whl

wireforge/_data/runtime/include/wireforge/span.hpp

@@ -0,0 +1,116 @@
+/**
+ * @file span.hpp
+ * @brief Non-owning view of contiguous memory.
+ */
+#ifndef WIREFORGE_SPAN_HPP
+#define WIREFORGE_SPAN_HPP
+
+#include <array>
+#include <cstddef>
+#include <iterator>
+#include <type_traits>
+
+namespace wireforge {
+
+/**
+ * @brief Non-owning view of a contiguous sequence, similar to C++20 `std::span` with a dynamic
+ *        extent.
+ *
+ * Element access is unchecked; check size() first. All constructors are explicit.
+ * @tparam T Element type; use `const T` for a read-only view.
+ */
+template <typename T> class Span {
+public:
+    using element_type = T;                 ///< Element type, including const.
+    using value_type = std::remove_cv_t<T>; ///< Element type without cv-qualifiers.
+    using size_type = std::size_t;          ///< Type of sizes and indices.
+    using pointer = T*;                     ///< Pointer to an element.
+    using reference = T&;                   ///< Reference to an element.
+    using iterator = T*;                    ///< Random-access iterator.
+
+    /// @brief Creates an empty view.
+    constexpr Span() noexcept = default;
+
+    /**
+     * @brief Creates a view of @p size elements starting at @p data.
+     * @param data First element (may be null when @p size is 0).
+     * @param size Number of elements.
+     */
+    constexpr Span(T* data, std::size_t size) noexcept : data_(data), size_(size) {}
+
+    /// @brief Creates a view of all elements of @p array.
+    template <std::size_t N>
+    explicit constexpr Span(std::array<value_type, N>& array) noexcept
+        : data_(array.data()), size_(N) {}
+
+    /// @brief Creates a read-only view of all elements of @p array.
+    template <std::size_t N, typename U = T, typename = std::enable_if_t<std::is_const_v<U>>>
+    explicit constexpr Span(const std::array<value_type, N>& array) noexcept
+        : data_(array.data()), size_(N) {}
+
+    /// @brief Creates a read-only view from a mutable view of the same elements.
+    template <typename U,
+              typename = std::enable_if_t<std::is_same_v<const U, T> && !std::is_same_v<U, T>>>
+    explicit constexpr Span(Span<U> other) noexcept : data_(other.data()), size_(other.size()) {}
+
+    /// @brief Pointer to the first element.
+    [[nodiscard]] constexpr T* data() const noexcept { return data_; }
+    /// @brief Number of elements.
+    [[nodiscard]] constexpr std::size_t size() const noexcept { return size_; }
+    /// @brief true when the view has no elements.
+    [[nodiscard]] constexpr bool empty() const noexcept { return size_ == 0U; }
+
+    /**
+     * @brief Element access without bounds check.
+     * @param index Position, must be less than size().
+     */
+    [[nodiscard]] constexpr T& operator[](std::size_t index) const noexcept {
+        return *std::next(data_, static_cast<std::ptrdiff_t>(index));
+    }
+
+    /// @brief Iterator to the first element.
+    [[nodiscard]] constexpr iterator begin() const noexcept { return data_; }
+    /// @brief Iterator past the last element.
+    [[nodiscard]] constexpr iterator end() const noexcept {
+        return std::next(data_, static_cast<std::ptrdiff_t>(size_));
+    }
+
+    /**
+     * @brief View of the elements [offset, offset + count), clamped to this view.
+     * @param offset First element of the result; values past the end give an empty view.
+     * @param count Maximum number of elements.
+     */
+    [[nodiscard]] constexpr Span subspan(std::size_t offset, std::size_t count) const noexcept {
+        const std::size_t start = offset < size_ ? offset : size_;
+        const std::size_t available = size_ - start;
+        return Span(std::next(data_, static_cast<std::ptrdiff_t>(start)),
+                    count < available ? count : available);
+    }
+    /// @brief View of the elements from @p offset to the end, clamped to this view.
+    [[nodiscard]] constexpr Span subspan(std::size_t offset) const noexcept {
+        return subspan(offset, size_);
+    }
+    /// @brief View of the first @p count elements, clamped to this view.
+    [[nodiscard]] constexpr Span first(std::size_t count) const noexcept {
+        return subspan(0U, count);
+    }
+
+private:
+    T* data_ = nullptr;
+    std::size_t size_ = 0U;
+};
+
+/// @brief Creates a mutable view of all elements of @p array.
+template <typename T, std::size_t N> constexpr Span<T> make_span(std::array<T, N>& array) noexcept {
+    return Span<T>(array);
+}
+
+/// @brief Creates a read-only view of all elements of @p array.
+template <typename T, std::size_t N>
+constexpr Span<const T> make_span(const std::array<T, N>& array) noexcept {
+    return Span<const T>(array);
+}
+
+} // namespace wireforge
+
+#endif // WIREFORGE_SPAN_HPP

wireforge/_data/runtime/include/wireforge/static_vector.hpp

@@ -0,0 +1,264 @@
+/**
+ * @file static_vector.hpp
+ * @brief Fixed-capacity containers: StaticVector and FixedString.
+ */
+#ifndef WIREFORGE_STATIC_VECTOR_HPP
+#define WIREFORGE_STATIC_VECTOR_HPP
+
+#include "wireforge/span.hpp"
+#include "wireforge/status.hpp"
+
+#include <array>
+#include <cstddef>
+#include <initializer_list>
+#include <iterator>
+#include <string_view>
+
+namespace wireforge {
+
+/**
+ * @brief Vector with a fixed capacity and in-place storage; never allocates.
+ *
+ * Holds an element count plus a `std::array<T, N>`. An optional field is a StaticVector<T, 1>, a
+ * bounded array a StaticVector<T, N>. Elements beyond size() keep their previous values. Element
+ * access is unchecked.
+ * @tparam T Element type, must be default-constructible.
+ * @tparam N Capacity.
+ */
+template <typename T, std::size_t N> class StaticVector {
+public:
+    using value_type = T;            ///< Element type.
+    using iterator = T*;             ///< Mutable iterator.
+    using const_iterator = const T*; ///< Read-only iterator.
+
+    /// @brief Creates an empty vector; the storage is value-initialized.
+    constexpr StaticVector() noexcept = default;
+
+    /**
+     * @brief Creates a vector holding @p values; values beyond the capacity are dropped.
+     */
+    explicit constexpr StaticVector(std::initializer_list<T> values) noexcept {
+        for (const T& value : values) {
+            static_cast<void>(push_back(value)); // values beyond the capacity are dropped
+        }
+    }
+
+    /// @brief Maximum number of elements (N).
+    [[nodiscard]] static constexpr std::size_t capacity() noexcept { return N; }
+    /// @brief Current number of elements.
+    [[nodiscard]] constexpr std::size_t size() const noexcept { return size_; }
+    /// @brief true when size() is 0.
+    [[nodiscard]] constexpr bool empty() const noexcept { return size_ == 0U; }
+    /// @brief true when size() equals capacity().
+    [[nodiscard]] constexpr bool full() const noexcept { return size_ == N; }
+
+    /**
+     * @brief Sets the element count; elements added by growing are value-initialized.
+     * @param count New size.
+     * @return Status::CountExceedsMax (and no change) when @p count > N, otherwise Status::Ok.
+     */
+    constexpr Status resize(std::size_t count) noexcept {
+        if (count > N) {
+            return Status::CountExceedsMax;
+        }
+        for (std::size_t index = size_; index < count; ++index) {
+            *slot(index) = T{};
+        }
+        size_ = count;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Appends a copy of @p value.
+     * @return Status::CountExceedsMax when the vector is full, otherwise Status::Ok.
+     */
+    constexpr Status push_back(const T& value) noexcept {
+        if (size_ == N) {
+            return Status::CountExceedsMax;
+        }
+        *slot(size_) = value;
+        ++size_;
+        return Status::Ok;
+    }
+
+    /// @brief Sets the size to 0 (the storage is not modified).
+    constexpr void clear() noexcept { size_ = 0U; }
+
+    /// @brief Element access without bounds check; @p index must be less than capacity().
+    [[nodiscard]] constexpr T& operator[](std::size_t index) noexcept { return *slot(index); }
+    /// @brief Read-only element access without bounds check.
+    [[nodiscard]] constexpr const T& operator[](std::size_t index) const noexcept {
+        return *slot(index);
+    }
+
+    /// @brief Pointer to the storage.
+    [[nodiscard]] constexpr T* data() noexcept { return storage_.data(); }
+    /// @brief Read-only pointer to the storage.
+    [[nodiscard]] constexpr const T* data() const noexcept { return storage_.data(); }
+    /// @brief Iterator to the first element.
+    [[nodiscard]] constexpr iterator begin() noexcept { return data(); }
+    /// @brief Iterator past the last element.
+    [[nodiscard]] constexpr iterator end() noexcept { return slot(size_); }
+    /// @brief Read-only iterator to the first element.
+    [[nodiscard]] constexpr const_iterator begin() const noexcept { return data(); }
+    /// @brief Read-only iterator past the last element.
+    [[nodiscard]] constexpr const_iterator end() const noexcept { return slot(size_); }
+
+    /// @brief View of the first size() elements.
+    [[nodiscard]] constexpr Span<T> span() noexcept { return Span<T>(data(), size_); }
+    /// @brief Read-only view of the first size() elements.
+    [[nodiscard]] constexpr Span<const T> span() const noexcept {
+        return Span<const T>(data(), size_);
+    }
+
+    /// @brief Equal when the sizes and the first size() elements are equal.
+    [[nodiscard]] friend constexpr bool operator==(const StaticVector& lhs,
+                                                   const StaticVector& rhs) noexcept {
+        if (lhs.size_ != rhs.size_) {
+            return false;
+        }
+        for (std::size_t index = 0U; index < lhs.size_; ++index) {
+            if (!(lhs[index] == rhs[index])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /// @brief Negation of operator==.
+    [[nodiscard]] friend constexpr bool operator!=(const StaticVector& lhs,
+                                                   const StaticVector& rhs) noexcept {
+        return !(lhs == rhs);
+    }
+
+private:
+    [[nodiscard]] constexpr T* slot(std::size_t index) noexcept {
+        return std::next(storage_.data(), static_cast<std::ptrdiff_t>(index));
+    }
+    [[nodiscard]] constexpr const T* slot(std::size_t index) const noexcept {
+        return std::next(storage_.data(), static_cast<std::ptrdiff_t>(index));
+    }
+
+    std::array<T, N> storage_{};
+    std::size_t size_ = 0U;
+};
+
+/**
+ * @brief Bounded character string with in-place storage; never allocates.
+ *
+ * Holds up to N characters plus a terminating zero, so c_str() is always valid. Only size()
+ * characters are transmitted.
+ * @tparam N Maximum number of characters.
+ */
+template <std::size_t N> class FixedString {
+public:
+    /// @brief Creates an empty string.
+    constexpr FixedString() noexcept = default;
+
+    /// @brief Creates a string holding @p text, truncated to N characters.
+    explicit constexpr FixedString(std::string_view text) noexcept {
+        static_cast<void>(assign(text.substr(0U, text.size() < N ? text.size() : N)));
+    }
+
+    /// @brief Maximum number of characters (N).
+    [[nodiscard]] static constexpr std::size_t capacity() noexcept { return N; }
+    /// @brief Current number of characters.
+    [[nodiscard]] constexpr std::size_t size() const noexcept { return size_; }
+    /// @brief true when size() is 0.
+    [[nodiscard]] constexpr bool empty() const noexcept { return size_ == 0U; }
+
+    /**
+     * @brief Replaces the content with @p text.
+     * @return Status::CountExceedsMax (and no change) when @p text is longer than N.
+     */
+    constexpr Status assign(std::string_view text) noexcept {
+        if (text.size() > N) {
+            return Status::CountExceedsMax;
+        }
+        for (std::size_t index = 0U; index < text.size(); ++index) {
+            *slot(index) = text[index];
+        }
+        size_ = text.size();
+        *slot(size_) = '\0';
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Sets the length; characters added by growing are zero.
+     * @return Status::CountExceedsMax (and no change) when @p count > N.
+     */
+    constexpr Status resize(std::size_t count) noexcept {
+        if (count > N) {
+            return Status::CountExceedsMax;
+        }
+        for (std::size_t index = size_; index <= count; ++index) {
+            *slot(index) = '\0';
+        }
+        size_ = count;
+        *slot(size_) = '\0';
+        return Status::Ok;
+    }
+
+    /// @brief Makes the string empty.
+    constexpr void clear() noexcept {
+        size_ = 0U;
+        *slot(0U) = '\0';
+    }
+
+    /// @brief Character access without bounds check; @p index must be at most capacity().
+    [[nodiscard]] constexpr char& operator[](std::size_t index) noexcept { return *slot(index); }
+    /// @brief Read-only character access without bounds check.
+    [[nodiscard]] constexpr const char& operator[](std::size_t index) const noexcept {
+        return *slot(index);
+    }
+
+    /// @brief Pointer to the characters.
+    [[nodiscard]] constexpr char* data() noexcept { return chars_.data(); }
+    /// @brief Read-only pointer to the characters.
+    [[nodiscard]] constexpr const char* data() const noexcept { return chars_.data(); }
+    /// @brief Zero-terminated content.
+    [[nodiscard]] constexpr const char* c_str() const noexcept { return chars_.data(); }
+    /// @brief Content as a string view of size() characters.
+    [[nodiscard]] constexpr std::string_view view() const noexcept {
+        return std::string_view(chars_.data(), size_);
+    }
+
+    /// @brief Equal when the contents are equal.
+    [[nodiscard]] friend constexpr bool operator==(const FixedString& lhs,
+                                                   const FixedString& rhs) noexcept {
+        return lhs.view() == rhs.view();
+    }
+    /// @brief Negation of operator==.
+    [[nodiscard]] friend constexpr bool operator!=(const FixedString& lhs,
+                                                   const FixedString& rhs) noexcept {
+        return !(lhs == rhs);
+    }
+
+private:
+    [[nodiscard]] constexpr char* slot(std::size_t index) noexcept {
+        return std::next(chars_.data(), static_cast<std::ptrdiff_t>(index));
+    }
+    [[nodiscard]] constexpr const char* slot(std::size_t index) const noexcept {
+        return std::next(chars_.data(), static_cast<std::ptrdiff_t>(index));
+    }
+
+    std::array<char, N + 1U> chars_{};
+    std::size_t size_ = 0U;
+};
+
+/**
+ * @brief Returns an array whose elements are all @p value.
+ * @tparam T Element type.
+ * @tparam N Number of elements.
+ */
+template <typename T, std::size_t N>
+[[nodiscard]] constexpr std::array<T, N> filled(T value) noexcept {
+    std::array<T, N> result{};
+    for (std::size_t index = 0U; index < N; ++index) {
+        *std::next(result.data(), static_cast<std::ptrdiff_t>(index)) = value;
+    }
+    return result;
+}
+
+} // namespace wireforge
+
+#endif // WIREFORGE_STATIC_VECTOR_HPP

wireforge/_data/runtime/include/wireforge/status.hpp

@@ -0,0 +1,75 @@
+/**
+ * @file status.hpp
+ * @brief Status codes returned by every WireForge runtime and generated codec function.
+ */
+#ifndef WIREFORGE_STATUS_HPP
+#define WIREFORGE_STATUS_HPP
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <iterator>
+
+namespace wireforge {
+
+/**
+ * @brief Result of a runtime or codec operation.
+ *
+ * The runtime never throws exceptions; every fallible function returns a Status that the caller
+ * must inspect.
+ */
+enum class Status : std::uint8_t {
+    Ok,               ///< The operation succeeded.
+    BufferTooSmall,   ///< The output buffer cannot hold the encoded data.
+    Truncated,        ///< The input ended before the data was complete.
+    OutOfRange,       ///< A value violates its min/max, enum or bit-width range.
+    CountExceedsMax,  ///< An element count is above the capacity (or below the minimum).
+    ConstMismatch,    ///< A constant field differs from its declared value.
+    ChecksumMismatch, ///< A received checksum does not match the recomputed one.
+    UnknownMessageId, ///< A message id is not known on this interface.
+    InvalidLength,    ///< A length field is inconsistent with the frame or buffer.
+    TrailingBytes,    ///< The payload was not fully consumed.
+    InvalidState,     ///< The API was misused (invalid argument or call sequence).
+};
+
+/**
+ * @brief Tests a status for success.
+ * @param status Status to test.
+ * @return true when @p status is Status::Ok.
+ */
+[[nodiscard]] constexpr bool is_ok(Status status) noexcept {
+    return status == Status::Ok;
+}
+
+/**
+ * @brief Returns the name of a status code.
+ * @param status Status to name.
+ * @return A static, zero-terminated string such as "Truncated"; "Unknown" for values outside the
+ *         enumeration.
+ */
+[[nodiscard]] constexpr const char* to_string(Status status) noexcept {
+    // Indexed by the enumerator value. A lookup table instead of a switch: a switch over
+    // every enumerator needs a default label that -Wcovered-switch-default rejects.
+    constexpr std::array<const char*, 11U> kNames{
+        "Ok",
+        "BufferTooSmall",
+        "Truncated",
+        "OutOfRange",
+        "CountExceedsMax",
+        "ConstMismatch",
+        "ChecksumMismatch",
+        "UnknownMessageId",
+        "InvalidLength",
+        "TrailingBytes",
+        "InvalidState",
+    };
+    const auto index = static_cast<std::size_t>(status);
+    if (index < kNames.size()) {
+        return *std::next(kNames.begin(), static_cast<std::ptrdiff_t>(index));
+    }
+    return "Unknown";
+}
+
+} // namespace wireforge
+
+#endif // WIREFORGE_STATUS_HPP

wireforge/_data/runtime/include/wireforge/transport.hpp

@@ -0,0 +1,95 @@
+/**
+ * @file transport.hpp
+ * @brief Byte transport requirements, a polymorphic transport base and an in-memory loopback.
+ *
+ * A transport is any type with two non-blocking member functions:
+ * @code
+ * std::size_t send(wireforge::Span<const std::uint8_t> bytes) noexcept;   // bytes accepted
+ * std::size_t receive(wireforge::Span<std::uint8_t> buffer) noexcept;     // bytes read, 0 = none
+ * @endcode
+ * An existing driver interface is connected by a thin adapter class with these two functions,
+ * either as a plain type (no virtual calls) or derived from ITransport.
+ */
+#ifndef WIREFORGE_TRANSPORT_HPP
+#define WIREFORGE_TRANSPORT_HPP
+
+#include "wireforge/ring_buffer.hpp"
+#include "wireforge/span.hpp"
+
+#include <cstddef>
+#include <cstdint>
+#include <type_traits>
+#include <utility>
+
+namespace wireforge {
+
+/// @brief Detects whether @p T satisfies the transport requirements.
+template <typename T, typename = void> struct is_transport : std::false_type {};
+
+/// @cond INTERNAL
+template <typename T>
+struct is_transport<
+    T, std::void_t<decltype(std::declval<T&>().send(std::declval<Span<const std::uint8_t>>())),
+                   decltype(std::declval<T&>().receive(std::declval<Span<std::uint8_t>>()))>>
+    : std::bool_constant<
+          std::is_same_v<decltype(std::declval<T&>().send(
+                             std::declval<Span<const std::uint8_t>>())),
+                         std::size_t> &&
+          std::is_same_v<decltype(std::declval<T&>().receive(std::declval<Span<std::uint8_t>>())),
+                         std::size_t>> {};
+/// @endcond
+
+/// @brief true when @p T is a transport.
+template <typename T> inline constexpr bool is_transport_v = is_transport<T>::value;
+
+/// @brief Base class for transports selected at run time.
+class ITransport {
+public:
+    /**
+     * @brief Hands bytes to the driver without blocking.
+     * @return Number of bytes accepted; 0 when the driver cannot take any now.
+     */
+    virtual std::size_t send(Span<const std::uint8_t> bytes) noexcept = 0;
+
+    /**
+     * @brief Copies received bytes into @p buffer without blocking.
+     * @return Number of bytes copied; 0 when nothing was received.
+     */
+    virtual std::size_t receive(Span<std::uint8_t> buffer) noexcept = 0;
+
+protected:
+    ITransport() = default;                             ///< Only derived classes construct.
+    ITransport(const ITransport&) = default;            ///< Copy for derived classes.
+    ITransport& operator=(const ITransport&) = default; ///< Copy for derived classes.
+    ITransport(ITransport&&) = default;                 ///< Move for derived classes.
+    ITransport& operator=(ITransport&&) = default;      ///< Move for derived classes.
+    /// @brief Not virtual: transports are never deleted through an ITransport pointer.
+    ~ITransport() = default;
+};
+
+static_assert(is_transport_v<ITransport>, "ITransport must satisfy the transport requirements");
+
+/**
+ * @brief Transport whose sent bytes are received again, for tests and local links.
+ *
+ * One thread may send while another receives.
+ * @tparam N Capacity in bytes; send() accepts only what fits.
+ */
+template <std::size_t N> class LoopbackTransport {
+public:
+    /// @brief Stores as many bytes as fit; returns how many.
+    std::size_t send(Span<const std::uint8_t> bytes) noexcept { return ring_.write(bytes); }
+    /// @brief Returns bytes in the order they were sent.
+    std::size_t receive(Span<std::uint8_t> buffer) noexcept { return ring_.read(buffer); }
+    /// @brief Bytes that can still be sent.
+    [[nodiscard]] std::size_t free_space() const noexcept { return ring_.free_space(); }
+    /// @brief Bytes waiting to be received.
+    [[nodiscard]] std::size_t pending() const noexcept { return ring_.size(); }
+
+private:
+    StaticSpscByteRing<N> ring_;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_TRANSPORT_HPP