1 //
2 // Format.h
3 //
4 // Library: Foundation
5 // Package: Core
6 // Module: Format
7 //
8 // Definition of the format freestanding function.
9 //
10 // Copyright (c) 2006, Applied Informatics Software Engineering GmbH.
11 // and Contributors.
12 //
13 // SPDX-License-Identifier: BSL-1.0
14 //
15
16
17 #ifndef Foundation_Format_INCLUDED
18 #define Foundation_Format_INCLUDED
19
20
21 #include "Poco/Foundation.h"
22 #include "Poco/Any.h"
23 #include <vector>
24 #include <type_traits>
25
26
27 namespace Poco {
28
29
30 std::string Foundation_API format(const std::string& fmt, const Any& value);
31 /// This function implements sprintf-style formatting in a typesafe way.
32 /// Various variants of the function are available, supporting a
33 /// different number of arguments (up to six).
34 ///
35 /// The formatting is controlled by the format string in fmt.
36 /// Format strings are quite similar to those of the std::printf() function, but
37 /// there are some minor differences.
38 ///
39 /// The format string can consist of any sequence of characters; certain
40 /// characters have a special meaning. Characters without a special meaning
41 /// are copied verbatim to the result. A percent sign (%) marks the beginning
42 /// of a format specification. Format specifications have the following syntax:
43 ///
44 /// %[<index>][<flags>][<width>][.<precision>][<modifier>]<type>
45 ///
46 /// Index, flags, width, precision and prefix are optional. The only required part of
47 /// the format specification, apart from the percent sign, is the type.
48 ///
49 /// The optional index argument has the format "[<n>]" and allows to
50 /// address an argument by its zero-based position (see the example below).
51 ///
52 /// Following are valid type specifications and their meaning:
53 ///
54 /// * b boolean (true = 1, false = 0)
55 /// * c character
56 /// * d signed decimal integer
57 /// * i signed decimal integer
58 /// * o unsigned octal integer
59 /// * u unsigned decimal integer
60 /// * x unsigned hexadecimal integer (lower case)
61 /// * X unsigned hexadecimal integer (upper case)
62 /// * e signed floating-point value in the form [-]d.dddde[<sign>]dd[d]
63 /// * E signed floating-point value in the form [-]d.ddddE[<sign>]dd[d]
64 /// * f signed floating-point value in the form [-]dddd.dddd
65 /// * s std::string
66 /// * z std::size_t
67 ///
68 /// The following flags are supported:
69 ///
70 /// * - left align the result within the given field width
71 /// * + prefix the output value with a sign (+ or -) if the output value is of a signed type
72 /// * 0 if width is prefixed with 0, zeros are added until the minimum width is reached
73 /// * # For o, x, X, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively;
74 /// for e, E, f, the # flag forces the output value to contain a decimal point in all cases.
75 ///
76 /// The following modifiers are supported:
77 ///
78 /// * (none) argument is char (c), int (d, i), unsigned (o, u, x, X) double (e, E, f, g, G) or string (s)
79 /// * l argument is long (d, i), unsigned long (o, u, x, X) or long double (e, E, f, g, G)
80 /// * L argument is long long (d, i), unsigned long long (o, u, x, X)
81 /// * h argument is short (d, i), unsigned short (o, u, x, X) or float (e, E, f, g, G)
82 /// * ? argument is any signed or unsigned int, short, long, or 64-bit integer (d, i, o, x, X)
83 ///
84 /// The width argument is a nonnegative decimal integer or '*' with an additional nonnegative integer value
85 /// preceding the value to be formated, controlling the minimum number of characters printed.
86 /// If the number of characters in the output value is less than the specified width, blanks or
87 /// leading zeros are added, according to the specified flags (-, +, 0).
88 ///
89 /// Precision is a nonnegative decimal integer or '*' with an additional nonnegative integer value preceding
90 /// the value to be formated, preceded by a period (.), which specifies the number of characters
91 /// to be printed, the number of decimal places, or the number of significant digits.
92 ///
93 /// Throws an InvalidArgumentException if an argument index is out of range.
94 ///
95 /// Starting with release 1.4.3, an argument that does not match the format
96 /// specifier no longer results in a BadCastException. The string [ERRFMT] is
97 /// written to the result string instead.
98 ///
99 /// If there are more format specifiers than values, the format specifiers without a corresponding value
100 /// are copied verbatim to output.
101 ///
102 /// If there are more values than format specifiers, the superfluous values are ignored.
103 ///
104 /// Usage Examples:
105 /// std::string s1 = format("The answer to life, the universe, and everything is %d", 42);
106 /// std::string s2 = format("second: %[1]d, first: %[0]d", 1, 2);
107
108 void Foundation_API format(std::string& result, const char *fmt, const std::vector<Any>& values);
109 /// Supports a variable number of arguments and is used by
110 /// all other variants of format().
111
112 void Foundation_API format(std::string& result, const std::string& fmt, const std::vector<Any>& values);
113 /// Supports a variable number of arguments and is used by
114 /// all other variants of format().
115
116
117 template <
118 typename T,
119 typename... Args>
format(std::string & result,const std::string & fmt,T arg1,Args...args)120 void format(std::string& result, const std::string& fmt, T arg1, Args... args)
121 /// Appends the formatted string to result.
122 {
123 std::vector<Any> values;
124 values.reserve(sizeof...(Args) + 1);
125 values.emplace_back(arg1);
126 values.insert(values.end(), { args... });
127 format(result, fmt, values);
128 }
129
130
131 template <
132 typename T,
133 typename... Args>
format(std::string & result,const char * fmt,T arg1,Args...args)134 void format(std::string& result, const char* fmt, T arg1, Args... args)
135 /// Appends the formatted string to result.
136 {
137 std::vector<Any> values;
138 values.reserve(sizeof...(Args) + 1);
139 values.emplace_back(arg1);
140 values.insert(values.end(), { args... });
141 format(result, fmt, values);
142 }
143
144
145 template <
146 typename T,
147 typename... Args>
format(const std::string & fmt,T arg1,Args...args)148 std::string format(const std::string& fmt, T arg1, Args... args)
149 /// Returns the formatted string.
150 {
151 std::vector<Any> values;
152 values.reserve(sizeof...(Args) + 1);
153 values.emplace_back(arg1);
154 values.insert(values.end(), { args... });
155 std::string result;
156 format(result, fmt, values);
157 return result;
158 }
159
160
161 template <
162 typename T,
163 typename... Args>
format(const char * fmt,T arg1,Args...args)164 std::string format(const char* fmt, T arg1, Args... args)
165 /// Returns the formatted string.
166 {
167 std::vector<Any> values;
168 values.reserve(sizeof...(Args) + 1);
169 values.emplace_back(arg1);
170 values.insert(values.end(), { args... });
171 std::string result;
172 format(result, fmt, values);
173 return result;
174 }
175
176
177 } // namespace Poco
178
179
180 #endif // Foundation_Format_INCLUDED
181