Skip to content

Commit a5f2f02

Browse files
tglsfdctglsfdc
committed
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.
1 parent 5517cfd commit a5f2f02

File tree

1 file changed

+53
-36
lines changed

1 file changed

+53
-36
lines changed

‎doc/src/sgml/func.sgml

Lines changed: 53 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -5529,11 +5529,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
55295529
</row>
55305530
<row>
55315531
<entry><literal>Y,YYY</literal></entry>
5532-
<entry>year (4 and more digits) with comma</entry>
5532+
<entry>year (4 or more digits) with comma</entry>
55335533
</row>
55345534
<row>
55355535
<entry><literal>YYYY</literal></entry>
5536-
<entry>year (4 and more digits)</entry>
5536+
<entry>year (4 or more digits)</entry>
55375537
</row>
55385538
<row>
55395539
<entry><literal>YYY</literal></entry>
@@ -5549,19 +5549,19 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
55495549
</row>
55505550
<row>
55515551
<entry><literal>IYYY</literal></entry>
5552-
<entry>ISO year (4 and more digits)</entry>
5552+
<entry>ISO 8601 week-numbering year (4 or more digits)</entry>
55535553
</row>
55545554
<row>
55555555
<entry><literal>IYY</literal></entry>
5556-
<entry>last 3 digits of ISO year</entry>
5556+
<entry>last 3 digits of ISO 8601 week-numbering year</entry>
55575557
</row>
55585558
<row>
55595559
<entry><literal>IY</literal></entry>
5560-
<entry>last 2 digits of ISO year</entry>
5560+
<entry>last 2 digits of ISO 8601 week-numbering year</entry>
55615561
</row>
55625562
<row>
55635563
<entry><literal>I</literal></entry>
5564-
<entry>last digit of ISO year</entry>
5564+
<entry>last digit of ISO 8601 week-numbering year</entry>
55655565
</row>
55665566
<row>
55675567
<entry><literal>BC</literal>, <literal>bc</literal>,
@@ -5631,35 +5631,35 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
56315631
</row>
56325632
<row>
56335633
<entry><literal>IDDD</literal></entry>
5634-
<entry>ISO day of year (001-371; day 1 of the year is Monday of the first ISO week.)</entry>
5634+
<entry>day of ISO 8601 week-numbering year (001-371; day 1 of the year is Monday of the first ISO week)</entry>
56355635
</row>
56365636
<row>
56375637
<entry><literal>DD</literal></entry>
56385638
<entry>day of month (01-31)</entry>
56395639
</row>
56405640
<row>
56415641
<entry><literal>D</literal></entry>
5642-
<entry>day of the week, Sunday(<literal>1</>) to Saturday(<literal>7</>)</entry>
5642+
<entry>day of the week, Sunday (<literal>1</>) to Saturday (<literal>7</>)</entry>
56435643
</row>
56445644
<row>
56455645
<entry><literal>ID</literal></entry>
5646-
<entry>ISO day of the week, Monday(<literal>1</>) to Sunday(<literal>7</>)</entry>
5646+
<entry>ISO 8601 day of the week, Monday (<literal>1</>) to Sunday (<literal>7</>)</entry>
56475647
</row>
56485648
<row>
56495649
<entry><literal>W</literal></entry>
5650-
<entry>week of month (1-5) (The first week starts on the first day of the month.)</entry>
5650+
<entry>week of month (1-5) (the first week starts on the first day of the month)</entry>
56515651
</row>
56525652
<row>
56535653
<entry><literal>WW</literal></entry>
5654-
<entry>week number of year (1-53) (The first week starts on the first day of the year.)</entry>
5654+
<entry>week number of year (1-53) (the first week starts on the first day of the year)</entry>
56555655
</row>
56565656
<row>
56575657
<entry><literal>IW</literal></entry>
5658-
<entry>ISO week number of year (01 - 53; the first Thursday of the new year is in week 1.)</entry>
5658+
<entry>week number of ISO 8601 week-numbering year (01-53; the first Thursday of the year is in week 1)</entry>
56595659
</row>
56605660
<row>
56615661
<entry><literal>CC</literal></entry>
5662-
<entry>century (2 digits) (The twenty-first century starts on 2001-01-01.)</entry>
5662+
<entry>century (2 digits) (the twenty-first century starts on 2001-01-01)</entry>
56635663
</row>
56645664
<row>
56655665
<entry><literal>J</literal></entry>
@@ -5796,7 +5796,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
57965796
Casting does not have this behavior.
57975797
</para>
57985798
</listitem>
5799-
5799+
58005800
<listitem>
58015801
<para>
58025802
Ordinary text is allowed in <function>to_char</function>
@@ -5859,16 +5859,16 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
58595859

58605860
<listitem>
58615861
<para>
5862-
An ISO week date (as distinct from a Gregorian date) can be
5863-
specified to <function>to_timestamp</function> and
5862+
An ISO 8601 week-numbering date (as distinct from a Gregorian date)
5863+
can be specified to <function>to_timestamp</function> and
58645864
<function>to_date</function> in one of two ways:
58655865
<itemizedlist>
58665866
<listitem>
58675867
<para>
5868-
Year, week, and weekday: for example <literal>to_date('2006-42-4',
5869-
'IYYY-IW-ID')</literal> returns the date
5870-
<literal>2006-10-19</literal>. If you omit the weekday it
5871-
is assumed to be 1 (Monday).
5868+
Year, week number, and weekday: for
5869+
example <literal>to_date('2006-42-4', 'IYYY-IW-ID')</literal>
5870+
returns the date <literal>2006-10-19</literal>.
5871+
If you omit the weekday it is assumed to be 1 (Monday).
58725872
</para>
58735873
</listitem>
58745874
<listitem>
@@ -5880,13 +5880,25 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
58805880
</itemizedlist>
58815881
</para>
58825882
<para>
5883-
Attempting to construct a date using a mixture of ISO week and
5884-
Gregorian date fields is nonsensical, and will cause an error. In the
5885-
context of an ISO year, the concept of a <quote>month</> or <quote>day
5886-
of month</> has no meaning. In the context of a Gregorian year, the
5887-
ISO week has no meaning. Users should avoid mixing Gregorian and
5888-
ISO date specifications.
5883+
Attempting to enter a date using a mixture of ISO 8601 week-numbering
5884+
fields and Gregorian date fields is nonsensical, and will cause an
5885+
error. In the context of an ISO 8601 week-numbering year, the
5886+
concept of a <quote>month</> or <quote>day of month</> has no
5887+
meaning. In the context of a Gregorian year, the ISO week has no
5888+
meaning.
58895889
</para>
5890+
<caution>
5891+
<para>
5892+
While <function>to_date</function> will reject a mixture of
5893+
Gregorian and ISO week-numbering date
5894+
fields, <function>to_char</function> will not, since output format
5895+
specifications like <literal>YYYY-MM-DD (IYYY-IDDD)</> can be
5896+
useful. But avoid writing something like <literal>IYYY-MM-DD</>;
5897+
that would yield surprising results near the start of the year.
5898+
(See <xref linkend="functions-datetime-extract"> for more
5899+
information.)
5900+
</para>
5901+
</caution>
58905902
</listitem>
58915903

58925904
<listitem>
@@ -7090,8 +7102,8 @@ SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
70907102
<term><literal>dow</literal></term>
70917103
<listitem>
70927104
<para>
7093-
The day of the week as Sunday(<literal>0</>) to
7094-
Saturday(<literal>6</>)
7105+
The day of the week as Sunday (<literal>0</>) to
7106+
Saturday (<literal>6</>)
70957107
</para>
70967108

70977109
<screen>
@@ -7173,8 +7185,8 @@ SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
71737185
<term><literal>isodow</literal></term>
71747186
<listitem>
71757187
<para>
7176-
The day of the week as Monday(<literal>1</>) to
7177-
Sunday(<literal>7</>)
7188+
The day of the week as Monday (<literal>1</>) to
7189+
Sunday (<literal>7</>)
71787190
</para>
71797191

71807192
<screen>
@@ -7193,7 +7205,8 @@ SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
71937205
<term><literal>isoyear</literal></term>
71947206
<listitem>
71957207
<para>
7196-
The <acronym>ISO</acronym> 8601 year that the date falls in (not applicable to intervals)
7208+
The <acronym>ISO</acronym> 8601 week-numbering year that the date
7209+
falls in (not applicable to intervals)
71977210
</para>
71987211

71997212
<screen>
@@ -7204,7 +7217,11 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
72047217
</screen>
72057218

72067219
<para>
7207-
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.
7220+
Each <acronym>ISO</acronym> 8601 week-numbering year begins with the
7221+
Monday of the week containing the 4th of January, so in early
7222+
January or late December the <acronym>ISO</acronym> year may be
7223+
different from the Gregorian year. See the <literal>week</literal>
7224+
field for more information.
72087225
</para>
72097226
<para>
72107227
This field is not available in PostgreSQL releases prior to 8.3.
@@ -7364,14 +7381,14 @@ SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
73647381
<term><literal>week</literal></term>
73657382
<listitem>
73667383
<para>
7367-
The number of the week of the year that the day is in. By definition
7368-
(<acronym>ISO</acronym> 8601), weeks start on Mondays and the first
7384+
The number of the <acronym>ISO</acronym> 8601 week-numbering week of
7385+
the year. By definition, ISO weeks start on Mondays and the first
73697386
week of a year contains January 4 of that year. In other words, the
73707387
first Thursday of a year is in week 1 of that year.
73717388
</para>
73727389
<para>
7373-
In the ISO definition, it is possible for early-January dates to be
7374-
part of the 52nd or 53rd week of the previous year, and for
7390+
In the ISO week-numbering system, it is possible for early-January
7391+
dates to be part of the 52nd or 53rd week of the previous year, and for
73757392
late-December dates to be part of the first week of the next year.
73767393
For example, <literal>2005-01-01</> is part of the 53rd week of year
73777394
2004, and <literal>2006-01-01</> is part of the 52nd week of year

0 commit comments

Comments
 (0)