Dogcows Code - chaz/yoink/blob - src/stlplus/portability/dprintf.hpp

   1 #ifndef STLPLUS_DPRINTF
   2 #define STLPLUS_DPRINTF
   3 ////////////////////////////////////////////////////////////////////////////////
   4
   5 //   Author:    Andy Rushton
   6 //   Copyright: (c) Southampton University 1999-2004
   7 //              (c) Andy Rushton           2004-2009
   8 //   License:   BSD License, see ../docs/license.html
   9
  10 //   Provides an sprintf-like function acting on STL strings. The 'd' in dprintf
  11 //   stands for "dynamic" in that the string is a dynamic string whereas a char*
  12 //   buffer would be static (in size that is, not static in C terms).
  13
  14 //   The obvious solution to the problem of in-memory formatted output is to use
  15 //   sprintf(), but this is a potentially dangerous operation since it will quite
  16 //   happily charge off the end of the string it is printing to and thereby
  17 //   corrupt memory. This kind of buffer-overflow vulnerability is the source of
  18 //   most security failures exploited by virus-writers. It means that sprintf
  19 //   should *never* be used and should be made obsolete.
  20
  21 //   In any case, using arbitrary-sized fixed-length buffers is not part of any
  22 //   quality-orientated design philosophy.
  23
  24 //   Most operating systems now have a safe version of sprintf, but this is
  25 //   non-standard. The functions in this file are platform-independent interfaces
  26 //   to the underlying safe implementation.
  27
  28 //   I would like to make this set of functions obsolete too, since I believe the
  29 //   C runtime should be deprecated in favour of C++ runtime which uses dynamic
  30 //   strings and can handle exceptions. However, there is as yet no C++
  31 //   equivalent functionality to some of the string-handling available through
  32 //   the printf-like functions, so it has to stay for now.
  33
  34 //     int dprintf (std::string& buffer, const char* format, ...);
  35
  36 //       Formats the message by appending to the std::string buffer according to
  37 //       the formatting codes in the format string. The return int is the number
  38 //       of characters generated by this call, i.e. the increase in the length of
  39 //       the std::string.
  40
  41 //     int vdprintf (std::string& buffer, const char* format, va_list args);
  42
  43 //       As above, but using a pre-initialised va_args argument list. Useful for
  44 //       nesting dprintf calls within variable argument functions.
  45
  46 //     std::string dformat (const char* format, ...);
  47
  48 //       Similar to dprintf() above, except the result is formatted into a new
  49 //       std::string which is returned by the function. Very useful for inline
  50 //       calls within an iostream expression.
  51
  52 //       e.g.    cout << "Total: " << dformat("%6i",t) << endl;
  53
  54 //     std::string vdformat (const char* format, va_list);
  55
  56 //       As above, but using a pre-initialised va_args argument list. Useful for nesting
  57 //       dformat calls within variable argument functions.
  58
  59 //   The format string supports the following format codes as in the C runtime library:
  60
  61 //     % [ flags ] [ field ] [ . precision ] [ modifier ] [ conversion ]
  62
  63 //     flags:
  64 //       -    - left justified
  65 //       +    - print sign for +ve numbers
  66 //       ' '  - leading space where + sign would be
  67 //       0    - leading zeros to width of field
  68 //       #    - alternate format
  69
  70 //     field:
  71 //       a numeric argument specifying the field width - default = 0
  72 //       * means take the next va_arg as the field width - if negative then left justify
  73
  74 //     precision:
  75 //       a numeric argument the meaning of which depends on the conversion -
  76 //       - %s - max characters from a string - default = strlen()
  77 //       - %e, %f - decimal places to be displayed - default = 6
  78 //       - %g - significant digits to be displayed - default = 6
  79 //       - all integer conversions - minimum digits to display - default = 0
  80 //       * means take the next va_arg as the field width - if negative then left justify
  81
  82 //     modifier:
  83 //       h    - short or unsigned short
  84 //       l    - long or unsigned long
  85 //       L    - long double
  86
  87 //     conversions:
  88 //       d, i - short/int/long as decimal
  89 //       u    - short/int/long as unsigned decimal
  90 //       o    - short/int/long as unsigned octal - # adds leading 0
  91 //       x, X - short/int/long as unsigned hexadecimal - # adds leading 0x
  92 //       c    - char
  93 //       s    - char*
  94 //       f    - double/long double as fixed point
  95 //       e, E - double/long double as floating point
  96 //       g, G - double/long double as fixed point/floating point depending on value
  97 //       p    - void* as unsigned hexadecimal
  98 //       %    - literal %
  99 //       n    - int* as recipient of length of formatted string so far
 100
 101 ////////////////////////////////////////////////////////////////////////////////
 102 #include "portability_fixes.hpp"
 103 #include <string>
 104 #include <stdexcept>
 105 #include <stdarg.h>
 106
 107 namespace stlplus
 108 {
 109
 110   // format by appending to a string and return the increase in length
 111   // if there is an error, return a negative number and leave the string unchanged
 112   int dprintf (std::string& formatted, const char* format, ...);
 113   int vdprintf (std::string& formatted, const char* format, va_list args);
 114
 115   // format into a new string and return the result
 116   // if there is an error, throw an exception
 117   std::string dformat (const char* format, ...) throw(std::invalid_argument);
 118   std::string vdformat (const char* format, va_list) throw(std::invalid_argument);
 119
 120 } // end namespace stlplus
 121
 122 #endif