Skip to content

P
Postgres FD Implementation
Commit 2f03ae69 authored by Tom Lane's avatar Tom Lane
Browse files
Options

Docs: improve descriptions of ISO week-numbering date features. 

Use the phraseology "ISO 8601 week-numbering year" in place of just
"ISO year", and make related adjustments to other terminology.

The point of this change is that it seems some people see "ISO year"
and think "standard year", whereupon they're surprised when constructs
like to_char(..., "IYYY-MM-DD") produce nonsensical results.  Perhaps
hanging a few more adjectives on it will discourage them from jumping
to false conclusions.  I put in an explicit warning against that
specific usage, too, though the main point is to discourage people
who haven't read this far down the page.

In passing fix some nearby markup and terminology inconsistencies.
parent a486841e
Hide whitespace changes
Inline Side-by-side
Showing with 55 additions and 38 deletions
doc/src/sgml/func.sgml
View file @ 2f03ae69
...@@ -5544,11 +5544,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5544,11 +5544,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row> </row>
<row> <row>
<entry><literal>Y,YYY</literal></entry> <entry><literal>Y,YYY</literal></entry>
<entry>year (4 and more digits) with comma</entry> <entry>year (4 or more digits) with comma</entry>
</row> </row>
<row> <row>
<entry><literal>YYYY</literal></entry> <entry><literal>YYYY</literal></entry>
<entry>year (4 and more digits)</entry> <entry>year (4 or more digits)</entry>
</row> </row>
<row> <row>
<entry><literal>YYY</literal></entry> <entry><literal>YYY</literal></entry>
...@@ -5564,19 +5564,19 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5564,19 +5564,19 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row> </row>
<row> <row>
<entry><literal>IYYY</literal></entry> <entry><literal>IYYY</literal></entry>
<entry>ISO year (4 and more digits)</entry> <entry>ISO 8601 week-numbering year (4 or more digits)</entry>
</row> </row>
<row> <row>
<entry><literal>IYY</literal></entry> <entry><literal>IYY</literal></entry>
<entry>last 3 digits of ISO year</entry> <entry>last 3 digits of ISO 8601 week-numbering year</entry>
</row> </row>
<row> <row>
<entry><literal>IY</literal></entry> <entry><literal>IY</literal></entry>
<entry>last 2 digits of ISO year</entry> <entry>last 2 digits of ISO 8601 week-numbering year</entry>
</row> </row>
<row> <row>
<entry><literal>I</literal></entry> <entry><literal>I</literal></entry>
<entry>last digit of ISO year</entry> <entry>last digit of ISO 8601 week-numbering year</entry>
</row> </row>
<row> <row>
<entry><literal>BC</literal>, <literal>bc</literal>, <entry><literal>BC</literal>, <literal>bc</literal>,
...@@ -5646,7 +5646,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5646,7 +5646,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row> </row>
<row> <row>
<entry><literal>IDDD</literal></entry> <entry><literal>IDDD</literal></entry>
<entry>ISO day of year (001-371; day 1 of the year is Monday of the first ISO week.)</entry> <entry>day of ISO 8601 week-numbering year (001-371; day 1 of the year is Monday of the first ISO week)</entry>
</row> </row>
<row> <row>
<entry><literal>DD</literal></entry> <entry><literal>DD</literal></entry>
...@@ -5654,27 +5654,27 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5654,27 +5654,27 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row> </row>
<row> <row>
<entry><literal>D</literal></entry> <entry><literal>D</literal></entry>
<entry>day of the week, Sunday(<literal>1</>) to Saturday(<literal>7</>)</entry> <entry>day of the week, Sunday (<literal>1</>) to Saturday (<literal>7</>)</entry>
</row> </row>
<row> <row>
<entry><literal>ID</literal></entry> <entry><literal>ID</literal></entry>
<entry>ISO day of the week, Monday(<literal>1</>) to Sunday(<literal>7</>)</entry> <entry>ISO 8601 day of the week, Monday (<literal>1</>) to Sunday (<literal>7</>)</entry>
</row> </row>
<row> <row>
<entry><literal>W</literal></entry> <entry><literal>W</literal></entry>
<entry>week of month (1-5) (The first week starts on the first day of the month.)</entry> <entry>week of month (1-5) (the first week starts on the first day of the month)</entry>
</row> </row>
<row> <row>
<entry><literal>WW</literal></entry> <entry><literal>WW</literal></entry>
<entry>week number of year (1-53) (The first week starts on the first day of the year.)</entry> <entry>week number of year (1-53) (the first week starts on the first day of the year)</entry>
</row> </row>
<row> <row>
<entry><literal>IW</literal></entry> <entry><literal>IW</literal></entry>
<entry>ISO week number of year (01 - 53; the first Thursday of the new year is in week 1.)</entry> <entry>week number of ISO 8601 week-numbering year (01-53; the first Thursday of the year is in week 1)</entry>
</row> </row>
<row> <row>
<entry><literal>CC</literal></entry> <entry><literal>CC</literal></entry>
<entry>century (2 digits) (The twenty-first century starts on 2001-01-01.)</entry> <entry>century (2 digits) (the twenty-first century starts on 2001-01-01)</entry>
</row> </row>
<row> <row>
<entry><literal>J</literal></entry> <entry><literal>J</literal></entry>
...@@ -5781,7 +5781,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5781,7 +5781,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem> <listitem>
<para> <para>
<literal>TM</literal> does not include trailing blanks. <literal>TM</literal> does not include trailing blanks.
<function>to_timestamp</> and <function>to_date</> ignore <function>to_timestamp</> and <function>to_date</> ignore
the <literal>TM</literal> modifier. the <literal>TM</literal> modifier.
</para> </para>
...@@ -5813,7 +5813,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5813,7 +5813,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
Casting does not have this behavior. Casting does not have this behavior.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Ordinary text is allowed in <function>to_char</function> Ordinary text is allowed in <function>to_char</function>
...@@ -5876,16 +5876,16 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5876,16 +5876,16 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem> <listitem>
<para> <para>
An ISO week date (as distinct from a Gregorian date) can be An ISO 8601 week-numbering date (as distinct from a Gregorian date)
specified to <function>to_timestamp</function> and can be specified to <function>to_timestamp</function> and
<function>to_date</function> in one of two ways: <function>to_date</function> in one of two ways:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Year, week, and weekday: for example <literal>to_date('2006-42-4', Year, week number, and weekday: for
'IYYY-IW-ID')</literal> returns the date example <literal>to_date('2006-42-4', 'IYYY-IW-ID')</literal>
<literal>2006-10-19</literal>. If you omit the weekday it returns the date <literal>2006-10-19</literal>.
is assumed to be 1 (Monday). If you omit the weekday it is assumed to be 1 (Monday).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
...@@ -5897,13 +5897,25 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5897,13 +5897,25 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
Attempting to construct a date using a mixture of ISO week and Attempting to enter a date using a mixture of ISO 8601 week-numbering
Gregorian date fields is nonsensical, and will cause an error. In the fields and Gregorian date fields is nonsensical, and will cause an
context of an ISO year, the concept of a <quote>month</> or <quote>day error. In the context of an ISO 8601 week-numbering year, the
of month</> has no meaning. In the context of a Gregorian year, the concept of a <quote>month</> or <quote>day of month</> has no
ISO week has no meaning. Users should avoid mixing Gregorian and meaning. In the context of a Gregorian year, the ISO week has no
ISO date specifications. meaning.
</para> </para>
<caution>
<para>
While <function>to_date</function> will reject a mixture of
Gregorian and ISO week-numbering date
fields, <function>to_char</function> will not, since output format
specifications like <literal>YYYY-MM-DD (IYYY-IDDD)</> can be
useful. But avoid writing something like <literal>IYYY-MM-DD</>;
that would yield surprising results near the start of the year.
(See <xref linkend="functions-datetime-extract"> for more
information.)
</para>
</caution>
</listitem> </listitem>
<listitem> <listitem>
...@@ -7107,8 +7119,8 @@ SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40'); ...@@ -7107,8 +7119,8 @@ SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
<term><literal>dow</literal></term> <term><literal>dow</literal></term>
<listitem> <listitem>
<para> <para>
The day of the week as Sunday(<literal>0</>) to The day of the week as Sunday (<literal>0</>) to
Saturday(<literal>6</>) Saturday (<literal>6</>)
</para> </para>
<screen> <screen>
...@@ -7190,8 +7202,8 @@ SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); ...@@ -7190,8 +7202,8 @@ SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
<term><literal>isodow</literal></term> <term><literal>isodow</literal></term>
<listitem> <listitem>
<para> <para>
The day of the week as Monday(<literal>1</>) to The day of the week as Monday (<literal>1</>) to
Sunday(<literal>7</>) Sunday (<literal>7</>)
</para> </para>
<screen> <screen>
...@@ -7210,7 +7222,8 @@ SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40'); ...@@ -7210,7 +7222,8 @@ SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
<term><literal>isoyear</literal></term> <term><literal>isoyear</literal></term>
<listitem> <listitem>
<para> <para>
The <acronym>ISO</acronym> 8601 year that the date falls in (not applicable to intervals) The <acronym>ISO</acronym> 8601 week-numbering year that the date
falls in (not applicable to intervals)
</para> </para>
<screen> <screen>
...@@ -7221,7 +7234,11 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02'); ...@@ -7221,7 +7234,11 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
</screen> </screen>
<para> <para>
Each <acronym>ISO</acronym> year begins with the Monday of the week containing the 4th of January, so in early January or late December the <acronym>ISO</acronym> year may be different from the Gregorian year. See the <literal>week</literal> field for more information. Each <acronym>ISO</acronym> 8601 week-numbering year begins with the
Monday of the week containing the 4th of January, so in early
January or late December the <acronym>ISO</acronym> year may be
different from the Gregorian year. See the <literal>week</literal>
field for more information.
</para> </para>
<para> <para>
This field is not available in PostgreSQL releases prior to 8.3. This field is not available in PostgreSQL releases prior to 8.3.
...@@ -7381,14 +7398,14 @@ SELECT EXTRACT(SECOND FROM TIME '17:12:28.5'); ...@@ -7381,14 +7398,14 @@ SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
<term><literal>week</literal></term> <term><literal>week</literal></term>
<listitem> <listitem>
<para> <para>
The number of the week of the year that the day is in. By definition The number of the <acronym>ISO</acronym> 8601 week-numbering week of
(<acronym>ISO</acronym> 8601), weeks start on Mondays and the first the year. By definition, ISO weeks start on Mondays and the first
week of a year contains January 4 of that year. In other words, the week of a year contains January 4 of that year. In other words, the
first Thursday of a year is in week 1 of that year. first Thursday of a year is in week 1 of that year.
</para> </para>
<para> <para>
In the ISO definition, it is possible for early-January dates to be In the ISO week-numbering system, it is possible for early-January
part of the 52nd or 53rd week of the previous year, and for dates to be part of the 52nd or 53rd week of the previous year, and for
late-December dates to be part of the first week of the next year. late-December dates to be part of the first week of the next year.
For example, <literal>2005-01-01</> is part of the 53rd week of year For example, <literal>2005-01-01</> is part of the 53rd week of year
2004, and <literal>2006-01-01</> is part of the 52nd week of year 2004, and <literal>2006-01-01</> is part of the 52nd week of year
...@@ -10305,7 +10322,7 @@ table2-mapping ...@@ -10305,7 +10322,7 @@ table2-mapping
from the type to <type>json</type>, the cast function will be used to from the type to <type>json</type>, the cast function will be used to
perform the conversion; otherwise, a scalar value is produced. perform the conversion; otherwise, a scalar value is produced.
For any scalar type other than a number, a Boolean, or a null value, For any scalar type other than a number, a Boolean, or a null value,
the text representation will be used, in such a fashion that it is a the text representation will be used, in such a fashion that it is a
valid <type>json</> or <type>jsonb</> value. valid <type>json</> or <type>jsonb</> value.
</entry> </entry>
<entry><literal>to_json('Fred said "Hi."'::text)</literal></entry> <entry><literal>to_json('Fred said "Hi."'::text)</literal></entry>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment