✨ Add from_le and from_be

Problem:
- It is counterintuitive (although representationally correct) to use `to_be` to
  do the job of both `htonl` and `ntohl`.

Solution:
- Add `from_be` and `from_le` to match `to_be` and `to_le`.

Author: elbeno

docs/bit.adoc

@@ -124,18 +124,28 @@ constexpr auto y = stdx::smallest_uint<1337>(); // std::uint16_t{}
 using T = stdx::smallest_uint_t<1337>; // std::uint16_t
 ----
 
-=== `to_le` and `to_be`
+=== `to_be`, `from_be`, `to_le`, `from_le`
 
-`to_le` and `to_be` are variations on `byteswap` that convert unsigned integral
-types to little- or big-endian respectively. On a little-endian machine, `to_le`
-does nothing, and `to_be` is the equivalent of `byteswap`. On a big endian
-machine it is the other way around.
+`to_be` and `from_be` are variations on `byteswap` that do the job of
+https://linux.die.net/man/3/htonl[`htonl` and friends]. On a big-endian machine,
+they do nothing, and on a little-endian machine, they are the equivalent of
+`byteswap`.
+
+`to_le` and `from_le` do the same thing for little-endian order.
 
 [source,cpp]
 ----
-constexpr auto x = std::uint32_t{0x12'34'56'78};
-constexpr auto y = stdx::to_be(x); // 0x78'56'34'12 (on a little-endian machine)
+constexpr auto addr = std::uint32_t{0x7f'00'00'01}; // localhost
+packet.dest_addr = stdx::to_be(addr);
 ----
 
-`to_le` and `to_be` are defined for unsigned integral types. Of course for
+These functions are defined for unsigned integral types. Of course for
 `std::uint8_t` they do nothing.
+
+NOTE: The implementations of `to_be` and `from_be` are identical on a machine
+with given endianness (either a no-op, or a byteswap). However they are provided
+for clarity of intent.
+
+CAUTION: `from_be` is not the same as `to_le`! (And _vice versa_.) These functions are named from
+the point of view of the serialization format. Either we are serializing to/from
+big-endian, or to/from little-endian.

include/stdx/bit.hpp

@@ -259,6 +259,26 @@ to_be(T x) noexcept -> std::enable_if_t<std::is_unsigned_v<T>, T> {
     }
 }
 
+template <typename T>
+[[nodiscard]] constexpr auto
+from_le(T x) noexcept -> std::enable_if_t<std::is_unsigned_v<T>, T> {
+    if constexpr (stdx::endian::native == stdx::endian::big) {
+        return byteswap(x);
+    } else {
+        return x;
+    }
+}
+
+template <typename T>
+[[nodiscard]] constexpr auto
+from_be(T x) noexcept -> std::enable_if_t<std::is_unsigned_v<T>, T> {
+    if constexpr (stdx::endian::native == stdx::endian::little) {
+        return byteswap(x);
+    } else {
+        return x;
+    }
+}
+
 template <typename To>
 constexpr auto bit_pack = [](auto... args) {
     static_assert(stdx::always_false_v<To, decltype(args)...>,
@@ -313,10 +333,8 @@ template <typename To, typename From> constexpr auto bit_unpack(From arg) {
 
     constexpr auto sz = sized<From>{1}.template in<To>();
     auto r = bit_cast<std::array<To, sz>>(to_be(arg));
-    if constexpr (stdx::endian::native == stdx::endian::little) {
-        for (auto &elem : r) {
-            elem = byteswap(elem);
-        }
+    for (auto &elem : r) {
+        elem = from_be(elem);
     }
     return r;
 }

test/bit.cpp

@@ -51,6 +51,42 @@ TEST_CASE("to big endian", "[bit]") {
     }
 }
 
+TEST_CASE("from little endian", "[bit]") {
+    static_assert(stdx::from_le(std::uint8_t{1u}) == 1u);
+
+    [[maybe_unused]] constexpr std::uint16_t u16{0x1234};
+    [[maybe_unused]] constexpr std::uint32_t u32{0x1234'5678};
+    [[maybe_unused]] constexpr std::uint64_t u64{0x1234'5678'9abc'def0};
+
+    if constexpr (stdx::endian::native == stdx::endian::little) {
+        CHECK(stdx::from_le(u16) == u16);
+        CHECK(stdx::from_le(u32) == u32);
+        CHECK(stdx::from_le(u64) == u64);
+    } else if constexpr (stdx::endian::native == stdx::endian::big) {
+        CHECK(stdx::from_le(u16) == stdx::byteswap(u16));
+        CHECK(stdx::from_le(u32) == stdx::byteswap(u32));
+        CHECK(stdx::from_le(u64) == stdx::byteswap(u64));
+    }
+}
+
+TEST_CASE("from big endian", "[bit]") {
+    static_assert(stdx::from_be(std::uint8_t{1u}) == 1u);
+
+    [[maybe_unused]] constexpr std::uint16_t u16{0x1234};
+    [[maybe_unused]] constexpr std::uint32_t u32{0x1234'5678};
+    [[maybe_unused]] constexpr std::uint64_t u64{0x1234'5678'9abc'def0};
+
+    if constexpr (stdx::endian::native == stdx::endian::big) {
+        CHECK(stdx::from_be(u16) == u16);
+        CHECK(stdx::from_be(u32) == u32);
+        CHECK(stdx::from_be(u64) == u64);
+    } else if constexpr (stdx::endian::native == stdx::endian::little) {
+        CHECK(stdx::from_be(u16) == stdx::byteswap(u16));
+        CHECK(stdx::from_be(u32) == stdx::byteswap(u32));
+        CHECK(stdx::from_be(u64) == stdx::byteswap(u64));
+    }
+}
+
 TEMPLATE_TEST_CASE("popcount", "[bit]", std::uint8_t, std::uint16_t,
                    std::uint32_t, std::uint64_t) {
     static_assert(stdx::popcount(TestType{}) == 0);