working on new API and details

Author: cliffg-softwarelibre

include/serialize/binary_serialize.hpp

@@ -1,11 +1,14 @@
 /** @mainpage Binary Serialuze, Classes and Functions For Binary Data Serialization
+ *
+ * ## Overview
  *
  * Serialization transforms objects into a byte stream for transmission over a 
  * network or for file IO. Deserialization is the converse, transforming a byte
  * stream into application level objects.
  *
  * This library differs from other binary serialization libraries in that the
- * main interfaces is a "std::format" like 
+ * main interfaces is a "std::format" like interface. 
+ *
  * These functions and classes provide a simple and light abstraction for binary big-endian serialization. There are no
  * message or element definitions, no embedded preprocesser syntax, and no extra 
  * build steps.
@@ -113,7 +116,6 @@
 #ifndef BINARY_SERIALIZE_HPP_INCLUDED
 #define BINARY_SERIALIZE_HPP_INCLUDED
 
-#include "utility/cast_ptr_to.hpp"
 #include "buffer/shared_buffer.hpp"
 #include "serialize/extract_append.hpp"
 
@@ -127,12 +129,28 @@
 #include <iterator> // value type of iterator
 #include <array>
 #include <cassert>
+#include <concepts>
 
 #include <iostream> // debugging
 
 namespace chops {
 
+template <typename Ctr>
+concept supports_expandable_buffer = 
+  std::same_as<Ctr::value_type, std::byte> &&
+  requires (Ctr ctr) {
+    { ctr.size() } -> std::integral;
+    ctr.resize(std::size_t{});
+    { ctr.data() } -> std::same_as<std::byte*>;
+  }
+
+template <supports_expandable_buffer Ctr = chops::mutable_shared_buffer,
+         std::endian Endian = std::endian::little>
+struct expandable_buffer : Ctr {
+  using Endian;
+}
 /**
+
  * @brief Extract a sequence in network byte order from a @c std::byte buffer into the
  * provided container.
  *
@@ -188,6 +206,8 @@ Container extract_sequence(const std::byte* buf) noexcept(fill in) {
  * the elements in the sequence.
  *
  */
+
+
 /*
 template <typename Cnt, typename Iter>
 std::size_t append_sequence(std::byte* buf, Cnt cnt, Iter start, Iter end) noexcept {
@@ -278,6 +298,17 @@ Buf& marshall(Buf& buf, const T& val, adl_tag) {
   return buf;
 }
 
+namespace detail {
+
+template <typename CastValType, typename T, typename Buf = expandable_buffer>
+constexpr Buf& serialize_val(Buf& buf, const T& val) {
+  auto old_sz = buf.size();
+  buf.resize(old_sz + sizeof(CastValType));
+  append_val(buf.data()+old_sz, static_cast<CastValType>(val));
+  return buf;
+}
+
+}
 /**
  * @brief Marshall a single arithmetic value or a @c std::byte into a buffer of bytes.
  *

include/serialize/byteswap.hpp

@@ -1,6 +1,6 @@
 /** @file
  *
- * @brief This is a direct implementation of the C++ 23 std::byteswap function,
+ * @brief This is an implementation of the C++ 23 @c std::byteswap function,
  * for use in pre C++ 23 applications.
  *
  * This implementation is taken directly from the CPP Reference page:
@@ -18,14 +18,25 @@
 #ifndef BYTESWAP_HPP_INCLUDED
 #define BYTESWAP_HPP_INCLUDED
 
-#include <concepts> // std::integral
+#include <concepts> // std::integral concept
 #include <bit> // std::bit_cast
 #include <array>
 #include <cstddef> // std::byte
 #include <algorithm> // std::ranges::reverse
 
 namespace chops {
 
+/**
+ * @brief Perform an in-place byte swap on an integral type (if size of the 
+ * type is greater than one).
+ *
+ * @tparam T Type of value where swapping will occur.
+ *
+ * @param value Integral value to be byte swapped.
+ *
+ * @pre There must not be any padding bits in the type.
+ *
+ */
 template<std::integral T>
 constexpr T byteswap(T value) noexcept {
   if constexpr (sizeof(T) == 1u) {

include/serialize/extract_append.hpp

@@ -4,9 +4,9 @@
  * endian order) to native format; conversely, given an arithmetic binary value, append 
  * it to a buffer of bytes in the specified endian order.
  *
- * The functions in this file are low-level. The handle fundamental arithmetic types and 
+ * The functions in this file are low-level. They handle fundamental arithmetic types and 
  * extracting or appending to @c std::byte buffers. It is meant to be the lower layer
- * of serializing utilities, where the next layer up provides buffer management,
+ * of serializing utilities, where the next higher layer provides buffer management,
  * sequences, and overloads for specific types such as @c std::string, @c bool, and 
  * @c std::optional.
  *
@@ -78,7 +78,7 @@ concept integral_or_byte = std::integral<T> || std::is_same_v<std::remove_cv_t<T
  * @brief Extract a value from a @c std::byte buffer into a fundamental integral
  * or @c std::byte type in native endianness, swapping bytes as needed.
  *
- * @tparam BufEndian The endianness of the buffer.
+ * @tparam BufEndian The endianness of the @c std::byte buffer.
  *
  * @tparam T Type of return value.
  *
@@ -166,7 +166,7 @@ constexpr std::size_t append_val(std::byte* buf, const T& val) noexcept {
  * will result in the native endianness of the platform. I.e. this works whether serialization 
  * is big-endian or little-endian.
  * 
- * @note Unsigned types are not supported.
+ * @note Signed types are not supported.
  *
  * @param val The input value. Any standard unsigned integer type is allowed.
  *
@@ -204,6 +204,8 @@ constexpr std::size_t append_var_int(std::byte* output, T val) {
  * For consistency with the @c append_var_int function, only unsigned integers are
  * supported for the output type of this function.
  *
+ * @note Signed types are not supported.
+ *
  * @param input A variable-length encoded integer stored in a buffer of @c std::bytes.
  *
  * @param input_size Number of bytes representing the integer.