|
120
|
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
|
|
121
|
29 #include "llvm/ADT/Optional.h"
|
|
120
|
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"
|
|
121
|
37 #include <cstddef>
|
|
120
|
38 #include <string>
|
|
|
39 #include <tuple>
|
|
121
|
40 #include <utility>
|
|
120
|
41 #include <vector>
|
|
|
42
|
|
|
43 namespace llvm {
|
|
|
44
|
|
|
45 enum class ReplacementType { Empty, Format, Literal };
|
|
|
46
|
|
|
47 struct ReplacementItem {
|
|
121
|
48 ReplacementItem() = default;
|
|
120
|
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) {}
|
|
121
|
55
|
|
120
|
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*>.
|
|
121
|
74 struct create_adapters {
|
|
120
|
75 template <typename... Ts>
|
|
121
|
76 std::vector<detail::format_adapter *> operator()(Ts &... Items) {
|
|
|
77 return std::vector<detail::format_adapter *>{&Items...};
|
|
120
|
78 }
|
|
|
79 };
|
|
|
80
|
|
|
81 StringRef Fmt;
|
|
121
|
82 std::vector<detail::format_adapter *> Adapters;
|
|
120
|
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)) {
|
|
121
|
94 Adapters.reserve(ParamCount);
|
|
120
|
95 }
|
|
|
96
|
|
121
|
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
|
|
120
|
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 }
|
|
121
|
114 if (R.Index >= Adapters.size()) {
|
|
120
|
115 S << R.Spec;
|
|
|
116 continue;
|
|
|
117 }
|
|
|
118
|
|
121
|
119 auto W = Adapters[R.Index];
|
|
120
|
120
|
|
|
121 FmtAlign Align(*W, R.Where, R.Align);
|
|
|
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
|
|
121
|
137 template <unsigned N> SmallString<N> sstr() const {
|
|
120
|
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 {
|
|
121
|
150 // Storage for the parameter adapters. Since the base class erases the type
|
|
120
|
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)) {
|
|
121
|
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);
|
|
120
|
168 }
|
|
|
169 };
|
|
|
170
|
|
|
171 // \brief 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===
|
|
121
|
216 // `index` specifies the index of the parameter in the parameter pack to format
|
|
120
|
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 //
|
|
121
|
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
|
|
120
|
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 //
|
|
|
241 // If a match cannot be found through either of the above methods, a compiler
|
|
|
242 // error is generated.
|
|
|
243 //
|
|
|
244 // ===Invalid Format String Handling===
|
|
|
245 //
|
|
|
246 // In the case of a format string which does not match the grammar described
|
|
|
247 // above, the output is undefined. With asserts enabled, LLVM will trigger an
|
|
|
248 // assertion. Otherwise, it will try to do something reasonable, but in general
|
|
|
249 // the details of what that is are undefined.
|
|
|
250 //
|
|
|
251 template <typename... Ts>
|
|
|
252 inline auto formatv(const char *Fmt, Ts &&... Vals) -> formatv_object<decltype(
|
|
121
|
253 std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...))> {
|
|
120
|
254 using ParamTuple = decltype(
|
|
121
|
255 std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
|
|
120
|
256 return formatv_object<ParamTuple>(
|
|
|
257 Fmt,
|
|
121
|
258 std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
|
|
120
|
259 }
|
|
|
260
|
|
121
|
261 // Allow a formatv_object to be formatted (no options supported).
|
|
|
262 template <typename T> struct format_provider<formatv_object<T>> {
|
|
|
263 static void format(const formatv_object<T> &V, raw_ostream &OS, StringRef) {
|
|
|
264 OS << V;
|
|
|
265 }
|
|
|
266 };
|
|
|
267
|
|
120
|
268 } // end namespace llvm
|
|
|
269
|
|
121
|
270 #endif // LLVM_SUPPORT_FORMATVARIADIC_H
|
