You signed in with another tab or window.Reload to refresh your session.You signed out in another tab or window.Reload to refresh your session.You switched accounts on another tab or window.Reload to refresh your session.Dismiss alert
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 constructslike to_char(..., "IYYY-MM-DD") produce nonsensical results. Perhapshanging a few more adjectives on it will discourage them from jumpingto false conclusions. I put in an explicit warning against thatspecific usage, too, though the main point is to discourage peoplewho haven't read this far down the page.In passing fix some nearby markup and terminology inconsistencies.
Attempting toconstruct a date using a mixture of ISOweek and
5826
-
Gregorian date fields is nonsensical, and will cause an error. In the
5827
-
context of an ISO year, the concept of a <quote>month</> or <quote>day
5828
-
of month</>has no meaning. In the contextofa Gregorian year, the
5829
-
ISO week has no meaning. Users should avoid mixing Gregorian and
5830
-
ISO date specifications.
5825
+
Attempting toenter a date using a mixture of ISO8601 week-numbering
5826
+
fields andGregorian date fields is nonsensical, and will cause an
5827
+
error. In thecontext of an ISO8601 week-numberingyear, the
5828
+
conceptofa <quote>month</>or <quote>dayofmonth</> has no
5829
+
meaning. In the context of a Gregorian year, the ISO week has no
5830
+
meaning.
5831
5831
</para>
5832
+
<caution>
5833
+
<para>
5834
+
While <function>to_date</function> will reject a mixture of
5835
+
Gregorian and ISO week-numbering date
5836
+
fields, <function>to_char</function> will not, since output format
5837
+
specifications like <literal>YYYY-MM-DD (IYYY-IDDD)</> can be
5838
+
useful. But avoid writing something like <literal>IYYY-MM-DD</>;
5839
+
that would yield surprising results near the start of the year.
5840
+
(See <xref linkend="functions-datetime-extract"> for more
5841
+
information.)
5842
+
</para>
5843
+
</caution>
5832
5844
</listitem>
5833
5845
5834
5846
<listitem>
@@ -6877,8 +6889,8 @@ SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
6877
6889
<term><literal>dow</literal></term>
6878
6890
<listitem>
6879
6891
<para>
6880
-
The day of the week as Sunday(<literal>0</>) to
6881
-
Saturday(<literal>6</>)
6892
+
The day of the week as Sunday(<literal>0</>) to
6893
+
Saturday(<literal>6</>)
6882
6894
</para>
6883
6895
6884
6896
<screen>
@@ -6960,8 +6972,8 @@ SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
6960
6972
<term><literal>isodow</literal></term>
6961
6973
<listitem>
6962
6974
<para>
6963
-
The day of the week as Monday(<literal>1</>) to
6964
-
Sunday(<literal>7</>)
6975
+
The day of the week as Monday(<literal>1</>) to
6976
+
Sunday(<literal>7</>)
6965
6977
</para>
6966
6978
6967
6979
<screen>
@@ -6980,7 +6992,8 @@ SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
6980
6992
<term><literal>isoyear</literal></term>
6981
6993
<listitem>
6982
6994
<para>
6983
-
The <acronym>ISO</acronym> 8601 year that the date falls in (not applicable to intervals)
6995
+
The <acronym>ISO</acronym> 8601 week-numbering year that the date
6996
+
falls in (not applicable to intervals)
6984
6997
</para>
6985
6998
6986
6999
<screen>
@@ -6991,7 +7004,11 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
6991
7004
</screen>
6992
7005
6993
7006
<para>
6994
-
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.
7007
+
Each <acronym>ISO</acronym> 8601 week-numbering year begins with the
7008
+
Monday of the week containing the 4th of January, so in early
7009
+
January or late December the <acronym>ISO</acronym> year may be
7010
+
different from the Gregorian year. See the <literal>week</literal>
7011
+
field for more information.
6995
7012
</para>
6996
7013
<para>
6997
7014
This field is not available in PostgreSQL releases prior to 8.3.
@@ -7157,14 +7174,14 @@ SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
7157
7174
<term><literal>week</literal></term>
7158
7175
<listitem>
7159
7176
<para>
7160
-
The number of theweek of the year that the day is in. By definition
7161
-
(<acronym>ISO</acronym> 8601), weeks start on Mondays and the first
7177
+
The number of the<acronym>ISO</acronym> 8601 week-numbering week of
7178
+
the year. By definition, ISO weeks start on Mondays and the first
7162
7179
week of a year contains January 4 of that year. In other words, the
7163
7180
first Thursday of a year is in week 1 of that year.
7164
7181
</para>
7165
7182
<para>
7166
-
In the ISOdefinition, it is possible for early-January dates to be
7167
-
part of the 52nd or 53rd week of the previous year, and for
7183
+
In the ISOweek-numbering system, it is possible for early-January
7184
+
dates to bepart of the 52nd or 53rd week of the previous year, and for
7168
7185
late-December dates to be part of the first week of the next year.
7169
7186
For example, <literal>2005-01-01</> is part of the 53rd week of year
7170
7187
2004, and <literal>2006-01-01</> is part of the 52nd week of year