1 | // |
2 | // DateTimeParser.h |
3 | // |
4 | // Library: Foundation |
5 | // Package: DateTime |
6 | // Module: DateTimeParser |
7 | // |
8 | // Definition of the DateTimeParser 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_DateTimeParser_INCLUDED |
18 | #define Foundation_DateTimeParser_INCLUDED |
19 | |
20 | |
21 | #include "Poco/Foundation.h" |
22 | #include "Poco/DateTime.h" |
23 | |
24 | |
25 | namespace Poco { |
26 | |
27 | |
28 | class Foundation_API DateTimeParser |
29 | /// This class provides a method for parsing dates and times |
30 | /// from strings. All parsing methods do their best to |
31 | /// parse a meaningful result, even from malformed input |
32 | /// strings. |
33 | /// |
34 | /// The returned DateTime will always contain a time in the same |
35 | /// timezone as the time in the string. Call DateTime::makeUTC() |
36 | /// with the timeZoneDifferential returned by parse() to convert |
37 | /// the DateTime to UTC. |
38 | /// |
39 | /// Note: When parsing a time in 12-hour (AM/PM) format, the hour |
40 | /// (%h) must be parsed before the AM/PM designator (%a, %A), |
41 | /// otherwise the AM/PM designator will be ignored. |
42 | /// |
43 | /// See the DateTimeFormatter class for a list of supported format specifiers. |
44 | /// In addition to the format specifiers supported by DateTimeFormatter, an |
45 | /// additional specifier is supported: %r will parse a year given by either |
46 | /// two or four digits. Years 69-00 are interpreted in the 20th century |
47 | /// (1969-2000), years 01-68 in the 21th century (2001-2068). |
48 | /// |
49 | /// Note that only formats defined in this class are checked for validity. This may |
50 | /// lead to non-error results even with nonsense input strings for custom formats, |
51 | /// which will only throw exception if format or date/time string are empty. |
52 | { |
53 | public: |
54 | static void parse(const std::string& fmt, const std::string& str, DateTime& dateTime, int& timeZoneDifferential); |
55 | /// Parses a date and time in the given format from the given string. |
56 | /// Throws a SyntaxException if the string cannot be successfully parsed. |
57 | /// Please see DateTimeFormatter::format() for a description of the format string. |
58 | /// Class DateTimeFormat defines format strings for various standard date/time formats. |
59 | |
60 | static DateTime parse(const std::string& fmt, const std::string& str, int& timeZoneDifferential); |
61 | /// Parses a date and time in the given format from the given string. |
62 | /// Throws a SyntaxException if the string cannot be successfully parsed. |
63 | /// Please see DateTimeFormatter::format() for a description of the format string. |
64 | /// Class DateTimeFormat defines format strings for various standard date/time formats. |
65 | |
66 | static bool tryParse(const std::string& fmt, const std::string& str, DateTime& dateTime, int& timeZoneDifferential); |
67 | /// Parses a date and time in the given format from the given string. |
68 | /// Returns true if the string has been successfully parsed, false otherwise. |
69 | /// Please see DateTimeFormatter::format() for a description of the format string. |
70 | /// Class DateTimeFormat defines format strings for various standard date/time formats. |
71 | |
72 | static void parse(const std::string& str, DateTime& dateTime, int& timeZoneDifferential); |
73 | /// Parses a date and time from the given dateTime string. Before parsing, the method |
74 | /// examines the dateTime string for a known date/time format. |
75 | /// Throws a SyntaxException if the string cannot be successfully parsed. |
76 | /// Please see DateTimeFormatter::format() for a description of the format string. |
77 | /// Class DateTimeFormat defines format strings for various standard date/time formats. |
78 | |
79 | static DateTime parse(const std::string& str, int& timeZoneDifferential); |
80 | /// Parses a date and time from the given dateTime string. Before parsing, the method |
81 | /// examines the dateTime string for a known date/time format. |
82 | /// Please see DateTimeFormatter::format() for a description of the format string. |
83 | /// Class DateTimeFormat defines format strings for various standard date/time formats. |
84 | |
85 | static bool tryParse(const std::string& str, DateTime& dateTime, int& timeZoneDifferential); |
86 | /// Parses a date and time from the given dateTime string. Before parsing, the method |
87 | /// examines the dateTime string for a known date/time format. |
88 | /// Please see DateTimeFormatter::format() for a description of the format string. |
89 | /// Class DateTimeFormat defines format strings for various standard date/time formats. |
90 | |
91 | static int parseMonth(std::string::const_iterator& it, const std::string::const_iterator& end); |
92 | /// Tries to interpret the given range as a month name. The range must be at least |
93 | /// three characters long. |
94 | /// Returns the month number (1 .. 12) if the month name is valid. Otherwise throws |
95 | /// a SyntaxException. |
96 | |
97 | static int parseDayOfWeek(std::string::const_iterator& it, const std::string::const_iterator& end); |
98 | /// Tries to interpret the given range as a weekday name. The range must be at least |
99 | /// three characters long. |
100 | /// Returns the weekday number (0 .. 6, where 0 = Sunday, 1 = Monday, etc.) if the |
101 | /// weekday name is valid. Otherwise throws a SyntaxException. |
102 | |
103 | protected: |
104 | static int parseTZD(std::string::const_iterator& it, const std::string::const_iterator& end); |
105 | static int parseAMPM(std::string::const_iterator& it, const std::string::const_iterator& end, int hour); |
106 | }; |
107 | |
108 | |
109 | } // namespace Poco |
110 | |
111 | |
112 | #endif // Foundation_DateTimeParser_INCLUDED |
113 | |