DateTime::Format::Strptime - Parse and format strp and strf time patterns
use DateTime::Format::Strptime;
my $Strp = new DateTime::Format::Strptime(
pattern => '%T',
locale => 'en_AU',
time_zone => 'Australia/Melbourne',
);
my $dt = $Strp->parse_datetime('23:16:42');
$Strp->format_datetime($dt);
# 23:16:42
# Croak when things go wrong:
my $Strp = new DateTime::Format::Strptime(
pattern => '%T',
locale => 'en_AU',
time_zone => 'Australia/Melbourne',
on_error => 'croak',
);
$newpattern = $Strp->pattern('%Q');
# Unidentified token in pattern: %Q in %Q at line 34 of script.pl
# Do something else when things go wrong:
my $Strp = new DateTime::Format::Strptime(
pattern => '%T',
locale => 'en_AU',
time_zone => 'Australia/Melbourne',
on_error => \&phone_police,
);
This module implements most of strptime(3), the POSIX function that is the reverse of strftime(3), for DateTime. While strftime takes a DateTime and a pattern and returns a string, strptime takes a string and a pattern and returns the DateTime object associated.
Creates the format object. You must specify a pattern, you can also specify a time_zone and a locale. If you specify a time zone then any resulting DateTime object will be in that time zone. If you do not specify a time_zone parameter, but there is a time zone in the string you pass to parse_datetime, then the resulting DateTime will use that time zone.
You can optionally use an on_error parameter. This parameter has three valid options:
(not undef, 'undef', it's a string not an undefined value)
This is the default behavior. The module will return undef whenever it gets upset. The error can be accessed using the $object->errstr method. This is the ideal behaviour for interactive use where a user might provide an illegal pattern or a date that doesn't match the pattern.
(not croak, 'croak', it's a string, not a function)
This used to be the default behaviour. The module will croak with an error message whenever it gets upset.
When given a code ref, the module will call that sub when it gets upset. The sub receives two parameters: the object and the error message. Using these two it is possible to emulate the 'undef' behavior. (Returning a true value causes the method to return undef. Returning a false value causes the method to bravely continue):
sub{$_[0]->{errmsg} = $_[1]; 1},
This class offers the following methods.
Given a string in the pattern specified in the constructor, this method will return a new DateTime object.
If given a string that doesn't match the pattern, the formatter will croak or return undef, depending on the setting of on_error in the constructor.
Given a DateTime object, this methods returns a string formatted in the object's format. This method is synonymous with DateTime's strftime method.
When given a locale, this method sets its locale appropriately. If the locale is not understood, the method will croak or return undef (depending on the setting of on_error in the constructor)
If successful this method returns the current locale. (After processing as above).
When given a pattern, this method sets the object's pattern. If the pattern is invalid, the method will croak or return undef (depending on the value of the on_error parameter)
If successful this method returns the current pattern. (After processing as above)
When given a name, offset or DateTime::TimeZone object, this method sets the object's time zone. This effects the DateTime object returned by parse_datetime
If the time zone is invalid, the method will croak or return undef (depending on the value of the on_error parameter)
If successful this method returns the current time zone. (After processing as above)
If the on_error behavior of the object is 'undef', error messages with this method so you can work out why things went wrong.
This code emulates a $DateTime::Format::Strptime with the on_error parameter equal to 'croak':
$Strp-pattern($pattern) or die $DateTime::Format::Strptime::errmsg>
There are no methods exported by default, however the following are available:
Given a pattern and a string this function will return a new DateTime object.
Given a pattern and a DateTime object this function will return a formatted string.
The following tokens are allowed in the pattern string for strptime (parse_datetime):
The % character.
The weekday name according to the current locale, in abbreviated form or the full name.
The month name according to the current locale, in abbreviated form or the full name.
The century number (0-99).
The day of month (1-31).
Equivalent to %m/%d/%y. (This is the American style date, very confusing to non-Americans, especially since %d/%m/%y is widely used in Europe. The ISO 8601 standard pattern is %F.)
Equivalent to %Y-%m-%d. (This is the ISO style date)
The year corresponding to the ISO week number, but without the century (0-99).
The year corresponding to the ISO week number.
The hour (0-23).
The hour on a 12-hour clock (1-12).
The day number in the year (1-366).
The month number (1-12).
The minute (0-59).
Arbitrary whitespace.
Nanoseconds. For other sub-second values use %[number]N.
The equivalent of AM or PM according to the locale in use. (See DateTime::Locale)
Equivalent to %I:%M:%S %p.
Equivalent to %H:%M.
Number of seconds since the Epoch.
The second (0-60; 60 may occur for leap seconds. See DateTime::LeapSecond).
Arbitrary whitespace.
Equivalent to %H:%M:%S.
The week number with Sunday the first day of the week (0-53). The first Sunday of January is the first day of week 1.
The weekday number (1-7) with Monday = 1. This is the DateTime standard.
The weekday number (0-6) with Sunday = 0.
The week number with Monday the first day of the week (0-53). The first Monday of January is the first day of week 1.
The year within century (0-99). When a century is not otherwise specified, values in the range 69-99 refer to years in the twen- tieth century (1969-1999); values in the range 00-68 refer to years in the twenty-first century (2000-2068).
The year, including century (for example, 1991).
An RFC-822/ISO 8601 standard time zone specification. (For example +1100) [See note below]
The timezone name. (For example EST -- which is ambiguous) [See note below]
This extended token allows the use of Olson Time Zone names to appear in parsed strings. NOTE: This pattern cannot be passed to DateTime's strftime() method, but can be passed to format_datetime().
Default behavior of this module is now to return undef on erroring.
Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.
Alternatively, log them via the CPAN RT system via the web or email:
bug-datetime-format-strptime@rt.cpan.org
This makes it much easier for me to track things and thus means your problem is less likely to be neglected.
Copyright © Rick Measham, 2003-2005. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the licenses can be found in the LICENCE file included with this module.
Rick Measham <rickm@cpan.org>
datetime@perl.org mailing list.
