GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
DateTime::Format::Flexible(3) User Contributed Perl Documentation DateTime::Format::Flexible(3)

DateTime::Format::Flexible - DateTime::Format::Flexible - Flexibly parse strings and turn them into DateTime objects.

  use DateTime::Format::Flexible;
  my $dt = DateTime::Format::Flexible->parse_datetime(
      'January 8, 1999'
  );
  # $dt = a DateTime object set at 1999-01-08T00:00:00

If you have ever had to use a program that made you type in the date a certain way and thought "Why can't the computer just figure out what date I wanted?", this module is for you.

DateTime::Format::Flexible attempts to take any string you give it and parse it into a DateTime object.

This module uses DateTime::Format::Builder under the covers.

Give it a string and it attempts to parse it and return a DateTime object.

If it cannot it will throw an exception.

 my $dt = DateTime::Format::Flexible->parse_datetime( $date );

 my $dt = DateTime::Format::Flexible->parse_datetime(
     $date,
     strip    => [qr{\.\z}],                  # optional, remove a trailing period
     tz_map   => {EDT => 'America/New_York'}, # optional, map the EDT timezone to America/New_York
     lang     => ['es'],                      # optional, only parse using spanish
     european => 1,                           # optional, catch some cases of DD-MM-YY
 );
  • "base" (optional)

    Does the same thing as the method "base". Sets a base datetime for incomplete dates. Requires a valid DateTime object as an argument.

    example:

     my $base_dt = DateTime->new( year => 2005, month => 2, day => 1 );
     my $dt = DateTime::Format::Flexible->parse_datetime(
        '18 Mar',
         base => $base_dt,
     );
     # $dt is now 2005-03-18T00:00:00
        
  • "strip" (optional)

    Remove a substring from the string you are trying to parse. You can pass multiple regexes in an arrayref.

    example:

     my $dt = DateTime::Format::Flexible->parse_datetime(
         '2011-04-26 00:00:00 (registry time)',
         strip => [qr{\(registry time\)\z}],
     );
     # $dt is now 2011-04-26T00:00:00
        

    This is helpful if you have a load of dates you want to normalize and you know of some weird formatting beforehand.

  • "tz_map" (optional)

    Map a given timezone to another recognized timezone Values are given as a hashref.

    example:

     my $dt = DateTime::Format::Flexible->parse_datetime(
         '25-Jun-2009 EDT',
         tz_map => {EDT => 'America/New_York'},
     );
     # $dt is now 2009-06-25T00:00:00 with a timezone of America/New_York
        

    This is helpful if you have a load of dates that have timezones that are not recognized by DateTime::Timezone.

  • "lang" (optional)

    Specify the language map plugins to use.

    When DateTime::Format::Flexible parses a date with a string in it, it will search for a way to convert that string to a number. By default it will search through all the language plugins to search for a match.

    NOTE: as of 0.22, it will only do this search if it detects a string in the given date.

    Setting "lang" this lets you limit the scope of the search.

    example:

     my $dt = DateTime::Format::Flexible->parse_datetime(
         'Wed, Jun 10, 2009',
         lang => ['en'],
     );
     # $dt is now 2009-06-10T00:00:00
        

    Currently supported languages are english (en), spanish (es) and german (de). Contributions, corrections, requests and examples are VERY welcome.

    See the DateTime::Format::Flexible::lang::en, DateTime::Format::Flexible::lang::es, and DateTime::Format::Flexible::lang::de for examples of the plugins.

  • "european" (optional)

    If european is set to a true value, an attempt will be made to parse as a DD-MM-YYYY date instead of the default MM-DD-YYYY. There is a chance that this will not do the right thing due to ambiguity.

    example:

     my $dt = DateTime::Format::Flexible->parse_datetime(
         '16/06/2010' , european => 1,
     );
     # $dt is now 2010-06-16T00:00:00
        
  • "MMYY" (optional)

    By default, this module will parse 12/10 as December 10th of the current year (MM/DD).

    If you want it to parse this as MM/YY instead, you can enable the "MMYY" option.

    example:

     my $dt = DateTime::Format::Flexible->parse_datetime('12/10');
     # $dt is now [current year]-12-10T00:00:00
    
     my $dt = DateTime::Format::Flexible->parse_datetime(
         '12/10', MMYY => 1,
     );
     # $dt is now 2010-12-01T00:00:00
        

    This is useful if you know you are going to be parsing a credit card expiration date.

gets/sets the base DateTime for incomplete dates. Requires a valid DateTime object as an argument when setting. This defaults to DateTime->now.

example:

 DateTime::Format::Flexible->base( DateTime->new(
     year => 2009, month => 6, day => 22
 ));
 my $dt = DateTime::Format::Flexible->parse_datetime( '23:59' );
 # $dt is now 2009-06-22T23:59:00

an alias for parse_datetime

A small list of supported formats:
YYYYMMDDTHHMMSS
YYYYMMDDTHHMM
YYYYMMDDTHH
YYYYMMDD
YYYYMM
MM-DD-YYYY
MM-D-YYYY
MM-DD-YY
M-DD-YY
YYYY/DD/MM
YYYY/M/DD
YYYY/MM/D
M-D
MM-D
M-D-Y
Month D, YYYY
Mon D, YYYY
Mon D, YYYY HH:MM:SS
... thousands more

there are 9000+ variations that are detected correctly in the test files (see t/data/* for most of them). If you can think of any that I do not cover, please let me know.

As of version 0.11 you will get a DateTime::Infinite::Future object if the passed in date is 'infinity' and a DateTime::Infinite::Past object if the passed in date is '-infinity'. If you are expecting these types of strings, you might want to check for 'is_infinite()' from the object returned.

example:

 my $dt = DateTime::Format::Flexible->parse_datetime( 'infinity' );
 if ( $dt->is_infinite )
 {
      # you have a Infinite object.
 }

You cannot use a 1 or 2 digit year as the first field unless the year is > 31:

 YY-MM-DD # not supported if YY is <= 31
 Y-MM-DD  # not supported

It gets confused with MM-DD-YY

Tom Heady <cpan@punch.net>

Copyright 2007-2018 Tom Heady.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
  • the Artistic License.

DateTime::Format::Builder, DateTime::Timezone, DateTime::Format::Natural
2021-07-07 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.