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 | 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 | std::vector<detail::format_adapter *> operator()(Ts &... Items) { |
77 | return std::vector<detail::format_adapter *>{&Items...}; |
78 | } |
79 | }; |
80 | |
81 | StringRef Fmt; |
82 | std::vector<detail::format_adapter *> Adapters; |
83 | std::vector<ReplacementItem> Replacements; |
84 | |
85 | static bool consumeFieldLayout(StringRef &Spec, AlignStyle &Where, |
86 | size_t &Align, char &Pad); |
87 | |
88 | static std::pair<ReplacementItem, StringRef> |
89 | splitLiteralAndReplacement(StringRef Fmt); |
90 | |
91 | public: |
92 | formatv_object_base(StringRef Fmt, std::size_t ParamCount) |
93 | : Fmt(Fmt), Replacements(parseFormatString(Fmt)) { |
94 | Adapters.reserve(ParamCount); |
95 | } |
96 | |
97 | formatv_object_base(formatv_object_base const &rhs) = delete; |
98 | |
99 | formatv_object_base(formatv_object_base &&rhs) |
100 | : Fmt(std::move(rhs.Fmt)), |
101 | Adapters(), // Adapters are initialized by formatv_object |
102 | Replacements(std::move(rhs.Replacements)) { |
103 | Adapters.reserve(rhs.Adapters.size()); |
104 | }; |
105 | |
106 | void format(raw_ostream &S) const { |
107 | for (auto &R : Replacements) { |
108 | if (R.Type == ReplacementType::Empty) |
109 | continue; |
110 | if (R.Type == ReplacementType::Literal) { |
111 | S << R.Spec; |
112 | continue; |
113 | } |
114 | if (R.Index >= Adapters.size()) { |
115 | S << R.Spec; |
116 | continue; |
117 | } |
118 | |
119 | auto W = Adapters[R.Index]; |
120 | |
121 | FmtAlign Align(*W, R.Where, R.Align, R.Pad); |
122 | Align.format(S, R.Options); |
123 | } |
124 | } |
125 | static std::vector<ReplacementItem> parseFormatString(StringRef Fmt); |
126 | |
127 | static Optional<ReplacementItem> parseReplacementItem(StringRef Spec); |
128 | |
129 | std::string str() const { |
130 | std::string Result; |
131 | raw_string_ostream Stream(Result); |
132 | Stream << *this; |
133 | Stream.flush(); |
134 | return Result; |
135 | } |
136 | |
137 | template <unsigned N> SmallString<N> sstr() const { |
138 | SmallString<N> Result; |
139 | raw_svector_ostream Stream(Result); |
140 | Stream << *this; |
141 | return Result; |
142 | } |
143 | |
144 | template <unsigned N> operator SmallString<N>() const { return sstr<N>(); } |
145 | |
146 | operator std::string() const { return str(); } |
147 | }; |
148 | |
149 | template <typename Tuple> class formatv_object : public formatv_object_base { |
150 | // Storage for the parameter adapters. Since the base class erases the type |
151 | // of the parameters, we have to own the storage for the parameters here, and |
152 | // have the base class store type-erased pointers into this tuple. |
153 | Tuple Parameters; |
154 | |
155 | public: |
156 | formatv_object(StringRef Fmt, Tuple &&Params) |
157 | : formatv_object_base(Fmt, std::tuple_size<Tuple>::value), |
158 | Parameters(std::move(Params)) { |
159 | Adapters = apply_tuple(create_adapters(), Parameters); |
160 | } |
161 | |
162 | formatv_object(formatv_object const &rhs) = delete; |
163 | |
164 | formatv_object(formatv_object &&rhs) |
165 | : formatv_object_base(std::move(rhs)), |
166 | Parameters(std::move(rhs.Parameters)) { |
167 | Adapters = apply_tuple(create_adapters(), Parameters); |
168 | } |
169 | }; |
170 | |
171 | // Format text given a format string and replacement parameters. |
172 | // |
173 | // ===General Description=== |
174 | // |
175 | // Formats textual output. `Fmt` is a string consisting of one or more |
176 | // replacement sequences with the following grammar: |
177 | // |
178 | // rep_field ::= "{" [index] ["," layout] [":" format] "}" |
179 | // index ::= <non-negative integer> |
180 | // layout ::= [[[char]loc]width] |
181 | // format ::= <any string not containing "{" or "}"> |
182 | // char ::= <any character except "{" or "}"> |
183 | // loc ::= "-" | "=" | "+" |
184 | // width ::= <positive integer> |
185 | // |
186 | // index - A non-negative integer specifying the index of the item in the |
187 | // parameter pack to print. Any other value is invalid. |
188 | // layout - A string controlling how the field is laid out within the available |
189 | // space. |
190 | // format - A type-dependent string used to provide additional options to |
191 | // the formatting operation. Refer to the documentation of the |
192 | // various individual format providers for per-type options. |
193 | // char - The padding character. Defaults to ' ' (space). Only valid if |
194 | // `loc` is also specified. |
195 | // loc - Where to print the formatted text within the field. Only valid if |
196 | // `width` is also specified. |
197 | // '-' : The field is left aligned within the available space. |
198 | // '=' : The field is centered within the available space. |
199 | // '+' : The field is right aligned within the available space (this |
200 | // is the default). |
201 | // width - The width of the field within which to print the formatted text. |
202 | // If this is less than the required length then the `char` and `loc` |
203 | // fields are ignored, and the field is printed with no leading or |
204 | // trailing padding. If this is greater than the required length, |
205 | // then the text is output according to the value of `loc`, and padded |
206 | // as appropriate on the left and/or right by `char`. |
207 | // |
208 | // ===Special Characters=== |
209 | // |
210 | // The characters '{' and '}' are reserved and cannot appear anywhere within a |
211 | // replacement sequence. Outside of a replacement sequence, in order to print |
212 | // a literal '{' or '}' it must be doubled -- "{{" to print a literal '{' and |
213 | // "}}" to print a literal '}'. |
214 | // |
215 | // ===Parameter Indexing=== |
216 | // `index` specifies the index of the parameter in the parameter pack to format |
217 | // into the output. Note that it is possible to refer to the same parameter |
218 | // index multiple times in a given format string. This makes it possible to |
219 | // output the same value multiple times without passing it multiple times to the |
220 | // function. For example: |
221 | // |
222 | // formatv("{0} {1} {0}", "a", "bb") |
223 | // |
224 | // would yield the string "abba". This can be convenient when it is expensive |
225 | // to compute the value of the parameter, and you would otherwise have had to |
226 | // save it to a temporary. |
227 | // |
228 | // ===Formatter Search=== |
229 | // |
230 | // For a given parameter of type T, the following steps are executed in order |
231 | // until a match is found: |
232 | // |
233 | // 1. If the parameter is of class type, and inherits from format_adapter, |
234 | // Then format() is invoked on it to produce the formatted output. The |
235 | // implementation should write the formatted text into `Stream`. |
236 | // 2. If there is a suitable template specialization of format_provider<> |
237 | // for type T containing a method whose signature is: |
238 | // void format(const T &Obj, raw_ostream &Stream, StringRef Options) |
239 | // Then this method is invoked as described in Step 1. |
240 | // 3. If an appropriate operator<< for raw_ostream exists, it will be used. |
241 | // For this to work, (raw_ostream& << const T&) must return raw_ostream&. |
242 | // |
243 | // If a match cannot be found through either of the above methods, a compiler |
244 | // error is generated. |
245 | // |
246 | // ===Invalid Format String Handling=== |
247 | // |
248 | // In the case of a format string which does not match the grammar described |
249 | // above, the output is undefined. With asserts enabled, LLVM will trigger an |
250 | // assertion. Otherwise, it will try to do something reasonable, but in general |
251 | // the details of what that is are undefined. |
252 | // |
253 | template <typename... Ts> |
254 | inline auto formatv(const char *Fmt, Ts &&... Vals) -> formatv_object<decltype( |
255 | std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...))> { |
256 | using ParamTuple = decltype( |
257 | std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...)); |
258 | return formatv_object<ParamTuple>( |
259 | Fmt, |
260 | std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...)); |
261 | } |
262 | |
263 | } // end namespace llvm |
264 | |
265 | #endif // LLVM_SUPPORT_FORMATVARIADIC_H |
266 | |