|
| constexpr size_type | size () const noexcept |
| | Returns the number of bytes in the view.
|
| template<trivial_bytes T> |
| constexpr const T & | at (const std::uint64_t offset=0) const noexcept |
| | Reinterpret a subregion of the view as a reference to T.
|
| template<trivial_bytes T> |
| constexpr const T * | fetch (const std::uint64_t offset=0) const noexcept |
| | Safely fetch a pointer to a T from the view.
|
| template<cv_free_pod_like T> |
| constexpr T | clone () const noexcept |
| | Clone the entire view contents into a value of type T on the stack.
|
| constexpr std::uint64_t | hash (jh::meta::c_hash hash_method=jh::meta::c_hash::fnv1a64) const noexcept |
| | Compute a deterministic 64-bit hash of the view contents.
|
| constexpr bool | operator== (const bytes_view &rhs) const noexcept |
| | Compare two views for byte-wise equality.
|
A read-only view over a block of raw bytes.
This struct holds a pointer + length representing a memory region. It supports reinterpretation as POD types, safe view extraction, and object-level clone utilities.
Clone Safety Model
The clone<T>() method is only available for pod_like types. This ensures:
-
Bitwise copies are semantically valid (no heap ownership, no reference count)
-
Cloned objects do not require custom destructors or resource management
-
Structures reconstructed from raw bytes behave identically to their originals
Formal constraints
In essence, this maps to:
-
std::is_standard_layout_v<T>
-
std::is_trivially_constructible_v<T>
-
std::is_trivially_copyable_v<T>
-
std::is_trivially_destructible_v<T>
Which is exactly what jh::pod::pod_like<T> ensures.
- Note
- The functions
from, at, fetch, and clone are declared constexpr primarily to enable aggressive compiler optimizations. However, because they internally use reinterpret_cast, they cannot be evaluated in consteval contexts. If you need to copy POD objects or construct one POD from another at compile time, write the copy or constructor manually instead of relying on these helpers.
template<trivial_bytes T>
| const T & jh::pod::bytes_view::at |
( |
const std::uint64_t | offset = 0 | ) |
const |
|
inlineconstexprnoexcept |
Reinterpret a subregion of the view as a reference to T.
This function provides POD-safe reinterpretation of the underlying bytes. The type T must satisfy trivial_bytes, ensuring the result is well-defined for POD-like memory.
Internally it uses std::launder to avoid undefined behavior when reinterpreting object representations. The operation is marked noexcept and is guaranteed not to throw.
- Template Parameters
-
- Parameters
-
| offset | Offset in bytes into the view (default 0). |
- Returns
- Reference to the reinterpreted value at the specified offset.
- Note
- The caller must ensure
offset + sizeof(T) <= size(). No bounds checking is performed; out-of-bounds access remains the caller's responsibility.
template<cv_free_pod_like T>
| T jh::pod::bytes_view::clone |
( |
| ) |
const |
|
inlinenodiscardconstexprnoexcept |
Clone the entire view contents into a value of type T on the stack.
This is the safest way to materialize a pod_like object from a bytes_view. It requires that:
-
len == sizeof(T) — the view must exactly match the size of T.
-
T must satisfy pod_like (standard layout, trivially constructible, trivially copyable, trivially destructible).
If the size check fails, a default-initialized T{} (zero-initialized POD object) is returned. Otherwise, this function copies the raw bytes into a local object and returns it by value, effectively performing a POD copy.
- Template Parameters
-
| T | Must satisfy cv_free_pod_like. Using const or volatile qualified types is disallowed, as this function constructs a writable value of type T. |
- Returns
- A value reconstructed from the view if sizes match, or a default-initialized
T{} if size mismatch.
template<trivial_bytes T>
| const T * jh::pod::bytes_view::fetch |
( |
const std::uint64_t | offset = 0 | ) |
const |
|
inlineconstexprnoexcept |
Safely fetch a pointer to a T from the view.
This is the bounds-checked counterpart to at. It reinterprets a subregion of the view as T if the memory range [offset, offset + sizeof(T)) is fully contained within the view. If the range would exceed size(), it returns nullptr instead of producing undefined behavior.
The type T must satisfy trivial_bytes, ensuring POD-safe reinterpretation semantics. Internally it uses std::launder to avoid undefined behavior when accessing object representations. The operation is marked noexcept.
- Template Parameters
-
- Parameters
-
| offset | Offset in bytes into the view (default 0). |
- Returns
- Pointer to the reinterpreted value, or
nullptr if out of bounds.
template<trivial_bytes T>
| constexpr bytes_view jh::pod::bytes_view::from |
( |
const T * | arr, |
|
|
const std::uint64_t | size ) |
|
inlinestaticconstexprnoexcept |
Construct a bytes_view from a contiguous array of objects.
Like the single-object overload, this provides a safer alternative to manual reinterpret_cast by requiring trivial_bytes elements. It enables treating a typed array or buffer (e.g., from a C-style array, span, or mmap'd structure) as a flat byte view.
- Template Parameters
-
- Parameters
-
| arr | Pointer to the first element (may be nullptr if size == 0). |
| size | Number of elements (of type T, not bytes). |
- Returns
- A
bytes_view covering sizeof(T) * size bytes starting at arr.
- Note
- The caller must ensure that
arr points to a valid contiguous block of at least size elements.
|
|
inlinenodiscardconstexprnoexcept |
Compute a deterministic 64-bit hash of the view contents.
This function computes a stable, non-cryptographic hash value from the raw bytes in the view. The result depends only on the byte sequence and its length, not on any type-level semantics. It is suitable for version checking, cache keys, or equality grouping.
- Parameters
-
| hash_method | Hash algorithm to use (default: fnv1a64). |
- Returns
- 64-bit hash of the byte content, or
0xFFFFFFFFFFFFFFFF if data == nullptr.
- Note
- This hash is not cryptographically secure and must not be used for security-sensitive purposes.
-
If
data == nullptr, the return value is 0xFFFFFFFFFFFFFFFF (sentinel).
-
Although declared
constexpr, this function cannot be used in consteval contexts due to its reliance on pointer reinterpretation. It is intended for runtime use.
