LCOV - code coverage report
Current view: top level - include/llvm/Support - FormatVariadic.h (source / functions) Hit Total Coverage
Test: llvm-toolchain.info Lines: 438 499 87.8 %
Date: 2018-10-20 13:21:21 Functions: 239 607 39.4 %
Legend: Lines: hit not hit

          Line data    Source code
       1             : //===- FormatVariadic.h - Efficient type-safe string formatting --*- C++-*-===//
       2             : //
       3             : //                     The LLVM Compiler Infrastructure
       4             : //
       5             : // This file is distributed under the University of Illinois Open Source
       6             : // License. See LICENSE.TXT for details.
       7             : //
       8             : //===----------------------------------------------------------------------===//
       9             : //
      10             : // This file implements the formatv() function which can be used with other LLVM
      11             : // subsystems to provide printf-like formatting, but with improved safety and
      12             : // flexibility.  The result of `formatv` is an object which can be streamed to
      13             : // a raw_ostream or converted to a std::string or llvm::SmallString.
      14             : //
      15             : //   // Convert to std::string.
      16             : //   std::string S = formatv("{0} {1}", 1234.412, "test").str();
      17             : //
      18             : //   // Convert to llvm::SmallString
      19             : //   SmallString<8> S = formatv("{0} {1}", 1234.412, "test").sstr<8>();
      20             : //
      21             : //   // Stream to an existing raw_ostream.
      22             : //   OS << formatv("{0} {1}", 1234.412, "test");
      23             : //
      24             : //===----------------------------------------------------------------------===//
      25             : 
      26             : #ifndef LLVM_SUPPORT_FORMATVARIADIC_H
      27             : #define LLVM_SUPPORT_FORMATVARIADIC_H
      28             : 
      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      175390 :   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;
      62             :   StringRef Options;
      63             : };
      64             : 
      65             : class formatv_object_base {
      66             : protected:
      67             :   // The parameters are stored in a std::tuple, which does not provide runtime
      68             :   // indexing capabilities.  In order to enable runtime indexing, we use this
      69             :   // structure to put the parameters into a std::vector.  Since the parameters
      70             :   // are not all the same type, we use some type-erasure by wrapping the
      71             :   // parameters in a template class that derives from a non-template superclass.
      72             :   // Essentially, we are converting a std::tuple<Derived<Ts...>> to a
      73             :   // std::vector<Base*>.
      74             :   struct create_adapters {
      75             :     template <typename... Ts>
      76           0 :     std::vector<detail::format_adapter *> operator()(Ts &... Items) {
      77       87237 :       return std::vector<detail::format_adapter *>{&Items...};
      78             :     }
      79           0 :   };
      80           0 : 
      81             :   StringRef Fmt;
      82           0 :   std::vector<detail::format_adapter *> Adapters;
      83           0 :   std::vector<ReplacementItem> Replacements;
      84             : 
      85           0 :   static bool consumeFieldLayout(StringRef &Spec, AlignStyle &Where,
      86           0 :                                  size_t &Align, char &Pad);
      87             : 
      88           0 :   static std::pair<ReplacementItem, StringRef>
      89           0 :   splitLiteralAndReplacement(StringRef Fmt);
      90             : 
      91           0 : public:
      92        6329 :   formatv_object_base(StringRef Fmt, std::size_t ParamCount)
      93       12658 :       : Fmt(Fmt), Replacements(parseFormatString(Fmt)) {
      94        6329 :     Adapters.reserve(ParamCount);
      95        6329 :   }
      96             : 
      97           0 :   formatv_object_base(formatv_object_base const &rhs) = delete;
      98        8524 : 
      99       17048 :   formatv_object_base(formatv_object_base &&rhs)
     100        8524 :       : Fmt(std::move(rhs.Fmt)),
     101       61513 :         Adapters(), // Adapters are initialized by formatv_object
     102      105978 :         Replacements(std::move(rhs.Replacements)) {
     103       52989 :     Adapters.reserve(rhs.Adapters.size());
     104       54908 :   };
     105        3838 : 
     106       89035 :   void format(raw_ostream &S) const {
     107      298761 :     for (auto &R : Replacements) {
     108      210066 :       if (R.Type == ReplacementType::Empty)
     109       94461 :         continue;
     110      210095 :       if (R.Type == ReplacementType::Literal) {
     111       94854 :         S << R.Spec;
     112       94485 :         continue;
     113        1028 :       }
     114      231858 :       if (R.Index >= Adapters.size()) {
     115         664 :         S << R.Spec;
     116         664 :         continue;
     117             :       }
     118           0 : 
     119      115291 :       auto W = Adapters[R.Index];
     120          52 : 
     121      115291 :       FmtAlign Align(*W, R.Where, R.Align, R.Pad);
     122      115291 :       Align.format(S, R.Options);
     123             :     }
     124       87116 :   }
     125        5318 :   static std::vector<ReplacementItem> parseFormatString(StringRef Fmt);
     126       10636 : 
     127        5318 :   static Optional<ReplacementItem> parseReplacementItem(StringRef Spec);
     128        5318 : 
     129        5359 :   std::string str() const {
     130           0 :     std::string Result;
     131        6164 :     raw_string_ostream Stream(Result);
     132        6969 :     Stream << *this;
     133         805 :     Stream.flush();
     134        6197 :     return Result;
     135         136 :   }
     136          33 : 
     137         194 :   template <unsigned N> SmallString<N> sstr() const {
     138          77 :     SmallString<N> Result;
     139          91 :     raw_svector_ostream Stream(Result);
     140         168 :     Stream << *this;
     141         149 :     return Result;
     142           0 :   }
     143          58 : 
     144          51 :   template <unsigned N> operator SmallString<N>() const { return sstr<N>(); }
     145           0 : 
     146        4285 :   operator std::string() const { return str(); }
     147         115 : };
     148         666 : 
     149        7171 : template <typename Tuple> class formatv_object : public formatv_object_base {
     150        1054 :   // Storage for the parameter adapters.  Since the base class erases the type
     151          61 :   // of the parameters, we have to own the storage for the parameters here, and
     152         449 :   // have the base class store type-erased pointers into this tuple.
     153         349 :   Tuple Parameters;
     154           0 : 
     155        8847 : public:
     156        6500 :   formatv_object(StringRef Fmt, Tuple &&Params)
     157          50 :       : formatv_object_base(Fmt, std::tuple_size<Tuple>::value),
     158       59502 :         Parameters(std::move(Params)) {
     159        6550 :     Adapters = apply_tuple(create_adapters(), Parameters);
     160        6329 :   }
     161        1899 : 
     162        8531 :   formatv_object(formatv_object const &rhs) = delete;
     163          11 : 
     164        9011 :   formatv_object(formatv_object &&rhs)
     165       61629 :       : formatv_object_base(std::move(rhs)),
     166        8573 :         Parameters(std::move(rhs.Parameters)) {
     167       60638 :     Adapters = apply_tuple(create_adapters(), Parameters);
     168       54857 :   }
     169       60028 : };
     170       15515 : 
     171        9237 : // Format text given a format string and replacement parameters.
     172        9503 : //
     173        7263 : // ===General Description===
     174        8354 : //
     175       21237 : // Formats textual output.  `Fmt` is a string consisting of one or more
     176        2601 : // replacement sequences with the following grammar:
     177       20440 : //
     178       19244 : // rep_field ::= "{" [index] ["," layout] [":" format] "}"
     179       19504 : // index     ::= <non-negative integer>
     180       29012 : // layout    ::= [[[char]loc]width]
     181         945 : // format    ::= <any string not containing "{" or "}">
     182       33782 : // char      ::= <any character except "{" or "}">
     183       28882 : // loc       ::= "-" | "=" | "+"
     184       28213 : // width     ::= <positive integer>
     185         626 : //
     186         902 : // index   - A non-negative integer specifying the index of the item in the
     187         665 : //           parameter pack to print.  Any other value is invalid.
     188        1649 : // layout  - A string controlling how the field is laid out within the available
     189        5802 : //           space.
     190         806 : // format  - A type-dependent string used to provide additional options to
     191        5901 : //           the formatting operation.  Refer to the documentation of the
     192        6048 : //           various individual format providers for per-type options.
     193        5413 : // char    - The padding character.  Defaults to ' ' (space).  Only valid if
     194         440 : //           `loc` is also specified.
     195         994 : // loc     - Where to print the formatted text within the field.  Only valid if
     196         440 : //           `width` is also specified.
     197        1076 : //           '-' : The field is left aligned within the available space.
     198        1100 : //           '=' : The field is centered within the available space.
     199         883 : //           '+' : The field is right aligned within the available space (this
     200          59 : //                 is the default).
     201         108 : // width   - The width of the field within which to print the formatted text.
     202         388 : //           If this is less than the required length then the `char` and `loc`
     203          88 : //           fields are ignored, and the field is printed with no leading or
     204         336 : //           trailing padding.  If this is greater than the required length,
     205         416 : //           then the text is output according to the value of `loc`, and padded
     206         480 : //           as appropriate on the left and/or right by `char`.
     207         685 : //
     208         370 : // ===Special Characters===
     209         476 : //
     210         192 : // The characters '{' and '}' are reserved and cannot appear anywhere within a
     211         191 : // replacement sequence.  Outside of a replacement sequence, in order to print
     212        1621 : // a literal '{' or '}' it must be doubled -- "{{" to print a literal '{' and
     213        3229 : // "}}" to print a literal '}'.
     214        1608 : //
     215        3113 : // ===Parameter Indexing===
     216        3012 : // `index` specifies the index of the parameter in the parameter pack to format
     217        1529 : // into the output.  Note that it is possible to refer to the same parameter
     218        1502 : // index multiple times in a given format string.  This makes it possible to
     219          32 : // output the same value multiple times without passing it multiple times to the
     220          22 : // function. For example:
     221          78 : //
     222          52 : //   formatv("{0} {1} {0}", "a", "bb")
     223          52 : //
     224          51 : // would yield the string "abba".  This can be convenient when it is expensive
     225           5 : // to compute the value of the parameter, and you would otherwise have had to
     226          31 : // save it to a temporary.
     227          35 : //
     228          89 : // ===Formatter Search===
     229           4 : //
     230          55 : // For a given parameter of type T, the following steps are executed in order
     231          55 : // until a match is found:
     232          55 : //
     233           1 : //   1. If the parameter is of class type, and inherits from format_adapter,
     234           4 : //      Then format() is invoked on it to produce the formatted output.  The
     235           1 : //      implementation should write the formatted text into `Stream`.
     236           5 : //   2. If there is a suitable template specialization of format_provider<>
     237           5 : //      for type T containing a method whose signature is:
     238           7 : //      void format(const T &Obj, raw_ostream &Stream, StringRef Options)
     239           5 : //      Then this method is invoked as described in Step 1.
     240         321 : //   3. If an appropriate operator<< for raw_ostream exists, it will be used.
     241           8 : //      For this to work, (raw_ostream& << const T&) must return raw_ostream&.
     242         326 : //
     243         341 : // If a match cannot be found through either of the above methods, a compiler
     244        5329 : // error is generated.
     245         149 : //
     246        5029 : // ===Invalid Format String Handling===
     247        5153 : //
     248        5150 : // In the case of a format string which does not match the grammar described
     249         131 : // above, the output is undefined.  With asserts enabled, LLVM will trigger an
     250         171 : // assertion.  Otherwise, it will try to do something reasonable, but in general
     251           2 : // the details of what that is are undefined.
     252         551 : //
     253         173 : template <typename... Ts>
     254        2582 : inline auto formatv(const char *Fmt, Ts &&... Vals) -> formatv_object<decltype(
     255         383 :     std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...))> {
     256           2 :   using ParamTuple = decltype(
     257        7446 :       std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
     258       14130 :   return formatv_object<ParamTuple>(
     259        7064 :       Fmt,
     260       12702 :       std::make_tuple(detail::build_format_adapter(std::forward<Ts>(Vals))...));
     261           1 : }
     262           1 : 
     263         159 : } // end namespace llvm
     264           0 : 
     265           1 : #endif // LLVM_SUPPORT_FORMATVARIADIC_H

Generated by: LCOV version 1.13