|
|
|
@ -1,8 +1,11 @@ |
|
|
|
<!-- |
|
|
|
<!-- |
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.5 1999/10/12 13:57:04 thomas Exp $ |
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.6 2000/02/02 16:21:06 thomas Exp $ |
|
|
|
Date/time details |
|
|
|
Date/time details |
|
|
|
|
|
|
|
|
|
|
|
$Log: datetime.sgml,v $ |
|
|
|
$Log: datetime.sgml,v $ |
|
|
|
|
|
|
|
Revision 2.6 2000/02/02 16:21:06 thomas |
|
|
|
|
|
|
|
Add detailed information on Australian time zones. |
|
|
|
|
|
|
|
|
|
|
|
Revision 2.5 1999/10/12 13:57:04 thomas |
|
|
|
Revision 2.5 1999/10/12 13:57:04 thomas |
|
|
|
Sequence of date interpretation not quite right. |
|
|
|
Sequence of date interpretation not quite right. |
|
|
|
|
|
|
|
|
|
|
|
@ -422,185 +425,220 @@ Finish initial markup of cvs.sgml, and include it in the programmer's guide |
|
|
|
</tbody> |
|
|
|
</tbody> |
|
|
|
</tgroup> |
|
|
|
</tgroup> |
|
|
|
</table> |
|
|
|
</table> |
|
|
|
<note> |
|
|
|
|
|
|
|
<para> |
|
|
|
|
|
|
|
If the compiler option USE_AUSTRALIAN_RULES is set |
|
|
|
|
|
|
|
then <literal>EST</literal> refers to Australia Eastern Std Time, |
|
|
|
|
|
|
|
which has an offset of +10:00 hours from UTC. |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
|
|
|
Australian time zones and their naming variants |
|
|
|
|
|
|
|
account for fully one quarter of all time zones in the |
|
|
|
|
|
|
|
<productname>Postgres</productname> time zone lookup table. |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
</note> |
|
|
|
|
|
|
|
</para> |
|
|
|
</para> |
|
|
|
|
|
|
|
|
|
|
|
<procedure> |
|
|
|
<sect2> |
|
|
|
|
|
|
|
<title>Australian Time Zones</title> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
|
|
|
Australian time zones and their naming variants |
|
|
|
|
|
|
|
account for fully one quarter of all time zones in the |
|
|
|
|
|
|
|
<productname>Postgres</productname> time zone lookup table. |
|
|
|
|
|
|
|
There are two naming conflicts with common time zones defined |
|
|
|
|
|
|
|
in the United States, <literal>CST</literal> and <literal>EST</literal>. |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
|
|
|
|
If the compiler option USE_AUSTRALIAN_RULES is set |
|
|
|
|
|
|
|
then <literal>CST</literal> and <literal>EST</literal> will be |
|
|
|
|
|
|
|
interpreted using Australian conventions. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<table tocentry="1"> |
|
|
|
|
|
|
|
<title><productname>Postgres</productname> Australian Time Zones</title> |
|
|
|
|
|
|
|
<titleabbrev>Australian Time Zones</titleabbrev> |
|
|
|
|
|
|
|
<tgroup cols="3"> |
|
|
|
|
|
|
|
<thead> |
|
|
|
|
|
|
|
<row> |
|
|
|
|
|
|
|
<entry>Time Zone</entry> |
|
|
|
|
|
|
|
<entry>Offset from UTC</entry> |
|
|
|
|
|
|
|
<entry>Description</entry> |
|
|
|
|
|
|
|
</row> |
|
|
|
|
|
|
|
</thead> |
|
|
|
|
|
|
|
<tbody> |
|
|
|
|
|
|
|
<row> |
|
|
|
|
|
|
|
<entry>CST</entry> |
|
|
|
|
|
|
|
<entry>+10:30</entry> |
|
|
|
|
|
|
|
<entry>Australian Central Standard Time</entry> |
|
|
|
|
|
|
|
</row> |
|
|
|
|
|
|
|
<row> |
|
|
|
|
|
|
|
<entry>EST</entry> |
|
|
|
|
|
|
|
<entry>+10:00</entry> |
|
|
|
|
|
|
|
<entry>Australian Eastern Standard Time</entry> |
|
|
|
|
|
|
|
</row> |
|
|
|
|
|
|
|
</tbody> |
|
|
|
|
|
|
|
</tgroup> |
|
|
|
|
|
|
|
</table> |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
</sect2> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<sect2> |
|
|
|
<title>Date/Time Input Interpretation</title> |
|
|
|
<title>Date/Time Input Interpretation</title> |
|
|
|
|
|
|
|
|
|
|
|
<para> |
|
|
|
<para> |
|
|
|
The date/time types are all decoded using a common set of routines. |
|
|
|
The date/time types are all decoded using a common set of routines. |
|
|
|
</para> |
|
|
|
</para> |
|
|
|
|
|
|
|
|
|
|
|
<step> |
|
|
|
<procedure> |
|
|
|
<para> |
|
|
|
<title>Date/Time Input Interpretation</title> |
|
|
|
Break the input string into tokens and categorize each token as |
|
|
|
|
|
|
|
a string, time, time zone, or number. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
|
|
|
|
Break the input string into tokens and categorize each token as |
|
|
|
<substeps> |
|
|
|
a string, time, time zone, or number. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
|
|
|
|
If the token contains a colon (":"), this is a time string. |
|
|
|
<substeps> |
|
|
|
</para> |
|
|
|
<step> |
|
|
|
</step> |
|
|
|
<para> |
|
|
|
|
|
|
|
If the token contains a colon (":"), this is a time string. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the token contains a dash ("-"), slash ("/"), or dot ("."), |
|
|
|
|
|
|
|
this is a date string which may have a text month. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the token contains a dash ("-"), slash ("/"), or dot ("."), |
|
|
|
|
|
|
|
this is a date string which may have a text month. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the token is numeric only, then it is either a single field |
|
|
|
|
|
|
|
or an ISO-8601 concatenated date (e.g. "19990113" for January 13, 1999) |
|
|
|
<step> |
|
|
|
or time (e.g. 141516 for 14:15:16). |
|
|
|
<para> |
|
|
|
</para> |
|
|
|
If the token is numeric only, then it is either a single field |
|
|
|
</step> |
|
|
|
or an ISO-8601 concatenated date (e.g. "19990113" for January 13, 1999) |
|
|
|
<step> |
|
|
|
or time (e.g. 141516 for 14:15:16). |
|
|
|
<para> |
|
|
|
</para> |
|
|
|
If the token starts with a plus ("+") or minus ("-"), |
|
|
|
</step> |
|
|
|
then it is either a time zone or a special field. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the token starts with a plus ("+") or minus ("-"), |
|
|
|
</substeps> |
|
|
|
then it is either a time zone or a special field. |
|
|
|
</step> |
|
|
|
</para> |
|
|
|
|
|
|
|
</step> |
|
|
|
<step> |
|
|
|
</substeps> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the token is a text string, match up with possible strings. |
|
|
|
|
|
|
|
</para> |
|
|
|
<step> |
|
|
|
|
|
|
|
<para> |
|
|
|
<substeps> |
|
|
|
If the token is a text string, match up with possible strings. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
|
|
|
|
Do a binary-search table lookup for the token |
|
|
|
|
|
|
|
as either a special string (e.g. <literal>today</literal>), |
|
|
|
|
|
|
|
day (e.g. <literal>Thursday</literal>), |
|
|
|
|
|
|
|
month (e.g. <literal>January</literal>), |
|
|
|
|
|
|
|
or noise word (e.g. <literal>on</literal>). |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
<para> |
|
|
|
|
|
|
|
Set field values and bit mask for fields. |
|
|
|
|
|
|
|
For example, set year, month, day for <literal>today</literal>, |
|
|
|
|
|
|
|
and additionally hour, minute, second for <literal>now</literal>. |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
</step> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<step> |
|
|
|
<substeps> |
|
|
|
<para> |
|
|
|
<step> |
|
|
|
If not found, do a similar binary-search table lookup to match |
|
|
|
<para> |
|
|
|
the token with a time zone. |
|
|
|
Do a binary-search table lookup for the token |
|
|
|
</para> |
|
|
|
as either a special string (e.g. <literal>today</literal>), |
|
|
|
</step> |
|
|
|
day (e.g. <literal>Thursday</literal>), |
|
|
|
|
|
|
|
month (e.g. <literal>January</literal>), |
|
|
|
<step> |
|
|
|
or noise word (e.g. <literal>on</literal>). |
|
|
|
<para> |
|
|
|
</para> |
|
|
|
If not found, throw an error. |
|
|
|
<para> |
|
|
|
</para> |
|
|
|
Set field values and bit mask for fields. |
|
|
|
</step> |
|
|
|
For example, set year, month, day for <literal>today</literal>, |
|
|
|
</substeps> |
|
|
|
and additionally hour, minute, second for <literal>now</literal>. |
|
|
|
</step> |
|
|
|
</para> |
|
|
|
|
|
|
|
</step> |
|
|
|
<step> |
|
|
|
|
|
|
|
<para> |
|
|
|
<step> |
|
|
|
The token is a number or number field. |
|
|
|
<para> |
|
|
|
</para> |
|
|
|
If not found, do a similar binary-search table lookup to match |
|
|
|
|
|
|
|
the token with a time zone. |
|
|
|
<substeps> |
|
|
|
</para> |
|
|
|
<step> |
|
|
|
</step> |
|
|
|
<para> |
|
|
|
|
|
|
|
If there are more than 4 digits, |
|
|
|
<step> |
|
|
|
and if no other date fields have been previously read, then interpret |
|
|
|
<para> |
|
|
|
as a "concatenated date" (e.g. <literal>19990118</literal>). 8 |
|
|
|
If not found, throw an error. |
|
|
|
and 6 digits are interpreted as year, month, and day, while 7 |
|
|
|
</para> |
|
|
|
and 5 digits are interpreted as year, day of year, respectively. |
|
|
|
</step> |
|
|
|
</para> |
|
|
|
</substeps> |
|
|
|
</step> |
|
|
|
</step> |
|
|
|
|
|
|
|
|
|
|
|
<step> |
|
|
|
<step> |
|
|
|
<para> |
|
|
|
<para> |
|
|
|
If the token is three digits |
|
|
|
The token is a number or number field. |
|
|
|
and a year has already been decoded, then interpret as day of year. |
|
|
|
</para> |
|
|
|
</para> |
|
|
|
|
|
|
|
</step> |
|
|
|
<substeps> |
|
|
|
|
|
|
|
<step> |
|
|
|
<step> |
|
|
|
<para> |
|
|
|
<para> |
|
|
|
If there are more than 4 digits, |
|
|
|
If longer than two digits, then interpret as a year. |
|
|
|
and if no other date fields have been previously read, then interpret |
|
|
|
</para> |
|
|
|
as a "concatenated date" (e.g. <literal>19990118</literal>). 8 |
|
|
|
</step> |
|
|
|
and 6 digits are interpreted as year, month, and day, while 7 |
|
|
|
|
|
|
|
and 5 digits are interpreted as year, day of year, respectively. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If in European date mode, and if the day field has not yet been read, |
|
|
|
|
|
|
|
and if the value is less than or equal to 31, then interpret as a day. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the token is three digits |
|
|
|
|
|
|
|
and a year has already been decoded, then interpret as day of year. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the month field has not yet been read, |
|
|
|
|
|
|
|
and if the value is less than or equal to 12, then interpret as a month. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If longer than two digits, then interpret as a year. |
|
|
|
|
|
|
|
</para> |
|
|
|
<step> |
|
|
|
</step> |
|
|
|
<para> |
|
|
|
|
|
|
|
If the day field has not yet been read, |
|
|
|
<step> |
|
|
|
and if the value is less than or equal to 31, then interpret as a day. |
|
|
|
<para> |
|
|
|
</para> |
|
|
|
If in European date mode, and if the day field has not yet been read, |
|
|
|
</step> |
|
|
|
and if the value is less than or equal to 31, then interpret as a day. |
|
|
|
|
|
|
|
</para> |
|
|
|
<step> |
|
|
|
</step> |
|
|
|
<para> |
|
|
|
|
|
|
|
Otherwise, interpret as a year. |
|
|
|
<step> |
|
|
|
</para> |
|
|
|
<para> |
|
|
|
</step> |
|
|
|
If the month field has not yet been read, |
|
|
|
</substeps> |
|
|
|
and if the value is less than or equal to 12, then interpret as a month. |
|
|
|
</step> |
|
|
|
</para> |
|
|
|
|
|
|
|
</step> |
|
|
|
<step> |
|
|
|
|
|
|
|
<para> |
|
|
|
<step> |
|
|
|
If BC has been specified, negate the year and offset by one for |
|
|
|
<para> |
|
|
|
internal storage |
|
|
|
If the day field has not yet been read, |
|
|
|
(there is no year zero in the Gregorian calendar, so numerically |
|
|
|
and if the value is less than or equal to 31, then interpret as a day. |
|
|
|
1BC becomes year zero). |
|
|
|
</para> |
|
|
|
</para> |
|
|
|
</step> |
|
|
|
</step> |
|
|
|
|
|
|
|
|
|
|
|
<step> |
|
|
|
<step> |
|
|
|
<para> |
|
|
|
<para> |
|
|
|
Otherwise, interpret as a year. |
|
|
|
If BC was not specified, and if the year field was two digits in length, then |
|
|
|
</para> |
|
|
|
adjust the year to 4 digits. If the field was less than 70, then add 2000; |
|
|
|
</step> |
|
|
|
otherwise, add 1900. |
|
|
|
</substeps> |
|
|
|
|
|
|
|
</step> |
|
|
|
<tip> |
|
|
|
|
|
|
|
<para> |
|
|
|
<step> |
|
|
|
Gregorian years 1-99AD may be entered by using 4 digits with leading |
|
|
|
<para> |
|
|
|
zeros (e.g. 0099 is 99AD). Three digits are also accepted as a |
|
|
|
If BC has been specified, negate the year and offset by one for |
|
|
|
year under most circumstances, though depending on position the |
|
|
|
internal storage |
|
|
|
numeric string may |
|
|
|
(there is no year zero in the Gregorian calendar, so numerically |
|
|
|
be interpreted as doy instead. |
|
|
|
1BC becomes year zero). |
|
|
|
</para> |
|
|
|
</para> |
|
|
|
</tip> |
|
|
|
</step> |
|
|
|
</para> |
|
|
|
|
|
|
|
</step> |
|
|
|
<step> |
|
|
|
</procedure> |
|
|
|
<para> |
|
|
|
|
|
|
|
If BC was not specified, and if the year field was two digits in length, then |
|
|
|
|
|
|
|
adjust the year to 4 digits. If the field was less than 70, then add 2000; |
|
|
|
|
|
|
|
otherwise, add 1900. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<tip> |
|
|
|
|
|
|
|
<para> |
|
|
|
|
|
|
|
Gregorian years 1-99AD may be entered by using 4 digits with leading |
|
|
|
|
|
|
|
zeros (e.g. 0099 is 99AD). Three digits are also accepted as a |
|
|
|
|
|
|
|
year under most circumstances, though depending on position the |
|
|
|
|
|
|
|
numeric string may |
|
|
|
|
|
|
|
be interpreted as doy instead. |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
</tip> |
|
|
|
|
|
|
|
</para> |
|
|
|
|
|
|
|
</step> |
|
|
|
|
|
|
|
</procedure> |
|
|
|
|
|
|
|
</sect2> |
|
|
|
</sect1> |
|
|
|
</sect1> |
|
|
|
|
|
|
|
|
|
|
|
<sect1> |
|
|
|
<sect1> |
|
|
|
|
Thomas G. Lockhart
26 years ago