Added byteswap header, redesigned extract_append with endian flexibility

Author: cliffg-softwarelibre

include/serialize/binary_serialize.hpp

@@ -1,15 +1,12 @@
-/** @file
+/** @mainpage Binary Serialuze, Classes and Functions For Binary Data Serialization
  *
- *  @defgroup marshall_module Classes and functions for big-endian binary data 
- *  marshalling and unmarshalling (transform objects into and out of byte streams 
- *  for transmission over a network or for file IO).
+ *  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.
  *
- *  @brief Classes and functions to transform objects into a big-endian binary stream 
- *  of bytes (marshall) and the converse (unmarshall), transform a stream of bytes into 
- *  objects.
- *
- *  The @c utility-rack @c marshall and @c unmarshall functions and classes provide a 
- *  simple and light abstraction for binary big-endian serialization. There are no
+ *  This library differs from other binary serialization libraries in that the
+ *  main interfaces is a "std::format" like 
+ *  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,8 +110,8 @@
  *
  */
 
-#ifndef MARSHALL_HPP_INCLUDED
-#define MARSHALL_HPP_INCLUDED
+#ifndef BINARY_SERIALIZE_HPP_INCLUDED
+#define BINARY_SERIALIZE_HPP_INCLUDED
 
 #include "utility/cast_ptr_to.hpp"
 #include "marshall/shared_buffer.hpp"

include/serialize/byteswap.hpp

@@ -0,0 +1,44 @@
+/** @file
+ *
+ * @brief This is a direct implementation of the C++ 23 std::byteswap function,
+ * for use in pre C++ 23 applications.
+ *
+ * This implementation is taken directly from the CPP Reference page:
+ * https://en.cppreference.com/w/cpp/numeric/byteswap
+ *
+ * @author Cliff Green, CPP Reference
+ *
+ * @copyright (c) 2024 by Cliff Green
+ *
+ * Distributed under the Boost Software License, Version 1.0. 
+ * (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ *
+ */
+
+#ifndef BYTESWAP_HPP_INCLUDED
+#define BYTESWAP_HPP_INCLUDED
+
+#include <concepts> // std::integral
+#include <bit> // std::bit_cast
+#include <array>
+#include <cstddef> // std::byte
+#include <algorithm> // std::ranges::reverse
+
+namespace chops {
+
+template<std::integral T>
+constexpr T byteswap(T value) noexcept {
+  if constexpr (sizeof(T) == 1u) {
+    return value;
+  }
+  static_assert(std::has_unique_object_representations_v<T>,
+                "T may not have padding bits");
+  auto value_representation = std::bit_cast<std::array<std::byte, sizeof(T)>>(value);
+  std::ranges::reverse(value_representation);
+  return std::bit_cast<T>(value_representation);
+}
+
+} // end namespace
+
+#endif
+