/ 
DateTime-Format-Strptime-1.0301
River stage three • 132 direct dependents • 272 total dependents
/ DateTime::Format::Strptime

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',
  				language	=> 'English',
  				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',
  				language	=> 'English',
  				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 {
      tell_user($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 language. 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 value of $DateTime::Format::Strptime::CROAK.

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

  • language($language)

    When given a language, this method sets its language appropriately. If the language is not understood, the method will croak or return undef (depending on the value of $DateTime::Format::Strptime::CROAK)

    If successful this method returns the current language. (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 $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 language in use. (See DateTime::Language)

  • %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

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