1 // Copyright 2013 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #ifndef BASE_STRINGS_STRINGPRINTF_H_
6 #define BASE_STRINGS_STRINGPRINTF_H_
7
8 #include <stdarg.h> // va_list
9
10 #include <string>
11 #include <string_view>
12
13 #include "base/base_export.h"
14 #include "base/compiler_specific.h"
15
16 namespace base {
17
18 // Returns a C++ string given `printf()`-like input. The format string should be
19 // a compile-time constant (like with `std::format()`).
20 // TODO(crbug.com/1371963): Implement in terms of `std::format()`,
21 // `absl::StrFormat()`, or similar.
22 [[nodiscard]] BASE_EXPORT std::string StringPrintf(const char* format, ...)
23 PRINTF_FORMAT(1, 2);
24
25 // Returns a C++ string given `printf()`-like input. The format string must be a
26 // run-time value (like with `std::vformat()`), or this will not compile.
27 // Because this does not check arguments at compile-time, prefer
28 // `StringPrintf()` whenever possible.
29 template <typename... Args>
StringPrintfNonConstexpr(std::string_view format,const Args &...args)30 [[nodiscard]] std::string StringPrintfNonConstexpr(std::string_view format,
31 const Args&... args) {
32 // TODO(crbug.com/1371963): Implement in terms of `std::vformat()`,
33 // `absl::FormatUntyped()`, or similar.
34 return StringPrintf(std::string(format).c_str(), args...);
35 }
36
37 // If possible, guide users to use `StringPrintf()` instead of
38 // `StringPrintfNonConstexpr()` when the format string is constexpr.
39 //
40 // It would be nice to do this with `std::enable_if`, but I don't know of a way;
41 // whether a string constant's value is available at compile time is not
42 // something easily obtained from the type system, and trying to pass various
43 // forms of string constant to non-type template parameters produces a variety
44 // of compile errors.
45 #if HAS_ATTRIBUTE(enable_if)
46 // Disable calling with a constexpr `std::string_view`.
47 template <typename... Args>
48 [[nodiscard]] std::string StringPrintfNonConstexpr(std::string_view format,
49 const Args&... args)
50 __attribute__((enable_if(
51 [](std::string_view s) { return s.empty() || s[0] == s[0]; }(format),
52 "Use StringPrintf() for constexpr format strings"))) = delete;
53 // Disable calling with a constexpr `char[]` or `char*`.
54 template <typename... Args>
55 [[nodiscard]] std::string StringPrintfNonConstexpr(const char* format,
56 const Args&... args)
57 __attribute__((
58 enable_if([](const char* s) { return !!s; }(format),
59 "Use StringPrintf() for constexpr format strings"))) = delete;
60 #endif
61
62 // Returns a C++ string given `vprintf()`-like input.
63 [[nodiscard]] BASE_EXPORT std::string StringPrintV(const char* format,
64 va_list ap)
65 PRINTF_FORMAT(1, 0);
66
67 // Like `StringPrintf()`, but appends result to a supplied string.
68 // TODO(crbug.com/1371963): Implement in terms of `std::format_to()`,
69 // `absl::StrAppendFormat()`, or similar.
70 BASE_EXPORT void StringAppendF(std::string* dst, const char* format, ...)
71 PRINTF_FORMAT(2, 3);
72
73 // Like `StringPrintV()`, but appends result to a supplied string.
74 BASE_EXPORT void StringAppendV(std::string* dst, const char* format, va_list ap)
75 PRINTF_FORMAT(2, 0);
76
77 } // namespace base
78
79 #endif // BASE_STRINGS_STRINGPRINTF_H_
80