]>
Dogcows Code - chaz/yoink/blob - src/stlplus/portability/dprintf.hpp
3e4aa92b6f171764f09ed574f61a346d9352d08e
1 #ifndef STLPLUS_DPRINTF
2 #define STLPLUS_DPRINTF
3 ////////////////////////////////////////////////////////////////////////////////
5 // Author: Andy Rushton
6 // Copyright: (c) Southampton University 1999-2004
7 // (c) Andy Rushton 2004 onwards
8 // License: BSD License, see ../docs/license.html
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).
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.
21 // In any case, using arbitrary-sized fixed-length buffers is not part of any
22 // quality-orientated design philosophy.
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.
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.
34 // int dprintf (std::string& buffer, const char* format, ...);
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
41 // int vdprintf (std::string& buffer, const char* format, va_list args);
43 // As above, but using a pre-initialised va_args argument list. Useful for
44 // nesting dprintf calls within variable argument functions.
46 // std::string dformat (const char* format, ...);
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.
52 // e.g. cout << "Total: " << dformat("%6i",t) << endl;
54 // std::string vdformat (const char* format, va_list);
56 // As above, but using a pre-initialised va_args argument list. Useful for nesting
57 // dformat calls within variable argument functions.
59 // The format string supports the following format codes as in the C runtime library:
61 // % [ flags ] [ field ] [ . precision ] [ modifier ] [ conversion ]
65 // + - print sign for +ve numbers
66 // ' ' - leading space where + sign would be
67 // 0 - leading zeros to width of field
68 // # - alternate format
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
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
83 // h - short or unsigned short
84 // l - long or unsigned long
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
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
99 // n - int* as recipient of length of formatted string so far
101 ////////////////////////////////////////////////////////////////////////////////
102 #include "portability_fixes.hpp"
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
);
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
);
120 } // end namespace stlplus
This page took 0.042445 seconds and 4 git commands to generate.