1 | // |
---|
2 | // Format.h |
---|
3 | // |
---|
4 | // $Id: //poco/1.3/Foundation/include/Poco/Format.h#6 $ |
---|
5 | // |
---|
6 | // Library: Foundation |
---|
7 | // Package: Core |
---|
8 | // Module: Format |
---|
9 | // |
---|
10 | // Definition of the format freestanding function. |
---|
11 | // |
---|
12 | // Copyright (c) 2006, Applied Informatics Software Engineering GmbH. |
---|
13 | // and Contributors. |
---|
14 | // |
---|
15 | // Permission is hereby granted, free of charge, to any person or organization |
---|
16 | // obtaining a copy of the software and accompanying documentation covered by |
---|
17 | // this license (the "Software") to use, reproduce, display, distribute, |
---|
18 | // execute, and transmit the Software, and to prepare derivative works of the |
---|
19 | // Software, and to permit third-parties to whom the Software is furnished to |
---|
20 | // do so, all subject to the following: |
---|
21 | // |
---|
22 | // The copyright notices in the Software and this entire statement, including |
---|
23 | // the above license grant, this restriction and the following disclaimer, |
---|
24 | // must be included in all copies of the Software, in whole or in part, and |
---|
25 | // all derivative works of the Software, unless such copies or derivative |
---|
26 | // works are solely in the form of machine-executable object code generated by |
---|
27 | // a source language processor. |
---|
28 | // |
---|
29 | // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
---|
30 | // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
---|
31 | // FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT |
---|
32 | // SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE |
---|
33 | // FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, |
---|
34 | // ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
---|
35 | // DEALINGS IN THE SOFTWARE. |
---|
36 | // |
---|
37 | |
---|
38 | |
---|
39 | #ifndef Foundation_Format_INCLUDED |
---|
40 | #define Foundation_Format_INCLUDED |
---|
41 | |
---|
42 | |
---|
43 | #include "Poco/Foundation.h" |
---|
44 | #include "Poco/Any.h" |
---|
45 | #include <vector> |
---|
46 | |
---|
47 | |
---|
48 | namespace Poco { |
---|
49 | |
---|
50 | |
---|
51 | std::string Foundation_API format(const std::string& fmt, const Any& value); |
---|
52 | /// This function implements sprintf-style formatting in a typesafe way. |
---|
53 | /// Various variants of the function are available, supporting a |
---|
54 | /// different number of arguments (up to six). |
---|
55 | /// |
---|
56 | /// The formatting is controlled by the format string in fmt. |
---|
57 | /// Format strings are quite similar to those of the std::printf() function, but |
---|
58 | /// there are some minor differences. |
---|
59 | /// |
---|
60 | /// The format string can consist of any sequence of characters; certain |
---|
61 | /// characters have a special meaning. Characters without a special meaning |
---|
62 | /// are copied verbatim to the result. A percent sign (%) marks the beginning |
---|
63 | /// of a format specification. Format specifications have the following syntax: |
---|
64 | /// |
---|
65 | /// %[<flags>][<width>][.<precision>][<modifier>]<type> |
---|
66 | /// |
---|
67 | /// Flags, width, precision and prefix are optional. The only required part of |
---|
68 | /// the format specification, apart from the percent sign, is the type. |
---|
69 | /// |
---|
70 | /// Following are valid type specifications and their meaning: |
---|
71 | /// |
---|
72 | /// * b boolean (true = 1, false = 0) |
---|
73 | /// * c character |
---|
74 | /// * d signed decimal integer |
---|
75 | /// * i signed decimal integer |
---|
76 | /// * o unsigned octal integer |
---|
77 | /// * u unsigned decimal integer |
---|
78 | /// * x unsigned hexadecimal integer (lower case) |
---|
79 | /// * X unsigned hexadecimal integer (upper case) |
---|
80 | /// * e signed floating-point value in the form [-]d.dddde[<sign>]dd[d] |
---|
81 | /// * E signed floating-point value in the form [-]d.ddddE[<sign>]dd[d] |
---|
82 | /// * f signed floating-point value in the form [-]dddd.dddd |
---|
83 | /// * s std::string |
---|
84 | /// * z std::size_t |
---|
85 | /// |
---|
86 | /// The following flags are supported: |
---|
87 | /// |
---|
88 | /// * - left align the result within the given field width |
---|
89 | /// * + prefix the output value with a sign (+ or ) if the output value is of a signed type |
---|
90 | /// * 0 if width is prefixed with 0, zeros are added until the minimum width is reached |
---|
91 | /// * # For o, x, X, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively; |
---|
92 | /// for e, E, f, the # flag forces the output value to contain a decimal point in all cases. |
---|
93 | /// |
---|
94 | /// The following modifiers are supported: |
---|
95 | /// |
---|
96 | /// * (none) argument is char (c), int (d, i), unsigned (o, u, x, X) double (e, E, f, g, G) or string (s) |
---|
97 | /// * l argument is long (d, i), unsigned long (o, u, x, X) or long double (e, E, f, g, G) |
---|
98 | /// * L argument is long long (d, i), unsigned long long (o, u, x, X) |
---|
99 | /// * h argument is short (d, i), unsigned short (o, u, x, X) or float (e, E, f, g, G) |
---|
100 | /// * ? argument is any signed or unsigned int, short, long, or 64-bit integer (d, i, o, x, X) |
---|
101 | /// |
---|
102 | /// The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. |
---|
103 | /// If the number of characters in the output value is less than the specified width, blanks or |
---|
104 | /// leading zeros are added, according to the specified flags (-, +, 0). |
---|
105 | /// |
---|
106 | /// Precision is a nonnegative decimal integer, preceded by a period (.), which specifies the number of characters |
---|
107 | /// to be printed, the number of decimal places, or the number of significant digits. |
---|
108 | /// |
---|
109 | /// Throws a BadCastException if an argument does not correspond to the type of its format specification. |
---|
110 | /// |
---|
111 | /// If there are more format specifiers than values, the format specifiers without a corresponding value |
---|
112 | /// are copied verbatim to output. |
---|
113 | /// |
---|
114 | /// If there are more values than format specifiers, the superfluous values are ignored. |
---|
115 | /// |
---|
116 | /// Usage Example: |
---|
117 | /// std::string s = format("The answer to life, the universe, and everything is %d", 42); |
---|
118 | |
---|
119 | std::string Foundation_API format(const std::string& fmt, const Any& value1, const Any& value2); |
---|
120 | std::string Foundation_API format(const std::string& fmt, const Any& value1, const Any& value2, const Any& value3); |
---|
121 | std::string Foundation_API format(const std::string& fmt, const Any& value1, const Any& value2, const Any& value3, const Any& value4); |
---|
122 | std::string Foundation_API format(const std::string& fmt, const Any& value1, const Any& value2, const Any& value3, const Any& value4, const Any& value5); |
---|
123 | std::string Foundation_API format(const std::string& fmt, const Any& value1, const Any& value2, const Any& value3, const Any& value4, const Any& value5, const Any& value6); |
---|
124 | |
---|
125 | |
---|
126 | void Foundation_API format(std::string& result, const std::string& fmt, const Any& value); |
---|
127 | /// Appends the formatted string to result. |
---|
128 | |
---|
129 | void Foundation_API format(std::string& result, const std::string& fmt, const Any& value1, const Any& value2); |
---|
130 | void Foundation_API format(std::string& result, const std::string& fmt, const Any& value1, const Any& value2, const Any& value3); |
---|
131 | void Foundation_API format(std::string& result, const std::string& fmt, const Any& value1, const Any& value2, const Any& value3, const Any& value4); |
---|
132 | void Foundation_API format(std::string& result, const std::string& fmt, const Any& value1, const Any& value2, const Any& value3, const Any& value4, const Any& value5); |
---|
133 | void Foundation_API format(std::string& result, const std::string& fmt, const Any& value1, const Any& value2, const Any& value3, const Any& value4, const Any& value5, const Any& value6); |
---|
134 | |
---|
135 | |
---|
136 | void Foundation_API format(std::string& result, const std::string& fmt, const std::vector<Any>& values); |
---|
137 | /// Supports a variable number of arguments and is used by |
---|
138 | /// all other variants of format(). |
---|
139 | |
---|
140 | |
---|
141 | } // namespace Poco |
---|
142 | |
---|
143 | |
---|
144 | #endif // Foundation_Format_INCLUDED |
---|