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
43namespace llvm {
44
45enum class ReplacementType { Empty, Format, Literal };
46
47struct 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
65class formatv_object_base {
66protected:
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
91public:
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
149template <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
155public:
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//
253template <typename... Ts>
254inline 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