.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DateTime::Format::Pg 3pm"
.TH DateTime::Format::Pg 3pm "2017-08-03" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Format::Pg \- Parse and format PostgreSQL dates and times
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use DateTime::Format::Pg;
\&
\&  my $dt = DateTime::Format::Pg\->parse_datetime( \*(Aq2003\-01\-16 23:12:01\*(Aq );
\&
\&  # 2003\-01\-16 23:12:01
\&  DateTime::Format::Pg\->format_datetime($dt);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module understands the formats used by PostgreSQL for its \s-1DATE, TIME,
TIMESTAMP,\s0 and \s-1INTERVAL\s0 data types.  It can be used to parse these formats in
order to create \f(CW\*(C`DateTime\*(C'\fR or \f(CW\*(C`DateTime::Duration\*(C'\fR objects, and it can take a
\&\f(CW\*(C`DateTime\*(C'\fR or \f(CW\*(C`DateTime::Duration\*(C'\fR object and produce a string representing
it in a format accepted by PostgreSQL.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
The following methods can be used to create \f(CW\*(C`DateTime::Format::Pg\*(C'\fR objects.
.IP "\(bu" 4
new( name => value, ... )
.Sp
Creates a new \f(CW\*(C`DateTime::Format::Pg\*(C'\fR 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.
.Sp
.Vb 2
\&  my $parser = DateTime::Format::Pg\->new()
\&  my $copy = $parser\->new( \*(Aqeuropean\*(Aq => 1 );
.Ve
.Sp
This method accepts the following options:
.RS 4
.IP "\(bu" 8
european
.Sp
If european is set to non-zero, dates are assumed to be in european
dd/mm/yyyy format. The default is to assume \s-1US\s0 mm/dd/yyyy format
(because this is the default for PostgreSQL).
.Sp
This option only has an effect if PostgreSQL is set to output dates in
the 'PostgreSQL' (\s-1DATE\s0 only) and '\s-1SQL\s0' (\s-1DATE\s0 and \s-1TIMESTAMP\s0) styles.
.Sp
Note that you don't have to set this option if the PostgreSQL server has
been set to use the '\s-1ISO\s0' format, which is the default.
.IP "\(bu" 8
server_tz
.Sp
This option can be set to a \f(CW\*(C`DateTime::TimeZone\*(C'\fR object or a string
that contains a time zone name.
.Sp
This value must be set to the same value as the PostgreSQL server's time
zone in order to parse \s-1TIMESTAMP WITH TIMEZONE\s0 values in the
\&'PostgreSQL', '\s-1SQL\s0', and 'German' formats correctly.
.Sp
Note that you don't have to set this option if the PostgreSQL server has
been set to use the '\s-1ISO\s0' format, which is the default.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\fIclone()\fR
.Sp
This method is provided for those who prefer to explicitly clone via a
method called \f(CW\*(C`clone()\*(C'\fR.
.Sp
.Vb 1
\&   my $clone = $original\->clone();
.Ve
.Sp
If called as a class method it will die.
.SH "METHODS"
.IX Header "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 \f(CW\*(C`DateTime::Format\*(C'\fR modules.
.PP
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 \s-1TIMESTAMP\s0 type was equivalent
to the \s-1TIMESTAMP WITH TIME ZONE\s0 type. This data type corresponds to the
format/parse_timestamp_with_time_zone method but not to the
format/parse_timestamp method.)
.SS "\s-1PARSING METHODS\s0"
.IX Subsection "PARSING METHODS"
This class provides the following parsing methods.
.PP
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
\&'\s-1SQL\s0' 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 '\s-1ISO\s0'.
.PP
The default DateStyle, '\s-1ISO\s0', will always produce unambiguous results
and is also parsed most efficiently by this parser class. I strongly
recommend using this setting unless you have a good reason not to.
.IP "\(bu" 4
parse_datetime($string,...)
.Sp
Given a string containing a date and/or time representation, this method
will return a new \f(CW\*(C`DateTime\*(C'\fR object.
.Sp
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.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_timestamptz($string,...)
.IP "\(bu" 4
parse_timestamp_with_time_zone($string,...)
.Sp
Given a string containing a timestamp (date and time) representation,
this method will return a new \f(CW\*(C`DateTime\*(C'\fR object. This method is
suitable for the \s-1TIMESTAMPTZ\s0 (or \s-1TIMESTAMP WITH TIME ZONE\s0) type.
.Sp
If the input string does not contain a time zone, it is set to the
floating time zone.
.Sp
Please note that PostgreSQL does not actually store a time zone along
with the \s-1TIMESTAMP WITH TIME ZONE\s0 (or \s-1TIMESTAMPTZ\s0) type but will just
return a time stamp converted for the server's local time zone.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_timestamp($string,...)
.IP "\(bu" 4
parse_timestamp_without_time_zone($string,...)
.Sp
Similar to the functions above, but always returns a \f(CW\*(C`DateTime\*(C'\fR object
with a floating time zone. This method is suitable for the \s-1TIMESTAMP\s0 (or
\&\s-1TIMESTAMP WITHOUT TIME ZONE\s0) type.
.Sp
If the server does return a time zone, it is ignored.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_timetz($string,...)
.IP "\(bu" 4
parse_time_with_time_zone($string,...)
.Sp
Given a string containing a time representation, this method will return
a new \f(CW\*(C`DateTime\*(C'\fR object. The date is set to 1970\-01\-01. This method is
suitable for the \s-1TIMETZ\s0 (or \s-1TIME WITH TIME ZONE\s0) type.
.Sp
If the input string does not contain a time zone, it is set to the
floating time zone.
.Sp
Please note that PostgreSQL stores a numerical offset with its \s-1TIME WITH
TIME ZONE\s0 (or \s-1TIMETZ\s0) type. It does not store a time zone name (such as
\&'Europe/Rome').
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_time($string,...)
.IP "\(bu" 4
parse_time_without_time_zone($string,...)
.Sp
Similar to the functions above, but always returns an \f(CW\*(C`DateTime\*(C'\fR object
with a floating time zone. If the server returns a time zone, it is
ignored. This method is suitable for use with the \s-1TIME\s0 (or \s-1TIME WITHOUT
TIME ZONE\s0) type.
.Sp
This ensures that the resulting \f(CW\*(C`DateTime\*(C'\fR object will always have the
time zone expected by your application.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_date($string,...)
.Sp
Given a string containing a date representation, this method will return
a new \f(CW\*(C`DateTime\*(C'\fR object. The time is set to 00:00:00 (floating time
zone). This method is suitable for the \s-1DATE\s0 type.
.Sp
If given an improperly formatted string, this method may die.
.IP "\(bu" 4
parse_duration($string)
.IP "\(bu" 4
parse_interval($string)
.Sp
Given a string containing a duration (\s-1SQL\s0 type \s-1INTERVAL\s0) representation,
this method will return a new \f(CW\*(C`DateTime::Duration\*(C'\fR object.
.Sp
If given an improperly formatted string, this method may die.
.SS "\s-1FORMATTING METHODS\s0"
.IX Subsection "FORMATTING METHODS"
This class provides the following formatting methods.
.PP
The output is always in the format mandated by the \s-1SQL\s0 standard (derived
from \s-1ISO 8601\s0), which is parsed by PostgreSQL unambiguously in all
DateStyle modes.
.IP "\(bu" 4
format_datetime($datetime,...)
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string appropriate as
input for all date and date/time types of PostgreSQL. It will contain
date and time.
.Sp
If the time zone of the \f(CW\*(C`DateTime\*(C'\fR part is floating, the resulting
string will contain no time zone, which will result in the server's time
zone being used. Otherwise, the numerical offset of the time zone is
used.
.IP "\(bu" 4
format_time($datetime,...)
.IP "\(bu" 4
format_time_without_time_zone($datetime,...)
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string appropriate as
input for the \s-1TIME\s0 type (also known as \s-1TIME WITHOUT TIME ZONE\s0), which
will contain the local time of the \f(CW\*(C`DateTime\*(C'\fR object and no time zone.
.IP "\(bu" 4
format_timetz($datetime)
.IP "\(bu" 4
format_time_with_time_zone($datetime)
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string appropriate as
input for the \s-1TIME WITH TIME ZONE\s0 type (also known as \s-1TIMETZ\s0), which
will contain the local part of the \f(CW\*(C`DateTime\*(C'\fR object and a numerical
time zone.
.Sp
You should not use the \s-1TIME WITH TIME ZONE\s0 type to store dates with
floating time zones.  If the time zone of the \f(CW\*(C`DateTime\*(C'\fR part is
floating, the resulting string will contain no time zone, which will
result in the server's time zone being used.
.IP "\(bu" 4
format_date($datetime)
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string appropriate as
input for the \s-1DATE\s0 type, which will contain the date part of the
\&\f(CW\*(C`DateTime\*(C'\fR object.
.IP "\(bu" 4
format_timestamp($datetime)
.IP "\(bu" 4
format_timestamp_without_time_zone($datetime)
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string appropriate as
input for the \s-1TIMESTAMP\s0 type (also known as \s-1TIMESTAMP WITHOUT TIME
ZONE\s0), which will contain the local time of the \f(CW\*(C`DateTime\*(C'\fR object and
no time zone.
.IP "\(bu" 4
format_timestamptz($datetime)
.IP "\(bu" 4
format_timestamp_with_time_zone($datetime)
.Sp
Given a \f(CW\*(C`DateTime\*(C'\fR object, this method returns a string appropriate as
input for the \s-1TIMESTAMP WITH TIME ZONE\s0 type, which will contain the
local part of the \f(CW\*(C`DateTime\*(C'\fR object and a numerical time zone.
.Sp
You should not use the \s-1TIMESTAMP WITH TIME ZONE\s0 type to store dates with
floating time zones.  If the time zone of the \f(CW\*(C`DateTime\*(C'\fR part is
floating, the resulting string will contain no time zone, which will
result in the server's time zone being used.
.IP "\(bu" 4
format_duration($du)
.IP "\(bu" 4
format_interval($du)
.Sp
Given a \f(CW\*(C`DateTime::Duration\*(C'\fR object, this method returns a string appropriate
as input for the \s-1INTERVAL\s0 type.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Some output formats of PostgreSQL have limitations that can only be passed on
by this class.
.PP
As a general rules, none of these limitations apply to the '\s-1ISO\s0' output
format.  It is strongly recommended to use this format (and to use
PostgreSQL's to_char function when another output format that's not
supposed to be handled by a parser of this class is desired). '\s-1ISO\s0' is
the default but you are advised to explicitly set it at the beginning of
the session by issuing a \s-1SET DATESTYLE TO\s0 '\s-1ISO\s0'; command in case the
server administrator changes that setting.
.PP
When formatting DateTime objects, this class always uses a format that's
handled unambiguously by PostgreSQL.
.SS "\s-1TIME ZONES\s0"
.IX Subsection "TIME ZONES"
If DateStyle is set to 'PostgreSQL', '\s-1SQL\s0', or 'German', PostgreSQL does
not send numerical time zones for the \s-1TIMESTAMPTZ\s0 (or \s-1TIMESTAMP WITH
TIME ZONE\s0) type. Unfortunately, the time zone names used instead can be
ambiguous: For example, '\s-1EST\s0' can mean \-0500, +1000, or +1100.
.PP
You must set the 'server_tz' variable to a time zone that is identical to that
of the PostgreSQL server. If the server is set to a different time zone (or the
underlying operating system interprets the time zone differently), the parser
will return wrong times.
.PP
You can avoid such problems by setting the server's time zone to \s-1UTC\s0
using the \s-1SET TIME ZONE\s0 '\s-1UTC\s0' command and setting 'server_tz' parameter
to '\s-1UTC\s0' (or by using the \s-1ISO\s0 output format, of course).
.SS "\s-1EUROPEAN DATES\s0"
.IX Subsection "EUROPEAN DATES"
For the \s-1SQL\s0 (for \s-1DATE\s0 and TIMSTAMP[\s-1TZ\s0]) and the PostgreSQL (for \s-1DATE\s0)
output format, the server can send dates in both European-style
\&'dd/mm/yyyy' and in US-style 'mm/dd/yyyy' format. In order to parse
these dates correctly, you have to pass the 'european' option to the
constructor or to the \f(CW\*(C`parse_xxx\*(C'\fR routines.
.PP
This problem does not occur when using the \s-1ISO\s0 or German output format
(and for PostgreSQL with TIMESTAMP[\s-1TZ\s0] as month names are used then).
.SS "\s-1INTERVAL ELEMENTS\s0"
.IX Subsection "INTERVAL ELEMENTS"
\&\f(CW\*(C`DateTime::Duration\*(C'\fR stores months, days, minutes and seconds
separately. PostgreSQL only stores months and seconds and disregards the
irregular length of days due to \s-1DST\s0 switching and the irregular length
of minutes due to leap seconds. Therefore, it is not possible to store
\&\f(CW\*(C`DateTime::Duration\*(C'\fR objects as \s-1SQL\s0 INTERVALs without the loss of some
information.
.SS "\s-1NEGATIVE INTERVALS\s0"
.IX Subsection "NEGATIVE INTERVALS"
In the \s-1SQL\s0 and German output formats, the server does not send an
indication of the sign with intervals. This means that '1 month ago' and
\&'1 month' are both returned as '1 mon'.
.PP
This problem can only be avoided by using the '\s-1ISO\s0' or 'PostgreSQL'
output format.
.SH "SUPPORT"
.IX Header "SUPPORT"
Support for this module is provided via the datetime@perl.org email
list.  See http://lists.perl.org/ for more details.
.SH "AUTHOR"
.IX Header "AUTHOR"
Daisuke Maki <daisuke@endeworks.jp>
.SH "AUTHOR EMERITUS"
.IX Header "AUTHOR EMERITUS"
Claus A. Faerber <perl@faerber.muc.de>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003 Claus A. Faerber. Copyright (c) 2005\-2007 Daisuke Maki
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included with
this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
datetime@perl.org mailing list
.PP
http://datetime.perl.org/