DateTime::Format::Strptime.3pm

Langue: en

Autres versions - même langue

Version: 2008-08-06 (fedora - 05/07/09)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

DateTime::Format::Strptime - Parse and format strp and strf time patterns

SYNOPSIS

   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,
                         );

DESCRIPTION

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.

CONSTRUCTOR

•
new( pattern=>$strptime_pattern )

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:

•
'undef'

(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.

•
'croak'

(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.

•
sub{...} or \&subname

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},

METHODS

This class offers the following methods.
•
parse_datetime($string)

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.

•
format_datetime($datetime)

Given a "DateTime" object, this methods returns a string formatted in the object's format. This method is synonymous with "DateTime"'s strftime method.

•
locale($locale)

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).

•
pattern($strptime_pattern)

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)

•
time_zone($time_zone)

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)

•
errmsg

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>

EXPORTS

There are no methods exported by default, however the following are available:
•
strptime($strptime_pattern, $string)

Given a pattern and a string this function will return a new "DateTime" object.

•
strftime($strftime_pattern, $datetime)

Given a pattern and a "DateTime" object this function will return a formatted string.

STRPTIME PATTERN TOKENS

The following tokens are allowed in the pattern string for strptime (parse_datetime):
•
%%

The % character.

•
%a or %A

The weekday name according to the current locale, in abbreviated form or the full name.

•
%b or %B or %h

The month name according to the current locale, in abbreviated form or the full name.

•
%C

The century number (0-99).

•
%d or %e

The day of month (1-31).

•
%D

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.)

•
%F

Equivalent to %Y-%m-%d. (This is the ISO style date)

•
%g

The year corresponding to the ISO week number, but without the century (0-99).

•
%G

The year corresponding to the ISO week number.

•
%H

The hour (0-23).

•
%I

The hour on a 12-hour clock (1-12).

•
%j

The day number in the year (1-366).

•
%m

The month number (1-12).

•
%M

The minute (0-59).

•
%n

Arbitrary whitespace.

•
%N

Nanoseconds. For other sub-second values use "%[number]N".

•
%p

The equivalent of AM or PM according to the locale in use. (See DateTime::Locale)

•
%r

Equivalent to %I:%M:%S %p.

•
%R

Equivalent to %H:%M.

•
%s

Number of seconds since the Epoch.

•
%S

The second (0-60; 60 may occur for leap seconds. See DateTime::LeapSecond).

•
%t

Arbitrary whitespace.

•
%T

Equivalent to %H:%M:%S.

•
%U

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.

•
%u

The weekday number (1-7) with Monday = 1. This is the "DateTime" standard.

•
%w

The weekday number (0-6) with Sunday = 0.

•
%W

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.

•
%y

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).

•
%Y

The year, including century (for example, 1991).

•
%z

An RFC-822/ISO 8601 standard time zone specification. (For example +1100) [See note below]

•
%Z

The timezone name. (For example EST --- which is ambiguous) [See note below]

•
%O

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()".

RESOURCES

•
Mailing List

Support for this module is primarily provided via the DateTime Mailing List: "datetime@perl.org"

http://lists.cpan.org/showlist.cgi?name=datetime

•
Bugtracker

For bug tracking and reporting, please use the google-code tracker rather than the RT interface linked at search.cpan.org

http://code.google.com/p/datetime-format-strptime/issues/list

•
Homepage

http://datetime-format-strptime.googlecode.com/

•
Subversion Repository

The latest version is always available via subversion:

http://datetime-format-strptime.googlecode.com/svn/trunk/

Copyright X Rick Measham, 2003-2007. 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.

AUTHOR

Rick Measham <rickm@cpan.org>

SEE ALSO

"datetime@perl.org" mailing list.

http://datetime.perl.org/

perl, DateTime, DateTime::TimeZone