LLVM  10.0.0svn
FormatVariadic.h
Go to the documentation of this file.
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/Optional.h"
29 #include "llvm/ADT/STLExtras.h"
30 #include "llvm/ADT/SmallString.h"
31 #include "llvm/ADT/StringRef.h"
36 #include <cstddef>
37 #include <string>
38 #include <tuple>
39 #include <utility>
40 #include <vector>
41 
42 namespace llvm {
43 
45 
47  ReplacementItem() = default;
48  explicit ReplacementItem(StringRef Literal)
49  : Type(ReplacementType::Literal), Spec(Literal) {}
50  ReplacementItem(StringRef Spec, size_t Index, size_t Align, AlignStyle Where,
51  char Pad, StringRef Options)
52  : Type(ReplacementType::Format), Spec(Spec), Index(Index), Align(Align),
53  Where(Where), Pad(Pad), Options(Options) {}
54 
57  size_t Index = 0;
58  size_t Align = 0;
60  char Pad;
62 };
63 
65 protected:
66  // The parameters are stored in a std::tuple, which does not provide runtime
67  // indexing capabilities. In order to enable runtime indexing, we use this
68  // structure to put the parameters into a std::vector. Since the parameters
69  // are not all the same type, we use some type-erasure by wrapping the
70  // parameters in a template class that derives from a non-template superclass.
71  // Essentially, we are converting a std::tuple<Derived<Ts...>> to a
72  // std::vector<Base*>.
73  struct create_adapters {
74  template <typename... Ts>
75  std::vector<detail::format_adapter *> operator()(Ts &... Items) {
76  return std::vector<detail::format_adapter *>{&Items...};
77  }
78  };
79 
81  std::vector<detail::format_adapter *> Adapters;
82  std::vector<ReplacementItem> Replacements;
83 
84  static bool consumeFieldLayout(StringRef &Spec, AlignStyle &Where,
85  size_t &Align, char &Pad);
86 
87  static std::pair<ReplacementItem, StringRef>
88  splitLiteralAndReplacement(StringRef Fmt);
89 
90 public:
91  formatv_object_base(StringRef Fmt, std::size_t ParamCount)
92  : Fmt(Fmt), Replacements(parseFormatString(Fmt)) {
93  Adapters.reserve(ParamCount);
94  }
95 
96  formatv_object_base(formatv_object_base const &rhs) = delete;
97 
99  : Fmt(std::move(rhs.Fmt)),
100  Adapters(), // Adapters are initialized by formatv_object
101  Replacements(std::move(rhs.Replacements)) {
102  Adapters.reserve(rhs.Adapters.size());
103  };
104 
105  void format(raw_ostream &S) const {
106  for (auto &R : Replacements) {
107  if (R.Type == ReplacementType::Empty)
108  continue;
109  if (R.Type == ReplacementType::Literal) {
110  S << R.Spec;
111  continue;
112  }
113  if (R.Index >= Adapters.size()) {
114  S << R.Spec;
115  continue;
116  }
117 
118  auto W = Adapters[R.Index];
119 
120  FmtAlign Align(*W, R.Where, R.Align, R.Pad);
121  Align.format(S, R.Options);
122  }
123  }
124  static std::vector<ReplacementItem> parseFormatString(StringRef Fmt);
125 
126  static Optional<ReplacementItem> parseReplacementItem(StringRef Spec);
127 
128  std::string str() const {
129  std::string Result;
130  raw_string_ostream Stream(Result);
131  Stream << *this;
132  Stream.flush();
133  return Result;
134  }
135 
136  template <unsigned N> SmallString<N> sstr() const {
137  SmallString<N> Result;
138  raw_svector_ostream Stream(Result);
139  Stream << *this;
140  return Result;
141  }
142 
143  template <unsigned N> operator SmallString<N>() const { return sstr<N>(); }
144 
145  operator std::string() const { return str(); }
146 };
147 
148 template <typename Tuple> class formatv_object : public formatv_object_base {
149  // Storage for the parameter adapters. Since the base class erases the type
150  // of the parameters, we have to own the storage for the parameters here, and
151  // have the base class store type-erased pointers into this tuple.
152  Tuple Parameters;
153 
154 public:
155  formatv_object(StringRef Fmt, Tuple &&Params)
156  : formatv_object_base(Fmt, std::tuple_size<Tuple>::value),
157  Parameters(std::move(Params)) {
158  Adapters = apply_tuple(create_adapters(), Parameters);
159  }
160 
161  formatv_object(formatv_object const &rhs) = delete;
162 
164  : formatv_object_base(std::move(rhs)),
165  Parameters(std::move(rhs.Parameters)) {
166  Adapters = apply_tuple(create_adapters(), Parameters);
167  }
168 };
169 
170 // Format text given a format string and replacement parameters.
171 //
172 // ===General Description===
173 //
174 // Formats textual output. `Fmt` is a string consisting of one or more
175 // replacement sequences with the following grammar:
176 //
177 // rep_field ::= "{" [index] ["," layout] [":" format] "}"
178 // index ::= <non-negative integer>
179 // layout ::= [[[char]loc]width]
180 // format ::= <any string not containing "{" or "}">
181 // char ::= <any character except "{" or "}">
182 // loc ::= "-" | "=" | "+"
183 // width ::= <positive integer>
184 //
185 // index - A non-negative integer specifying the index of the item in the
186 // parameter pack to print. Any other value is invalid.
187 // layout - A string controlling how the field is laid out within the available
188 // space.
189 // format - A type-dependent string used to provide additional options to
190 // the formatting operation. Refer to the documentation of the
191 // various individual format providers for per-type options.
192 // char - The padding character. Defaults to ' ' (space). Only valid if
193 // `loc` is also specified.
194 // loc - Where to print the formatted text within the field. Only valid if
195 // `width` is also specified.
196 // '-' : The field is left aligned within the available space.
197 // '=' : The field is centered within the available space.
198 // '+' : The field is right aligned within the available space (this
199 // is the default).
200 // width - The width of the field within which to print the formatted text.
201 // If this is less than the required length then the `char` and `loc`
202 // fields are ignored, and the field is printed with no leading or
203 // trailing padding. If this is greater than the required length,
204 // then the text is output according to the value of `loc`, and padded
205 // as appropriate on the left and/or right by `char`.
206 //
207 // ===Special Characters===
208 //
209 // The characters '{' and '}' are reserved and cannot appear anywhere within a
210 // replacement sequence. Outside of a replacement sequence, in order to print
211 // a literal '{' or '}' it must be doubled -- "{{" to print a literal '{' and
212 // "}}" to print a literal '}'.
213 //
214 // ===Parameter Indexing===
215 // `index` specifies the index of the parameter in the parameter pack to format
216 // into the output. Note that it is possible to refer to the same parameter
217 // index multiple times in a given format string. This makes it possible to
218 // output the same value multiple times without passing it multiple times to the
219 // function. For example:
220 //
221 // formatv("{0} {1} {0}", "a", "bb")
222 //
223 // would yield the string "abba". This can be convenient when it is expensive
224 // to compute the value of the parameter, and you would otherwise have had to
225 // save it to a temporary.
226 //
227 // ===Formatter Search===
228 //
229 // For a given parameter of type T, the following steps are executed in order
230 // until a match is found:
231 //
232 // 1. If the parameter is of class type, and inherits from format_adapter,
233 // Then format() is invoked on it to produce the formatted output. The
234 // implementation should write the formatted text into `Stream`.
235 // 2. If there is a suitable template specialization of format_provider<>
236 // for type T containing a method whose signature is:
237 // void format(const T &Obj, raw_ostream &Stream, StringRef Options)
238 // Then this method is invoked as described in Step 1.
239 // 3. If an appropriate operator<< for raw_ostream exists, it will be used.
240 // For this to work, (raw_ostream& << const T&) must return raw_ostream&.
241 //
242 // If a match cannot be found through either of the above methods, a compiler
243 // error is generated.
244 //
245 // ===Invalid Format String Handling===
246 //
247 // In the case of a format string which does not match the grammar described
248 // above, the output is undefined. With asserts enabled, LLVM will trigger an
249 // assertion. Otherwise, it will try to do something reasonable, but in general
250 // the details of what that is are undefined.
251 //
252 template <typename... Ts>
253 inline auto formatv(const char *Fmt, Ts &&... Vals) -> formatv_object<decltype(
254  std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...))> {
255  using ParamTuple = decltype(
256  std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
258  Fmt,
259  std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
260 }
261 
262 } // end namespace llvm
263 
264 #endif // LLVM_SUPPORT_FORMATVARIADIC_H
constexpr char Align[]
Key for Kernel::Arg::Metadata::mAlign.
ReplacementItem(StringRef Literal)
This class represents lattice values for constants.
Definition: AllocatorList.h:23
formatv_object_base(StringRef Fmt, std::size_t ParamCount)
A raw_ostream that writes to an SmallVector or SmallString.
Definition: raw_ostream.h:530
auto formatv(const char *Fmt, Ts &&... Vals) -> formatv_object< decltype(std::make_tuple(detail::build_format_adapter(std::forward< Ts >(Vals))...))>
void format(raw_ostream &S, StringRef Options)
Definition: FormatCommon.h:29
Definition: BitVector.h:937
ReplacementType
SmallString< N > sstr() const
std::vector< detail::format_adapter * > Adapters
SmallString - A SmallString is just a SmallVector with methods and accessors that make it work better...
Definition: SmallString.h:25
auto apply_tuple(F &&f, Tuple &&t) -> decltype(detail::apply_tuple_impl(std::forward< F >(f), std::forward< Tuple >(t), std::make_index_sequence< std::tuple_size< typename std::decay< Tuple >::type >::value >
Given an input tuple (a1, a2, ..., an), pass the arguments of the tuple variadically to f as if by ca...
Definition: STLExtras.h:1518
formatv_object(formatv_object &&rhs)
The instances of the Type class are immutable: once they are created, they are never changed...
Definition: Type.h:46
AlignStyle
Definition: FormatCommon.h:17
void format(raw_ostream &S) const
std::vector< ReplacementItem > Replacements
This struct is a compact representation of a valid (non-zero power of two) alignment.
Definition: Alignment.h:40
ReplacementItem(StringRef Spec, size_t Index, size_t Align, AlignStyle Where, char Pad, StringRef Options)
std::vector< detail::format_adapter * > operator()(Ts &... Items)
formatv_object_base(formatv_object_base &&rhs)
formatv_object(StringRef Fmt, Tuple &&Params)
std::enable_if< uses_format_member< T >::value, T >::type build_format_adapter(T &&Item)
A raw_ostream that writes to an std::string.
Definition: raw_ostream.h:503
std::string str() const
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:45
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48