refactor: Improve byte_span with type safety, flexible construction, and string handling

Author: range3

README.md

@@ -1,73 +1,96 @@
-# byte_span
+# range3::byte_span
 
-`byte_span` is a lightweight view class for efficient handling of byte data. Based on the concept of `std::span`, it provides specialized functionality for byte data manipulation.
+byte_span is a non-owning view class for byte sequences, similar to std::span.
+It provides unified handling of byte-like types (`std::byte`, `char`, `unsigned char`)
+and allows viewing any trivially copyable data as a byte sequence.
 
 ## Features
 
-- Non-owning view type
+- Non-owning view type with zero overhead
 - Unified handling of byte-like types (`std::byte`, `char`, `unsigned char`)
-- View trivially copyable data types as byte sequences
+- View any trivially copyable type as byte sequences
+- Compatible with any contiguous range (vectors, arrays, C-style arrays)
 - Type-safe design using C++20 concepts
-- Zero-overhead abstraction
 
 ## Basic Usage
 
-### 1. Creating from Byte Arrays
+### Creating from Byte-like Types
 
-The most basic usage is creating a `byte_span` from a byte array:
+The most common use case is creating a byte view from containers of byte-like types:
 
 ```cpp
-std::byte data[4] = {
-    std::byte{0x00}, std::byte{0x01}, 
-    std::byte{0x02}, std::byte{0x03}
+std::vector<char> chars = {'a', 'b', 'c'};
+byte_span view1{chars};  // Deduced as byte_span<std::byte>
+
+unsigned char raw[4] = {0x00, 0x01, 0x02, 0x03};
+byte_span view2{raw};   // Deduced as byte_span<std::byte, 4>
+
+std::array<std::byte, 3> bytes = {
+    std::byte{1}, std::byte{2}, std::byte{3}
 };
-byte_span view{data};  // Deduced as byte_span<std::byte, 4>
+byte_span view3{bytes}; // Deduced as byte_span<std::byte, 3>
 ```
 
-### 2. Creating from std::array
-
-Easy creation from `std::array`:
+### Creating from Any Trivially Copyable Type
+View any trivially copyable data as bytes:
 
 ```cpp
-std::array<std::byte, 4> arr = {
-    std::byte{0x00}, std::byte{0x01}, 
-    std::byte{0x02}, std::byte{0x03}
-};
-byte_span view{arr};  // Deduced as byte_span<std::byte, 4>
+// From vector of integers
+std::vector<int> ints = {1, 2, 3};
+byte_span view1{ints};  // Deduced as byte_span<std::byte>
+assert(view1.size() == sizeof(int) * 3);
+
+// From custom struct
+struct Point { 
+    float x, y; 
+}; 
+Point p{1.0f, 2.0f};
+byte_span view2{&p, 1};  // Deduced as byte_span<std::byte>
+assert(view2.size() == sizeof(Point)); // sizeof(Point) = 8 bytes (typically)
 ```
 
-### 3. Creating from std::vector
+### Dynamic and Static Extents
+```cpp
+// Dynamic extent (size known at runtime)
+std::vector<std::byte> vec(100);
+byte_span view1{vec};  // Deduced as byte_span<std::byte, dynamic_extent>
 
-You can create views from any contiguous container, including `std::vector`:
+// Static extent (size known at compile time)
+std::array<char, 4> arr = {'a', 'b', 'c', 'd'};
+byte_span view2{arr};  // Deduced as byte_span<std::byte, 4>
 
-```cpp
-// Integer data
-std::vector<int> numbers = {1, 2, 3, 4};
-byte_span view{numbers};  // View integers as bytes
+// Converting from static to dynamic extent is always possible
+byte_view view3 = view2;  // OK: byte_view has dynamic extent
 
-// Access underlying bytes
-auto first_byte = view[0];
-auto size_in_bytes = view.size();  // size = sizeof(int) * numbers.size()
+// Converting from dynamic to static extent requires explicit extent
+std::vector<char> vec2(4);
+byte_span<std::byte, 4> view4{vec2};  // OK if vec2.size() == 4
 ```
 
-### 4. Dynamic Size Views
+## Advanced Usage
 
-For runtime-sized views, use `dynamic_extent`:
+### Using byte_view and cbyte_view
 
-```cpp
-std::vector<std::byte> vec(100);
-byte_span view{vec};  // Deduced as byte_span<std::byte, dynamic_extent>
-```
+Two convenient aliases are provided:
+- `byte_view`: Alias for `byte_span<std::byte>` (mutable, dynamic_extent)
+- `cbyte_view`: Alias for `byte_span<const std::byte>` (immutable, dynamic_extent)
 
-## Advanced Usage
+Example:
 
-### 1. Using byte_view and cbyte_view
+```cpp
+void process_bytes(cbyte_view data) {  // Accept any byte-like input
+    for (auto b : data) {
+        std::cout << std::format("{:02x} ", std::to_integer<int>(b));
+    }
+}
 
-The library provides two convenient type aliases:
-- `byte_view`: Mutable byte span (alias for `byte_span<std::byte>`)
-- `cbyte_view`: Immutable byte span (alias for `byte_span<const std::byte>`)
+// Works with any byte-like container
+std::vector<char> chars = {'a', 'b', 'c'};
+process_bytes(chars);
 
-Example usage in functions:
+std::array<unsigned char, 4> raw = {0x00, 0x01, 0x02, 0x03};
+process_bytes(raw);
+```
 
 ```cpp
 // Function accepting read-only byte view
@@ -90,68 +113,61 @@ fill_pattern(buffer);      // Modify buffer
 print_hex_dump(buffer);    // Read buffer
 ```
 
-### 2. Trivially Copyable Types as Byte Views
-
-Any trivially copyable type can be viewed as bytes:
+### Error Handling
+`byte_span` provides safety guarantees at both compile-time and runtime:
 
 ```cpp
-struct Point {
-    float x;
-    float y;
+// Compile-time checks
+struct non_trivially_copyable {
+    std::string str;  // non-trivially copyable member
 };
+non_trivially_copyable obj;
+byte_span view{obj};  // Compilation error: type requirements not met
 
-Point p{1.0f, 2.0f};
-byte_span view{std::span{&p, 1}};  // View Point's bytes
-```
-
-### 3. String Data Handling
+// Extent mismatch
+std::vector<char> vec(3);
+byte_span<std::byte, 4> view{vec};  // Runtime assertion failure: size mismatch
 
-String data can be easily handled:
-
-```cpp
-std::string str = "Hello, World!";
-byte_span view{str};  // View string data as bytes
-
-// Convert to string_view
-auto sv = as_sv(view);  // Get as std::string_view
+std::array<char, 8> arr;
+byte_span<std::byte, 4> view{arr};  // Compilation error: static extent mismatch
 ```
 
-### 4. Implicit Conversion in Function Arguments
-
-Functions can accept various container types through implicit conversion:
+### String Handling
+Work seamlessly with string types:
 
 ```cpp
-void process_bytes(byte_span view) {
-    // Process byte data
-}
-
-// Various ways to call
-std::vector<std::byte> vec(100);
-process_bytes(vec);  // OK
+std::string str = "Hello";
+byte_span view1{str};  // View string data as bytes
 
-std::array<char, 10> arr;
-process_bytes(arr);  // OK
+std::string_view sv = "World";
+byte_span view2{sv};   // View string_view data as bytes
+// Note: does not include null terminator
 
-unsigned char raw_data[20];
-process_bytes(raw_data);  // OK
+// Convert back to string_view
+auto sv2 = as_sv(view1);  // Get std::string_view
 ```
 
-### 5. Data Type Conversions
+### Type Conversions
 
-Safe data type conversions:
+Safe conversions between types:
 
 ```cpp
 std::vector<int> numbers = {1, 2, 3, 4};
 byte_span view{numbers};
 
-// Read as span of ints
-auto int_span = as_span<int>(view);
-// Get first value
-auto& first_int = as_value<int>(view);
-```
+// Convert to span of ints
+std::span<const int> cint_span = as_span<int>(view);  
+std::span<int> int_span = as_writable_span<int>(view);
 
-### 6. Creating Sub-views
+// Get reference to first value
+const int& first = as_value<int>(view);  
+
+// Convert to std::span of bytes
+std::span<const std::byte> cbyte_std_span = as_bytes(view);
+std::span<std::byte> byte_std_span = as_writable_bytes(view);
+```
 
+### Sub-views
 Create views of specific ranges:
 
 ```cpp