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