absl::FormatSpec

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.