1 | // |
2 | // DateTimeFormatter.h |
3 | // |
4 | // Library: Foundation |
5 | // Package: DateTime |
6 | // Module: DateTimeFormatter |
7 | // |
8 | // Definition of the DateTimeFormatter class. |
9 | // |
10 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
11 | // and Contributors. |
12 | // |
13 | // SPDX-License-Identifier: BSL-1.0 |
14 | // |
15 | |
16 | |
17 | #ifndef Foundation_DateTimeFormatter_INCLUDED |
18 | #define Foundation_DateTimeFormatter_INCLUDED |
19 | |
20 | |
21 | #include "Poco/Foundation.h" |
22 | #include "Poco/DateTime.h" |
23 | #include "Poco/LocalDateTime.h" |
24 | |
25 | |
26 | namespace Poco { |
27 | |
28 | |
29 | class Timestamp; |
30 | class Timespan; |
31 | |
32 | |
33 | class Foundation_API DateTimeFormatter |
34 | /// This class converts dates and times into strings, supporting a |
35 | /// variety of standard and custom formats. |
36 | /// |
37 | /// There are two kind of static member functions: |
38 | /// * format* functions return a std::string containing |
39 | /// the formatted value. |
40 | /// * append* functions append the formatted value to |
41 | /// an existing string. |
42 | { |
43 | public: |
44 | enum |
45 | { |
46 | UTC = 0xFFFF /// Special value for timeZoneDifferential denoting UTC. |
47 | }; |
48 | |
49 | static std::string format(const Timestamp& timestamp, const std::string& fmt, int timeZoneDifferential = UTC); |
50 | /// Formats the given timestamp according to the given format. |
51 | /// The format string is used as a template to format the date and |
52 | /// is copied character by character except for the following special characters, |
53 | /// which are replaced by the corresponding value. |
54 | /// |
55 | /// * %w - abbreviated weekday (Mon, Tue, ...) |
56 | /// * %W - full weekday (Monday, Tuesday, ...) |
57 | /// * %b - abbreviated month (Jan, Feb, ...) |
58 | /// * %B - full month (January, February, ...) |
59 | /// * %d - zero-padded day of month (01 .. 31) |
60 | /// * %e - day of month (1 .. 31) |
61 | /// * %f - space-padded day of month ( 1 .. 31) |
62 | /// * %m - zero-padded month (01 .. 12) |
63 | /// * %n - month (1 .. 12) |
64 | /// * %o - space-padded month ( 1 .. 12) |
65 | /// * %y - year without century (70) |
66 | /// * %Y - year with century (1970) |
67 | /// * %H - hour (00 .. 23) |
68 | /// * %h - hour (00 .. 12) |
69 | /// * %a - am/pm |
70 | /// * %A - AM/PM |
71 | /// * %M - minute (00 .. 59) |
72 | /// * %S - second (00 .. 59) |
73 | /// * %s - seconds and microseconds (equivalent to %S.%F) |
74 | /// * %i - millisecond (000 .. 999) |
75 | /// * %c - centisecond (0 .. 9) |
76 | /// * %F - fractional seconds/microseconds (000000 - 999999) |
77 | /// * %z - time zone differential in ISO 8601 format (Z or +NN.NN) |
78 | /// * %Z - time zone differential in RFC format (GMT or +NNNN) |
79 | /// * %% - percent sign |
80 | /// |
81 | /// Class DateTimeFormat defines format strings for various standard date/time formats. |
82 | |
83 | static std::string format(const DateTime& dateTime, const std::string& fmt, int timeZoneDifferential = UTC); |
84 | /// Formats the given date and time according to the given format. |
85 | /// See format(const Timestamp&, const std::string&, int) for more information. |
86 | |
87 | static std::string format(const LocalDateTime& dateTime, const std::string& fmt); |
88 | /// Formats the given local date and time according to the given format. |
89 | /// See format(const Timestamp&, const std::string&, int) for more information. |
90 | |
91 | static std::string format(const Timespan& timespan, const std::string& fmt = "%dd %H:%M:%S.%i" ); |
92 | /// Formats the given timespan according to the given format. |
93 | /// The format string is used as a template to format the date and |
94 | /// is copied character by character except for the following special characters, |
95 | /// which are replaced by the corresponding value. |
96 | /// |
97 | /// * %d - days |
98 | /// * %H - hours (00 .. 23) |
99 | /// * %h - total hours (0 .. n) |
100 | /// * %M - minutes (00 .. 59) |
101 | /// * %m - total minutes (0 .. n) |
102 | /// * %S - seconds (00 .. 59) |
103 | /// * %s - total seconds (0 .. n) |
104 | /// * %i - milliseconds (000 .. 999) |
105 | /// * %c - centisecond (0 .. 9) |
106 | /// * %F - fractional seconds/microseconds (000000 - 999999) |
107 | /// * %% - percent sign |
108 | |
109 | static void append(std::string& str, const Timestamp& timestamp, const std::string& fmt, int timeZoneDifferential = UTC); |
110 | /// Formats the given timestamp according to the given format and appends it to str. |
111 | /// |
112 | /// See format() for documentation of the formatting string. |
113 | |
114 | static void append(std::string& str, const DateTime& dateTime, const std::string& fmt, int timeZoneDifferential = UTC); |
115 | /// Formats the given date and time according to the given format and appends it to str. |
116 | /// |
117 | /// See format() for documentation of the formatting string. |
118 | |
119 | static void append(std::string& str, const LocalDateTime& dateTime, const std::string& fmt); |
120 | /// Formats the given local date and time according to the given format and appends it to str. |
121 | /// |
122 | /// See format() for documentation of the formatting string. |
123 | |
124 | static void append(std::string& str, const Timespan& timespan, const std::string& fmt = "%dd %H:%M:%S.%i" ); |
125 | /// Formats the given timespan according to the given format and appends it to str. |
126 | /// |
127 | /// See format() for documentation of the formatting string. |
128 | |
129 | static std::string tzdISO(int timeZoneDifferential); |
130 | /// Formats the given timezone differential in ISO format. |
131 | /// If timeZoneDifferential is UTC, "Z" is returned, |
132 | /// otherwise, +HH.MM (or -HH.MM) is returned. |
133 | |
134 | static std::string tzdRFC(int timeZoneDifferential); |
135 | /// Formats the given timezone differential in RFC format. |
136 | /// If timeZoneDifferential is UTC, "GMT" is returned, |
137 | /// otherwise ++HHMM (or -HHMM) is returned. |
138 | |
139 | static void tzdISO(std::string& str, int timeZoneDifferential); |
140 | /// Formats the given timezone differential in ISO format |
141 | /// and appends it to the given string. |
142 | /// If timeZoneDifferential is UTC, "Z" is returned, |
143 | /// otherwise, +HH.MM (or -HH.MM) is returned. |
144 | |
145 | static void tzdRFC(std::string& str, int timeZoneDifferential); |
146 | /// Formats the given timezone differential in RFC format |
147 | /// and appends it to the given string. |
148 | /// If timeZoneDifferential is UTC, "GMT" is returned, |
149 | /// otherwise ++HHMM (or -HHMM) is returned. |
150 | }; |
151 | |
152 | |
153 | // |
154 | // inlines |
155 | // |
156 | inline std::string DateTimeFormatter::format(const Timestamp& timestamp, const std::string& fmt, int timeZoneDifferential) |
157 | { |
158 | DateTime dateTime(timestamp); |
159 | return format(dateTime, fmt, timeZoneDifferential); |
160 | } |
161 | |
162 | |
163 | inline std::string DateTimeFormatter::format(const DateTime& dateTime, const std::string& fmt, int timeZoneDifferential) |
164 | { |
165 | std::string result; |
166 | result.reserve(64); |
167 | append(result, dateTime, fmt, timeZoneDifferential); |
168 | return result; |
169 | } |
170 | |
171 | |
172 | inline std::string DateTimeFormatter::format(const LocalDateTime& dateTime, const std::string& fmt) |
173 | { |
174 | return format(dateTime._dateTime, fmt, dateTime._tzd); |
175 | } |
176 | |
177 | |
178 | inline std::string DateTimeFormatter::format(const Timespan& timespan, const std::string& fmt) |
179 | { |
180 | std::string result; |
181 | result.reserve(32); |
182 | append(result, timespan, fmt); |
183 | return result; |
184 | } |
185 | |
186 | |
187 | inline void DateTimeFormatter::append(std::string& str, const Timestamp& timestamp, const std::string& fmt, int timeZoneDifferential) |
188 | { |
189 | DateTime dateTime(timestamp); |
190 | append(str, dateTime, fmt, timeZoneDifferential); |
191 | } |
192 | |
193 | |
194 | inline std::string DateTimeFormatter::tzdISO(int timeZoneDifferential) |
195 | { |
196 | std::string result; |
197 | result.reserve(8); |
198 | tzdISO(result, timeZoneDifferential); |
199 | return result; |
200 | } |
201 | |
202 | |
203 | inline std::string DateTimeFormatter::tzdRFC(int timeZoneDifferential) |
204 | { |
205 | std::string result; |
206 | result.reserve(8); |
207 | tzdRFC(result, timeZoneDifferential); |
208 | return result; |
209 | } |
210 | |
211 | |
212 | } // namespace Poco |
213 | |
214 | |
215 | #endif // Foundation_DateTimeFormatter_INCLUDED |
216 | |