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" 32 #include "llvm/Support/FormatCommon.h" 33 #include "llvm/Support/FormatProviders.h" 34 #include "llvm/Support/FormatVariadicDetails.h" 35 #include "llvm/Support/raw_ostream.h" 36 #include <cstddef> 37 #include <string> 38 #include <tuple> 39 #include <utility> 40 #include <vector> 41 42 namespace llvm { 43 44 enum class ReplacementType { Empty, Format, Literal }; 45 46 struct ReplacementItem { 47 ReplacementItem() = default; ReplacementItemReplacementItem48 explicit ReplacementItem(StringRef Literal) 49 : Type(ReplacementType::Literal), Spec(Literal) {} ReplacementItemReplacementItem50 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 55 ReplacementType Type = ReplacementType::Empty; 56 StringRef Spec; 57 size_t Index = 0; 58 size_t Align = 0; 59 AlignStyle Where = AlignStyle::Right; 60 char Pad; 61 StringRef Options; 62 }; 63 64 class formatv_object_base { 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> operatorcreate_adapters75 std::vector<detail::format_adapter *> operator()(Ts &... Items) { 76 return std::vector<detail::format_adapter *>{&Items...}; 77 } 78 }; 79 80 StringRef Fmt; 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: formatv_object_base(StringRef Fmt,std::size_t ParamCount)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 formatv_object_base(formatv_object_base && rhs)98 formatv_object_base(formatv_object_base &&rhs) 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 format(raw_ostream & S)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 str()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 sstr()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 string()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: formatv_object(StringRef Fmt,Tuple && Params)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 formatv_object(formatv_object && rhs)163 formatv_object(formatv_object &&rhs) 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))...)); 257 return formatv_object<ParamTuple>( 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 265