From f9078cc9f96dde1739a0b0408e8ca4ab78f63bb7 Mon Sep 17 00:00:00 2001 From: Neargye Date: Sat, 25 Jan 2020 23:45:33 +0500 Subject: [PATCH] update doc --- README.md | 8 +++++ doc/limitations.md | 71 +++++++++++++++++++++++++------------ doc/reference.md | 88 ++++++++++++++++++++++++++-------------------- 3 files changed, 105 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index f3b7228..dfb8acb 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ Header-only C++17 library provides nameof macros and functions to simply obtain ## [Examples](example/example.cpp) * Nameof + ```cpp // Name of variable. NAMEOF(somevar) -> "somevar" @@ -62,6 +63,7 @@ Header-only C++17 library provides nameof macros and functions to simply obtain ``` * Nameof enum + ```cpp auto color = Color::RED; // Name of enum variable. @@ -75,6 +77,7 @@ Header-only C++17 library provides nameof macros and functions to simply obtain ``` * Nameof type + ```cpp using T = const int&; T var = 42; @@ -92,6 +95,7 @@ Header-only C++17 library provides nameof macros and functions to simply obtain ``` * Compile-time + ```cpp constexpr auto somevar_name = NAMEOF(somevar); // somevar_name -> "somevar" @@ -103,6 +107,10 @@ Header-only C++17 library provides nameof macros and functions to simply obtain // type_name -> "int" ``` +## Remarks + +* Before use, read the [limitations](doc/limitations.md) of functionality. + ## Integration You should add required file [nameof.hpp](include/nameof.hpp). diff --git a/doc/limitations.md b/doc/limitations.md index e6f970a..7614822 100644 --- a/doc/limitations.md +++ b/doc/limitations.md @@ -1,8 +1,10 @@ -# Nameof +# Limitations + +## Nameof * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. -# Nameof Type +## Nameof Type * To check is nameof type supported compiler use macro `NAMEOF_TYPE_SUPPORTED` or constexpr constant `nameof::is_nameof_type_supported`. @@ -12,7 +14,7 @@ * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. -# Nameof Enum +## Nameof Enum * To check is nameof enum supported compiler use macro `NAMEOF_ENUM_SUPPORTED` or constexpr constant `nameof::is_nameof_enum_supported`. @@ -20,31 +22,52 @@ * Enum can't reflect if the enum is a forward declaration. -* Enum value must be in range `[NAMEOF_ENUM_RANGE_MIN, NAMEOF_ENUM_RANGE_MAX]`. By default `NAMEOF_ENUM_RANGE_MIN = -128`, `NAMEOF_ENUM_RANGE_MAX = 128`. +* Enum value must be in range `[NAMEOF_ENUM_RANGE_MIN, NAMEOF_ENUM_RANGE_MAX]`. -* If need another range for all enum types by default, redefine the macro `NAMEOF_ENUM_RANGE_MIN` and `NAMEOF_ENUM_RANGE_MAX`. - ```cpp - #define NAMEOF_ENUM_RANGE_MIN 0 - #define NAMEOF_ENUM_RANGE_MAX 256 - #include + * By default `NAMEOF_ENUM_RANGE_MIN = -128`, `NAMEOF_ENUM_RANGE_MAX = 128`. + + * `NAMEOF_ENUM_RANGE_MIN` must be less or equals than `0` and must be greater than `INT16_MIN`. + + * `NAMEOF_ENUM_RANGE_MAX` must be greater than `0` and must be less than `INT16_MAX`. + + * If need another range for all enum types by default, redefine the macro `NAMEOF_ENUM_RANGE_MIN` and `NAMEOF_ENUM_RANGE_MAX`. + + ```cpp + #define NAMEOF_ENUM_RANGE_MIN 0 + #define NAMEOF_ENUM_RANGE_MAX 256 + #include + ``` + + * If need another range for specific enum type, add specialization `enum_range` for necessary enum type. + + ```cpp + #include + + enum number { one = 100, two = 200, three = 300 }; + + namespace nameof { + template <> + struct enum_range { + static constexpr int min = 100; + static constexpr int max = 300; + }; + } + ``` + +* If you hit a message like this: + + ```text + [...] + note: constexpr evaluation hit maximum step limit; possible infinite loop? ``` -* If need another range for specific enum type, add specialization `enum_range` for necessary enum type. - ```cpp - #include - - enum number { one = 100, two = 200, three = 300 }; - - namespace nameof { - template <> - struct enum_range { - static constexpr int min = 100; - static constexpr int max = 300; - }; - } - ``` + Change the limit for the number of constexpr evaluated: + * MSVC `/constexpr:depthN`, `/constexpr:stepsN` + * Clang `-fconstexpr-depth=N`, `-fconstexpr-steps=N` + * GCC `-fconstexpr-depth=N`, `-fconstexpr-loop-limit=N`, `-fconstexpr-ops-limit=N` * Nameof enum obtains the first defined value enums, and won't work if value are aliased. + ```cpp enum ShapeKind { ConvexBegin = 0, @@ -58,7 +81,9 @@ // nameof::nameof_enum(ShapeKind::Box) -> "ConvexBegin" // NAMEOF_ENUM(ShapeKind::Box) -> "ConvexBegin" ``` + Work around the issue: + ```cpp enum ShapeKind { // Convex shapes, see ConvexBegin and ConvexEnd below. diff --git a/doc/reference.md b/doc/reference.md index 7f59a5a..f0fbdc6 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -1,30 +1,29 @@ # Reference -* [`NAMEOF` macro that obtains simple (unqualified) string name of variable, function, macro.](#NAMEOF) -* [`NAMEOF_FULL` macro that obtains simple (unqualified) full (with template suffix) string name of variable, function, macro.](#NAMEOF_FULL) -* [`NAMEOF_RAW` macro that obtains raw string name of variable, function, macro.](#NAMEOF_RAW) -* [`nameof_enum(E value)` function that obtains simple (unqualified) string enum name of enum variable.](#nameof_enum(value)) -* [`nameof_enum()` function that obtains simple (unqualified) string enum name of static storage enum variable.](#nameof_enum()) -* [`NAMEOF_ENUM` macro that obtains simple (unqualified) string enum name of enum variable.](#NAMEOF_ENUM) +* [`NAMEOF` macro that obtains simple (unqualified) string name of variable, function, macro.](#nameof) +* [`NAMEOF_FULL` macro that obtains simple (unqualified) full (with template suffix) string name of variable, function, macro.](#nameof_full) +* [`NAMEOF_RAW` macro that obtains raw string name of variable, function, macro.](#nameof_raw) +* [`nameof_enum` function that obtains simple (unqualified) string enum name of enum variable.](#nameof_enum) +* [`NAMEOF_ENUM` macro that obtains simple (unqualified) string enum name of enum variable.](#nameof_enum-1) * [`NAMEOF_CONST_ENUM` macro that obtains simple (unqualified) string enum name of static storage enum variable.](#NAMEOF_CONST_ENUM) -* [`nameof_type()` function that obtains string name of type, reference and cv-qualifiers are ignored.](#nameof_type()) -* [`nameof_full_type()` function that obtains string name of full type, with reference and cv-qualifiers.](#nameof_full_type()) -* [`NAMEOF_TYPE` macro that obtains string name of type, reference and cv-qualifiers are ignored.](#NAMEOF_TYPE) -* [`NAMEOF_FULL_TYPE` macro that obtains string name of full type, with reference and cv-qualifiers.](#NAMEOF_FULL_TYPE) -* [`NAMEOF_TYPE_EXPR` macro that obtains string name type of expression, reference and cv-qualifiers are ignored.](#NAMEOF_TYPE_EXPR) -* [`NAMEOF_FULL_TYPE_EXPR` macro that obtains string name full type of expression, with reference and cv-qualifiers.](#NAMEOF_FULL_TYPE_EXPR) +* [`nameof_type` function that obtains string name of type, reference and cv-qualifiers are ignored.](#nameof_type) +* [`nameof_full_type` function that obtains string name of full type, with reference and cv-qualifiers.](#nameof_full_type) +* [`NAMEOF_TYPE` macro that obtains string name of type, reference and cv-qualifiers are ignored.](#nameof_type-1) +* [`NAMEOF_FULL_TYPE` macro that obtains string name of full type, with reference and cv-qualifiers.](#nameof_full_type-1) +* [`NAMEOF_TYPE_EXPR` macro that obtains string name type of expression, reference and cv-qualifiers are ignored.](#nameof_type_expr) +* [`NAMEOF_FULL_TYPE_EXPR` macro that obtains string name full type of expression, with reference and cv-qualifiers.](#nameof_full_type_expr) -# Synopsis +## Synopsis * Before use, read the [limitations](limitations.md) of functionality. * All functions `constexpr` and `noexcept`. -* To check is nameof_type supported compiler use macro `NAMEOF_TYPE_SUPPORTED` or constexpr constant `nameof::is_nameof_type_supported`. -If nameof_type used on unsupported compiler, occurs the compilation error. To suppress error define macro `NAMEOF_TYPE_NO_CHECK_SUPPORT`. +* To check is nameof_type supported compiler use macro `NAMEOF_TYPE_SUPPORTED` or constexpr constant `nameof::is_nameof_type_supported`.
+ If nameof_type used on unsupported compiler, occurs the compilation error. To suppress error define macro `NAMEOF_TYPE_NO_CHECK_SUPPORT`. -* To check is nameof_enum supported compiler use macro `NAMEOF_ENUM_SUPPORTED` or constexpr constant `nameof::is_nameof_enum_supported`. -If nameof_enum used on unsupported compiler, occurs the compilation error. To suppress error define macro `NAMEOF_ENUM_NO_CHECK_SUPPORT`. +* To check is nameof_enum supported compiler use macro `NAMEOF_ENUM_SUPPORTED` or constexpr constant `nameof::is_nameof_enum_supported`.
+ If nameof_enum used on unsupported compiler, occurs the compilation error. To suppress error define macro `NAMEOF_ENUM_NO_CHECK_SUPPORT`. ## `NAMEOF` @@ -35,6 +34,7 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp // Name of variable. NAMEOF(somevar) -> "somevar" @@ -63,6 +63,7 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp // Full name of template function. NAMEOF_FULL(foo()) -> "foo" @@ -80,39 +81,40 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp NAMEOF_RAW(::somevar.somefield) -> "::somevar.somefield" NAMEOF_RAW(&some_class::some_method) -> "&some_class::some_method" ``` -## `nameof_enum(value)` +## `nameof_enum` * Function that obtains simple (unqualified) string enum name of enum variable. * Returns `std::string_view`. -* If argument does not have name, returns empty `std::string_view`. +* Enum variable to string. -* Examples - ```cpp - auto color = Color::RED; - nameof::nameof_enum(color) -> "RED" - ``` + * If argument does not have name or [out of range](limitations.md#nameof-enum), returns empty `std::string_view`. -## `nameof_enum()` + * Examples -* Function that obtains simple (unqualified) string enum name of static storage enum variable. + ```cpp + auto color = Color::RED; + nameof::nameof_enum(color) -> "RED" + ``` -* Returns `std::string_view`. +* Static storage enum variable to string. -* This version is much lighter on the compile times and is not restricted to the enum_range [limitation](limitations.md). + * This version is much lighter on the compile times and is not restricted to the enum_range [limitation](limitations.md#nameof-enum). -* If argument does not have name, returns empty `std::string_view`. + * If argument does not have name, occurs the compilation error `"Enum value does not have a name."`. -* Examples - ```cpp - nameof::nameof_enum() -> "GREEN" - ``` + * Examples + + ```cpp + nameof::nameof_enum() -> "GREEN" + ``` ## `NAMEOF_ENUM` @@ -120,9 +122,10 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * Returns `std::string_view`. -* If argument does not have name, returns empty `std::string_view`. +* If argument does not have name or [out of range](limitations.md#nameof-enum), returns empty `std::string_view`. * Examples + ```cpp auto color = Color::RED; NAMEOF_ENUM(color) -> "RED" @@ -134,16 +137,17 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * Returns `std::string_view`. -* This version is much lighter on the compile times and is not restricted to the enum_range [limitation](limitations.md). +* This version is much lighter on the compile times and is not restricted to the enum_range [limitation](limitations.md#nameof-enum). -* If argument does not have name, returns empty `std::string_view`. +* If argument does not have name, occurs the compilation error `"Enum value does not have a name."`. * Examples + ```cpp NAMEOF_CONST_ENUM(Color::GREEN) -> "GREEN" ``` -## `nameof_type()` +## `nameof_type` * Function macro that obtains string name of type, reference and cv-qualifiers are ignored. @@ -156,12 +160,13 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp using T = const int&; nameof::nameof_type() -> "int" ``` -## `nameof_full_type()` +## `nameof_full_type` * Function that obtains string name of full type, with reference and cv-qualifiers. @@ -172,6 +177,7 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp using T = const int&; nameof::nameof_full_type() -> "const int&" @@ -190,6 +196,7 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp using T = const int&; NAMEOF_TYPE(T) -> "int" @@ -206,6 +213,7 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp using T = const int&; NAMEOF_TYPE(T) -> "const int&" @@ -224,13 +232,14 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp using T = const int&; T var = 42; NAMEOF_TYPE_EXPR(var) -> "int" ``` -## `NAMEOF_TYPE_EXPR` +## `NAMEOF_FULL_TYPE_EXPR` * Macro that obtains string name full type of expression, with reference and cv-qualifiers. @@ -241,6 +250,7 @@ If nameof_enum used on unsupported compiler, occurs the compilation error. To su * If argument does not have name, occurs the compilation error `"Expression does not have a name."`. * Examples + ```cpp using T = const int&; T var = 42;