Class Poco::DateTimeParser

File Information

Library: Foundation
Package: DateTime
Header: Poco/DateTimeParser.h

Description

This class provides a method for parsing dates and times from strings. All parsing methods do their best to parse a meaningful result, even from malformed input strings.

The returned DateTime will always contain a time in the same timezone as the time in the string. Call DateTime::makeUTC() with the timeZoneDifferential returned by parse() to convert the DateTime to UTC.

Note: When parsing a time in 12-hour (AM/PM) format, the hour (%h) must be parsed before the AM/PM designator (%a, %A), otherwise the AM/PM designator will be ignored.

See the DateTimeFormatter class for a list of supported format specifiers. In addition to the format specifiers supported by DateTimeFormatter, an additional specifier is supported: %r will parse a year given by either two or four digits. Years 69-00 are interpreted in the 20th century (1969-2000), years 01-68 in the 21th century (2001-2068).

Note that in the current implementation all characters other than format specifiers in the format string are ignored/not matched against the date/time string. This may lead to non-error results even with nonsense input strings. This may change in a future version to a more strict behavior. If more strict format validation of date/time strings is required, a regular expression could be used for initial validation, before passing the string to DateTimeParser.

Member Summary

Member Functions: parse, parseAMPM, parseDayOfWeek, parseMonth, parseTZD, tryParse

Member Functions

parse

static void parse(
    const std::string & fmt,
    const std::string & str,
    DateTime & dateTime,
    int & timeZoneDifferential
);

Parses a date and time in the given format from the given string. Throws a SyntaxException if the string cannot be successfully parsed. Please see DateTimeFormatter::format() for a description of the format string. Class DateTimeFormat defines format strings for various standard date/time formats.

parse

static DateTime parse(
    const std::string & fmt,
    const std::string & str,
    int & timeZoneDifferential
);

parse

static void parse(
    const std::string & str,
    DateTime & dateTime,
    int & timeZoneDifferential
);

Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Throws a SyntaxException if the string cannot be successfully parsed. Please see DateTimeFormatter::format() for a description of the format string. Class DateTimeFormat defines format strings for various standard date/time formats.

parse

static DateTime parse(
const std::string & str,
int & timeZoneDifferential
);

Parses a date and time from the given dateTime string. Before parsing, the method examines the dateTime string for a known date/time format. Please see DateTimeFormatter::format() for a description of the format string. Class DateTimeFormat defines format strings for various standard date/time formats.

parseDayOfWeek

static int parseDayOfWeek(
std::string::const_iterator & it,
const std::string::const_iterator & end
);

Tries to interpret the given range as a weekday name. The range must be at least three characters long. Returns the weekday number (0 .. 6, where 0 = Sunday, 1 = Monday, etc.) if the weekday name is valid. Otherwise throws a SyntaxException.

parseMonth

static int parseMonth(
std::string::const_iterator & it,
const std::string::const_iterator & end
);

Tries to interpret the given range as a month name. The range must be at least three characters long. Returns the month number (1 .. 12) if the month name is valid. Otherwise throws a SyntaxException.

tryParse

static bool tryParse(
    const std::string & fmt,
    const std::string & str,
    DateTime & dateTime,
    int & timeZoneDifferential
);

Parses a date and time in the given format from the given string. Returns true if the string has been successfully parsed, false otherwise. Please see DateTimeFormatter::format() for a description of the format string. Class DateTimeFormat defines format strings for various standard date/time formats.