- Renamed Nat literal from _uarb to _nat

- Put literals in their own sub-namespace with usage instructions

Author: saxbophone

arby/include/arby/Nat.hpp

@@ -646,47 +646,59 @@ namespace com::saxbophone::arby {
     };
 
     /**
-     * @brief raw user-defined-literal for Nat class
-     * @param literal the literal
-     * @returns Corresponding arby::Nat value
-     * @note we use a raw literal in this case because as the Nat type is
-     * unbounded, we want to support a potentially infinite number of digits,
-     * or certainly more than can be stored in unsigned long long...
+     * @brief Various custom user-defined-literals for creating arby objects
+     * @note You need to introduce this namespace into global scope with
+     * `using namespace com::saxbophone::arby::literals` in order to be able
+     * to use these literals in your code e.g. `arby::Nat f = 12345_nat`
+     * This can be done without bringing the whole of arby into global scope
+     * and these literals are provided in a sub-namespace for this exact reason
+     * @todo Maybe we should also import this namespace into arby's so that
+     * users get literals in global scope when they put arby into global scope
      */
-    constexpr Nat operator "" _uarb(const char* literal) {
-        // detect number base
-        std::uint8_t base = 10; // base-10 is the fallback base
-        if (literal[0] == '0' and literal[1] != 0) { // first digit 0, second non-null, maybe a 0x/0b prefix?
-            switch (literal[1]) {
-            case 'X': // hexadecimal
-            case 'x':
-                base = 16;
-                // advance string pointer to skip the prefix
-                literal = literal + 2;
-                break;
-            case 'B': // binary
-            case 'b':
-                base = 2;
-                literal = literal + 2;
-                break;
-            default: // not allowed --we don't support 0-prefixed octal literals or anything else
-                throw std::invalid_argument("invalid arby::Nat literal");
+    namespace literals {
+        /**
+         * @brief raw user-defined-literal for Nat class
+         * @param literal the literal
+         * @returns Corresponding arby::Nat value
+         * @note we use a raw literal in this case because as the Nat type is
+         * unbounded, we want to support a potentially infinite number of digits,
+         * or certainly more than can be stored in unsigned long long...
+         */
+        constexpr Nat operator "" _nat(const char* literal) {
+            // detect number base
+            std::uint8_t base = 10; // base-10 is the fallback base
+            if (literal[0] == '0' and literal[1] != 0) { // first digit 0, second non-null, maybe a 0x/0b prefix?
+                switch (literal[1]) {
+                case 'X': // hexadecimal
+                case 'x':
+                    base = 16;
+                    // advance string pointer to skip the prefix
+                    literal = literal + 2;
+                    break;
+                case 'B': // binary
+                case 'b':
+                    base = 2;
+                    literal = literal + 2;
+                    break;
+                default: // not allowed --we don't support 0-prefixed octal literals or anything else
+                    throw std::invalid_argument("invalid arby::Nat literal");
+                }
             }
+            Nat value; // accumulator
+            // consume digits
+            while (*literal != 0) { // until null-terminator is found
+                std::uint8_t digit = (std::uint8_t)*literal; // get character
+                // when dealing with digits, subtract 32 from any after 'Z' to convert lowercase to upper
+                if (digit > 'Z') { digit -= 32; }
+                // calculate digit's value, handling the two contiguous ranges of 0-9 and A-F
+                std::uint8_t digit_value = digit >= 'A' ? (digit - 'A') + 10 : digit - '0';
+                // add to accumulator and then shift it up
+                value *= base;
+                value += digit_value;
+                literal++; // next character
+            }
+            return value;
         }
-        Nat value; // accumulator
-        // consume digits
-        while (*literal != 0) { // until null-terminator is found
-            std::uint8_t digit = (std::uint8_t)*literal; // get character
-            // when dealing with digits, subtract 32 from any after 'Z' to convert lowercase to upper
-            if (digit > 'Z') { digit -= 32; }
-            // calculate digit's value, handling the two contiguous ranges of 0-9 and A-F
-            std::uint8_t digit_value = digit >= 'A' ? (digit - 'A') + 10 : digit - '0';
-            // add to accumulator and then shift it up
-            value *= base;
-            value += digit_value;
-            literal++; // next character
-        }
-        return value;
     }
 }
 

arby/src/Nat.cpp

@@ -16,7 +16,7 @@
 namespace com::saxbophone::arby {
     Nat::Nat(std::string digits)
         // use user-defined-literal to convert the digits in the string
-      : _digits(operator "" _uarb(digits.c_str())._digits)
+      : _digits(literals::operator "" _nat(digits.c_str())._digits)
       {}
 
     std::string Nat::_stringify_for_base(std::uint8_t base) const {

tests/stringification.cpp

@@ -7,7 +7,7 @@
 #include <arby/Nat.hpp>
 
 using namespace com::saxbophone;
-using namespace com::saxbophone::arby;
+using namespace com::saxbophone::arby::literals;
 
 TEST_CASE("Using std::ostream << arby::Nat generates decimal string of value", "[stringification]") {
     auto values = GENERATE(
@@ -45,11 +45,11 @@ TEST_CASE("Using std::ostream << std::hex << arby::Nat generates hexadecimal str
     auto values = GENERATE(
         table<arby::Nat, std::string>(
             {
-                {0_uarb, "0"},
-                {0x123456789_uarb, "123456789"},
+                {0_nat, "0"},
+                {0x123456789_nat, "123456789"},
                 {0xcafebabe3362, "cafebabe3362"},
-                {0x100f32a8d1_uarb, "100f32a8d1"},
-                {0x900100390_uarb, "900100390"},
+                {0x100f32a8d1_nat, "100f32a8d1"},
+                {0x900100390_nat, "900100390"},
                 {0xf503, "f503"},
             }
         )

tests/user_defined_literals.cpp

@@ -7,63 +7,64 @@
 
 #include <arby/Nat.hpp>
 
-using namespace com::saxbophone::arby;
+using namespace com::saxbophone;
+using namespace com::saxbophone::arby::literals;
 
-TEST_CASE("Initialising arby::Nat objects with decimal _uarb user-defined-literal", "[user-defined-literal]") {
+TEST_CASE("Initialising arby::Nat objects with decimal _nat user-defined-literal", "[user-defined-literal]") {
     auto [literal, object] = GENERATE(
-        table<Nat, Nat>(
+        table<arby::Nat, arby::Nat>(
             {
-                {0_uarb, 0},
-                {10_uarb, 10},
-                {123_uarb, 123},
-                {1234_uarb, 1234},
-                {10000_uarb, 10000},
-                {100000_uarb, 100000},
-                {123456_uarb, 123456},
-                {9999999_uarb, 9999999},
-                {56213870_uarb, 56213870},
+                {0_nat, 0},
+                {10_nat, 10},
+                {123_nat, 123},
+                {1234_nat, 1234},
+                {10000_nat, 10000},
+                {100000_nat, 100000},
+                {123456_nat, 123456},
+                {9999999_nat, 9999999},
+                {56213870_nat, 56213870},
             }
         )
     );
 
     CHECK(literal == object);
 }
 
-TEST_CASE("Initialising arby::Nat objects with hexadecimal _uarb user-defined-literal", "[user-defined-literal]") {
+TEST_CASE("Initialising arby::Nat objects with hexadecimal _nat user-defined-literal", "[user-defined-literal]") {
     auto [literal, object] = GENERATE(
-        table<Nat, Nat>(
+        table<arby::Nat, arby::Nat>(
             {
-                {0x1172443_uarb, 0x1172443},
-                {0x19721871_uarb, 0x19721871},
-                {0x0_uarb, 0x0},
-                {0xf3c1d28a_uarb, 0xf3c1d28a},
-                {0x01234567_uarb, 0x01234567},
-                {0x89abcdef_uarb, 0x89abcdef},
-                {0xffffffff_uarb, 0xffffffff},
-                {0xf00000e1_uarb, 0xf00000e1},
+                {0x1172443_nat, 0x1172443},
+                {0x19721871_nat, 0x19721871},
+                {0x0_nat, 0x0},
+                {0xf3c1d28a_nat, 0xf3c1d28a},
+                {0x01234567_nat, 0x01234567},
+                {0x89abcdef_nat, 0x89abcdef},
+                {0xffffffff_nat, 0xffffffff},
+                {0xf00000e1_nat, 0xf00000e1},
             }
         )
     );
 
     CHECK(literal == object);
 }
 
-TEST_CASE("Initialising arby::Nat objects with binary _uarb user-defined-literal", "[user-defined-literal]") {
+TEST_CASE("Initialising arby::Nat objects with binary _nat user-defined-literal", "[user-defined-literal]") {
     auto [literal, object] = GENERATE(
-        table<Nat, Nat>(
+        table<arby::Nat, arby::Nat>(
             {
-                {0b0_uarb, 0b0},
-                {0b1_uarb, 0b1},
-                {0b11010010_uarb, 0b11010010},
-                {0b1111111111111111111111111111_uarb, 0b1111111111111111111111111111},
-                {0b1010011010100011110101110101_uarb, 0b1010011010100011110101110101},
+                {0b0_nat, 0b0},
+                {0b1_nat, 0b1},
+                {0b11010010_nat, 0b11010010},
+                {0b1111111111111111111111111111_nat, 0b1111111111111111111111111111},
+                {0b1010011010100011110101110101_nat, 0b1010011010100011110101110101},
             }
         )
     );
 
     CHECK(literal == object);
 }
 
-TEST_CASE("Malformed octal _uarb literal throws std::invalid_argument") {
-    CHECK_THROWS_AS(01234_uarb, std::invalid_argument);
+TEST_CASE("Malformed octal _nat literal throws std::invalid_argument") {
+    CHECK_THROWS_AS(01234_nat, std::invalid_argument);
 }