include/llvm/Support/Format.h

   1 //===- Format.h - Efficient printf-style formatting for streams -*- 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 format() function, which can be used with other
  10 // LLVM subsystems to provide printf-style formatting.  This gives all the power
  11 // and risk of printf.  This can be used like this (with raw_ostreams as an
  12 // example):
  13 //
  14 //    OS << "mynumber: " << format("%4.5f", 1234.412) << '\n';
  15 //
  16 // Or if you prefer:
  17 //
  18 //  OS << format("mynumber: %4.5f\n", 1234.412);
  19 //
  20 //===----------------------------------------------------------------------===//
  21
  22 #ifndef LLVM_SUPPORT_FORMAT_H
  23 #define LLVM_SUPPORT_FORMAT_H
  24
  25 #include "llvm/ADT/ArrayRef.h"
  26 #include "llvm/ADT/STLExtras.h"
  27 #include "llvm/ADT/StringRef.h"
  28 #include "llvm/Support/DataTypes.h"
  29 #include <cassert>
  30 #include <cstdio>
  31 #include <tuple>
  32
  33 namespace llvm {
  34
  35 /// This is a helper class used for handling formatted output.  It is the
  36 /// abstract base class of a templated derived class.
  37 class format_object_base {
  38 protected:
  39   const char *Fmt;
  40   ~format_object_base() = default; // Disallow polymorphic deletion.
  41   format_object_base(const format_object_base &) = default;
  42   virtual void home(); // Out of line virtual method.
  43
  44   /// Call snprintf() for this object, on the given buffer and size.
  45   virtual int snprint(char *Buffer, unsigned BufferSize) const = 0;
  46
  47 public:
  48   format_object_base(const char *fmt) : Fmt(fmt) {}
  49
  50   /// Format the object into the specified buffer.  On success, this returns
  51   /// the length of the formatted string.  If the buffer is too small, this
  52   /// returns a length to retry with, which will be larger than BufferSize.
  53   unsigned print(char *Buffer, unsigned BufferSize) const {
  54     assert(BufferSize && "Invalid buffer size!");
  55
  56     // Print the string, leaving room for the terminating null.
  57     int N = snprint(Buffer, BufferSize);
  58
  59     // VC++ and old GlibC return negative on overflow, just double the size.
  60     if (N < 0)
  61       return BufferSize * 2;
  62
  63     // Other implementations yield number of bytes needed, not including the
  64     // final '\0'.
  65     if (unsigned(N) >= BufferSize)
  66       return N + 1;
  67
  68     // Otherwise N is the length of output (not including the final '\0').
  69     return N;
  70   }
  71 };
  72
  73 /// These are templated helper classes used by the format function that
  74 /// capture the object to be formatted and the format string. When actually
  75 /// printed, this synthesizes the string into a temporary buffer provided and
  76 /// returns whether or not it is big enough.
  77
  78 // Helper to validate that format() parameters are scalars or pointers.
  79 template <typename... Args> struct validate_format_parameters;
  80 template <typename Arg, typename... Args>
  81 struct validate_format_parameters<Arg, Args...> {
  82   static_assert(std::is_scalar<Arg>::value,
  83                 "format can't be used with non fundamental / non pointer type");
  84   validate_format_parameters() { validate_format_parameters<Args...>(); }
  85 };
  86 template <> struct validate_format_parameters<> {};
  87
  88 template <typename... Ts>
  89 class format_object final : public format_object_base {
  90   std::tuple<Ts...> Vals;
  91
  92   template <std::size_t... Is>
  93   int snprint_tuple(char *Buffer, unsigned BufferSize,
  94                     index_sequence<Is...>) const {
  95 #ifdef _MSC_VER
  96     return _snprintf(Buffer, BufferSize, Fmt, std::get<Is>(Vals)...);
  97 #else
  98     return snprintf(Buffer, BufferSize, Fmt, std::get<Is>(Vals)...);
  99 #endif
 100   }
 101
 102 public:
 103   format_object(const char *fmt, const Ts &... vals)
 104       : format_object_base(fmt), Vals(vals...) {
 105     validate_format_parameters<Ts...>();
 106   }
 107
 108   int snprint(char *Buffer, unsigned BufferSize) const override {
 109     return snprint_tuple(Buffer, BufferSize, index_sequence_for<Ts...>());
 110   }
 111 };
 112
 113 /// These are helper functions used to produce formatted output.  They use
 114 /// template type deduction to construct the appropriate instance of the
 115 /// format_object class to simplify their construction.
 116 ///
 117 /// This is typically used like:
 118 /// \code
 119 ///   OS << format("%0.4f", myfloat) << '\n';
 120 /// \endcode
 121
 122 template <typename... Ts>
 123 inline format_object<Ts...> format(const char *Fmt, const Ts &... Vals) {
 124   return format_object<Ts...>(Fmt, Vals...);
 125 }
 126
 127 /// This is a helper class for left_justify, right_justify, and center_justify.
 128 class FormattedString {
 129 public:
 130   enum Justification { JustifyNone, JustifyLeft, JustifyRight, JustifyCenter };
 131   FormattedString(StringRef S, unsigned W, Justification J)
 132       : Str(S), Width(W), Justify(J) {}
 133
 134 private:
 135   StringRef Str;
 136   unsigned Width;
 137   Justification Justify;
 138   friend class raw_ostream;
 139 };
 140
 141 /// left_justify - append spaces after string so total output is
 142 /// \p Width characters.  If \p Str is larger that \p Width, full string
 143 /// is written with no padding.
 144 inline FormattedString left_justify(StringRef Str, unsigned Width) {
 145   return FormattedString(Str, Width, FormattedString::JustifyLeft);
 146 }
 147
 148 /// right_justify - add spaces before string so total output is
 149 /// \p Width characters.  If \p Str is larger that \p Width, full string
 150 /// is written with no padding.
 151 inline FormattedString right_justify(StringRef Str, unsigned Width) {
 152   return FormattedString(Str, Width, FormattedString::JustifyRight);
 153 }
 154
 155 /// center_justify - add spaces before and after string so total output is
 156 /// \p Width characters.  If \p Str is larger that \p Width, full string
 157 /// is written with no padding.
 158 inline FormattedString center_justify(StringRef Str, unsigned Width) {
 159   return FormattedString(Str, Width, FormattedString::JustifyCenter);
 160 }
 161
 162 /// This is a helper class used for format_hex() and format_decimal().
 163 class FormattedNumber {
 164   uint64_t HexValue;
 165   int64_t DecValue;
 166   unsigned Width;
 167   bool Hex;
 168   bool Upper;
 169   bool HexPrefix;
 170   friend class raw_ostream;
 171
 172 public:
 173   FormattedNumber(uint64_t HV, int64_t DV, unsigned W, bool H, bool U,
 174                   bool Prefix)
 175       : HexValue(HV), DecValue(DV), Width(W), Hex(H), Upper(U),
 176         HexPrefix(Prefix) {}
 177 };
 178
 179 /// format_hex - Output \p N as a fixed width hexadecimal. If number will not
 180 /// fit in width, full number is still printed.  Examples:
 181 ///   OS << format_hex(255, 4)              => 0xff
 182 ///   OS << format_hex(255, 4, true)        => 0xFF
 183 ///   OS << format_hex(255, 6)              => 0x00ff
 184 ///   OS << format_hex(255, 2)              => 0xff
 185 inline FormattedNumber format_hex(uint64_t N, unsigned Width,
 186                                   bool Upper = false) {
 187   assert(Width <= 18 && "hex width must be <= 18");
 188   return FormattedNumber(N, 0, Width, true, Upper, true);
 189 }
 190
 191 /// format_hex_no_prefix - Output \p N as a fixed width hexadecimal. Does not
 192 /// prepend '0x' to the outputted string.  If number will not fit in width,
 193 /// full number is still printed.  Examples:
 194 ///   OS << format_hex_no_prefix(255, 2)              => ff
 195 ///   OS << format_hex_no_prefix(255, 2, true)        => FF
 196 ///   OS << format_hex_no_prefix(255, 4)              => 00ff
 197 ///   OS << format_hex_no_prefix(255, 1)              => ff
 198 inline FormattedNumber format_hex_no_prefix(uint64_t N, unsigned Width,
 199                                             bool Upper = false) {
 200   assert(Width <= 16 && "hex width must be <= 16");
 201   return FormattedNumber(N, 0, Width, true, Upper, false);
 202 }
 203
 204 /// format_decimal - Output \p N as a right justified, fixed-width decimal. If
 205 /// number will not fit in width, full number is still printed.  Examples:
 206 ///   OS << format_decimal(0, 5)     => "    0"
 207 ///   OS << format_decimal(255, 5)   => "  255"
 208 ///   OS << format_decimal(-1, 3)    => " -1"
 209 ///   OS << format_decimal(12345, 3) => "12345"
 210 inline FormattedNumber format_decimal(int64_t N, unsigned Width) {
 211   return FormattedNumber(0, N, Width, false, false, false);
 212 }
 213
 214 class FormattedBytes {
 215   ArrayRef<uint8_t> Bytes;
 216
 217   // If not None, display offsets for each line relative to starting value.
 218   Optional<uint64_t> FirstByteOffset;
 219   uint32_t IndentLevel;  // Number of characters to indent each line.
 220   uint32_t NumPerLine;   // Number of bytes to show per line.
 221   uint8_t ByteGroupSize; // How many hex bytes are grouped without spaces
 222   bool Upper;            // Show offset and hex bytes as upper case.
 223   bool ASCII;            // Show the ASCII bytes for the hex bytes to the right.
 224   friend class raw_ostream;
 225
 226 public:
 227   FormattedBytes(ArrayRef<uint8_t> B, uint32_t IL, Optional<uint64_t> O,
 228                  uint32_t NPL, uint8_t BGS, bool U, bool A)
 229       : Bytes(B), FirstByteOffset(O), IndentLevel(IL), NumPerLine(NPL),
 230         ByteGroupSize(BGS), Upper(U), ASCII(A) {
 231
 232     if (ByteGroupSize > NumPerLine)
 233       ByteGroupSize = NumPerLine;
 234   }
 235 };
 236
 237 inline FormattedBytes
 238 format_bytes(ArrayRef<uint8_t> Bytes, Optional<uint64_t> FirstByteOffset = None,
 239              uint32_t NumPerLine = 16, uint8_t ByteGroupSize = 4,
 240              uint32_t IndentLevel = 0, bool Upper = false) {
 241   return FormattedBytes(Bytes, IndentLevel, FirstByteOffset, NumPerLine,
 242                         ByteGroupSize, Upper, false);
 243 }
 244
 245 inline FormattedBytes
 246 format_bytes_with_ascii(ArrayRef<uint8_t> Bytes,
 247                         Optional<uint64_t> FirstByteOffset = None,
 248                         uint32_t NumPerLine = 16, uint8_t ByteGroupSize = 4,
 249                         uint32_t IndentLevel = 0, bool Upper = false) {
 250   return FormattedBytes(Bytes, IndentLevel, FirstByteOffset, NumPerLine,
 251                         ByteGroupSize, Upper, true);
 252 }
 253
 254 } // end namespace llvm
 255
 256 #endif