refactor: 💥 text_encoding renamed to character_set

docs/users_guide/framework_basics/text_output.md

@@ -454,15 +454,15 @@ as text and, thus, are aligned to the left by default.
 
 ```ebnf
 dimension-format-spec = [fill-and-align], [width], [dimension-spec];
-dimension-spec        = [text-encoding];
-text-encoding         = 'U' | 'P';
+dimension-spec        = [character-set];
+character-set         = 'U' | 'P';
 ```
 
 In the above grammar:
 
 - `fill-and-align` and `width` tokens are defined in the [format.string.std](https://wg21.link/format.string.std)
   chapter of the C++ standard specification,
-- `text-encoding` token specifies the symbol text encoding:
+- `character-set` token specifies the symbol text encoding:
     - `U` (default) uses the **UTF-8** symbols defined by [@ISO80000] (e.g., `LT⁻²`),
     - `P` forces non-standard **portable** output (e.g., `LT^-2`).
 
@@ -471,7 +471,7 @@ Dimension symbols of some quantities are specified to use Unicode signs by the
 dimension). The library follows this by default. From the engineering point of view, sometimes
 Unicode text might not be the best solution, as terminals of many (especially embedded) devices
 can output only letters from the basic literal character set. In such a case, the dimension
-symbol can be forced to be printed using such characters thanks to `text-encoding` token:
+symbol can be forced to be printed using such characters thanks to `character-set` token:
 
 ```cpp
 std::println("{}", isq::dim_thermodynamic_temperature);   // Θ
@@ -484,12 +484,12 @@ std::println("{:P}", isq::power.dimension);               // L^2MT^-3
 
 ```ebnf
 unit-format-spec      = [fill-and-align], [width], [unit-spec];
-unit-spec             = [text-encoding], [unit-symbol-solidus], [unit-symbol-separator], [L]
-                      | [text-encoding], [unit-symbol-separator], [unit-symbol-solidus], [L]
-                      | [unit-symbol-solidus], [text-encoding], [unit-symbol-separator], [L]
-                      | [unit-symbol-solidus], [unit-symbol-separator], [text-encoding], [L]
-                      | [unit-symbol-separator], [text-encoding], [unit-symbol-solidus], [L]
-                      | [unit-symbol-separator], [unit-symbol-solidus], [text-encoding], [L];
+unit-spec             = [character-set], [unit-symbol-solidus], [unit-symbol-separator], [L]
+                      | [character-set], [unit-symbol-separator], [unit-symbol-solidus], [L]
+                      | [unit-symbol-solidus], [character-set], [unit-symbol-separator], [L]
+                      | [unit-symbol-solidus], [unit-symbol-separator], [character-set], [L]
+                      | [unit-symbol-separator], [character-set], [unit-symbol-solidus], [L]
+                      | [unit-symbol-separator], [unit-symbol-solidus], [character-set], [L];
 unit-symbol-solidus   = '1' | 'a' | 'n';
 unit-symbol-separator = 's' | 'd';
 ```
@@ -521,7 +521,7 @@ Unit symbols of some quantities are specified to use Unicode signs by the [SI](.
 engineering point of view, Unicode text might not be the best solution sometimes, as terminals
 of many (especially embedded) devices can output only letters from the basic literal character set.
 In such a case, the unit symbol can be forced to be printed using such characters thanks to
-`text-encoding` token:
+`character-set` token:
 
 ```cpp
 std::println("{}", si::ohm);      // Ω

src/core/include/mp-units/bits/text_tools.h

@@ -96,9 +96,9 @@ template<std::intmax_t Value>
 }
 
 template<typename CharT, std::size_t N, std::size_t M, std::output_iterator<CharT> Out>
-constexpr Out copy(const symbol_text<N, M>& txt, text_encoding encoding, Out out)
+constexpr Out copy(const symbol_text<N, M>& txt, character_set char_set, Out out)
 {
-  if (encoding == text_encoding::utf8) {
+  if (char_set == character_set::utf8) {
     if constexpr (is_same_v<CharT, char8_t>)
       return ::mp_units::detail::copy(txt.utf8().begin(), txt.utf8().end(), out);
     else if constexpr (is_same_v<CharT, char>) {
@@ -115,37 +115,37 @@ constexpr Out copy(const symbol_text<N, M>& txt, text_encoding encoding, Out out
 }
 
 template<typename CharT, std::size_t N, std::size_t M, std::output_iterator<CharT> Out>
-constexpr Out copy_symbol(const symbol_text<N, M>& txt, text_encoding encoding, bool negative_power, Out out)
+constexpr Out copy_symbol(const symbol_text<N, M>& txt, character_set char_set, bool negative_power, Out out)
 {
-  out = copy<CharT>(txt, encoding, out);
+  out = copy<CharT>(txt, char_set, out);
   if (negative_power) {
     constexpr auto exp = superscript<-1>();
-    out = copy<CharT>(exp, encoding, out);
+    out = copy<CharT>(exp, char_set, out);
   }
   return out;
 }
 
 template<typename CharT, int Num, int... Den, std::output_iterator<CharT> Out>
-constexpr Out copy_symbol_exponent(text_encoding encoding, bool negative_power, Out out)
+constexpr Out copy_symbol_exponent(character_set char_set, bool negative_power, Out out)
 {
   constexpr ratio r{Num, Den...};
   if constexpr (r.den != 1) {
     // add root part
     if (negative_power) {
       constexpr auto txt =
         symbol_text("^-(") + regular<r.num>() + symbol_text("/") + regular<r.den>() + symbol_text(")");
-      return copy<CharT>(txt, encoding, out);
+      return copy<CharT>(txt, char_set, out);
     }
     constexpr auto txt = symbol_text("^(") + regular<r.num>() + symbol_text("/") + regular<r.den>() + symbol_text(")");
-    return copy<CharT>(txt, encoding, out);
+    return copy<CharT>(txt, char_set, out);
   } else if constexpr (r.num != 1) {
     // add exponent part
     if (negative_power) {
       constexpr auto txt = superscript<-r.num>();
-      return copy<CharT>(txt, encoding, out);
+      return copy<CharT>(txt, char_set, out);
     }
     constexpr auto txt = superscript<r.num>();
-    return copy<CharT>(txt, encoding, out);
+    return copy<CharT>(txt, char_set, out);
   } else {
     return out;
   }

src/core/include/mp-units/format.h

@@ -111,8 +111,8 @@ MP_UNITS_EXPORT_END
 // Grammar
 //
 // dimension-format-spec = [fill-and-align], [width], [dimension-spec];
-// dimension-spec        = [text-encoding];
-// text-encoding         = 'U' | 'P';
+// dimension-spec        = [character-set];
+// character-set         = 'U' | 'P';
 //
 template<mp_units::Dimension D, typename Char>
 class MP_UNITS_STD_FMT::formatter<D, Char> {
@@ -135,7 +135,7 @@ class MP_UNITS_STD_FMT::formatter<D, Char> {
 
     if (it = mp_units::detail::at_most_one_of(begin, end, "UAP"); it != end)
       // TODO 'A' stands for an old and deprecated ASCII encoding
-      specs_.encoding = (*it == 'U') ? mp_units::text_encoding::utf8 : mp_units::text_encoding::portable;
+      specs_.char_set = (*it == 'U') ? mp_units::character_set::utf8 : mp_units::character_set::portable;
 
     return end;
   }
@@ -177,12 +177,12 @@ class MP_UNITS_STD_FMT::formatter<D, Char> {
 // Grammar
 //
 // unit-format-spec      = [fill-and-align], [width], [unit-spec];
-// unit-spec             = [text-encoding], [unit-symbol-solidus], [unit-symbol-separator], [L]
-//                       | [text-encoding], [unit-symbol-separator], [unit-symbol-solidus], [L]
-//                       | [unit-symbol-solidus], [text-encoding], [unit-symbol-separator], [L]
-//                       | [unit-symbol-solidus], [unit-symbol-separator], [text-encoding], [L]
-//                       | [unit-symbol-separator], [text-encoding], [unit-symbol-solidus], [L]
-//                       | [unit-symbol-separator], [unit-symbol-solidus], [text-encoding], [L];
+// unit-spec             = [character-set], [unit-symbol-solidus], [unit-symbol-separator], [L]
+//                       | [character-set], [unit-symbol-separator], [unit-symbol-solidus], [L]
+//                       | [unit-symbol-solidus], [character-set], [unit-symbol-separator], [L]
+//                       | [unit-symbol-solidus], [unit-symbol-separator], [character-set], [L]
+//                       | [unit-symbol-separator], [character-set], [unit-symbol-solidus], [L]
+//                       | [unit-symbol-separator], [unit-symbol-solidus], [character-set], [L];
 // unit-symbol-solidus   = '1' | 'a' | 'n';
 // unit-symbol-separator = 's' | 'd';
 //
@@ -208,7 +208,7 @@ class MP_UNITS_STD_FMT::formatter<U, Char> {
 
     if (it = mp_units::detail::at_most_one_of(begin, end, "UAP"); it != end)
       // TODO 'A' stands for an old and deprecated ASCII encoding
-      specs_.encoding = (*it == 'U') ? mp_units::text_encoding::utf8 : mp_units::text_encoding::portable;
+      specs_.char_set = (*it == 'U') ? mp_units::character_set::utf8 : mp_units::character_set::portable;
     if (it = mp_units::detail::at_most_one_of(begin, end, "1an"); it != end) {
       switch (*it) {
         case '1':
@@ -223,7 +223,7 @@ class MP_UNITS_STD_FMT::formatter<U, Char> {
       }
     }
     if (it = mp_units::detail::at_most_one_of(begin, end, "sd"); it != end) {
-      if (*it == 'd' && specs_.encoding == mp_units::text_encoding::portable)
+      if (*it == 'd' && specs_.char_set == mp_units::character_set::portable)
         throw MP_UNITS_STD_FMT::format_error("half_high_dot unit separator allowed only for UTF-8 encoding");
       specs_.separator =
         (*it == 's') ? mp_units::unit_symbol_separator::space : mp_units::unit_symbol_separator::half_high_dot;

src/core/include/mp-units/framework/dimension.h

@@ -220,9 +220,13 @@ template<std::intmax_t Num, std::intmax_t Den = 1, Dimension D>
 [[nodiscard]] consteval Dimension auto cbrt(Dimension auto d) { return pow<1, 3>(d); }
 
 
+MP_UNITS_DIAGNOSTIC_PUSH
+MP_UNITS_DIAGNOSTIC_IGNORE_DEPRECATED
 struct dimension_symbol_formatting {
-  text_encoding encoding = text_encoding::default_encoding;
+  [[deprecated("Use `char_set` instead")]] character_set encoding = character_set::default_character_set;
+  character_set char_set = encoding;
 };
+MP_UNITS_DIAGNOSTIC_POP
 
 MP_UNITS_EXPORT_END
 
@@ -232,15 +236,15 @@ template<typename CharT, std::output_iterator<CharT> Out, Dimension D>
   requires requires { D::_symbol_; }
 constexpr Out dimension_symbol_impl(Out out, D, const dimension_symbol_formatting& fmt, bool negative_power)
 {
-  return copy_symbol<CharT>(D::_symbol_, fmt.encoding, negative_power, out);
+  return copy_symbol<CharT>(D::_symbol_, fmt.char_set, negative_power, out);
 }
 
 template<typename CharT, std::output_iterator<CharT> Out, typename F, int Num, int... Den>
 constexpr auto dimension_symbol_impl(Out out, const power<F, Num, Den...>&, const dimension_symbol_formatting& fmt,
                                      bool negative_power)
 {
   out = dimension_symbol_impl<CharT>(out, F{}, fmt, false);  // negative power component will be added below if needed
-  return copy_symbol_exponent<CharT, Num, Den...>(fmt.encoding, negative_power, out);
+  return copy_symbol_exponent<CharT, Num, Den...>(fmt.char_set, negative_power, out);
 }
 
 template<typename CharT, std::output_iterator<CharT> Out, typename... Ms>

src/core/include/mp-units/framework/magnitude.h

@@ -316,9 +316,9 @@ template<typename CharT, std::output_iterator<CharT> Out>
 constexpr Out print_separator(Out out, const unit_symbol_formatting& fmt)
 {
   if (fmt.separator == unit_symbol_separator::half_high_dot) {
-    if (fmt.encoding != text_encoding::utf8)
+    if (fmt.char_set != character_set::utf8)
       MP_UNITS_THROW(
-        std::invalid_argument("'unit_symbol_separator::half_high_dot' can be only used with 'text_encoding::utf8'"));
+        std::invalid_argument("'unit_symbol_separator::half_high_dot' can be only used with 'character_set::utf8'"));
     const std::string_view dot = "⋅" /* U+22C5 DOT OPERATOR */;
     out = detail::copy(dot.begin(), dot.end(), out);
   } else {
@@ -339,9 +339,9 @@ template<typename CharT, std::output_iterator<CharT> Out, auto M, auto... Rest>
                                                 bool negative_power)
 {
   auto to_symbol = [&]<typename T>(T v) {
-    out = copy_symbol<CharT>(get_base(v)._symbol_, fmt.encoding, negative_power, out);
+    out = copy_symbol<CharT>(get_base(v)._symbol_, fmt.char_set, negative_power, out);
     constexpr ratio r = get_exponent(T{});
-    return copy_symbol_exponent<CharT, abs(r.num), r.den>(fmt.encoding, negative_power, out);
+    return copy_symbol_exponent<CharT, abs(r.num), r.den>(fmt.char_set, negative_power, out);
   };
   return (to_symbol(M), ..., (print_separator<CharT>(out, fmt), to_symbol(Rest)));
 }
@@ -354,7 +354,7 @@ constexpr Out magnitude_symbol_impl(Out out, const unit_symbol_formatting& fmt)
   constexpr auto num_value = _get_value<std::intmax_t>(Num);
   if constexpr (num_value != 1) {
     constexpr auto num = detail::regular<num_value>();
-    out = copy_symbol<CharT>(num, fmt.encoding, false, out);
+    out = copy_symbol<CharT>(num, fmt.char_set, false, out);
     numerator = true;
   }
 
@@ -383,7 +383,7 @@ constexpr Out magnitude_symbol_impl(Out out, const unit_symbol_formatting& fmt)
   if constexpr (den_value != 1) {
     constexpr auto den = detail::regular<den_value>();
     start_denominator();
-    out = copy_symbol<CharT>(den, fmt.encoding, negative_power, out);
+    out = copy_symbol<CharT>(den, fmt.char_set, negative_power, out);
     denominator = true;
   }
 
@@ -400,10 +400,10 @@ constexpr Out magnitude_symbol_impl(Out out, const unit_symbol_formatting& fmt)
   if constexpr (Exp10 != 0) {
     if (numerator || denominator) {
       constexpr auto mag_multiplier = symbol_text(u8" × " /* U+00D7 MULTIPLICATION SIGN */, " x ");
-      out = copy_symbol<CharT>(mag_multiplier, fmt.encoding, negative_power, out);
+      out = copy_symbol<CharT>(mag_multiplier, fmt.char_set, negative_power, out);
     }
     constexpr auto exp = symbol_text("10") + detail::superscript<Exp10>();
-    out = copy_symbol<CharT>(exp, fmt.encoding, negative_power, out);
+    out = copy_symbol<CharT>(exp, fmt.char_set, negative_power, out);
   }
 
   return out;

src/core/include/mp-units/framework/symbol_text.h

@@ -55,14 +55,17 @@ static_assert(std::text_encoding::literal().mib() == std::text_encoding::id::UTF
 namespace mp_units {
 
 // NOLINTNEXTLINE(readability-enum-initial-value)
-MP_UNITS_EXPORT enum class text_encoding : std::int8_t {
+MP_UNITS_EXPORT enum class character_set : std::int8_t {
   utf8,  // µs; m³;  L²MT⁻³
   unicode [[deprecated("Use `utf8` instead")]] = utf8,
   portable,  // us; m^3; L^2MT^-3
   ascii [[deprecated("Use `portable` instead")]] = portable,
-  default_encoding = utf8
+  default_character_set = utf8,
+  default_encoding [[deprecated("Use `default_character_set` instead")]] = default_character_set
 };
 
+using text_encoding [[deprecated("Use `character_set` instead")]] = character_set;
+
 namespace detail {
 
 constexpr bool is_basic_literal_character_set_char(char ch)

src/core/include/mp-units/framework/unit.h

@@ -785,7 +785,7 @@ template<typename CharT, std::output_iterator<CharT> Out, Unit U>
   requires requires { U::_symbol_; }
 constexpr Out unit_symbol_impl(Out out, U, const unit_symbol_formatting& fmt, bool negative_power)
 {
-  return copy_symbol<CharT>(U::_symbol_, fmt.encoding, negative_power, out);
+  return copy_symbol<CharT>(U::_symbol_, fmt.char_set, negative_power, out);
 }
 
 template<typename CharT, std::output_iterator<CharT> Out, auto M, typename U>
@@ -842,7 +842,7 @@ constexpr auto unit_symbol_impl(Out out, const power<F, Num, Den...>&, const uni
                                 bool negative_power)
 {
   out = unit_symbol_impl<CharT>(out, F{}, fmt, false);  // negative power component will be added below if needed
-  return copy_symbol_exponent<CharT, Num, Den...>(fmt.encoding, negative_power, out);
+  return copy_symbol_exponent<CharT, Num, Den...>(fmt.char_set, negative_power, out);
 }
 
 template<typename CharT, std::output_iterator<CharT> Out, typename... Us>

src/core/include/mp-units/framework/unit_symbol_formatting.h

@@ -23,6 +23,7 @@
 #pragma once
 
 // IWYU pragma: private, include <mp-units/framework.h>
+#include <mp-units/bits/hacks.h>
 #include <mp-units/bits/module_macros.h>
 #include <mp-units/framework/symbol_text.h>
 
@@ -52,10 +53,15 @@ enum class unit_symbol_separator : std::int8_t {
   default_separator = space
 };
 
+MP_UNITS_DIAGNOSTIC_PUSH
+MP_UNITS_DIAGNOSTIC_IGNORE_DEPRECATED
 struct unit_symbol_formatting {
-  text_encoding encoding = text_encoding::default_encoding;
+  [[deprecated("Use `char_set` instead")]] character_set encoding = character_set::default_character_set;
+  character_set char_set = encoding;
+
   unit_symbol_solidus solidus = unit_symbol_solidus::default_denominator;
   unit_symbol_separator separator = unit_symbol_separator::default_separator;
 };
+MP_UNITS_DIAGNOSTIC_POP
 
 }  // namespace mp_units

test/static/dimension_symbol_test.cpp

@@ -32,21 +32,21 @@ namespace {
 
 using namespace mp_units;
 
-using enum text_encoding;
+using enum character_set;
 
 static_assert(dimension_symbol(dimension_one) == "1");
 
 // base dimensions
 static_assert(dimension_symbol(isq::dim_length) == "L");
 static_assert(dimension_symbol(isq::dim_thermodynamic_temperature) == "Θ");
-static_assert(dimension_symbol<dimension_symbol_formatting{.encoding = portable}>(isq::dim_thermodynamic_temperature) ==
+static_assert(dimension_symbol<dimension_symbol_formatting{.char_set = portable}>(isq::dim_thermodynamic_temperature) ==
               "O");
 
 // derived dimensions
 static_assert(dimension_symbol(isq::speed.dimension) == "LT⁻¹");
-static_assert(dimension_symbol<dimension_symbol_formatting{.encoding = portable}>(isq::speed.dimension) == "LT^-1");
+static_assert(dimension_symbol<dimension_symbol_formatting{.char_set = portable}>(isq::speed.dimension) == "LT^-1");
 static_assert(dimension_symbol(isq::power.dimension) == "L²MT⁻³");
-static_assert(dimension_symbol<dimension_symbol_formatting{.encoding = portable}>(isq::power.dimension) == "L^2MT^-3");
+static_assert(dimension_symbol<dimension_symbol_formatting{.char_set = portable}>(isq::power.dimension) == "L^2MT^-3");
 
 static_assert(dimension_symbol(pow<123>(isq::dim_length)) == "L¹²³");
 static_assert(dimension_symbol(pow<1, 2>(isq::dim_length)) == "L^(1/2)");