conversion: fix to_string overload resolution and document module

- Fix template overload conflict between integral and floating to_string
- Make bool and enum conversions unambiguous
- Document conversion module with clear API overview and examples
- Align README with Vix conversion design (expected-based, no exceptions)

Author: GaspardKirira

README.md

@@ -1,2 +1,241 @@
-# conversion
-Low-level, zero-overhead type conversion utilities for C++ (string to int, enum, bool, etc.) with explicit error handling.
+# Vix Conversion
+
+The **conversion module** provides fast, explicit, and allocation-aware helpers
+to convert **strings to typed values** and **typed values to strings** in C++.
+
+It is designed as a low-level building block for:
+- parsers
+- configuration systems
+- CLI tools
+- HTTP APIs
+- validation pipelines (used by `vix::validation`)
+
+The module favors **predictability**, **performance**, and **explicit error handling**.
+
+---
+
+## Philosophy
+
+Conversion in Vix follows strict rules:
+
+- No exceptions
+- No implicit conversions
+- No locale dependence
+- No iostreams
+- Precise error reporting (code, position, input)
+
+Every conversion returns an `expected<T, ConversionError>`.
+
+---
+
+## Core Concepts
+
+| Concept | Purpose |
+|------|-------|
+| `to_int<T>` | Parse integer from string |
+| `to_float<T>` | Parse floating point from string |
+| `to_bool` | Parse boolean values |
+| `to_enum<T>` | Parse enum using explicit mapping |
+| `parse<T>` | Generic typed parsing facade |
+| `to_string` | Convert values to string |
+| `ConversionError` | Structured conversion error |
+| `expected<T,E>` | Explicit success / failure |
+
+---
+
+## Error Model
+
+All conversions return:
+
+```cpp
+expected<T, ConversionError>
+```
+
+Where `ConversionError` contains:
+
+- `code` — semantic error code
+- `position` — error index in input
+- `input` — original input
+
+Example:
+
+```cpp
+static void print_err(const ConversionError &e)
+{
+  std::cout << "error: " << to_string(e.code)
+            << " position=" << e.position
+            << " input='" << e.input << "'\n";
+}
+```
+
+---
+
+## Parsing Integers
+
+```cpp
+#include <vix/conversion/ToInt.hpp>
+
+auto r = to_int<int>("  -42  ");
+if (!r)
+{
+  // handle r.error()
+}
+else
+{
+  int value = r.value();
+}
+```
+
+Examples:
+- `examples/parse_int.cpp`
+- `examples/parse_generic.cpp`
+
+---
+
+## Parsing Floating Point Values
+
+```cpp
+#include <vix/conversion/ToFloat.hpp>
+
+auto r = to_float<double>(" 3.14 ");
+```
+
+Supports:
+- scientific notation
+- leading / trailing spaces
+
+Examples:
+- `examples/parse_float.cpp`
+
+---
+
+## Parsing Booleans
+
+Accepted values (case-insensitive):
+- `true`, `false`
+- `1`, `0`
+- `yes`, `no`
+- `on`, `off`
+
+```cpp
+#include <vix/conversion/ToBool.hpp>
+
+auto r = to_bool("yes");
+```
+
+Examples:
+- `examples/parse_bool.cpp`
+
+---
+
+## Parsing Enums
+
+Enums are parsed using an explicit mapping table.
+
+```cpp
+enum class Role { Admin, User };
+
+static constexpr EnumEntry<Role> roles[] = {
+  {"admin", Role::Admin},
+  {"user",  Role::User},
+};
+
+auto r = to_enum<Role>("ADMIN", roles); // case-insensitive
+```
+
+Examples:
+- `examples/parse_enum.cpp`
+
+---
+
+## Generic Parsing
+
+`parse<T>` automatically selects the correct converter.
+
+```cpp
+#include <vix/conversion/Parse.hpp>
+
+auto a = parse<int>("42");
+auto b = parse<double>("3.14");
+auto c = parse<bool>("true");
+```
+
+Examples:
+- `examples/parse_generic.cpp`
+
+---
+
+## Converting Values to String
+
+```cpp
+#include <vix/conversion/ToString.hpp>
+
+auto a = to_string(42);
+auto b = to_string(3.14);
+auto c = to_string(true);
+```
+
+Enums require a mapping table:
+
+```cpp
+auto r = to_string(Role::Admin, roles);
+```
+
+Examples:
+- `examples/to_string.cpp`
+
+---
+
+## Performance Notes
+
+- Uses `std::from_chars` / `std::to_chars`
+- No heap allocations in parsing paths
+- Stack buffers only
+- Locale-independent
+
+This makes the module suitable for hot paths and low-latency systems.
+
+---
+
+## Tests
+
+Unit tests are located in `tests/`:
+
+- `to_int_smoke.cpp`
+- `to_float_smoke.cpp`
+- `to_bool_smoke.cpp`
+- `to_enum_smoke.cpp`
+
+Run:
+
+```bash
+ctest
+```
+
+---
+
+## Relationship with Validation
+
+The `conversion` module is the foundation of `vix::validation`:
+
+- `ParsedValidator<T>` relies on `parse<T>`
+- Form binding depends on conversion error reporting
+- Errors propagate without loss of information
+
+---
+
+## Design Goals Recap
+
+- Explicit over implicit
+- Errors as values
+- No runtime surprises
+- Easy to embed
+- Predictable behavior
+
+---
+
+## License
+
+MIT
+Part of the **Vix.cpp** project.
+

include/vix/conversion/ToString.hpp

@@ -16,6 +16,7 @@
 #define VIX_CONVERSION_TO_STRING_HPP
 
 #include <charconv>
+#include <cstddef>
 #include <string>
 #include <string_view>
 #include <type_traits>
@@ -32,16 +33,17 @@ namespace vix::conversion
    *
    * Uses std::to_chars for fast, allocation-free formatting into a stack buffer.
    *
-   * @tparam Int Integral type.
+   * Note: bool is excluded from this overload (use to_string(bool)).
+   *
+   * @tparam Int Integral type (excluding bool).
    * @param value Value to format.
    * @return expected<std::string, ConversionError> containing the string or an error.
    */
   template <typename Int>
+    requires(std::is_integral_v<Int> && !std::is_same_v<std::remove_cv_t<Int>, bool>)
   [[nodiscard]] VIX_EXPECTED_CONSTEXPR expected<std::string, ConversionError>
   to_string(Int value) noexcept
   {
-    static_assert(std::is_integral_v<Int>, "to_string<Int>: Int must be integral");
-
     char buffer[64];
     auto [ptr, ec] = std::to_chars(buffer, buffer + sizeof(buffer), value);
 
@@ -65,11 +67,10 @@ namespace vix::conversion
    * @return expected<std::string, ConversionError> containing the string or an error.
    */
   template <typename Float>
+    requires(std::is_floating_point_v<Float>)
   [[nodiscard]] VIX_EXPECTED_CONSTEXPR expected<std::string, ConversionError>
   to_string(Float value) noexcept
   {
-    static_assert(std::is_floating_point_v<Float>, "to_string<Float>: Float must be floating point");
-
     char buffer[128];
     auto [ptr, ec] = std::to_chars(buffer, buffer + sizeof(buffer), value);
 
@@ -100,29 +101,20 @@ namespace vix::conversion
    *
    * If the enum value is not found in the mapping table, returns UnknownEnumValue.
    *
-   * Example:
-   *   static constexpr EnumEntry<Role> roles[] = {
-   *     {"admin", Role::Admin},
-   *     {"user",  Role::User}
-   *   };
-   *
-   *   auto s = to_string(Role::Admin, roles);
-   *
    * @tparam Enum Enum type.
    * @param value Enum value.
    * @param entries Mapping table entries.
    * @param count Number of entries.
    * @return expected<std::string, ConversionError> containing the string or an error.
    */
   template <typename Enum>
+    requires(std::is_enum_v<Enum>)
   [[nodiscard]] VIX_EXPECTED_CONSTEXPR expected<std::string, ConversionError>
   to_string(
       Enum value,
       const EnumEntry<Enum> *entries,
       std::size_t count) noexcept
   {
-    static_assert(std::is_enum_v<Enum>, "to_string<Enum>: Enum must be an enum");
-
     for (std::size_t i = 0; i < count; ++i)
     {
       if (entries[i].value == value)
@@ -146,6 +138,7 @@ namespace vix::conversion
    * @return expected<std::string, ConversionError> containing the string or an error.
    */
   template <typename Enum, std::size_t N>
+    requires(std::is_enum_v<Enum>)
   [[nodiscard]] VIX_EXPECTED_CONSTEXPR expected<std::string, ConversionError>
   to_string(Enum value, const EnumEntry<Enum> (&entries)[N]) noexcept
   {
@@ -154,4 +147,4 @@ namespace vix::conversion
 
 } // namespace vix::conversion
 
-#endif
+#endif // VIX_CONVERSION_TO_STRING_HPP