LLVM  13.0.0git
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/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"
37 #include <cstddef>
38 #include <string>
39 #include <tuple>
40 #include <utility>
41 #include <vector>
42 
43 namespace llvm {
44 
46 
48  ReplacementItem() = default;
49  explicit ReplacementItem(StringRef Literal)
52  char Pad, StringRef Options)
55 
58  size_t Index = 0;
59  size_t Align = 0;
61  char Pad = 0;
63 };
64 
66 protected:
69 
70  static bool consumeFieldLayout(StringRef &Spec, AlignStyle &Where,
71  size_t &Align, char &Pad);
72 
73  static std::pair<ReplacementItem, StringRef>
75 
78  : Fmt(Fmt), Adapters(Adapters) {}
79 
80  formatv_object_base(formatv_object_base const &rhs) = delete;
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  }
104 
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 
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))...));
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
llvm
Definition: AllocatorList.h:23
llvm::ReplacementItem::Spec
StringRef Spec
Definition: FormatVariadic.h:57
llvm::formatv_object::formatv_object
formatv_object(StringRef Fmt, Tuple &&Params)
Definition: FormatVariadic.h:151
Optional.h
FormatProviders.h
llvm::formatv_object_base::sstr
SmallString< N > sstr() const
Definition: FormatVariadic.h:115
StringRef.h
llvm::raw_string_ostream
A raw_ostream that writes to an std::string.
Definition: raw_ostream.h:614
llvm::formatv_object_base::consumeFieldLayout
static bool consumeFieldLayout(StringRef &Spec, AlignStyle &Where, size_t &Align, char &Pad)
Definition: FormatVariadic.cpp:27
llvm::ReplacementType
ReplacementType
Definition: FormatVariadic.h:45
llvm::SmallVector
This is a 'vector' (really, a variable-sized array), optimized for the case when the array is small.
Definition: SmallVector.h:1168
llvm::formatv_object_base::str
std::string str() const
Definition: FormatVariadic.h:107
llvm::RISCVFenceField::W
@ W
Definition: RISCVBaseInfo.h:181
llvm::formatv_object_base::parseFormatString
static SmallVector< ReplacementItem, 2 > parseFormatString(StringRef Fmt)
Definition: FormatVariadic.cpp:144
llvm::Type
The instances of the Type class are immutable: once they are created, they are never changed.
Definition: Type.h:46
llvm::Optional
Definition: APInt.h:33
llvm::formatv_object_base::format
void format(raw_ostream &S) const
Definition: FormatVariadic.h:84
llvm::formatv_object
Definition: FormatVariadic.h:127
llvm::apply_tuple
decltype(auto) apply_tuple(F &&f, Tuple &&t)
Given an input tuple (a1, a2, ..., an), pass the arguments of the tuple variadically to f as if by ca...
Definition: STLExtras.h:1917
STLExtras.h
llvm::ReplacementItem::Pad
char Pad
Definition: FormatVariadic.h:61
llvm::detail::build_format_adapter
std::enable_if_t< uses_format_member< T >::value, T > build_format_adapter(T &&Item)
Definition: FormatVariadicDetails.h:131
llvm::formatv_object_base::formatv_object_base
formatv_object_base(StringRef Fmt, ArrayRef< detail::format_adapter * > Adapters)
Definition: FormatVariadic.h:76
llvm::formatv_object::formatv_object
formatv_object(formatv_object &&rhs)
Definition: FormatVariadic.h:159
llvm::formatv
auto formatv(const char *Fmt, Ts &&... Vals) -> formatv_object< decltype(std::make_tuple(detail::build_format_adapter(std::forward< Ts >(Vals))...))>
Definition: FormatVariadic.h:250
SmallString.h
llvm::ReplacementItem::Where
AlignStyle Where
Definition: FormatVariadic.h:60
llvm::ReplacementType::Literal
@ Literal
llvm::AlignStyle
AlignStyle
Definition: FormatCommon.h:17
llvm::ReplacementItem::ReplacementItem
ReplacementItem(StringRef Spec, size_t Index, size_t Align, AlignStyle Where, char Pad, StringRef Options)
Definition: FormatVariadic.h:51
llvm::formatv_object_base::Fmt
StringRef Fmt
Definition: FormatVariadic.h:67
llvm::formatv_object_base::splitLiteralAndReplacement
static std::pair< ReplacementItem, StringRef > splitLiteralAndReplacement(StringRef Fmt)
Definition: FormatVariadic.cpp:93
llvm::raw_ostream
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:50
llvm::raw_ostream::flush
void flush()
Definition: raw_ostream.h:183
Align
uint64_t Align
Definition: ELFObjHandler.cpp:83
llvm::Align
This struct is a compact representation of a valid (non-zero power of two) alignment.
Definition: Alignment.h:39
llvm::SmallString
SmallString - A SmallString is just a SmallVector with methods and accessors that make it work better...
Definition: SmallString.h:25
llvm::ReplacementItem
Definition: FormatVariadic.h:47
llvm::ReplacementItem::Options
StringRef Options
Definition: FormatVariadic.h:62
FormatCommon.h
llvm::ReplacementType::Empty
@ Empty
ArrayRef.h
llvm::ReplacementItem::ReplacementItem
ReplacementItem()=default
llvm::move
OutputIt move(R &&Range, OutputIt Out)
Provide wrappers to std::move which take ranges instead of having to pass begin/end explicitly.
Definition: STLExtras.h:1540
FormatVariadicDetails.h
llvm::ArrayRef
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory),...
Definition: APInt.h:32
llvm::StringRef
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:57
S
add sub stmia L5 ldr r0 bl L_printf $stub Instead of a and a wouldn t it be better to do three moves *Return an aggregate type is even return S
Definition: README.txt:210
std
Definition: BitVector.h:838
llvm::ReplacementType::Format
@ Format
llvm::ReplacementItem::Index
size_t Index
Definition: FormatVariadic.h:58
llvm::formatv_object_base::parseReplacementItem
static Optional< ReplacementItem > parseReplacementItem(StringRef Spec)
Definition: FormatVariadic.cpp:58
llvm::ReplacementItem::ReplacementItem
ReplacementItem(StringRef Literal)
Definition: FormatVariadic.h:49
llvm::raw_svector_ostream
A raw_ostream that writes to an SmallVector or SmallString.
Definition: raw_ostream.h:647
llvm::FmtAlign
Definition: FormatCommon.h:19
llvm::formatv_object_base
Definition: FormatVariadic.h:65
llvm::AlignStyle::Right
@ Right
raw_ostream.h
llvm::formatv_object_base::Adapters
ArrayRef< detail::format_adapter * > Adapters
Definition: FormatVariadic.h:68