diff --git a/docs/ct_format.adoc b/docs/ct_format.adoc index 381bc87..5be15ba 100644 --- a/docs/ct_format.adoc +++ b/docs/ct_format.adoc @@ -11,12 +11,12 @@ The format string is provided as a template argument, and the arguments to be formatted as regular function arguments. The result type is a `stdx::format_result` containing two members: the -xref:ct_string.adoc#_ct_string_hpp[`ct_string`] and a +xref:ct_string.adoc#_ct_string_hpp[`ct_string`] (wrapped in a `cts_t`) and a xref:tuple.adoc#_tuple_hpp[`tuple`] of the format arguments. [source,cpp] ---- auto s = stdx::ct_format<"Hello {} {}">(42, 17); -// s is stdx::format_result{"Hello {} {}"_cts, stdx::tuple{42, 17}} +// s is stdx::format_result{"Hello {} {}"_ctst, stdx::tuple{42, 17}} ---- When format arguments are available at compile-time, wrapping them in @@ -24,14 +24,21 @@ When format arguments are available at compile-time, wrapping them in [source,cpp] ---- auto s = stdx::ct_format<"Hello {} {}">(CX_VALUE(42), 17); -// s is stdx::format_result{"Hello 42 {}"_cts, stdx::tuple{17}} +// s is stdx::format_result{"Hello 42 {}"_ctst, stdx::tuple{17}} ---- -If there are no runtime arguments, the result is just a `stdx::ct_string`: +If there are no runtime arguments, the result is a `format_result` with an empty tuple... [source,cpp] ---- auto s = stdx::ct_format<"Hello {} {}">(CX_VALUE(42), CX_VALUE(17)); -// s is "Hello 42 17"_cts +// s is stdx::format_result{"Hello 42 17"_ctst, stdx::tuple{}} +---- +...and a `format_result` like this without an runtime arguments is implicitly convertible back to a `ct_string`: +[source,cpp] +---- +template auto f() { ... }; + +f(CX_VALUE(42))>(); // equivalent to f<"Hello 42">() ---- Types and compile-time enumeration values are stringified thus: @@ -39,34 +46,20 @@ Types and compile-time enumeration values are stringified thus: ---- enum struct E { value }; auto s = stdx::ct_format<"Hello {} {}">(CX_VALUE(int), CX_VALUE(E::value)); -// s is "Hello int value"_cts +// s is stdx::format_result{"Hello int value"_ctst, stdx::tuple{}} ---- NOTE: Compile-time formatting is done with https://github.com/fmtlib/fmt[fmtlib] and supports the same formatting DSL. Positional arguments are not supported. -`ct_format` is designed for use with a logging backend like the one in -https://github.com/intel/compile-time-init-build. Hence `stdx::format_result` -allows lazy runtime formatting. For the same reason, compile-time formatting can -output string information in a -https://github.com/intel/compile-time-init-build/tree/main/include/sc[suitable -type] rather than as a value. This is done by passing the template as a second -template argument to `ct_format`. - -[source,cpp] ----- -auto s = stdx::ct_format<"{}", sc::string_constant>(CX_VALUE(42)); -// s is sc::string_constant{} ----- - When formatting a compile-time `stdx::format_result`, the strings and argument tuples are collapsed to a single `stdx::format_result`: [source,cpp] ---- constexpr static auto a = stdx::ct_format<"The answer is {}">(42); -// a is stdx::format_result{"The answer is {}", stdx::tuple{42}} +// a is stdx::format_result{"The answer is {}"_ctst, stdx::tuple{42}} constexpr static auto q = stdx::ct_format<"{}. But what is the question?">(CX_VALUE(a)); -// q is stdx::format_result{"The answer is {}. But what is the question?", stdx::tuple{42}} +// q is stdx::format_result{"The answer is {}. But what is the question?"_ctst, stdx::tuple{42}} ---- diff --git a/docs/ct_string.adoc b/docs/ct_string.adoc index 906631b..74a102d 100644 --- a/docs/ct_string.adoc +++ b/docs/ct_string.adoc @@ -84,3 +84,14 @@ However, for interfacing with legacy functions, a null terminator can be useful. See https://github.com/intel/compile-time-init-build/tree/main/include/sc[cib documentation] for details about the cib string constant class. + +Sometimes it is useful to wrap a `ct_string` in a type to preserve compile-time +properties. For this, there is `cts_t` and a corresponding user-defined literal. +[source,cpp] +---- +using namespace stdx::literals; + +constexpr auto s = "hello"_ctst; +// s is a stdx::cts_t<"hello"> +---- +Think of `cts_t` relating to `ct_string` as `std::integral_constant` relates to `int`.