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