include/llvm/Support/FormatVariadic.h

   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;
  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;
  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>
  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
  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
  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
 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
 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