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
26namespace Poco {
27
28
29class Timestamp;
30class Timespan;
31
32
33class 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{
43public:
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//
156inline 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
163inline 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
172inline std::string DateTimeFormatter::format(const LocalDateTime& dateTime, const std::string& fmt)
173{
174 return format(dateTime._dateTime, fmt, dateTime._tzd);
175}
176
177
178inline 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
187inline 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
194inline 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
203inline 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