Line data Source code
1 : //===- FormatVariadic.h - Efficient type-safe string formatting --*- C++-*-===//
2 : //
3 : // The LLVM Compiler Infrastructure
4 : //
5 : // This file is distributed under the University of Illinois Open Source
6 : // License. See LICENSE.TXT for details.
7 : //
8 : //===----------------------------------------------------------------------===//
9 : //
10 : // This file implements the formatv() function which can be used with other LLVM
11 : // subsystems to provide printf-like formatting, but with improved safety and
12 : // flexibility. The result of `formatv` is an object which can be streamed to
13 : // a raw_ostream or converted to a std::string or llvm::SmallString.
14 : //
15 : // // Convert to std::string.
16 : // std::string S = formatv("{0} {1}", 1234.412, "test").str();
17 : //
18 : // // Convert to llvm::SmallString
19 : // SmallString<8> S = formatv("{0} {1}", 1234.412, "test").sstr<8>();
20 : //
21 : // // Stream to an existing raw_ostream.
22 : // OS << formatv("{0} {1}", 1234.412, "test");
23 : //
24 : //===----------------------------------------------------------------------===//
25 :
26 : #ifndef LLVM_SUPPORT_FORMATVARIADIC_H
27 : #define LLVM_SUPPORT_FORMATVARIADIC_H
28 :
29 : #include "llvm/ADT/Optional.h"
30 : #include "llvm/ADT/STLExtras.h"
31 : #include "llvm/ADT/SmallString.h"
32 : #include "llvm/ADT/StringRef.h"
33 : #include "llvm/Support/FormatCommon.h"
34 : #include "llvm/Support/FormatProviders.h"
35 : #include "llvm/Support/FormatVariadicDetails.h"
36 : #include "llvm/Support/raw_ostream.h"
37 : #include <cstddef>
38 : #include <string>
39 : #include <tuple>
40 : #include <utility>
41 : #include <vector>
42 :
43 : namespace llvm {
44 :
45 : enum class ReplacementType { Empty, Format, Literal };
46 :
47 : struct ReplacementItem {
48 175390 : ReplacementItem() = default;
49 : explicit ReplacementItem(StringRef Literal)
50 : : Type(ReplacementType::Literal), Spec(Literal) {}
51 : ReplacementItem(StringRef Spec, size_t Index, size_t Align, AlignStyle Where,
52 : char Pad, StringRef Options)
53 : : Type(ReplacementType::Format), Spec(Spec), Index(Index), Align(Align),
54 : Where(Where), Pad(Pad), Options(Options) {}
55 :
56 : ReplacementType Type = ReplacementType::Empty;
57 : StringRef Spec;
58 : size_t Index = 0;
59 : size_t Align = 0;
60 : AlignStyle Where = AlignStyle::Right;
61 : char Pad;
62 : StringRef Options;
63 : };
64 :
65 : class formatv_object_base {
66 : protected:
67 : // The parameters are stored in a std::tuple, which does not provide runtime
68 : // indexing capabilities. In order to enable runtime indexing, we use this
69 : // structure to put the parameters into a std::vector. Since the parameters
70 : // are not all the same type, we use some type-erasure by wrapping the
71 : // parameters in a template class that derives from a non-template superclass.
72 : // Essentially, we are converting a std::tuple<Derived<Ts...>> to a
73 : // std::vector<Base*>.
74 : struct create_adapters {
75 : template <typename... Ts>
76 0 : std::vector<detail::format_adapter *> operator()(Ts &... Items) {
77 87237 : return std::vector<detail::format_adapter *>{&Items...};
78 : }
79 0 : };
80 0 :
81 : StringRef Fmt;
82 0 : std::vector<detail::format_adapter *> Adapters;
83 0 : std::vector<ReplacementItem> Replacements;
84 :
85 0 : static bool consumeFieldLayout(StringRef &Spec, AlignStyle &Where,
86 0 : size_t &Align, char &Pad);
87 :
88 0 : static std::pair<ReplacementItem, StringRef>
89 0 : splitLiteralAndReplacement(StringRef Fmt);
90 :
91 0 : public:
92 6329 : formatv_object_base(StringRef Fmt, std::size_t ParamCount)
93 12658 : : Fmt(Fmt), Replacements(parseFormatString(Fmt)) {
94 6329 : Adapters.reserve(ParamCount);
95 6329 : }
96 :
97 0 : formatv_object_base(formatv_object_base const &rhs) = delete;
98 8524 :
99 17048 : formatv_object_base(formatv_object_base &&rhs)
100 8524 : : Fmt(std::move(rhs.Fmt)),
101 61513 : Adapters(), // Adapters are initialized by formatv_object
102 105978 : Replacements(std::move(rhs.Replacements)) {
103 52989 : Adapters.reserve(rhs.Adapters.size());
104 54908 : };
105 3838 :
106 89035 : void format(raw_ostream &S) const {
107 298761 : for (auto &R : Replacements) {
108 210066 : if (R.Type == ReplacementType::Empty)
109 94461 : continue;
110 210095 : if (R.Type == ReplacementType::Literal) {
111 94854 : S << R.Spec;
112 94485 : continue;
113 1028 : }
114 231858 : if (R.Index >= Adapters.size()) {
115 664 : S << R.Spec;
116 664 : continue;
117 : }
118 0 :
119 115291 : auto W = Adapters[R.Index];
120 52 :
121 115291 : FmtAlign Align(*W, R.Where, R.Align, R.Pad);
122 115291 : Align.format(S, R.Options);
123 : }
124 87116 : }
125 5318 : static std::vector<ReplacementItem> parseFormatString(StringRef Fmt);
126 10636 :
127 5318 : static Optional<ReplacementItem> parseReplacementItem(StringRef Spec);
128 5318 :
129 5359 : std::string str() const {
130 0 : std::string Result;
131 6164 : raw_string_ostream Stream(Result);
132 6969 : Stream << *this;
133 805 : Stream.flush();
134 6197 : return Result;
135 136 : }
136 33 :
137 194 : template <unsigned N> SmallString<N> sstr() const {
138 77 : SmallString<N> Result;
139 91 : raw_svector_ostream Stream(Result);
140 168 : Stream << *this;
141 149 : return Result;
142 0 : }
143 58 :
144 51 : template <unsigned N> operator SmallString<N>() const { return sstr<N>(); }
145 0 :
146 4285 : operator std::string() const { return str(); }
147 115 : };
148 666 :
149 7171 : template <typename Tuple> class formatv_object : public formatv_object_base {
150 1054 : // Storage for the parameter adapters. Since the base class erases the type
151 61 : // of the parameters, we have to own the storage for the parameters here, and
152 449 : // have the base class store type-erased pointers into this tuple.
153 349 : Tuple Parameters;
154 0 :
155 8847 : public:
156 6500 : formatv_object(StringRef Fmt, Tuple &&Params)
157 50 : : formatv_object_base(Fmt, std::tuple_size<Tuple>::value),
158 59502 : Parameters(std::move(Params)) {
159 6550 : Adapters = apply_tuple(create_adapters(), Parameters);
160 6329 : }
161 1899 :
162 8531 : formatv_object(formatv_object const &rhs) = delete;
163 11 :
164 9011 : formatv_object(formatv_object &&rhs)
165 61629 : : formatv_object_base(std::move(rhs)),
166 8573 : Parameters(std::move(rhs.Parameters)) {
167 60638 : Adapters = apply_tuple(create_adapters(), Parameters);
168 54857 : }
169 60028 : };
170 15515 :
171 9237 : // Format text given a format string and replacement parameters.
172 9503 : //
173 7263 : // ===General Description===
174 8354 : //
175 21237 : // Formats textual output. `Fmt` is a string consisting of one or more
176 2601 : // replacement sequences with the following grammar:
177 20440 : //
178 19244 : // rep_field ::= "{" [index] ["," layout] [":" format] "}"
179 19504 : // index ::= <non-negative integer>
180 29012 : // layout ::= [[[char]loc]width]
181 945 : // format ::= <any string not containing "{" or "}">
182 33782 : // char ::= <any character except "{" or "}">
183 28882 : // loc ::= "-" | "=" | "+"
184 28213 : // width ::= <positive integer>
185 626 : //
186 902 : // index - A non-negative integer specifying the index of the item in the
187 665 : // parameter pack to print. Any other value is invalid.
188 1649 : // layout - A string controlling how the field is laid out within the available
189 5802 : // space.
190 806 : // format - A type-dependent string used to provide additional options to
191 5901 : // the formatting operation. Refer to the documentation of the
192 6048 : // various individual format providers for per-type options.
193 5413 : // char - The padding character. Defaults to ' ' (space). Only valid if
194 440 : // `loc` is also specified.
195 994 : // loc - Where to print the formatted text within the field. Only valid if
196 440 : // `width` is also specified.
197 1076 : // '-' : The field is left aligned within the available space.
198 1100 : // '=' : The field is centered within the available space.
199 883 : // '+' : The field is right aligned within the available space (this
200 59 : // is the default).
201 108 : // width - The width of the field within which to print the formatted text.
202 388 : // If this is less than the required length then the `char` and `loc`
203 88 : // fields are ignored, and the field is printed with no leading or
204 336 : // trailing padding. If this is greater than the required length,
205 416 : // then the text is output according to the value of `loc`, and padded
206 480 : // as appropriate on the left and/or right by `char`.
207 685 : //
208 370 : // ===Special Characters===
209 476 : //
210 192 : // The characters '{' and '}' are reserved and cannot appear anywhere within a
211 191 : // replacement sequence. Outside of a replacement sequence, in order to print
212 1621 : // a literal '{' or '}' it must be doubled -- "{{" to print a literal '{' and
213 3229 : // "}}" to print a literal '}'.
214 1608 : //
215 3113 : // ===Parameter Indexing===
216 3012 : // `index` specifies the index of the parameter in the parameter pack to format
217 1529 : // into the output. Note that it is possible to refer to the same parameter
218 1502 : // index multiple times in a given format string. This makes it possible to
219 32 : // output the same value multiple times without passing it multiple times to the
220 22 : // function. For example:
221 78 : //
222 52 : // formatv("{0} {1} {0}", "a", "bb")
223 52 : //
224 51 : // would yield the string "abba". This can be convenient when it is expensive
225 5 : // to compute the value of the parameter, and you would otherwise have had to
226 31 : // save it to a temporary.
227 35 : //
228 89 : // ===Formatter Search===
229 4 : //
230 55 : // For a given parameter of type T, the following steps are executed in order
231 55 : // until a match is found:
232 55 : //
233 1 : // 1. If the parameter is of class type, and inherits from format_adapter,
234 4 : // Then format() is invoked on it to produce the formatted output. The
235 1 : // implementation should write the formatted text into `Stream`.
236 5 : // 2. If there is a suitable template specialization of format_provider<>
237 5 : // for type T containing a method whose signature is:
238 7 : // void format(const T &Obj, raw_ostream &Stream, StringRef Options)
239 5 : // Then this method is invoked as described in Step 1.
240 321 : // 3. If an appropriate operator<< for raw_ostream exists, it will be used.
241 8 : // For this to work, (raw_ostream& << const T&) must return raw_ostream&.
242 326 : //
243 341 : // If a match cannot be found through either of the above methods, a compiler
244 5329 : // error is generated.
245 149 : //
246 5029 : // ===Invalid Format String Handling===
247 5153 : //
248 5150 : // In the case of a format string which does not match the grammar described
249 131 : // above, the output is undefined. With asserts enabled, LLVM will trigger an
250 171 : // assertion. Otherwise, it will try to do something reasonable, but in general
251 2 : // the details of what that is are undefined.
252 551 : //
253 173 : template <typename... Ts>
254 2582 : inline auto formatv(const char *Fmt, Ts &&... Vals) -> formatv_object<decltype(
255 383 : std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...))> {
256 2 : using ParamTuple = decltype(
257 7446 : std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
258 14130 : return formatv_object<ParamTuple>(
259 7064 : Fmt,
260 12702 : std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
261 1 : }
262 1 :
263 159 : } // end namespace llvm
264 0 :
265 1 : #endif // LLVM_SUPPORT_FORMATVARIADIC_H
|
