Improve ascii_string_view

Author: Julian LALU

core.vscode.code-workspace

@@ -32,8 +32,7 @@
     "extensions": {
         "recommendations": [
             "ms-vscode.cpptools-extension-pack",
-            "ryanluker.vscode-coverage-gutters",
-            "matepek.vscode-catch2-test-adapter"
+            "ryanluker.vscode-coverage-gutters"
         ]
     }
 }

interface/core/slice.h

@@ -9,37 +9,38 @@ namespace hud
 {
 
     /**
-     * Describes an object that can refer to a contiguous sequence of elements to type type_t
-     * with the first element of the sequence at position zero.
-     * @tparam type_t The element type
+     * Represents a contiguous sequence of elements of type `type_t`, starting at index zero.
+     * This class provides bounds-checked access, iteration, and the ability to create sub-slices.
+     * Note: Copy and move operations do NOT perform deep copies; they only copy the pointer and the count.
+     * @tparam type_t The element type of the slice.
      */
     template<typename type_t>
     class slice
     {
     public:
-        /** Mutable slice iterator type */
+        /** Mutable iterator type for the slice. */
         using iterator = random_access_iterator<type_t *>;
-        /** Constant slice iterator type */
+        /** Constant iterator type for the slice. */
         using const_iterator = random_access_iterator<const type_t *>;
 
-        /** Default construct with value-initialized slice. */
+        /** Default constructs an empty slice. */
         constexpr slice() noexcept = default;
 
         /**
-         * Construct with user-defined begin_ptr_ and number of elements to sequence.
-         * @param first The begin_ptr_ to the first element of the contiguous sequence of elements
-         * @param count The number of elements in the sequence
+         * Constructs a slice from a pointer to the first element and a number of elements.
+         * @param first Pointer to the first element of the contiguous sequence.
+         * @param count Number of elements in the sequence.
          */
         HD_FORCEINLINE constexpr slice(type_t *first, const usize count) noexcept
             : begin_ptr_(first)
             , count_element_(count)
         {
         }
 
-        /** Copy construct the slice. */
+        /** Copy constructor (shallow copy, does NOT copy underlying elements). */
         constexpr slice(const slice &other) noexcept = default;
 
-        /** Move construct the slice. */
+        /** Move constructor (shallow move, resets moved-from slice to empty). */
         HD_FORCEINLINE constexpr slice(slice &&other) noexcept
             : begin_ptr_(other.begin_ptr_)
             , count_element_(other.count_element_)
@@ -48,10 +49,10 @@ namespace hud
             other.count_element_ = 0u;
         }
 
-        /** Copy assign the slice. */
+        /** Copy assignment (shallow copy, does NOT copy underlying elements). */
         constexpr slice &operator=(const slice &other) noexcept = default;
 
-        /** Move assign the slice. */
+        /** Move assignment (shallow move, resets moved-from slice to empty). */
         HD_FORCEINLINE constexpr slice &operator=(slice &&other) noexcept
         {
             if (this != &other) {
@@ -63,20 +64,20 @@ namespace hud
             return *this;
         }
 
-        /** Reset the slice to empty. */
+        /** Resets the slice to empty. */
         HD_FORCEINLINE constexpr void reset() noexcept
         {
             begin_ptr_ = nullptr;
             count_element_ = 0u;
         }
 
-        /** Retrieves reference on the element at the given index. */
+        /** Returns a reference to the element at the given index (bounds-checked). */
         [[nodiscard]] HD_FORCEINLINE constexpr type_t &operator[](const usize index) noexcept
         {
             return *data_at(index);
         }
 
-        /** Retrieves reference on the element at the given index. */
+        /** Returns a const reference to the element at the given index (bounds-checked). */
         [[nodiscard]] HD_FORCEINLINE constexpr const type_t &operator[](const usize index) const noexcept
         {
             return const_cast<slice &>(*this)[index];
@@ -88,59 +89,59 @@ namespace hud
             return count_element_ == 0u;
         }
 
-        /** Retrieves a pointer to the beginning of the sequence. */
+        /** Returns  a pointer to the beginning of the sequence. */
         [[nodiscard]] HD_FORCEINLINE constexpr type_t *data() noexcept
         {
             return begin_ptr_;
         }
 
-        /** Retrieves a pointer to the beginning of the sequence. */
+        /** Returns  a pointer to the beginning of the sequence. */
         [[nodiscard]] HD_FORCEINLINE constexpr const type_t *data() const noexcept
         {
             return begin_ptr_;
         }
 
-        /** Retrieves a pointer to the the sequence at the given index. */
+        /** Returns  a pointer to the the sequence at the given index. */
         [[nodiscard]] HD_FORCEINLINE constexpr type_t *data_at(const usize index) noexcept
         {
             check(is_valid_index(index));
             return data() + index;
         }
 
-        /** Retrieves a pointer to the the sequence at the given index. */
+        /** Returns  a pointer to the the sequence at the given index. */
         [[nodiscard]] HD_FORCEINLINE constexpr const type_t *data_at(const usize index) const noexcept
         {
             return const_cast<slice &>(*this).data_at(index);
         }
 
-        /** Retrieves the number of elements the slice refers to. */
+        /** Returns the number of elements the slice covers. */
         [[nodiscard]] HD_FORCEINLINE constexpr usize count() const noexcept
         {
             return count_element_;
         }
 
-        /** Retrieves the count of bytes the slice refers to. */
+        /** Returns the number of bytes the slice covers. */
         [[nodiscard]] HD_FORCEINLINE constexpr usize byte_count() const noexcept
         {
             return count() * sizeof(type_t);
         }
 
-        /** Check whether index is in valid range or not. */
+        /** Returns true if the range [start_index, start_index+range_count) is valid. */
         [[nodiscard]] HD_FORCEINLINE constexpr bool is_valid_index(const usize index) const noexcept
         {
             // When index is unsigned, we don't need to check for negative values
             static_assert(is_unsigned_v<decltype(index)>);
             return count() - index > 0u;
         }
 
-        /** Check whether a range from index of countis in valid or not. */
+        /** Returns true if the range [start_index, start_index+range_count) is valid. */
         [[nodiscard]] HD_FORCEINLINE constexpr bool is_valid_range(const usize start_index, const usize range_count) const noexcept
         {
             return is_valid_index(start_index) && (start_index + range_count) <= count(); // Valid if more element is available than required
         }
 
         /**
-         * Retrieves a sub slice of the slice.
+         * Returns a sub-slice starting at `first_index` spanning `count` elements.
          * @param first_index The index of the first element in the slice sequence
          * @param count The number of elements the slice sequence must contains
          * @return The sub slice from data()+first_index over a sequence of count elements
@@ -152,7 +153,7 @@ namespace hud
         }
 
         /**
-         * Retrieves a sub-slice of the slice.
+         * Returns a sub-slice starting at `first_index` spanning `count` elements.
          * @param first_index The index of the first element in the slice sequence
          * @param count The number of elements the slice sequence must contains
          * @return The sub-slice from data()+first_index over a sequence of count elements
@@ -162,25 +163,25 @@ namespace hud
             return const_cast<slice &>(*this).sub_slice(first_index, count);
         }
 
-        /** Retrieves an iterator to the beginning of the slice. */
+        /** Returns an iterator to the beginning of the slice. */
         [[nodiscard]] HD_FORCEINLINE constexpr iterator begin() noexcept
         {
             return iterator(begin_ptr_);
         }
 
-        /** Retrieves an const_iterator to the beginning of the slice. */
+        /** Returns an const_iterator to the beginning of the slice. */
         [[nodiscard]] HD_FORCEINLINE constexpr const_iterator begin() const noexcept
         {
             return const_iterator(begin_ptr_);
         }
 
-        /** Retrieves an iterator to the end of the slice. */
+        /** Returns an iterator to the end of the slice. */
         [[nodiscard]] HD_FORCEINLINE constexpr iterator end() noexcept
         {
             return iterator(begin_ptr_ + count_element_);
         }
 
-        /** Retrieves an const_iterator to the end of the slice. */
+        /** Returns an const_iterator to the end of the slice. */
         [[nodiscard]] HD_FORCEINLINE constexpr const_iterator end() const noexcept
         {
             return const_iterator(begin_ptr_ + count_element_);
@@ -193,6 +194,19 @@ namespace hud
         usize count_element_ = 0u;
     };
 
+    /**
+     * Class template argument deduction guide for C-style arrays of const elements.
+     * Deduces a slice of const type from a const C-style array.
+     */
+    template<typename type_t, size_t N>
+    slice(const type_t (&)[N]) -> slice<const type_t>;
+
+    /**
+     * Class template argument deduction guide for C-style arrays of mutable elements.
+     * Deduces a slice of mutable type from a C-style array.
+     */
+    template<typename type_t, size_t N>
+    slice(type_t (&)[N]) -> slice<type_t>;
 } // namespace hud
 
 #endif // HD_INC_CORE_SLICE_H