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   => 'Melbourne/Australia',
  			);
  			
  my $dt = $Strp->parse_datetime('23:16:42');

  $Strp->format_datetime($dt);
	# 23:16:42

	
	
  # Stop croak so interactions work:

  my $Strp = new DateTime::Format::Strptime(
  				pattern 	=> '%T',
  				locale	    => 'en_AU',
  				time_zone	=> 'Melbourne/Australia',
  				on_error	=> 'undef',
  			);

  $pattern = $CGI->param('user_pattern');

  # This would normally croak with an invalid pattern:
  $newpattern = $Strp->pattern($pattern); 
  
  unless $newpattern {
      do_something_with($Strp->errmsg);
  }

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 strptime method.
locale($locale) =item * language($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).

For backwards compatability the language() method still exists. The method is deprecated and you are advised to update. Using the language method will result in a CORE::warn being generated.
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 $DateTime::Format::Strptime::CROAK)

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 $DateTime::Format::Strptime::CROAK)

If successful this method returns the current pattern. (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 $DateTime::Format::Strptime::CROAK being true:

$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 %Y-%m-%d.)
%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]

NOTES

on_error

Default behavior of this module is now to return undef on erroring.

SUPPORT

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.

LICENSE AND COPYRIGHT

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>

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)