add some docs

Author: 16bit-ykiko

README.md

@@ -1,79 +1,77 @@
-# Magic Cpp
+![cover](docs/assets/cover.png)
 
-Header-only C++20 library provides static reflection for type, aggregate class and enum, no external dependencies, no registration, no macro, no code generation, just magic.
+magic-cpp is C++20 header-only library provides static reflection for type, struct and enum, no external dependencies, no registration, no macro, no code generation. 
 
-## Documentation
+# Documentation
 * [Reference](doc/reference.md)
 * [Limitations](doc/limitations.md)
 * [Integration](#Integration)
 
-## [Examples](example/)
-### type
+# [Examples](example/)
+## type
 
-*just include `magic/type.h` to use these features*
+**just include `magic/type.h` to use the features below**
 
-* full name of type 
+- *retrieve the full name of a type*:
 ```cpp
 struct Point{};
+
 constexpr auto name = magic::full_name_of<Point>();
-static_assert(name == "Point");
+// name => "Point"
 
 constexpr auto name2 = magic::full_name_of<std::vector<int>>();
-static_assert(name2 == "std::vector<int, std::allocator<int>>");
+// name2 => "std::vector<int>"
 
 constexpr auto name3 = magic::full_name_of<std::size_t>();
-static_assert(name3 == "unsigned long long int");
+// name3 => "unsigned long long int"
 ```
-* display name of type
+- *retrieve the display name of a type*
 ```cpp
-// specialization for type to get better readable
-namespace magic
+// specialize for type to customize the display name
+template<>
+struct magic::type_info<std::size_t>
 {
-    template<>
-    struct type_info<std::size_t>
-    {
-        constexpr static auto value = "std::size_t";
-    };
+    constexpr static auto value = "std::size_t";
+};
 
-    template<>
-    struct type_info<std::string>
-    {
-        constexpr static auto value = "std::string";
-    };
-}
+template<>
+struct magic::type_info<std::string>
+{
+    constexpr static auto value = "std::string";
+};
 
 // use name_of to get the display name
 constexpr auto name = magic::name_of<std::size_t>();
-static_assert(name == "std::size_t");
+// name => "std::size_t"
 
 constexpr auto name2 = magic::name_of<std::string>();
-static_assert(name2 == "std::string");
+// name => "std::string"
 ```
 
-* visualize type
+- *visualize type*
 ```cpp
 // for some complex type, it is hard to understand for human
-// we can visualize it to a more readable form
+// we can visualize it as a tree to make it more readable
 
 using T = int (*(*(*)(int*))[4])(int*); // hard to understand
 std::cout << magic::full_tree_of<T>() << std::endl;
 ```
-Output:
+*Output:*
 
-![ptr](docs/ptr.png)
+![ptr](docs/assets/sample_ptr.png)
 
+----------------
 ```cpp
 using T = std::map<int, std::string>;
 std::cout << magic::full_tree_of<T>() << std::endl;
 ```
-Output:
-
-![map](docs/map.png)
+*Output*:
+![map](docs/assets/sample_map.png)
 
 you can also use `tree_of` to get a more compact form, more details see [type](docs/type.md).
 
-### [aggregate class](https://en.cppreference.com/w/cpp/language/aggregate_initialization#Definitions)
-*just include `magic/struct.h` to use these features*
+## [aggregate class](https://en.cppreference.com/w/cpp/language/aggregate_initialization#Definitions)
+**just include `magic/struct.h` to use these features**
 
 ```cpp
 struct Complex
@@ -83,56 +81,119 @@ struct Complex
 }; // Complex is an aggregate class
 ```
 
--  Retrieve field count of an aggregate class
+-  *retrieve field count of an aggregate class*
 ```cpp
-static_assert(magic::field_count_of<Complex>() == 2);
+constexpr auto count = magic::field_count_of<Complex>();
+// count => 2
 ```
-- Retrieve the field types for an aggregate class
+- *retrieve the field types for an aggregate class*
 ```cpp
-using T = magic::field_types_of<Complex>;
-static_assert(std::same_as<T, std::tuple<std::string, std::vector<int>>>);
+using Types = magic::field_types_of<Complex>;
+// Types => std::tuple<std::string, std::vector<int>>
 ```
-- Retrieve the field type at a given index for an aggregate class
+- *retrieve the field type at a given index for an aggregate class*
 ```cpp
-static_assert(std::same_as<magic::field_type_of<Complex, 0>, std::string>);
-static_assert(std::same_as<magic::field_type_of<Complex, 1>, std::vector<int>>);
+using First = magic::field_type_of<Complex, 0>;
+// First => std::string
+
+using Second = magic::field_type_of<Complex, 1>;
+// Second => std::vector<int>
 ```
-- Retrieve the field names for an aggregate class
+- *retrieve the field names for an aggregate class*
 ```cpp
 constexpr auto names = magic::field_names_of<Complex>();
-static_assert(names == std::array<std::string_view, 2>{"name", "vec"});
+// names => std::array{"name", "vec"}
 ```
 
-- Retrieve the field name at a given index for an aggregate class
+- *retrieve the field name at a given index for an aggregate class*
 ```cpp
-static_assert(magic::field_name_of<Complex>(0) == "name");
-static_assert(magic::field_name_of<Complex>(1) == "vec");
+constexpr auto name1 = magic::field_name_of<Complex>(0);
+// name1 => "name"
+
+constexpr auto name2 = magic::field_name_of<Complex>(1);
+// name2 => "vec"
 ```
 
-- Retrieve the field reference at a given index for an aggregate class
+- *retrieve the field reference at a given index for an aggregate class*
 ```cpp
 Complex c{"hello", {1, 2, 3}};
-std::cout << magic::field_of<0>(c) << std::endl;
-// output: hello
 
-std::cout << magic::field_of<1>(c)[1] << std::endl;
-// output: 2
+auto& value = magic::field_of<0>(c);
+// value => "hello"
+
+auto& value2 = magic::field_of<1>(c);
+// value2 => std::vector{1, 2, 3}
 ```
 
-- Traverse all fields of an aggregate class
+- *traverse all fields of an aggregate class*
 ```cpp
-Complex c{"hello", {1, 2, 3}};
 auto f = [](auto field)
 {
+    constexpr auto index = field.index();
+    constexpr auto name = field.name();
+    using type = decltype(field)::type;
+    if constexpr (name == "name")
+    {
+        std::cout << "index: " << index
+                  << ", name: " << name
+                  << ", value: " << field.value() << std::endl;
+    }
+    else if constexpr (name == "vec")
+    {
+        std::cout << "index: " << index
+                  << ", name: " << name
+                  << ", value: " << field.value()[0] << std::endl;
+    }
+};
 
+magic::foreach (complex, f);
+// out =>
+// index: 0, name: name, value: hello
+// index: 1, name: vec, value: 1
+```
+## enum
+**just include `magic/enum.h` to use these features**
+```cpp
+enum Color
+{
+    RED,
+    GREEN,
+    BLUE
 };
-magic::foreach(c, f);
 ```
-### enum
-- Retrieve the enum count
+- *retrieve the enum count*
+```cpp
+constexpr auto count = magic::enum_count_of<Color>();
+// count => 3
+```
+- *retrieve the enum names*
+```cpp
+constexpr auto& names = magic::enum_names_of<Color>();
+// names => std::array{"RED", "GREEN", "BLUE"}
+```
+- *retrieve the enum name*
+```cpp
+constexpr auto name = magic::name_of<Color::RED>();
+// name => "RED"
 
-- Retrieve the enum names
+Color color = Color::GREEN;
+auto name2 = magic::name_of(color);
+// name => "GREEN"
+```
+- *retrieve the bit field enum value*
+```cpp
+
+
+```
+
+- *traverse all enum values*
+```cpp
+
+```
 
-- Retrieve the enum nam
+# Limitations
 
-- Retrieve the bit field enum value
+# Support
+- `gcc` > 12
+- `clang` > 15
+- `msvc` > 19.29

docs/assets/cover.png

@@ -245,6 +245,14 @@ namespace magic
     {
         return details::enum_names_storage<T>::names;
     }
+
+    template <typename T>
+    requires std::is_enum_v<T>
+    constexpr auto& name_of(T value)
+    {
+        constexpr auto start = enum_start<T>();
+        return details::enum_names_storage<T>::names[static_cast<std::size_t>(value + start)];
+    }
 } // namespace magic
 
 #endif // MAGIC_CPP_ENUM_H

docs/assets/sample_map.png

@@ -27,9 +27,7 @@ namespace magic::details
     template <typename T, std::size_t N>
     consteval std::size_t try_initialize_with_n()
     {
-        return []<std::size_t... Is>(std::index_sequence<Is...>) {
-            return requires { T{Any(Is)...}; } && !requires { T{Any(Is)..., Any(0)}; };
-        }(std::make_index_sequence<N>{});
+        return []<std::size_t... Is>(std::index_sequence<Is...>) { return requires { T{Any(Is)...}; }; }(std::make_index_sequence<N>{});
     }
 
     template <typename T, std::size_t N1, std::size_t N2, std::size_t N3>
@@ -45,11 +43,7 @@ namespace magic::details
     template <typename T, std::size_t N = 0>
     consteval std::size_t total_count_of_fields()
     {
-        if constexpr (N > sizeof(T) * 8 + 1)
-        {
-            static_assert(N <= sizeof(T) * 8 + 1, "Unexpected Error in total_count_of_fields");
-        }
-        else if constexpr (try_initialize_with_n<T, N>())
+        if constexpr (try_initialize_with_n<T, N>() && !try_initialize_with_n<T, N + 1>())
         {
             return N;
         }
@@ -186,7 +180,7 @@ namespace magic::details
     constexpr auto field_types_of_impl(T object)
     {
         constexpr auto N = field_count_of<T>();
-// clang-format off
+        // clang-format off
         #include "generate/struct_bind_of_field_types.code"
         // clang-format on
     }
@@ -196,7 +190,7 @@ namespace magic::details
     {
         using T = std::remove_cvref_t<decltype(object)>;
         constexpr auto N = field_count_of<T>();
-// clang-format off
+        // clang-format off
         #include "generate/struct_bind_of_field_access.code"
         // clang-format on
     }