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

Defines the makeup of a format string within the `str_format` library.

== Synopsis

Declared in `<absl/strings/str_format.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<typename... Args>
using FormatSpec = str_format_internal::FormatSpecTemplate<str_format_internal::ArgumentToConv<Args>()...>;
----

== Description

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

You should not need to manipulate this type directly. 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. Such a wrapper function might be a class method that provides format arguments and/or internally uses the result of formatting.

For a `FormatSpec` to be valid at compile‐time, it must be provided as either:

* A `constexpr` literal or `absl::string_view`, which is how it is most often used. * A `ParsedFormat` instantiation, which ensures the format string is valid before use. (See below.)

Example:

// Provided as a string literal. absl::StrFormat("Welcome to %s, Number %d!", "The Village", 6);

// Provided as a constexpr absl::string_view. constexpr absl::string_view formatString = "Welcome to %s, Number %d!"; absl::StrFormat(formatString, "The Village", 6);

// Provided as a pre‐compiled ParsedFormat object. // Note that this example is useful only for illustration purposes. absl::ParsedFormat<'s', 'd'> formatString("Welcome to %s, Number %d!"); absl::StrFormat(formatString, "TheVillage", 6);

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

(See http://pubs.opengroup.org/onlinepubs/9699919799/functions/fprintf.html)

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

Implementation‐defined behavior: * A null pointer provided to "%s" or "%p" is output as "(nil)". * A non‐null pointer provided to "%p" is output in hex as if by %#x or %#lx.

NOTE: `o`, `xX` and `u` will convert signed values to their unsigned counterpart before formatting.

Examples: "%c", 'a' ‐> "a" "%c", 32 ‐> " " "%s", "C" ‐> "C" "%s", std::string("C++") ‐> "C++" "%d", ‐10 ‐> "‐10" "%o", 10 ‐> "12" "%x", 16 ‐> "10" "%f", 123456789 ‐> "123456789.000000" "%e", .01 ‐> "1.00000e‐2" "%a", ‐3.0 ‐> "‐0x1.8p+1" "%g", .01 ‐> "1e‐2" "%p", (void*)&value ‐> "0x7ffdeb6ad2a4"

int n = 0; std::string s = absl::StrFormat( "%s%d%n", "hello", 123, absl::FormatCountCapture(&n)); EXPECT_EQ(8, n);

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

The `FormatSpec` intrinsically supports all of these fundamental C++ types:

* Characters: `char`, `signed char`, `unsigned char`, `wchar_t` * Integers: `int`, `short`, `unsigned short`, `unsigned`, `long`, `unsigned long`, `long long`, `unsigned long long` * Enums: printed as their underlying integral value * Floating‐point: `float`, `double`, `long double`

However, in the `str_format` library, a format conversion specifies a broader C++ conceptual category instead of an exact type. For example, `%s` binds to any string‐like argument, so `std::string`, `std::wstring`, `absl::string_view`, `const char*`, and `const wchar_t*` are all accepted. Likewise, `%d` accepts any integer‐like argument, etc.

Note: Compile‐time format string checking is supported on GCC and Clang. On MSVC, these checks are performed at runtime instead.


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