FormatVariadic.h revision 360784
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 42namespace llvm { 43 44enum class ReplacementType { Empty, Format, Literal }; 45 46struct ReplacementItem { 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 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 = 0; 61 StringRef Options; 62}; 63 64class formatv_object_base { 65protected: 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 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 90public: 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 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 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 148template <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 154public: 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 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// 252template <typename... Ts> 253inline 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