[#absl-FormatSpec]
= xref:absl.adoc[absl]::FormatSpec
:relfileprefix: ../
:mrdocs:

Defines the makeup of a format string within the `str&lowbar;format` library&period;

== Synopsis

Declared in `&lt;absl&sol;strings&sol;str&lowbar;format&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;typename&period;&period;&period; Args&gt;
using FormatSpec = str&lowbar;format&lowbar;internal::FormatSpecTemplate&lt;str&lowbar;format&lowbar;internal&colon;&colon;ArgumentToConv&lt;Args&gt;()&period;&period;&period;&gt;;
----

== Description

The `FormatSpec` type is a variadic class template that is evaluated at compile&hyphen;time, according to the format string and arguments that are passed to it&period;

You should not need to manipulate this type directly&period; You should only name it if you are writing wrapper functions which accept format arguments that will be provided unmodified to functions in this library&period; Such a wrapper function might be a class method that provides format arguments and&sol;or internally uses the result of formatting&period;

For a `FormatSpec` to be valid at compile&hyphen;time, it must be provided as either&colon;

&ast; A `constexpr` literal or `absl&colon;&colon;string&lowbar;view`, which is how it is most often used&period; &ast; A `ParsedFormat` instantiation, which ensures the format string is valid before use&period; (See below&period;)

Example&colon;

&sol;&sol; Provided as a string literal&period; absl&colon;&colon;StrFormat(&quot;Welcome to %s, Number %d!&quot;, &quot;The Village&quot;, 6)&semi;

&sol;&sol; Provided as a constexpr absl&colon;&colon;string&lowbar;view&period; constexpr absl&colon;&colon;string&lowbar;view formatString &equals; &quot;Welcome to %s, Number %d!&quot;&semi; absl&colon;&colon;StrFormat(formatString, &quot;The Village&quot;, 6)&semi;

&sol;&sol; Provided as a pre&hyphen;compiled ParsedFormat object&period; &sol;&sol; Note that this example is useful only for illustration purposes&period; absl&colon;&colon;ParsedFormat&lt;&apos;s&apos;, &apos;d&apos;&gt; formatString(&quot;Welcome to %s, Number %d!&quot;)&semi; absl&colon;&colon;StrFormat(formatString, &quot;TheVillage&quot;, 6)&semi;

A format string generally follows the POSIX syntax as used within the POSIX `printf` specification&period; (Exceptions are noted below&period;)

(See http&colon;&sol;&sol;pubs&period;opengroup&period;org&sol;onlinepubs&sol;9699919799&sol;functions&sol;fprintf&period;html)

In specific, the `FormatSpec` supports the following type specifiers&colon; &ast; `c` for characters &ast; `s` for strings &ast; `d` or `i` for integers &ast; `o` for unsigned integer conversions into octal &ast; `x` or `X` for unsigned integer conversions into hex &ast; `u` for unsigned integers &ast; `f` or `F` for floating point values into decimal notation &ast; `e` or `E` for floating point values into exponential notation &ast; `a` or `A` for floating point values into hex exponential notation &ast; `g` or `G` for floating point values into decimal or exponential notation based on their precision &ast; `p` for pointer address values &ast; `n` for the special case of writing out the number of characters written to this point&period; The resulting value must be captured within an `absl&colon;&colon;FormatCountCapture` type&period; &ast; `v` for values using the default format for a deduced type&period; These deduced types include many of the primitive types denoted here as well as user&hyphen;defined types containing the proper extensions&period; (See below for more information&period;)

Implementation&hyphen;defined behavior&colon; &ast; A null pointer provided to &quot;%s&quot; or &quot;%p&quot; is output as &quot;(nil)&quot;&period; &ast; A non&hyphen;null pointer provided to &quot;%p&quot; is output in hex as if by %&num;x or %&num;lx&period;

NOTE&colon; `o`, `xX` and `u` will convert signed values to their unsigned counterpart before formatting&period;

Examples&colon; &quot;%c&quot;, &apos;a&apos; &hyphen;&gt; &quot;a&quot; &quot;%c&quot;, 32 &hyphen;&gt; &quot; &quot; &quot;%s&quot;, &quot;C&quot; &hyphen;&gt; &quot;C&quot; &quot;%s&quot;, std&colon;&colon;string(&quot;C&plus;&plus;&quot;) &hyphen;&gt; &quot;C&plus;&plus;&quot; &quot;%d&quot;, &hyphen;10 &hyphen;&gt; &quot;&hyphen;10&quot; &quot;%o&quot;, 10 &hyphen;&gt; &quot;12&quot; &quot;%x&quot;, 16 &hyphen;&gt; &quot;10&quot; &quot;%f&quot;, 123456789 &hyphen;&gt; &quot;123456789&period;000000&quot; &quot;%e&quot;, &period;01 &hyphen;&gt; &quot;1&period;00000e&hyphen;2&quot; &quot;%a&quot;, &hyphen;3&period;0 &hyphen;&gt; &quot;&hyphen;0x1&period;8p&plus;1&quot; &quot;%g&quot;, &period;01 &hyphen;&gt; &quot;1e&hyphen;2&quot; &quot;%p&quot;, (void&ast;)&amp;value &hyphen;&gt; &quot;0x7ffdeb6ad2a4&quot;

int n &equals; 0&semi; std&colon;&colon;string s &equals; absl&colon;&colon;StrFormat( &quot;%s%d%n&quot;, &quot;hello&quot;, 123, absl&colon;&colon;FormatCountCapture(&amp;n))&semi; EXPECT&lowbar;EQ(8, n)&semi;

NOTE&colon; the `v` specifier (for &quot;value&quot;) is a type specifier not present in the POSIX specification&period; %v will format values according to their deduced type&period; `v` uses `d` for signed integer values, `u` for unsigned integer values, `g` for floating point values, and formats boolean values as &quot;true&quot;&sol;&quot;false&quot; (instead of 1 or 0 for booleans formatted using d)&period; `const char&ast;` is not supported&semi; please use `std&colon;&colon;string` and `string&lowbar;view`&period; `char` is also not supported due to ambiguity of the type&period; This specifier does not support modifiers&period;

The `FormatSpec` intrinsically supports all of these fundamental C&plus;&plus; types&colon;

&ast; Characters&colon; `char`, `signed char`, `unsigned char`, `wchar&lowbar;t` &ast; Integers&colon; `int`, `short`, `unsigned short`, `unsigned`, `long`, `unsigned long`, `long long`, `unsigned long long` &ast; Enums&colon; printed as their underlying integral value &ast; Floating&hyphen;point&colon; `float`, `double`, `long double`

However, in the `str&lowbar;format` library, a format conversion specifies a broader C&plus;&plus; conceptual category instead of an exact type&period; For example, `%s` binds to any string&hyphen;like argument, so `std&colon;&colon;string`, `std&colon;&colon;wstring`, `absl&colon;&colon;string&lowbar;view`, `const char&ast;`, and `const wchar&lowbar;t&ast;` are all accepted&period; Likewise, `%d` accepts any integer&hyphen;like argument, etc&period;

Note&colon; Compile&hyphen;time format string checking is supported on GCC and Clang&period; On MSVC, these checks are performed at runtime instead&period;


[.small]#Created with https://www.mrdocs.com[MrDocs]#
