Merge pull request #438 from elbeno/clarify-at-sequence

✅ Clarify the ordering of `at` arguments in a field
intel · Dec 6, 2023 · 2853f82 · 2853f82
2 parents b5dee7b + fbe560f
commit 2853f82
Show file tree

Hide file tree

Showing 3 changed files with 16 additions and 6 deletions.
diff --git a/docs/message.adoc b/docs/message.adoc
@@ -44,8 +44,18 @@ using my_field =
                          24_lsb}>;  // least significant bit
 ----
 
-NOTE: A field can specify multiple `at` arguments if it has several disjoint
-parts.
+A field can specify multiple `at` arguments if it has several disjoint parts. In
+that case, earlier `at` arguments specify more significant bits in the field,
+with later `at` arguments being less significant. For example:
+[source,cpp]
+----
+using namespace msg;
+using my_field =
+    field<"my field",               // name
+          std::uint16_t>            // type
+            ::located<at{0_dw, 31_msb, 24_lsb},  // high byte
+                      at{0_dw,  7_msb,  0_lsb}>; // low byte
+----
 
 Fields also expose several matcher aliases which can typically be used to
 specify field values for a given message type; an example of this follows

diff --git a/test/msg/field_extract.cpp b/test/msg/field_extract.cpp
@@ -45,9 +45,9 @@ TEST_CASE("across two storage elements", "[field extract]") {
 TEST_CASE("disjoint", "[field extract]") {
     using F = field<"", std::uint32_t>::located<at{0_dw, 5_msb, 3_lsb},
                                                 at{0_dw, 11_msb, 9_lsb}>;
-    std::array<std::uint32_t, 1> data{0b1'1011'1110'1110u};
+    std::array<std::uint32_t, 1> data{0b1'1101'1110'1110u};
     //                                    ^-^    ^--^
-    CHECK(0b101'101u == F::extract(data));
+    CHECK(0b101'110u == F::extract(data));
 }
 
 TEST_CASE("across multiple storage elements", "[field extract]") {

diff --git a/test/msg/field_insert.cpp b/test/msg/field_insert.cpp
@@ -51,8 +51,8 @@ TEST_CASE("disjoint", "[field insert]") {
                                                 at{0_dw, 11_msb, 9_lsb}>;
     std::array<std::uint32_t, 1> data{0b1'0001'1100'0110u};
     //                                    ^-^    ^--^
-    F::insert(data, 0b101'101u);
-    CHECK(0b1'1011'1110'1110u == data[0]);
+    F::insert(data, 0b101'110u);
+    CHECK(0b1'1101'1110'1110u == data[0]);
 }
 
 TEST_CASE("across multiple storage elements", "[field insert]") {