HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_Format.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_Format.h ( UT Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __UT_Format__
12 #define __UT_Format__
13 
14 #include "UT_API.h"
15 
16 #include "UT_Assert.h"
17 #include "UT_NonCopyable.h"
18 
19 #include <SYS/SYS_Types.h>
20 
21 #include <algorithm>
22 #include <initializer_list>
23 #include <iosfwd>
24 #include <limits>
25 #include <string>
26 #include <type_traits>
27 
28 #include <stdio.h>
29 
30 class UT_String;
31 class UT_StringHolder;
32 class UT_StringRef;
33 class UT_StringView;
34 
35 /// @file UT_Format.h
36 /// @brief Type-safe formatting, modeled on the Python @c str.format function.
37 ///
38 /// This formatter supports a sub-set of the Python format syntax. Notably,
39 /// only indexed arguments are supported for now, not named ones.
40 ///
41 /// Like with the @c printf() formatting, the format string contains
42 /// replacement fields that will be substituted by the textual representation
43 /// of the arguments to the various format functions. The replacement fields
44 /// for this formatter are surrounded by curly braces `{}`, rather than
45 /// prefixed with a `%`.
46 ///
47 /// Note the string `{{` or `}}` will result in a single `{` or `}` being
48 /// output.
49 ///
50 /// @section format_grammar Format Grammar
51 /// The grammar for the replacement field is as follows:
52 ///
53 /// {[<index>][:<spec>]}
54 ///
55 /// The `<index>` is an optional integer value, which refers to the position of
56 /// the argument after the format string. If the `<index>` is omitted for all
57 /// replacement fields, then they are automatically substituted with
58 /// `0, 1, 2, ...`
59 /// It is not permitted to mix indexed and non-indexed.
60 ///
61 /// If a colon separator is found, the string after that is interpreted as a
62 /// formatting specification. The grammar for the `<spec>` field is as follows:
63 ///
64 /// [[<fill>]<align>][<sign>][#][,][0][<width>][.<precision>][<type>]
65 ///
66 /// Where:
67 /// - `<fill>` is the fill character to use when the width of the field is
68 /// greater than the length of the argument value being printed.
69 /// - `<align>` is a single character code which sets the alignment of the
70 /// value within the field:
71 /// - `<`: The field is left-aligned. This is the default for non-numeric
72 /// values.
73 /// - `>`: The field is right-aligned. This is the default for numeric values.
74 /// - `^`: The field is center-aligned.
75 /// - `=`: The field is number aligned. This is the same as right-aligned,
76 /// except the fill value is inserted between the sign indicator and
77 /// the numeric value. This alignment is only available for numeric
78 /// values.
79 /// - <sign> is a single character that specifies how the sign is printed for
80 /// numeric values:
81 /// - `+`: Always print a sign, whether positive or negative.
82 /// - `-`: Only print a sign when the number is negative.
83 /// - `<space>`: Use a leading space on positive numbers, minus sign for
84 /// negative.
85 /// - The '#' option is only available for binary, octal or hexadecimal output.
86 /// It indicates that they should be prefixed with '0b', '0' and '0x',
87 /// respectively.
88 /// - The ',' option will add digit grouping to numerical outputs. For float
89 //// numbers, this only applies to the integer portion of the float.
90 /// - `<width>` specifies the minimum width of the field. Arguments wider than
91 /// this value will still be printed out in full. Preceding the width field
92 /// with `0` will automatically set the alignment to number alignment, and
93 /// the fill value to `0`.
94 /// - `<precision>` sets the precision for floating point numbers. For other
95 /// types it specifies the maximum width of the field.
96 /// - `<type>` is a single character code that specifies how the type should be
97 /// interpreted. If an argument type is not valid for the formatting type,
98 /// the formatting type is ignored. The supported types are:
99 /// - `b`: Output integers as binary numbers.
100 /// - `B`: Output integers as binary numbers with an upper-case prefix (if
101 /// using the `#` option.
102 /// - `c`: Output integers interpreted as a Unicode code point.
103 /// - `d`: Output integers as decimal numbers. This is the default for
104 /// integers.
105 /// - `e`: Use the exponent notation for floating point numbers.
106 /// - `E`: Same as `e`, except the exponent separator is upper-cased.
107 /// - `f`: Use the fixed point notation for floating point numbers.
108 /// - `F`: Same as `f`.
109 /// - `g`: Format a floating point number as either fixed point or scientific,
110 /// depending on its magnitude, which mostly results in the shortest
111 /// form being used. This is the default for floats.
112 /// - `G`: Same as `g`, except the exponent separator is upper-cased.
113 /// - `o`: Output integers as octals.
114 /// - `x`: Output integers and floats as hexadecimal. For floats this uses
115 /// the special hexadecimal float output.
116 /// - `X`: The same as `x`, except all alphabetic digits and prefix are
117 /// output in upper-case.
118 /// - `%`: Takes a floating point number, multiplies it by 100 and outputs it
119 /// with a percentage sign appended, using fixed point notation. The
120 /// default precision in this mode is 2.
121 ///
122 /// Example:
123 /// @code{.cpp}
124 /// UTformat("Number: {}\n", 1);
125 /// UTformat("String: {}\n", "foobar");
126 /// UTformat("Field : {:=^20}\n", 1);
127 /// UTformat("Index : {3} {0} {2} {1}\n", 'A', 'B', 'C', 'D');
128 /// UTformat("Perc : {:.1%}\n", 0.1234);
129 /// @endcode
130 /// Result:
131 /// @code{.txt}
132 /// Number: 1
133 /// String: foobar
134 /// Field : =========1==========
135 /// Index : D A C B
136 /// Perc : 12.3%
137 /// @endcode
138 /// @section printf_grammar Printf Grammar
139 /// The UTprintf and UT_Format::printf functions use formatting code very
140 /// similar to the POSIX specification for printf.
141 /// The code begins with a single @c % character, followed by zero or more
142 /// modifiers, ending with the type specifier. Where this implementation of the
143 /// @c printf formatting code differs, is that there is no need to add length
144 /// modifiers. Any length modifers will simply be ignored.
145 
146 /// @section custom_format Custom Formatting
147 /// Custom types are supported through custom formatting functions. To define
148 /// a custom formatting function for a specific type, the following function
149 /// specialization needs to be implemented:
150 /// @code{.cpp}
151 /// size_t format(char *buffer, size_t buffer_size, const CustomType &val);
152 /// @endcode
153 /// Where:
154 /// - @c buffer is a byte buffer to write the result into. If @c buffer is a
155 /// @c nullptr, then the function should return the number of bytes required
156 /// to store the final result.
157 /// - @c buffer_size is the size of the byte buffer passed in via @c buffer.
158 /// This should be ignored if @c buffer is @c nullptr.
159 /// - @val is value to custom format.
160 /// The function should return the number of bytes written out, or, if @c buffer
161 /// is @c nullptr, the amount of bytes needed to write out the entire custom
162 /// type representation.
163 
164 
165 /// @name Standalone formatting functions
166 /// @{
167 
168 /// Takes a formatting string and a set of arguments and writes out the
169 /// formatted string to the FILE pointer.
170 /// @param file The @c FILE pointer to write to. The FILE must be opened in
171 /// write or append mode.
172 /// @param format The formatting codes, as defined in @ref format_grammar.
173 /// @param args The arguments to the formatting.
174 /// @return The number of bytes successfully written out.
175 template<typename... Args>
176 size_t UTformat(FILE *file, const char *format, const Args& ...args);
177 
178 /// Takes a formatting string and a set of arguments and writes out the
179 /// formatted string to @c stdout.
180 /// @param format The formatting codes, as defined in @ref format_grammar.
181 /// @param args The arguments to the formatting.
182 /// @return The number of bytes successfully written out.
183 template<typename... Args>
184 size_t UTformat(const char *format, const Args& ...args);
185 
186 /// Takes a formatting string and a set of arguments and writes out the
187 /// formatted string to the output stream object.
188 /// @param os The output stream to write to.
189 /// @param format The formatting codes, as defined in @ref format_grammar.
190 /// @param args The arguments to the formatting.
191 /// @return The number of bytes successfully written out.
192 template<typename... Args>
193 size_t UTformat(std::ostream &os, const char *format, const Args& ...args);
194 
195 /// Takes a formatting string and a set of arguments and writes out the
196 /// formatted string into the buffer provided. If @c buffer is @c nullptr,
197 /// then nothing is written out, but the number of bytes needed to store
198 /// the entire formatted string is returned. A termination byte is not written
199 /// out to the buffer. If termination is required, the caller must take care
200 /// of it.
201 /// @param buffer The character buffer to write the formatted string to.
202 /// @param buffer_size The size of the character buffer.
203 /// @param format The formatting codes, as defined in @ref format_grammar.
204 /// @param args The arguments to the formatting.
205 /// @return The number of bytes successfully written out.
206 template<typename... Args>
207 size_t UTformat(char *buffer, size_t buffer_size, const char *format,
208  const Args& ...args);
209 
210 /// @}
211 
212 /// @name Standalone printf-like functions
213 /// @{
214 
215 /// Takes a formatting string and a set of arguments and writes out the
216 /// formatted string to the FILE pointer.
217 /// @param file The @c FILE pointer to write to. The FILE must be opened in
218 /// write or append mode.
219 /// @param format The formatting codes, as defined in @ref printf_grammar.
220 /// @param args The arguments to the formatting.
221 /// @return The number of bytes successfully written out.
222 template<typename... Args>
223 size_t UTprintf(FILE *file, const char *format, const Args& ...args);
224 
225 /// Takes a formatting string and a set of arguments and writes out the
226 /// formatted string to @c stdout.
227 /// @param format The formatting codes, as defined in @ref printf_grammar.
228 /// @param args The arguments to the formatting.
229 /// @return The number of bytes successfully written out.
230 template<typename... Args>
231 size_t UTprintf(const char *format, const Args& ...args);
232 
233 /// Takes a formatting string and a set of arguments and writes out the
234 /// formatted string to the output stream object.
235 /// @param os The output stream to write to.
236 /// @param format The formatting codes, as defined in @ref printf_grammar.
237 /// @param args The arguments to the formatting.
238 /// @return The number of bytes successfully written out.
239 template<typename... Args>
240 size_t UTprintf(std::ostream &os, const char *format, const Args& ...args);
241 
242 /// Takes a formatting string and a set of arguments and writes out the
243 /// formatted string into the buffer provided. If @c buffer is @c nullptr,
244 /// then nothing is written out, but the number of bytes needed to store
245 /// the entire formatted string is returned. A termination byte is not written
246 /// out to the buffer. If termination is required, the caller must take care
247 /// of it.
248 /// @param buffer The character buffer to write the formatted string to.
249 /// @param buffer_size The size of the character buffer.
250 /// @param format The formatting codes, as defined in @ref printf_grammar.
251 /// @param args The arguments to the formatting.
252 /// @return The number of bytes successfully written out.
253 template<typename... Args>
254 size_t UTprintf(char *buffer, size_t buffer_size, const char *format,
255  const Args& ...args);
256 
257 /// @}
258 
259 
260 namespace UT { namespace Format {
261 
262 /// @name Writer functors for formatted strings
263 /// @{
264 
265 /// A writer class that writes to a raw character buffer. If initializing with
266 /// a default constructor, the writer won't store anything. This can be useful
267 /// to count the number of bytes required for storage before allocating a buffer
268 /// for the final result.
269 struct Writer : public UT_NonCopyable
270 {
271  Writer() :
272  myBuffer(nullptr),
273  myBufferSize(std::numeric_limits<size_t>::max()) { }
274 
275  Writer(char *buffer, size_t buffer_size) :
276  myBuffer(buffer),
277  myBufferSize(buffer_size) { }
278 
279  void setBuffer(char *buffer, size_t buffer_size)
280  {
281  myBuffer = buffer;
282  myBufferSize = buffer_size;
283  }
284 
285  size_t operator()(const char *begin, const char *end)
286  {
287  // Exhausted?
288  if (!myBufferSize)
289  return false;
290 
291  size_t size = size_t(end - begin);
292  size = std::min(size, myBufferSize);
293  if (myBuffer)
294  {
295  std::copy(begin, begin + size, myBuffer);
296  myBuffer += size;
297  }
298  myBufferSize -= size;
299 
300  return size;
301  }
302 
303 private:
304  char *myBuffer;
305  size_t myBufferSize;
306 };
307 
308 /// A specialized @c Writer class that writes to a stdio @c FILE buffer.
310 {
311  FileWriter(FILE *file) : myFile(file) {}
312 
313  size_t operator()(const char *begin, const char *end);
314 
315 private:
316  FILE *myFile;
317 };
318 
319 /// A specialized @c Writer class that writes to a @c std::ostream object.
321 {
322  StreamWriter(std::ostream &os) : myOS(os) {}
323 
324  size_t operator()(const char *begin, const char *end);
325 
326 private:
327  std::ostream &myOS;
328 };
329 
330 /// Class outline of a writer class for the formatter. This serves as a
331 /// template when writing a new @ref Formatter writer for cases that the
332 /// @ref FileWriter, @ref StreamWriter, and @ref Writer don't cover.
334 {
335  /// Write the range of bytes from @c begin to @c end, non-inclusive (i.e.
336  /// don't write out the byte pointed to by @c end). Return the number of
337  /// bytes written.
338  size_t operator()(const char *begin, const char *end);
339 };
340 
341 /// @}
342 
343 // A template to check whether a variation of format(...) exists for the
344 // given type.
345 namespace Impl
346 {
347  template<typename> struct TrueType : std::true_type {};
348  // SFINAE will pick one of the two HasFormat() variants below, depending on
349  // if it can resolve the declaration type of the format() declaration given
350  // below. We wrap the result through the TrueType class above (which
351  // accepts any type) in order to get a true value for it in the actual
352  // HasFormat implementation below.
353  template<typename T>
354  static auto TestHasFormat(int) ->
356  size_t(), std::declval<T>()))>;
357  template<typename T>
358  static auto TestHasFormat(long) -> std::false_type;
359 }
360 
361 template<typename T>
362 struct HasFormat
363 {
364  static constexpr bool value = decltype(Impl::TestHasFormat<T>(0))::value;
365 };
366 
367 /// A container class that holds the individual argument values to be formatted
368 /// with the format string.
370 {
371 
372 public:
373  enum class Type
374  {
375  None,
376  Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64,
377  Float16, Float32, Float64,
378  ZeroString, SizedString, CharString,
379  Pointer, Custom
380  };
381 
382  ArgValue(char v) : myType(Type::CharString), myChar(v) {}
383  ArgValue(int8 v) : myType(Type::Int8), myI8(v) {}
384  ArgValue(uint8 v) : myType(Type::UInt8), myU8(v) {}
385  ArgValue(int16 v) : myType(Type::Int16), myI16(v) {}
386  ArgValue(uint16 v) : myType(Type::UInt16), myU16(v) {}
387  ArgValue(int32 v) : myType(Type::Int32), myI32(v) {}
388  ArgValue(uint32 v) : myType(Type::UInt32), myU32(v) {}
389  ArgValue(int64 v) : myType(Type::Int64), myI64(v) {}
390  ArgValue(uint64 v) : myType(Type::UInt64), myU64(v) {}
391  ArgValue(fpreal16 v) : myType(Type::Float16), myF16(v) {}
392  ArgValue(fpreal32 v) : myType(Type::Float32), myF32(v) {}
393  ArgValue(fpreal64 v) : myType(Type::Float64), myF64(v) {}
394 
395 #if defined(LINUX) && defined(AMD64)
396  // Special overload to deal with long longs, which both gcc and clang
397  // treat as a distinct type from long, on 64-bit Linux, even if they're the
398  // same size.
399  static_assert(sizeof(long long) == 8, "long long should be 8 bytes.");
400  ArgValue(long long v) : myType(Type::Int64), myI64(int64(v)) {}
401  ArgValue(unsigned long long v) : myType(Type::UInt64), myU64(uint64(v)) {}
402 #endif
403 #if defined(MBSD) && defined(__clang__)
404  // Special overload for size_t with clang on OSX.
405  ArgValue(size_t myValuePtr) : myType(Type::UInt64), myU64(uint64(myValuePtr)) {}
406 #endif
407 
408  ArgValue(bool v) : myType(Type::SizedString)
409  {
410  if (v)
411  {
412  mySizedStr.myStr = "true";
413  mySizedStr.mySize = 4;
414  }
415  else
416  {
417  mySizedStr.myStr = "false";
418  mySizedStr.mySize = 5;
419  }
420  }
421 
422  ArgValue(char *v) : myType(Type::ZeroString), myStr(v) {}
423  ArgValue(const char *v) : myType(Type::ZeroString), myStr(v) {}
424  ArgValue(const UT_String &v);
425  ArgValue(const UT_StringRef &v);
426  ArgValue(const UT_StringHolder &v);
427  ArgValue(const UT_StringView &v);
429  myType(Type::SizedString), mySizedStr(v.c_str(), v.length()) {}
430 
431  // void pointer overrides because std::is_pointer<void*>::value is false!
432  ArgValue(void *v) :
433  myType(Type::Pointer), myPtr(v)
434  {
435  }
436  ArgValue(const void *v) :
437  myType(Type::Pointer), myPtr(v)
438  {
439  }
440 
441 #define UT_ENABLE_IF(T) typename std::enable_if<T>::type * = nullptr
442 #define UT_HAS_FMT(T) HasFormat<T>::value
443 #define UT_REMOVE_PTR(T) typename std::remove_pointer<T>::type
444 #define UT_IS_PTR(T) std::is_pointer<T>::value
445 
446  // Accept any pointer type that doesn't have a custom formatter.
447  // We use std::enable_if magic to allow SFINAE to elide any constructor
448  // that doesn't properly evaluate (a template argument value of false to
449  // std::enable_if results in std::enable_if::type not being defined).
450  template<typename T>
453  myType(Type::Pointer), myPtr(v)
454  {
455  }
456 
457  // For pointer types that have custom formatters. In this case we print
458  // out the pointer value and the de-referenced formatted value pointed to,
459  // or (null), if the value is \c nullptr.
460  template<typename T>
461  ArgValue(T v,
463  myType(Type::Custom)
464  {
465  myCustom.myFormatFunc = customPtrWrapper<UT_REMOVE_PTR(T)>;
466  myCustom.myValuePtr = static_cast<const void *>(v);
467  }
468 
469  // For fixed length arrays
470  template<typename T, unsigned N>
471  ArgValue(T (&v)[N]) :
472  myType(Type::Custom)
473  {
474  myCustom.myFormatFunc = customArrayWrapper<UT_REMOVE_PTR(T),N>;
475  myCustom.myValuePtr = static_cast<const void *>(&v[0]);
476  }
477 
478  // For reference types that have custom formatters.
479  template<typename T>
481  myType(Type::Custom)
482  {
483  static_assert(UT_HAS_FMT(T), "No formatting function for custom type.");
484  myCustom.myFormatFunc = customRefWrapper<T>;
485  myCustom.myValuePtr = &t;
486  }
487 
488  size_t formatCustom(char *buffer, size_t buffer_size) const
489  {
490  UT_ASSERT(isCustom());
491  if (!isCustom())
492  return 0;
493 
494  return myCustom.myFormatFunc(buffer, buffer_size, myCustom.myValuePtr);
495  }
496 
497 #undef UT_ENABLE_IF
498 #undef UT_HAS_FMT
499 #undef UT_REMOVE_PTR
500 #undef UT_IS_PTR
501 
502  // In the presence of a union with non-POD types, we have to provide our
503  // own destructor, even if there are no destructors to call.
505 
506  Type type() const { return myType; }
507 
508  bool isEmpty() const { return myType == Type::None; }
509 
510  bool isInteger() const
511  {
512  return myType == Type::Int8 || myType == Type::UInt8 ||
513  myType == Type::Int16 || myType == Type::UInt16 ||
514  myType == Type::Int32 || myType == Type::UInt32 ||
515  myType == Type::Int64 || myType == Type::UInt64;
516  }
517 
518  bool isFloat() const
519  {
520  return myType == Type::Float16 ||
521  myType == Type::Float32 ||
522  myType == Type::Float64;
523  }
524 
525  bool isSigned() const
526  {
527  return myType == Type::Int8 ||
528  myType == Type::Int16 ||
529  myType == Type::Int32 ||
530  myType == Type::Int64 ||
531  isFloat();
532  }
533 
534  bool isNumeric() const
535  {
536  return isInteger() || isFloat();
537  }
538 
539  bool isString() const
540  {
541  return myType == Type::CharString ||
542  myType == Type::ZeroString ||
543  myType == Type::SizedString;
544  }
545 
546  bool isPointer() const
547  {
548  return myType == Type::Pointer;
549  }
550 
551  bool isCustom() const
552  {
553  return myType == Type::Custom;
554  }
555 
556 protected:
557  template<typename W> friend class Formatter;
558 
559  ArgValue() : myType(Type::None), myU64(0) {}
560  ArgValue(Type type) : myType(type), myI64(0) {}
561 
562  struct SizedString
563  {
564  SizedString(const char *str, size_t size) : myStr(str), mySize(size) {}
565  const char *myStr;
566  size_t mySize;
567  };
568 
569  using CustomFormat = size_t(*)(char *buffer, size_t buffer_size, const void *value);
570 
571  struct Custom
572  {
573  const void *myValuePtr;
575  };
576 
577  union
578  {
590  char myChar;
591  const char *myStr;
593  const void *myPtr;
595  };
596 
597 private:
598  Type myType;
599 
600  // Wraper function to invoke the writer for the custom type.
601  template <typename T>
602  static inline size_t
603  customRefWrapper(char *buffer, size_t buffer_size, const void *value)
604  {
605  return format(buffer, buffer_size, *static_cast<const T*>(value));
606  }
607 
608  template <typename T>
609  static inline size_t
610  customPtrWrapper(char *buffer, size_t buffer_size, const void *value)
611  {
612  if (value)
613  return UTformat(buffer, buffer_size, "<{} {}>",
614  value, *static_cast<const T*>(value));
615  else
616  return UTformat(buffer, buffer_size, "<{}>", value);
617  }
618 
619  template <typename T, unsigned N>
620  static inline size_t
621  customArrayWrapper(char *buffer, size_t buffer_size, const void *value);
622 };
623 
624 /// The main formatting class. This accepts a set of arguments and can
625 /// subsequently format them in various ways.
626 template<typename W = Writer>
627 class Formatter : public UT_NonCopyable
628 {
629  // A utility class to keep track of number of bytes written.
630  struct WriteTracker
631  {
632  WriteTracker(W &writer) : myWriter(writer), myBytesWritten(0) {}
633 
634  bool write(const char *begin, const char *end)
635  {
636  size_t bytes_to_write = size_t(end - begin);
637  size_t n_written = myWriter(begin, end);
638  myBytesWritten += n_written;
639  return n_written == bytes_to_write;
640  }
641  size_t written() const { return myBytesWritten; }
642 
643  void increment(size_t n_bytes) { myBytesWritten += n_bytes; }
644 
645  private:
646  W &myWriter;
647  size_t myBytesWritten;
648  };
649 public:
650  using WriterType = W;
651 
652  /// Constructs a new @ref Formatter object.
654  myNextArgIndex(0),
655  myReportErrors(true),
656  myDigitGroupings(false) {}
657 
658  /// Sets whether to report format string errors or not.
659  void setReportErrors(bool flag) { myReportErrors = flag; }
660 
661  /// Sets whether to force numbers to print with digit grouping. Otherwise
662  /// only the ',' (format), or '\'' (printf) flags dictate whether digit
663  /// grouping is done.
664  void setForceDigitGroupings(bool flag) { myDigitGroupings = flag; }
665 
666  /// Format the arguments into the writer, using the format string given.
667  /// Returns the number of bytes written.
668  /// @param writer A functor that does the writing of the formatted output.
669  /// See @ref CustomWriter for an example of how to do a custom writer.
670  /// @param format The formatting codes, as defined in @ref format_grammar.
671  /// @param args An initializer list that forms the list of arguments to
672  /// bake into the formatted result using the format string.
673  /// @return The number of bytes written out to the @p writer functor.
674  size_t format(W &writer, const char * format,
675  std::initializer_list<ArgValue> args);
676 
677  /// Format the arguments into the writer, using the format string given.
678  /// Returns the number of bytes written.
679  /// @param writer A functor that does the writing of the formatted output.
680  /// See @ref CustomWriter for an example of how to do a custom writer.
681  /// @param format The formatting codes, as defined in @ref format_grammar.
682  /// @param args An array of arguments to bake into the formatted result
683  /// using the format string.
684  /// @param nb_args The number of items in the argument array passed in.
685  /// @return The number of bytes written out to the @p writer functor.
686  size_t format(W &writer, const char * format,
687  const ArgValue args[], size_t nb_args);
688 
689  /// Format the arguments into the writer, using the format string given.
690  /// Returns the number of bytes written.
691  /// @param writer A functor that does the writing of the formatted output.
692  /// See @ref CustomWriter for an example of how to do a custom writer.
693  /// @param format The formatting codes, as defined by
694  /// [std::printf](http://www.cplusplus.com/reference/cstdio/printf/)
695  /// @param args An initializer list that forms the list of arguments to
696  /// bake into the formatted result using the format string.
697  /// @return The number of bytes written out to the @p writer functor.
698  size_t printf(W &writer, const char * format,
699  std::initializer_list<ArgValue> args);
700 
701  /// Format the arguments into the writer, using the format string given.
702  /// Returns the number of bytes written.
703  /// @param writer A functor that does the writing of the formatted output.
704  /// See @ref CustomWriter for an example of how to do a custom writer.
705  /// @param format The formatting codes, as defined by
706  /// [std::printf](http://www.cplusplus.com/reference/cstdio/printf/)
707  /// @param args An array of arguments to bake into the formatted result
708  /// using the format string.
709  /// @param nb_args The number of items in the argument array passed in.
710  /// @return The number of bytes written out to the @p writer functor.
711  size_t printf(W &writer, const char * format,
712  const ArgValue args[], size_t nb_args);
713 
714 private:
715  struct FormatSpec
716  {
717  FormatSpec() :
718  field_width(0),
719  str_width(std::numeric_limits<size_t>::max()),
720  precision(-1),
721  align(Left),
722  sign(Minus),
723  alt_form(false),
724  digit_grouping(false),
725  fill(' '),
726  type(0)
727  {
728  }
729 
730  size_t field_width;
731  size_t str_width;
733  enum { Left, Center, Right, Number } align;
734  enum { Minus, Plus, Space } sign;
735  bool alt_form;
736  bool digit_grouping;
737  char fill;
738  char type;
739  };
740 
741  bool parseFormatSpec(const char *&ptr, const ArgValue &arg,
742  const ArgValue args[], size_t nb_args,
743  FormatSpec &spec);
744  bool parsePrintfSpec(const char *&ptr, const ArgValue &arg,
745  const ArgValue args[], size_t nb_args,
746  FormatSpec &spec);
747 
748  size_t formatArg(W &writer, const FormatSpec &spec, const ArgValue &arg);
749  size_t formatInteger(W &writer, const FormatSpec &spec, const ArgValue &arg);
750  size_t formatFloat(W &writer, const FormatSpec &spec, const ArgValue &arg);
751  size_t formatString(W &writer, const FormatSpec &spec, const ArgValue &arg);
752  size_t formatPointer(W &writer, const FormatSpec &spec, const ArgValue &arg);
753  size_t formatCustom(W &writer, const FormatSpec &spec, const ArgValue &arg);
754  size_t formatCodePoint(W &writer, const FormatSpec &spec, const ArgValue &arg);
755  size_t formatPercentage(W &writer, const FormatSpec &spec, const ArgValue &arg);
756 
757  size_t formatAdjustAndFill(W &writer, const char *str, size_t str_size,
758  const FormatSpec &spec);
759 
760  // Get the argument pointed at by the current location of the format string.
761  // If the first character is a digit, assume the argument is being referred
762  // to by index, otherwise assume we're using the next argument.
763  const ArgValue &getFormatArg(const char *&ptr, const ArgValue args[],
764  size_t nb_args);
765  const ArgValue &getPrintfArg(const char *&ptr, const ArgValue args[],
766  size_t nb_args);
767  static int64 getIntValueFromArg(const ArgValue &arg);
768  static fpreal64 getFloatValueFromArg(const ArgValue &arg);
769 
770  int64 myNextArgIndex;
771  bool myReportErrors:1,
772  myDigitGroupings:1;
773 };
774 
775  } // namespace Format
776 } // namespace UT
777 
778 
779 // The inline implementation
780 #include "UT_FormatImpl.h"
781 
782 #endif // __UT_Format__
size_t printf(W &writer, const char *format, std::initializer_list< ArgValue > args)
#define UT_IS_PTR(T)
Definition: UT_Format.h:444
size_t format(W &writer, const char *format, std::initializer_list< ArgValue > args)
size_t formatCustom(char *buffer, size_t buffer_size) const
Definition: UT_Format.h:488
SizedString(const char *str, size_t size)
Definition: UT_Format.h:564
#define UT_ENABLE_IF(T)
Definition: UT_Format.h:441
void setBuffer(char *buffer, size_t buffer_size)
Definition: UT_Format.h:279
const GLdouble * v
Definition: glcorearb.h:836
void setForceDigitGroupings(bool flag)
Definition: UT_Format.h:664
ArgValue(fpreal64 v)
Definition: UT_Format.h:393
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
png_voidp ptr
Definition: png.h:2145
ArgValue(const std::string &v)
Definition: UT_Format.h:428
#define UT_API
Definition: UT_API.h:13
ArgValue(uint32 v)
Definition: UT_Format.h:388
#define UT_HAS_FMT(T)
Definition: UT_Format.h:442
size_t(*)(char *buffer, size_t buffer_size, const void *value) CustomFormat
Definition: UT_Format.h:569
GLuint buffer
Definition: glcorearb.h:659
GLsizeiptr size
Definition: glcorearb.h:663
ArgValue(const char *v)
Definition: UT_Format.h:423
ArgValue(uint16 v)
Definition: UT_Format.h:386
bool isFloat() const
Definition: UT_Format.h:518
signed char int8
Definition: SYS_Types.h:31
long long int64
Definition: SYS_Types.h:107
A utility class to do read-only operations on a subset of an existing string.
Definition: UT_StringView.h:31
Formatter()
Constructs a new Formatter object.
Definition: UT_Format.h:653
unsigned long long uint64
Definition: SYS_Types.h:108
ArgValue(T v, UT_ENABLE_IF(UT_IS_PTR(T)&&UT_HAS_FMT(UT_REMOVE_PTR(T))))
Definition: UT_Format.h:461
StreamWriter(std::ostream &os)
Definition: UT_Format.h:322
const std::enable_if<!VecTraits< T >::IsVec, T >::type & max(const T &a, const T &b)
Definition: Composite.h:133
bool isString() const
Definition: UT_Format.h:539
bool isNumeric() const
Definition: UT_Format.h:534
double fpreal64
Definition: SYS_Types.h:192
IMATH_INTERNAL_NAMESPACE_HEADER_ENTER typedef long long unsigned int Int64
Definition: ImathInt64.h:56
#define UT_REMOVE_PTR(T)
Definition: UT_Format.h:443
GLuint GLuint end
Definition: glcorearb.h:474
void setReportErrors(bool flag)
Sets whether to report format string errors or not.
Definition: UT_Format.h:659
bool isPointer() const
Definition: UT_Format.h:546
A specialized Writer class that writes to a std::ostream object.
Definition: UT_Format.h:320
ArgValue(fpreal32 v)
Definition: UT_Format.h:392
int sign(T a)
Definition: ImathFun.h:63
ArgValue(T &t, UT_ENABLE_IF(!UT_IS_PTR(T)))
Definition: UT_Format.h:480
int int32
Definition: SYS_Types.h:35
const void * myPtr
Definition: UT_Format.h:593
A specialized Writer class that writes to a stdio FILE buffer.
Definition: UT_Format.h:309
Type type() const
Definition: UT_Format.h:506
size_t UTprintf(FILE *file, const char *format, const Args &...args)
GLenum GLint GLint * precision
Definition: glcorearb.h:1924
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:107
bool isEmpty() const
Definition: UT_Format.h:508
Writer(char *buffer, size_t buffer_size)
Definition: UT_Format.h:275
unsigned short uint16
Definition: SYS_Types.h:34
GLsizei const GLfloat * value
Definition: glcorearb.h:823
SizedString mySizedStr
Definition: UT_Format.h:592
ArgValue(T v, UT_ENABLE_IF(UT_IS_PTR(T)&&!UT_HAS_FMT(UT_REMOVE_PTR(T))))
Definition: UT_Format.h:451
unsigned char uint8
Definition: SYS_Types.h:32
size_t operator()(const char *begin, const char *end)
Definition: UT_Format.h:285
bool isSigned() const
Definition: UT_Format.h:525
png_infop png_bytep png_size_t buffer_size
Definition: png.h:2124
ArgValue(T(&v)[N])
Definition: UT_Format.h:471
GA_API const UT_StringHolder N
size_t UTformat(FILE *file, const char *format, const Args &...args)
ArgValue(Type type)
Definition: UT_Format.h:560
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
#define UT_ASSERT(ZZ)
Definition: UT_Assert.h:126
ArgValue(fpreal16 v)
Definition: UT_Format.h:391
short int16
Definition: SYS_Types.h:33
png_infop png_uint_32 flag
Definition: png.h:2242
void write(T &out, bool v)
Definition: ImfXdr.h:332
const std::enable_if<!VecTraits< T >::IsVec, T >::type & min(const T &a, const T &b)
Definition: Composite.h:129
ArgValue(const void *v)
Definition: UT_Format.h:436
float fpreal32
Definition: SYS_Types.h:191
FileWriter(FILE *file)
Definition: UT_Format.h:311
const char * myStr
Definition: UT_Format.h:591
bool isInteger() const
Definition: UT_Format.h:510
size_t operator()(const char *begin, const char *end)
bool isCustom() const
Definition: UT_Format.h:551
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:794
unsigned int uint32
Definition: SYS_Types.h:36
ArgValue(uint64 v)
Definition: UT_Format.h:390