implement P3394R4 for utils::span

src/linyaps_box/utils/span.h

@@ -10,6 +10,7 @@
 #include <cassert>
 #include <cstddef>
 #include <iterator>
+#include <stdexcept>
 #include <type_traits>
 
 namespace linyaps_box::utils {
@@ -250,6 +251,14 @@ class span : public detail::view_base
         return data()[idx];
     }
 
+    [[nodiscard]] constexpr reference at(size_type idx) const
+    {
+        if (idx >= size()) {
+            throw std::out_of_range("span::at: index out of range");
+        }
+        return data()[idx];
+    }
+
     [[nodiscard]] constexpr reference front() const noexcept
     {
         assert(!empty());

tests/ll-box-ut/CMakeLists.txt

@@ -1,7 +1,8 @@
 include(GoogleTest)
 
 set(linyaps-box_UNIT_TESTS ll-box-ut)
-set(linyaps-box_UNIT_TESTS_SOURCE ./src/test.cpp ./src/semver_test.cpp)
+set(linyaps-box_UNIT_TESTS_SOURCE ./src/test.cpp ./src/semver_test.cpp
+                                  ./src/span_test.cpp)
 set(linyaps-box_UNIT_TESTS_LINK_LIBRARIES PRIVATE "${linyaps-box_LIBRARY}")
 set(linyaps-box_UNIT_TESTS_SOURCE_INCLUDE_DIRS
     PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src")

tests/ll-box-ut/src/span_test.cpp

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd.
+//
+// SPDX-License-Identifier: LGPL-3.0-or-later
+
+#include <gtest/gtest.h>
+
+#include <linyaps_box/utils/span.h>
+
+#include <array>
+#include <vector>
+
+namespace utils = linyaps_box::utils;
+
+TEST(SpanAt, ValidIndexDynamicExtent)
+{
+    std::array arr{ 10, 20, 30, 40 };
+    const utils::span<int> s(arr);
+
+    EXPECT_EQ(s.at(0), 10);
+    EXPECT_EQ(s.at(1), 20);
+    EXPECT_EQ(s.at(2), 30);
+    EXPECT_EQ(s.at(3), 40);
+}
+
+TEST(SpanAt, OutOfRangeThrows)
+{
+    std::array arr{ 1, 2, 3 };
+    const utils::span<int> s(arr);
+
+    EXPECT_THROW(std::ignore = s.at(3), std::out_of_range);
+    EXPECT_THROW(std::ignore = s.at(100), std::out_of_range);
+}
+
+TEST(SpanAt, EmptySpanThrows)
+{
+    const utils::span<int> s;
+    EXPECT_THROW(std::ignore = s.at(0), std::out_of_range);
+}
+
+TEST(SpanAt, ReturnsMutableReference)
+{
+    std::array arr{ 1, 2 };
+    const utils::span<int> s(arr);
+
+    s.at(1) = 42;
+    EXPECT_EQ(arr[1], 42);
+}
+
+TEST(SpanAt, ConstSpanReadsCorrectly)
+{
+    std::array arr{ 5, 6 };
+    const utils::span<const int> s(arr);
+
+    EXPECT_EQ(s.at(0), 5);
+    EXPECT_EQ(s.at(1), 6);
+}
+
+TEST(SpanAt, BoundaryIndex)
+{
+    std::array arr = { 99 };
+    const utils::span<int> s(arr);
+
+    EXPECT_EQ(s.at(0), 99);
+    EXPECT_THROW(std::ignore = s.at(1), std::out_of_range);
+}
+
+TEST(SpanAt, SubspanAt)
+{
+    std::array raw{ 0, 1, 2, 3, 4 };
+    auto s = utils::span<int>(raw).subspan(1, 3);
+
+    EXPECT_EQ(s.at(0), 1);
+    EXPECT_EQ(s.at(2), 3);
+    EXPECT_THROW(std::ignore = s.at(3), std::out_of_range);
+}