LLVM API Documentation

Format.h
Go to the documentation of this file.
00001 //===- Format.h - Efficient printf-style formatting for streams -*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file implements the format() function, which can be used with other
00011 // LLVM subsystems to provide printf-style formatting.  This gives all the power
00012 // and risk of printf.  This can be used like this (with raw_ostreams as an
00013 // example):
00014 //
00015 //    OS << "mynumber: " << format("%4.5f", 1234.412) << '\n';
00016 //
00017 // Or if you prefer:
00018 //
00019 //  OS << format("mynumber: %4.5f\n", 1234.412);
00020 //
00021 //===----------------------------------------------------------------------===//
00022 
00023 #ifndef LLVM_SUPPORT_FORMAT_H
00024 #define LLVM_SUPPORT_FORMAT_H
00025 
00026 #include "llvm/ADT/StringRef.h"
00027 #include "llvm/Support/DataTypes.h"
00028 
00029 #include <cassert>
00030 #include <cstdio>
00031 #ifdef _MSC_VER
00032 // FIXME: This define is wrong:
00033 //  - _snprintf does not guarantee that trailing null is always added - if
00034 //    there is no space for null, it does not report any error.
00035 //  - According to C++ standard, snprintf should be visible in the 'std' 
00036 //    namespace - this define makes this impossible.
00037 #define snprintf _snprintf
00038 #endif
00039 
00040 namespace llvm {
00041 
00042 /// This is a helper class used for handling formatted output.  It is the
00043 /// abstract base class of a templated derived class.
00044 class format_object_base {
00045 protected:
00046   const char *Fmt;
00047   ~format_object_base() {} // Disallow polymorphic deletion.
00048   virtual void home(); // Out of line virtual method.
00049 
00050   /// Call snprintf() for this object, on the given buffer and size.
00051   virtual int snprint(char *Buffer, unsigned BufferSize) const = 0;
00052 
00053 public:
00054   format_object_base(const char *fmt) : Fmt(fmt) {}
00055 
00056   /// Format the object into the specified buffer.  On success, this returns
00057   /// the length of the formatted string.  If the buffer is too small, this
00058   /// returns a length to retry with, which will be larger than BufferSize.
00059   unsigned print(char *Buffer, unsigned BufferSize) const {
00060     assert(BufferSize && "Invalid buffer size!");
00061 
00062     // Print the string, leaving room for the terminating null.
00063     int N = snprint(Buffer, BufferSize);
00064 
00065     // VC++ and old GlibC return negative on overflow, just double the size.
00066     if (N < 0)
00067       return BufferSize * 2;
00068 
00069     // Other implementations yield number of bytes needed, not including the
00070     // final '\0'.
00071     if (unsigned(N) >= BufferSize)
00072       return N + 1;
00073 
00074     // Otherwise N is the length of output (not including the final '\0').
00075     return N;
00076   }
00077 };
00078 
00079 /// These are templated helper classes used by the format function that
00080 /// capture the object to be formated and the format string. When actually
00081 /// printed, this synthesizes the string into a temporary buffer provided and
00082 /// returns whether or not it is big enough.
00083 
00084 template <typename T>
00085 class format_object1 final : public format_object_base {
00086   T Val;
00087 public:
00088   format_object1(const char *fmt, const T &val)
00089     : format_object_base(fmt), Val(val) {
00090   }
00091 
00092   int snprint(char *Buffer, unsigned BufferSize) const override {
00093     return snprintf(Buffer, BufferSize, Fmt, Val);
00094   }
00095 };
00096 
00097 template <typename T1, typename T2>
00098 class format_object2 final : public format_object_base {
00099   T1 Val1;
00100   T2 Val2;
00101 public:
00102   format_object2(const char *fmt, const T1 &val1, const T2 &val2)
00103   : format_object_base(fmt), Val1(val1), Val2(val2) {
00104   }
00105 
00106   int snprint(char *Buffer, unsigned BufferSize) const override {
00107     return snprintf(Buffer, BufferSize, Fmt, Val1, Val2);
00108   }
00109 };
00110 
00111 template <typename T1, typename T2, typename T3>
00112 class format_object3 final : public format_object_base {
00113   T1 Val1;
00114   T2 Val2;
00115   T3 Val3;
00116 public:
00117   format_object3(const char *fmt, const T1 &val1, const T2 &val2,const T3 &val3)
00118     : format_object_base(fmt), Val1(val1), Val2(val2), Val3(val3) {
00119   }
00120 
00121   int snprint(char *Buffer, unsigned BufferSize) const override {
00122     return snprintf(Buffer, BufferSize, Fmt, Val1, Val2, Val3);
00123   }
00124 };
00125 
00126 template <typename T1, typename T2, typename T3, typename T4>
00127 class format_object4 final : public format_object_base {
00128   T1 Val1;
00129   T2 Val2;
00130   T3 Val3;
00131   T4 Val4;
00132 public:
00133   format_object4(const char *fmt, const T1 &val1, const T2 &val2,
00134                  const T3 &val3, const T4 &val4)
00135     : format_object_base(fmt), Val1(val1), Val2(val2), Val3(val3), Val4(val4) {
00136   }
00137 
00138   int snprint(char *Buffer, unsigned BufferSize) const override {
00139     return snprintf(Buffer, BufferSize, Fmt, Val1, Val2, Val3, Val4);
00140   }
00141 };
00142 
00143 template <typename T1, typename T2, typename T3, typename T4, typename T5>
00144 class format_object5 final : public format_object_base {
00145   T1 Val1;
00146   T2 Val2;
00147   T3 Val3;
00148   T4 Val4;
00149   T5 Val5;
00150 public:
00151   format_object5(const char *fmt, const T1 &val1, const T2 &val2,
00152                  const T3 &val3, const T4 &val4, const T5 &val5)
00153     : format_object_base(fmt), Val1(val1), Val2(val2), Val3(val3), Val4(val4),
00154       Val5(val5) {
00155   }
00156 
00157   int snprint(char *Buffer, unsigned BufferSize) const override {
00158     return snprintf(Buffer, BufferSize, Fmt, Val1, Val2, Val3, Val4, Val5);
00159   }
00160 };
00161 
00162 template <typename T1, typename T2, typename T3, typename T4, typename T5,
00163           typename T6>
00164 class format_object6 final : public format_object_base {
00165   T1 Val1;
00166   T2 Val2;
00167   T3 Val3;
00168   T4 Val4;
00169   T5 Val5;
00170   T6 Val6;
00171 public:
00172   format_object6(const char *Fmt, const T1 &Val1, const T2 &Val2,
00173                  const T3 &Val3, const T4 &Val4, const T5 &Val5, const T6 &Val6)
00174     : format_object_base(Fmt), Val1(Val1), Val2(Val2), Val3(Val3), Val4(Val4),
00175       Val5(Val5), Val6(Val6) { }
00176 
00177   int snprint(char *Buffer, unsigned BufferSize) const override {
00178     return snprintf(Buffer, BufferSize, Fmt, Val1, Val2, Val3, Val4, Val5, Val6);
00179   }
00180 };
00181 
00182 /// These are helper functions used to produce formatted output.  They use
00183 /// template type deduction to construct the appropriate instance of the
00184 /// format_object class to simplify their construction.
00185 ///
00186 /// This is typically used like:
00187 /// \code
00188 ///   OS << format("%0.4f", myfloat) << '\n';
00189 /// \endcode
00190 
00191 template <typename T>
00192 inline format_object1<T> format(const char *Fmt, const T &Val) {
00193   return format_object1<T>(Fmt, Val);
00194 }
00195 
00196 template <typename T1, typename T2>
00197 inline format_object2<T1, T2> format(const char *Fmt, const T1 &Val1,
00198                                      const T2 &Val2) {
00199   return format_object2<T1, T2>(Fmt, Val1, Val2);
00200 }
00201 
00202 template <typename T1, typename T2, typename T3>
00203   inline format_object3<T1, T2, T3> format(const char *Fmt, const T1 &Val1,
00204                                            const T2 &Val2, const T3 &Val3) {
00205   return format_object3<T1, T2, T3>(Fmt, Val1, Val2, Val3);
00206 }
00207 
00208 template <typename T1, typename T2, typename T3, typename T4>
00209 inline format_object4<T1, T2, T3, T4> format(const char *Fmt, const T1 &Val1,
00210                                              const T2 &Val2, const T3 &Val3,
00211                                              const T4 &Val4) {
00212   return format_object4<T1, T2, T3, T4>(Fmt, Val1, Val2, Val3, Val4);
00213 }
00214 
00215 template <typename T1, typename T2, typename T3, typename T4, typename T5>
00216 inline format_object5<T1, T2, T3, T4, T5> format(const char *Fmt,const T1 &Val1,
00217                                              const T2 &Val2, const T3 &Val3,
00218                                              const T4 &Val4, const T5 &Val5) {
00219   return format_object5<T1, T2, T3, T4, T5>(Fmt, Val1, Val2, Val3, Val4, Val5);
00220 }
00221 
00222 template <typename T1, typename T2, typename T3, typename T4, typename T5,
00223           typename T6>
00224 inline format_object6<T1, T2, T3, T4, T5, T6>
00225 format(const char *Fmt, const T1 &Val1, const T2 &Val2, const T3 &Val3,
00226        const T4 &Val4, const T5 &Val5, const T6 &Val6) {
00227   return format_object6<T1, T2, T3, T4, T5, T6>(Fmt, Val1, Val2, Val3, Val4,
00228                                                 Val5, Val6);
00229 }
00230 
00231 /// This is a helper class used for left_justify() and right_justify().
00232 class FormattedString {
00233   StringRef Str;
00234   unsigned Width;
00235   bool RightJustify;
00236   friend class raw_ostream;
00237 public:
00238     FormattedString(StringRef S, unsigned W, bool R)
00239       : Str(S), Width(W), RightJustify(R) { }
00240 };
00241 
00242 /// left_justify - append spaces after string so total output is
00243 /// \p Width characters.  If \p Str is larger that \p Width, full string
00244 /// is written with no padding.
00245 inline FormattedString left_justify(StringRef Str, unsigned Width) {
00246   return FormattedString(Str, Width, false);
00247 }
00248 
00249 /// right_justify - add spaces before string so total output is
00250 /// \p Width characters.  If \p Str is larger that \p Width, full string
00251 /// is written with no padding.
00252 inline FormattedString right_justify(StringRef Str, unsigned Width) {
00253   return FormattedString(Str, Width, true);
00254 }
00255 
00256 /// This is a helper class used for format_hex() and format_decimal().
00257 class FormattedNumber {
00258   uint64_t HexValue;
00259   int64_t DecValue;
00260   unsigned Width;
00261   bool Hex;
00262   bool Upper;
00263   friend class raw_ostream;
00264 public:
00265     FormattedNumber(uint64_t HV, int64_t DV, unsigned W, bool H, bool U)
00266       : HexValue(HV), DecValue(DV), Width(W), Hex(H), Upper(U) { }
00267 };
00268 
00269 /// format_hex - Output \p N as a fixed width hexadecimal. If number will not
00270 /// fit in width, full number is still printed.  Examples:
00271 ///   OS << format_hex(255, 4)        => 0xff
00272 ///   OS << format_hex(255, 4, true)  => 0xFF
00273 ///   OS << format_hex(255, 6)        => 0x00ff
00274 ///   OS << format_hex(255, 2)        => 0xff
00275 inline FormattedNumber format_hex(uint64_t N, unsigned Width, bool Upper=false) {
00276   assert(Width <= 18 && "hex width must be <= 18");
00277   return FormattedNumber(N, 0, Width, true, Upper);
00278 }
00279 
00280 /// format_decimal - Output \p N as a right justified, fixed-width decimal. If 
00281 /// number will not fit in width, full number is still printed.  Examples:
00282 ///   OS << format_decimal(0, 5)     => "    0"
00283 ///   OS << format_decimal(255, 5)   => "  255"
00284 ///   OS << format_decimal(-1, 3)    => " -1"
00285 ///   OS << format_decimal(12345, 3) => "12345"
00286 inline FormattedNumber format_decimal(int64_t N, unsigned Width) {
00287   return FormattedNumber(0, N, Width, false, false);
00288 }
00289 
00290 
00291 } // end namespace llvm
00292 
00293 #endif