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" 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 43 namespace llvm { 44 45 enum class ReplacementType { Empty, Format, Literal }; 46 47 struct 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 = 0; 62 StringRef Options; 63 }; 64 65 class formatv_object_base { 66 protected: 67 StringRef Fmt; 68 ArrayRef<detail::format_adapter *> Adapters; 69 70 static bool consumeFieldLayout(StringRef &Spec, AlignStyle &Where, 71 size_t &Align, char &Pad); 72 73 static std::pair<ReplacementItem, StringRef> 74 splitLiteralAndReplacement(StringRef Fmt); 75 76 formatv_object_base(StringRef Fmt, 77 ArrayRef<detail::format_adapter *> Adapters) 78 : Fmt(Fmt), Adapters(Adapters) {} 79 80 formatv_object_base(formatv_object_base const &rhs) = delete; 81 formatv_object_base(formatv_object_base &&rhs) = default; 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 } 103 static SmallVector<ReplacementItem, 2> parseFormatString(StringRef Fmt); 104 105 static Optional<ReplacementItem> parseReplacementItem(StringRef Spec); 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 159 formatv_object(formatv_object &&rhs) 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 '{' or '}' it must be doubled -- "{{" to print a literal '{' and 209 // "}}" to print a literal '}'. 210 // 211 // ===Parameter Indexing=== 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))...)); 254 return formatv_object<ParamTuple>( 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 262