Coverage Report

Created: 2025-06-13 06:07

/src/poco/Foundation/include/Poco/Format.h
Line
Count
Source (jump to first uncovered line)
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
  ///   * g use the shortest representation: %e or %f
66
  ///   * G use the shortest representation: %E or %F
67
  ///   * s std::string
68
  ///   * v std::string_view
69
  ///   * z std::size_t
70
  ///
71
  /// The following flags are supported:
72
  ///
73
  ///   * - left align the result within the given field width
74
  ///   * + prefix the output value with a sign (+ or -) if the output value is of a signed type
75
  ///   * 0 if width is prefixed with 0, zeros are added until the minimum width is reached
76
  ///   * # For o, x, X, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively;
77
  ///     for e, E, f, the # flag forces the output value to contain a decimal point in all cases.
78
  ///
79
  /// The following modifiers are supported:
80
  ///
81
  ///   * (none) argument is char (c), int (d, i), unsigned (o, u, x, X) double (e, E, f, g, G) or string (s)
82
  ///   * l      argument is long (d, i), unsigned long (o, u, x, X) or long double (e, E, f, g, G)
83
  ///   * L      argument is long long (d, i), unsigned long long (o, u, x, X)
84
  ///   * h      argument is short (d, i), unsigned short (o, u, x, X) or float (e, E, f, g, G)
85
  ///   * ?      argument is any signed or unsigned int, short, long, or 64-bit integer (d, i, o, x, X)
86
  ///
87
  /// The width argument is a nonnegative decimal integer or '*' with an additional nonnegative integer value
88
  /// preceding the value to be formated, controlling the minimum number of characters printed.
89
  /// If the number of characters in the output value is less than the specified width, blanks or
90
  /// leading zeros are added, according to the specified flags (-, +, 0).
91
  ///
92
  /// Precision is a nonnegative decimal integer or '*' with an additional nonnegative integer value preceding
93
  /// the value to be formated, preceded by a period (.), which specifies the number of characters
94
  /// to be printed, the number of decimal places, or the number of significant digits.
95
  ///
96
  /// Throws an InvalidArgumentException if an argument index is out of range.
97
  ///
98
  /// Starting with release 1.4.3, an argument that does not match the format
99
  /// specifier no longer results in a BadCastException. The string [ERRFMT] is
100
  /// written to the result string instead.
101
  ///
102
  /// If there are more format specifiers than values, the format specifiers without a corresponding value
103
  /// are copied verbatim to output.
104
  ///
105
  /// If there are more values than format specifiers, the superfluous values are ignored.
106
  ///
107
  /// Usage Examples:
108
  ///     std::string s1 = format("The answer to life, the universe, and everything is %d", 42);
109
  ///     std::string s2 = format("second: %[1]d, first: %[0]d", 1, 2);
110
111
void Foundation_API format(std::string& result, const char *fmt, const std::vector<Any>& values);
112
  /// Supports a variable number of arguments.
113
114
void Foundation_API format(std::string& result, const std::string& fmt, const std::vector<Any>& values);
115
  /// Supports a variable number of arguments.
116
117
inline void formatAny(std::string& result, const std::string& fmt, const std::vector<Any>& values)
118
  /// Supports a variable number of arguments and is used by
119
  /// all other variants of format().
120
0
{
121
0
  Poco::format(result, fmt, values);
122
0
}
123
124
inline void formatAny(std::string& result, const char *fmt, const std::vector<Any>& values)
125
  /// Supports a variable number of arguments and is used by
126
  /// all other variants of format().
127
4.54k
{
128
4.54k
  Poco::format(result, fmt, values);
129
4.54k
}
130
131
template <typename T, typename... Args>
132
void format(std::string& result, const std::string& fmt, T arg1, Args... args)
133
  /// Appends the formatted string to result.
134
0
{
135
0
  std::vector<Any> values;
136
0
  values.reserve(sizeof...(Args) + 1);
137
0
  values.emplace_back(arg1);
138
0
  values.insert(values.end(), { args... });
139
0
  formatAny(result, fmt, values);
140
0
}
141
142
143
template <typename T, typename... Args>
144
void format(std::string& result, const char* fmt, T arg1, Args... args)
145
  /// Appends the formatted string to result.
146
4.47k
{
147
4.47k
  std::vector<Any> values;
148
4.47k
  values.reserve(sizeof...(Args) + 1);
149
4.47k
  values.emplace_back(arg1);
150
4.47k
  values.insert(values.end(), { args... });
151
4.47k
  formatAny(result, fmt, values);
152
4.47k
}
153
154
155
template <typename T, typename... Args>
156
std::string format(const std::string& fmt, T arg1, Args... args)
157
  /// Returns the formatted string.
158
{
159
  std::vector<Any> values;
160
  values.reserve(sizeof...(Args) + 1);
161
  values.emplace_back(arg1);
162
  values.insert(values.end(), { args... });
163
  std::string result;
164
  formatAny(result, fmt, values);
165
  return result;
166
}
167
168
169
template <typename T, typename... Args>
170
std::string format(const char* fmt, T arg1, Args... args)
171
  /// Returns the formatted string.
172
70
{
173
70
  std::vector<Any> values;
174
70
  values.reserve(sizeof...(Args) + 1);
175
70
  values.emplace_back(arg1);
176
70
  values.insert(values.end(), { args... });
177
70
  std::string result;
178
70
  formatAny(result, fmt, values);
179
70
  return result;
180
70
}
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<int>(char const*, int)
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<short, short, short, short, short, short, short, short, int>(char const*, short, short, short, short, short, short, short, short, int)
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<unsigned long, unsigned long>(char const*, unsigned long, unsigned long)
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<std::__1::basic_string_view<char, std::__1::char_traits<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, int, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, int, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > >(char const*, std::__1::basic_string_view<char, std::__1::char_traits<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, int, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, int, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >)
std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > >(char const*, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >)
Line
Count
Source
172
70
{
173
70
  std::vector<Any> values;
174
70
  values.reserve(sizeof...(Args) + 1);
175
70
  values.emplace_back(arg1);
176
70
  values.insert(values.end(), { args... });
177
70
  std::string result;
178
70
  formatAny(result, fmt, values);
179
70
  return result;
180
70
}
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > >(char const*, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >)
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >>(char const*, std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >)
Unexecuted instantiation: std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > Poco::format<int, int>(char const*, int, int)
181
182
183
} // namespace Poco
184
185
186
#endif // Foundation_Format_INCLUDED