LLVM  9.0.0svn
Format.h
Go to the documentation of this file.
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.
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>
82  static_assert(std::is_scalar<Arg>::value,
83  "format can't be used with non fundamental / non pointer type");
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...) {
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.
129 public:
130  enum Justification { JustifyNone, JustifyLeft, JustifyRight, JustifyCenter };
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.
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.
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.
160 }
161 
162 /// This is a helper class used for format_hex() and format_decimal().
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 
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:
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
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
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
format_object(const char *fmt, const Ts &... vals)
Definition: Format.h:103
FormattedString left_justify(StringRef Str, unsigned Width)
left_justify - append spaces after string so total output is Width characters.
Definition: Format.h:144
These are templated helper classes used by the format function that capture the object to be formatte...
Definition: Format.h:79
This class represents lattice values for constants.
Definition: AllocatorList.h:23
FormattedNumber format_hex(uint64_t N, unsigned Width, bool Upper=false)
format_hex - Output N as a fixed width hexadecimal.
Definition: Format.h:185
format_object< Ts... > format(const char *Fmt, const Ts &... Vals)
These are helper functions used to produce formatted output.
Definition: Format.h:123
const char * Fmt
Definition: Format.h:39
FormattedBytes format_bytes_with_ascii(ArrayRef< uint8_t > Bytes, Optional< uint64_t > FirstByteOffset=None, uint32_t NumPerLine=16, uint8_t ByteGroupSize=4, uint32_t IndentLevel=0, bool Upper=false)
Definition: Format.h:246
virtual int snprint(char *Buffer, unsigned BufferSize) const =0
Call snprintf() for this object, on the given buffer and size.
This is a helper class for left_justify, right_justify, and center_justify.
Definition: Format.h:128
FormattedBytes format_bytes(ArrayRef< uint8_t > Bytes, Optional< uint64_t > FirstByteOffset=None, uint32_t NumPerLine=16, uint8_t ByteGroupSize=4, uint32_t IndentLevel=0, bool Upper=false)
Definition: Format.h:238
FormattedString center_justify(StringRef Str, unsigned Width)
center_justify - add spaces before and after string so total output is Width characters.
Definition: Format.h:158
Alias for the common case of a sequence of size_ts.
Definition: STLExtras.h:533
This is a helper class used for handling formatted output.
Definition: Format.h:37
FormattedString right_justify(StringRef Str, unsigned Width)
right_justify - add spaces before string so total output is Width characters.
Definition: Format.h:151
static GCRegistry::Add< OcamlGC > B("ocaml", "ocaml 3.10-compatible GC")
#define H(x, y, z)
Definition: MD5.cpp:57
amdgpu Simplify well known AMD library false FunctionCallee Value * Arg
FormattedString(StringRef S, unsigned W, Justification J)
Definition: Format.h:131
This is a helper class used for format_hex() and format_decimal().
Definition: Format.h:163
FormattedNumber(uint64_t HV, int64_t DV, unsigned W, bool H, bool U, bool Prefix)
Definition: Format.h:173
Creates a compile-time integer sequence for a parameter pack.
Definition: STLExtras.h:535
format_object_base(const char *fmt)
Definition: Format.h:48
FormattedNumber format_decimal(int64_t N, unsigned Width)
format_decimal - Output N as a right justified, fixed-width decimal.
Definition: Format.h:210
FormattedNumber format_hex_no_prefix(uint64_t N, unsigned Width, bool Upper=false)
format_hex_no_prefix - Output N as a fixed width hexadecimal.
Definition: Format.h:198
#define N
static GCRegistry::Add< ErlangGC > A("erlang", "erlang-compatible garbage collector")
FormattedBytes(ArrayRef< uint8_t > B, uint32_t IL, Optional< uint64_t > O, uint32_t NPL, uint8_t BGS, bool U, bool A)
Definition: Format.h:227
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
format_object_base(const format_object_base &)=default
unsigned print(char *Buffer, unsigned BufferSize) const
Format the object into the specified buffer.
Definition: Format.h:53
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:45
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48
constexpr char Args[]
Key for Kernel::Metadata::mArgs.
int snprint(char *Buffer, unsigned BufferSize) const override
Call snprintf() for this object, on the given buffer and size.
Definition: Format.h:108