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
25namespace Poco {
26
27
28class 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{
53public:
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
103protected:
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