Merge pull request #3 from connectivecpp/develop

Merging develop to main

Author: cliffg-softwarelibre

.github/workflows/build_run_unit_test_cmake.yml

@@ -12,8 +12,8 @@ jobs:
   build_matrix:
     strategy:
       matrix:
-        # os: [ubuntu-latest, windows-latest, macos-14]
-        os: [ubuntu-latest]
+        os: [ubuntu-latest, windows-latest, macos-14]
+        # os: [ubuntu-latest]
     runs-on: ${{ matrix.os }}
     defaults:
       run:

README.md

@@ -1,4 +1,4 @@
-# Binary Serialize, Header-Only C++ 20 Binary Serialization Classes and Functions
+# Binary Serialize, Header-Only C++ 20 Binary Serialization Classes and Functions Using a `std::format` Like Syntax
 
 #### Unit Test and Documentation Generation Workflow Status
 
@@ -10,11 +10,52 @@
 
 ![GH Tag](https://img.shields.io/github/v/tag/connectivecpp/binary-serialize?label=GH%20tag)
 
+![License](https://img.shields.io/badge/License-Boost%201.0-blue)
+
 ## Overview
 
-The `binary_serialize` functions and classes provide serializing and unserializing of binary data. Serialization provides a way to transform application objects into and out of byte streams that can be sent over a network (or used for file IO).
+The `binary_serialize` functions and classes provide serializing and unserializing of binary data. Serialization provides a way to transform application objects into and out of byte streams that can be sent over a network (or used for file IO). Many serialization libraries transform objects to and from text representations, but this library keeps data in binary formats.
+
+The serialization functionality in this repository is useful when explicit control is needed for every bit and byte. This allows a developer to match an existing wire protocol or encoding scheme or to define his or her own wire protocol. Support is provided for fundamental arithmetic types as well as many C++ vocabulary types such as `std::optional`. Both big and little endian support is provided.
+
+Full flexibility is provided for sequences such as `std::string` or `std::vector`. The number of elements can be specified to take 8 or 16 or 32 (etc) bits, followed by the sequence of chars or array elements. Similar flexibility is provided for vocabulary types such as `std::optional`, where the boolean flag can be specified as 8 or 16 or 32 (etc) bits, followed by the object (or none, if there is no value in the optional).
+
+This library uses `std::format` style formatting. For example:
+
+```
+  struct Hike {
+    unsigned int  distance;
+    int  elevation;
+    std::optional<std::string>> name;
+    std::vector<int> waypoints;
+  };
+  // ...
+  chops::expandable_buffer<std::endian::big, chops::mutable_shared_buffer> buf;
+
+  chops::binary_serialize(buf, "{32u}{16}{8u}{16u}{16u}{64}", 
+                          hike_obj.distance, hike_obj.elevation, hike_obj.name, hike_obj.waypoints);
+
+  // ...
+  net_obj.send(buf.get_buf());
+                                                                   
+```
+
+The buffer will contain the following (note that truncation or casting will happen between the application
+object types and the serialized types as needed):
+
+```
+  32 bit unsigned integer containing distance value
+  16 bit signed integer containing elevation value
+  8 bit unsigned integer corresponding to true or false for the optional
+  16 bit unsigned integer for the size of the name string (if optional is true)
+  0 - N 8 bit characters for the name string (if optional is true)
+  16 bit unsigned integer for the size of the waypoints vector
+  0 - N 64 bit signed integers for each waypoint value
+```
+
+The documentation overview provides a comparison with other serialization libraries as well as a rationale for the design decisions.
 
-The serialization functionality in this repository is useful when explicit control is needed for every bit and byte. This allows a developer to match an existing wire protocol or encoding scheme or to define his or her own wire protocol. Support is provided for fundamental arithmetic types as well as certain C++ vocabulary types such as `std::optional`. Both big and little endian support is provided.
+Inspiration and thanks go to [Louis Langholtz](https://github.com/louis-langholtz), who steered me towards considering the `std::format` API.
 
 ## Generated Documentation
 
@@ -38,7 +79,7 @@ The unit test code uses [Catch2](https://github.com/catchorg/Catch2). If the `BI
 
 The unit test uses utilities from Connective C++'s [utility-rack](https://github.com/connectivecpp/utility-rack).
 
-Specific version (or branch) specs for the dependenies are in `test/CMakeLists.txt`.
+Specific version (or branch) specs for the dependencies are in the [test/CMakeLists.txt](test/CMakeLists.txt) file, look for the `CPMAddPackage` commands.
 
 ## Build and Run Unit Tests