NAME
SYNOPSIS
DESCRIPTION
CONSTRUCTORS
METHODS
- PARSING METHODS
- FORMATTING METHODS
LIMITATIONS
SUPPORT
AUTHOR
COPYRIGHT
SEE ALSO

NAME

DateTime::Format::Pg - Parse and format PostgreSQL dates and times

SYNOPSIS

  use DateTime::Format::Pg;

  my $dt = DateTime::Format::Pg->parse_datetime( '2003-01-16 23:12:01' );

  # 2003-01-16T23:12:01+0200
  DateTime::Format::Pg->format_datetime($dt);

DESCRIPTION

This module understands the formats used by PostgreSQL for its DATE, TIME, TIMESTAMP, and INTERVAL data types. It can be used to parse these formats in order to create DateTime or DateTime::Duration objects, and it can take a DateTime or DateTime::Duration object and produce a string representing it in a format accepted by PostgreSQL.

CONSTRUCTORS

The following methods can be used to create DateTime::Format::Pg objects.

* new( name => value, ... )

Creates a new DateTime::Format::Pg instance. This is generally not required for simple operations. If you wish to use a different parsing style from the default then it is more comfortable to create an object.

  my $parser = DateTime::Format::Pg->new()
  my $copy = $parser->new( 'european' => 1 );

This method accepts the following options:

* european

If european is set to non-zero, dates are assumed to be in european dd/mm/yyyy format. The default is to assume US mm/dd/yyyy format (because this is the default for PostgreSQL).

This option only has an effect if PostgreSQL is set to output dates in the 'PostgreSQL' (DATE only) and 'SQL' (DATE and TIMESTAMP) styles.

Note that you don't have to set this option if the PostgreSQL server has been set to use the 'ISO' format, which is the default.

* server_tz

This option can be set to a DateTime::TimeZone object or a string that contains a time zone name.

This value must be set to the same value as the PostgreSQL server's time zone in order to parse TIMESTAMP WITH TIMEZONE values in the 'PostgreSQL', 'SQL', and 'German' formats correctly.

Note that you don't have to set this option if the PostgreSQL server has been set to use the 'ISO' format, which is the default.

* clone()

This method is provided for those who prefer to explicitly clone via a method called clone().

   my $clone = $original->clone();

If called as a class method it will die.

METHODS

This class provides the following methods. The parse_datetime, parse_duration, format_datetime, and format_duration methods are general-purpose methods provided for compatibility with other DateTime::Format modules.

The other methods are specific to the corresponding PostgreSQL date/time data types. The names of these methods are derived from the name of the PostgreSQL data type. (Note: Prior to PostgreSQL 7.3, the TIMESTAMP type was equivalent to the TIMESTAMP WITH TIME ZONE type. This data type corresponds to the format/parse_timestamp_with_time_zone method but not to the format/parse_timestamp method.)

PARSING METHODS

This class provides the following parsing methods.

As a general rule, the parsing methods accept input in any format that the PostgreSQL server can produce. However, if PostgreSQL's DateStyle is set to 'SQL' or 'PostgreSQL', dates can only be parsed correctly if the 'european' option is set correctly (i.e. same as the PostgreSQL server). The same is true for time zones and the 'australian_timezones' option in all modes but 'ISO'.

The default DateStyle, 'ISO', will always produce unambiguous results and is also parsed most efficiently by this parser class. I stronlgly recommend using this setting unless you have a good reason not to.

* parse_datetime($string,...)

Given a string containing a date and/or time representation, this method will return a new DateTime object.

If the input string does not contain a date, it is set to 1970-01-01. If the input string does not contain a time, it is set to 00:00:00. If the input string does not contain a time zone, it is set to the floating time zone.