Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit5f8fe02

Browse files
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 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.
1 parent2600e44 commit5f8fe02

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
@@ -4990,11 +4990,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
49904990
</row>
49914991
<row>
49924992
<entry><literal>Y,YYY</literal></entry>
4993-
<entry>year (4and more digits) with comma</entry>
4993+
<entry>year (4or more digits) with comma</entry>
49944994
</row>
49954995
<row>
49964996
<entry><literal>YYYY</literal></entry>
4997-
<entry>year (4and more digits)</entry>
4997+
<entry>year (4or more digits)</entry>
49984998
</row>
49994999
<row>
50005000
<entry><literal>YYY</literal></entry>
@@ -5010,19 +5010,19 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
50105010
</row>
50115011
<row>
50125012
<entry><literal>IYYY</literal></entry>
5013-
<entry>ISO year (4and more digits)</entry>
5013+
<entry>ISO8601 week-numberingyear (4or more digits)</entry>
50145014
</row>
50155015
<row>
50165016
<entry><literal>IYY</literal></entry>
5017-
<entry>last 3 digits of ISO year</entry>
5017+
<entry>last 3 digits of ISO8601 week-numberingyear</entry>
50185018
</row>
50195019
<row>
50205020
<entry><literal>IY</literal></entry>
5021-
<entry>last 2 digits of ISO year</entry>
5021+
<entry>last 2 digits of ISO8601 week-numberingyear</entry>
50225022
</row>
50235023
<row>
50245024
<entry><literal>I</literal></entry>
5025-
<entry>last digit of ISO year</entry>
5025+
<entry>last digit of ISO8601 week-numberingyear</entry>
50265026
</row>
50275027
<row>
50285028
<entry><literal>BC</literal>, <literal>bc</literal>,
@@ -5092,35 +5092,35 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
50925092
</row>
50935093
<row>
50945094
<entry><literal>IDDD</literal></entry>
5095-
<entry>ISOday of year (001-371; day 1 of the year is Monday of the first ISO week.)</entry>
5095+
<entry>day ofISO 8601 week-numberingyear (001-371; day 1 of the year is Monday of the first ISO week)</entry>
50965096
</row>
50975097
<row>
50985098
<entry><literal>DD</literal></entry>
50995099
<entry>day of month (01-31)</entry>
51005100
</row>
51015101
<row>
51025102
<entry><literal>D</literal></entry>
5103-
<entry>day of the week, Sunday(<literal>1</>) to Saturday(<literal>7</>)</entry>
5103+
<entry>day of the week, Sunday(<literal>1</>) to Saturday(<literal>7</>)</entry>
51045104
</row>
51055105
<row>
51065106
<entry><literal>ID</literal></entry>
5107-
<entry>ISO day of the week, Monday(<literal>1</>) to Sunday(<literal>7</>)</entry>
5107+
<entry>ISO8601day of the week, Monday(<literal>1</>) to Sunday(<literal>7</>)</entry>
51085108
</row>
51095109
<row>
51105110
<entry><literal>W</literal></entry>
5111-
<entry>week of month (1-5) (The first week starts on the first day of the month.)</entry>
5112-
</row>
5111+
<entry>week of month (1-5) (the first week starts on the first day of the month)</entry>
5112+
</row>
51135113
<row>
51145114
<entry><literal>WW</literal></entry>
5115-
<entry>week number of year (1-53) (The first week starts on the first day of the year.)</entry>
5115+
<entry>week number of year (1-53) (the first week starts on the first day of the year)</entry>
51165116
</row>
51175117
<row>
51185118
<entry><literal>IW</literal></entry>
5119-
<entry>ISOweek number of year (01 -53; the first Thursday of thenewyear is in week 1.)</entry>
5119+
<entry>week number ofISO 8601 week-numberingyear (01-53; the first Thursday of the year is in week 1)</entry>
51205120
</row>
51215121
<row>
51225122
<entry><literal>CC</literal></entry>
5123-
<entry>century (2 digits) (The twenty-first century starts on 2001-01-01.)</entry>
5123+
<entry>century (2 digits) (the twenty-first century starts on 2001-01-01)</entry>
51245124
</row>
51255125
<row>
51265126
<entry><literal>J</literal></entry>
@@ -5293,16 +5293,16 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
52935293

52945294
<listitem>
52955295
<para>
5296-
An ISO week date (as distinct from a Gregorian date) can be
5297-
specified to <function>to_timestamp</function> and
5296+
An ISO8601week-numbering date (as distinct from a Gregorian date)
5297+
can bespecified to <function>to_timestamp</function> and
52985298
<function>to_date</function> in one of two ways:
52995299
<itemizedlist>
53005300
<listitem>
53015301
<para>
5302-
Year, week, and weekday: for example <literal>to_date('2006-42-4',
5303-
'IYYY-IW-ID')</literal> returns the date
5304-
<literal>2006-10-19</literal>. If you omit the weekday it
5305-
is assumed to be 1 (Monday).
5302+
Year, week number, and weekday: for
5303+
example <literal>to_date('2006-42-4', 'IYYY-IW-ID')</literal>
5304+
returns the date<literal>2006-10-19</literal>.
5305+
If you omit the weekday itis assumed to be 1 (Monday).
53065306
</para>
53075307
</listitem>
53085308
<listitem>
@@ -5314,13 +5314,25 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
53145314
</itemizedlist>
53155315
</para>
53165316
<para>
5317-
Attempting toconstruct a date using a mixture of ISOweek and
5318-
Gregorian date fields is nonsensical, and will cause an error. In the
5319-
context of an ISO year, the concept of a <quote>month</> or <quote>day
5320-
of month</>has no meaning. In the contextofa Gregorian year, the
5321-
ISO week has no meaning. Users should avoid mixing Gregorian and
5322-
ISO date specifications.
5317+
Attempting toenter a date using a mixture of ISO8601 week-numbering
5318+
fields andGregorian date fields is nonsensical, and will cause an
5319+
error. In thecontext of an ISO8601 week-numberingyear, the
5320+
conceptofa <quote>month</>or <quote>dayofmonth</> has no
5321+
meaning. In the context of a Gregorian year, the ISO week has no
5322+
meaning.
53235323
</para>
5324+
<caution>
5325+
<para>
5326+
While <function>to_date</function> will reject a mixture of
5327+
Gregorian and ISO week-numbering date
5328+
fields, <function>to_char</function> will not, since output format
5329+
specifications like <literal>YYYY-MM-DD (IYYY-IDDD)</> can be
5330+
useful. But avoid writing something like <literal>IYYY-MM-DD</>;
5331+
that would yield surprising results near the start of the year.
5332+
(See <xref linkend="functions-datetime-extract"> for more
5333+
information.)
5334+
</para>
5335+
</caution>
53245336
</listitem>
53255337

53265338
<listitem>
@@ -6324,8 +6336,8 @@ SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
63246336
<term><literal>dow</literal></term>
63256337
<listitem>
63266338
<para>
6327-
The day of the week as Sunday(<literal>0</>) to
6328-
Saturday(<literal>6</>)
6339+
The day of the week as Sunday(<literal>0</>) to
6340+
Saturday(<literal>6</>)
63296341
</para>
63306342

63316343
<screen>
@@ -6405,8 +6417,8 @@ SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
64056417
<term><literal>isodow</literal></term>
64066418
<listitem>
64076419
<para>
6408-
The day of the week as Monday(<literal>1</>) to
6409-
Sunday(<literal>7</>)
6420+
The day of the week as Monday(<literal>1</>) to
6421+
Sunday(<literal>7</>)
64106422
</para>
64116423

64126424
<screen>
@@ -6425,7 +6437,8 @@ SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
64256437
<term><literal>isoyear</literal></term>
64266438
<listitem>
64276439
<para>
6428-
The <acronym>ISO</acronym> 8601 year that the date falls in (not applicable to intervals)
6440+
The <acronym>ISO</acronym> 8601 week-numbering year that the date
6441+
falls in (not applicable to intervals)
64296442
</para>
64306443

64316444
<screen>
@@ -6436,7 +6449,11 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
64366449
</screen>
64376450

64386451
<para>
6439-
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.
6452+
Each <acronym>ISO</acronym> 8601 week-numbering year begins with the
6453+
Monday of the week containing the 4th of January, so in early
6454+
January or late December the <acronym>ISO</acronym> year may be
6455+
different from the Gregorian year. See the <literal>week</literal>
6456+
field for more information.
64406457
</para>
64416458
<para>
64426459
This field is not available in PostgreSQL releases prior to 8.3.
@@ -6600,14 +6617,14 @@ SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
66006617
<term><literal>week</literal></term>
66016618
<listitem>
66026619
<para>
6603-
The number of theweek of the year that the day is in. By definition
6604-
(<acronym>ISO</acronym> 8601), weeks start on Mondays and the first
6620+
The number of the<acronym>ISO</acronym> 8601 week-numbering week of
6621+
the year. By definition, ISO weeks start on Mondays and the first
66056622
week of a year contains January 4 of that year. In other words, the
66066623
first Thursday of a year is in week 1 of that year.
66076624
</para>
66086625
<para>
6609-
In the ISOdefinition, it is possible for early-January dates to be
6610-
part of the 52nd or 53rd week of the previous year, and for
6626+
In the ISOweek-numbering system, it is possible for early-January
6627+
dates to bepart of the 52nd or 53rd week of the previous year, and for
66116628
late-December dates to be part of the first week of the next year.
66126629
For example, <literal>2005-01-01</> is part of the 53rd week of year
66136630
2004, and <literal>2006-01-01</> is part of the 52nd week of year

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp