diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 2016c5a8b06..5e7b000da8f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -5544,11 +5544,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
Y,YYY
- year (4 and more digits) with comma
+ year (4 or more digits) with comma
YYYY
- year (4 and more digits)
+ year (4 or more digits)
YYY
@@ -5564,19 +5564,19 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
IYYY
- ISO year (4 and more digits)
+ ISO 8601 week-numbering year (4 or more digits)
IYY
- last 3 digits of ISO year
+ last 3 digits of ISO 8601 week-numbering year
IY
- last 2 digits of ISO year
+ last 2 digits of ISO 8601 week-numbering year
I
- last digit of ISO year
+ last digit of ISO 8601 week-numbering year
BC, bc,
@@ -5646,7 +5646,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
IDDD
- ISO day of year (001-371; day 1 of the year is Monday of the first ISO week.)
+ day of ISO 8601 week-numbering year (001-371; day 1 of the year is Monday of the first ISO week)
DD
@@ -5654,27 +5654,27 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
D
- day of the week, Sunday(1) to Saturday(7)
+ day of the week, Sunday (1) to Saturday (7)
ID
- ISO day of the week, Monday(1) to Sunday(7)
+ ISO 8601 day of the week, Monday (1) to Sunday (7)
W
- week of month (1-5) (The first week starts on the first day of the month.)
+ week of month (1-5) (the first week starts on the first day of the month)
WW
- week number of year (1-53) (The first week starts on the first day of the year.)
+ week number of year (1-53) (the first week starts on the first day of the year)
IW
- ISO week number of year (01 - 53; the first Thursday of the new year is in week 1.)
+ week number of ISO 8601 week-numbering year (01-53; the first Thursday of the year is in week 1)
CC
- century (2 digits) (The twenty-first century starts on 2001-01-01.)
+ century (2 digits) (the twenty-first century starts on 2001-01-01)
J
@@ -5781,7 +5781,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
- TM does not include trailing blanks.
+ TM does not include trailing blanks.
to_timestamp and to_date ignore
the TM modifier.
@@ -5813,7 +5813,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
Casting does not have this behavior.
-
+
Ordinary text is allowed in to_char
@@ -5876,16 +5876,16 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
- An ISO week date (as distinct from a Gregorian date) can be
- specified to to_timestamp and
+ An ISO 8601 week-numbering date (as distinct from a Gregorian date)
+ can be specified to to_timestamp and
to_date in one of two ways:
- Year, week, and weekday: for example to_date('2006-42-4',
- 'IYYY-IW-ID') returns the date
- 2006-10-19. If you omit the weekday it
- is assumed to be 1 (Monday).
+ Year, week number, and weekday: for
+ example to_date('2006-42-4', 'IYYY-IW-ID')
+ returns the date 2006-10-19.
+ If you omit the weekday it is assumed to be 1 (Monday).
@@ -5897,13 +5897,25 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
- Attempting to construct a date using a mixture of ISO week and
- Gregorian date fields is nonsensical, and will cause an error. In the
- context of an ISO year, the concept of a month or day
- of month has no meaning. In the context of a Gregorian year, the
- ISO week has no meaning. Users should avoid mixing Gregorian and
- ISO date specifications.
+ Attempting to enter a date using a mixture of ISO 8601 week-numbering
+ fields and Gregorian date fields is nonsensical, and will cause an
+ error. In the context of an ISO 8601 week-numbering year, the
+ concept of a month or day of month has no
+ meaning. In the context of a Gregorian year, the ISO week has no
+ meaning.
+
+
+ While to_date will reject a mixture of
+ Gregorian and ISO week-numbering date
+ fields, to_char will not, since output format
+ specifications like YYYY-MM-DD (IYYY-IDDD) can be
+ useful. But avoid writing something like IYYY-MM-DD;
+ that would yield surprising results near the start of the year.
+ (See for more
+ information.)
+
+
@@ -7107,8 +7119,8 @@ SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
dow
- The day of the week as Sunday(0) to
- Saturday(6)
+ The day of the week as Sunday (0) to
+ Saturday (6)
@@ -7190,8 +7202,8 @@ SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
isodow
- The day of the week as Monday(1) to
- Sunday(7)
+ The day of the week as Monday (1) to
+ Sunday (7)
@@ -7210,7 +7222,8 @@ SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
isoyear
- The ISO 8601 year that the date falls in (not applicable to intervals)
+ The ISO 8601 week-numbering year that the date
+ falls in (not applicable to intervals)
@@ -7221,7 +7234,11 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
- Each ISO year begins with the Monday of the week containing the 4th of January, so in early January or late December the ISO year may be different from the Gregorian year. See the week field for more information.
+ Each ISO 8601 week-numbering year begins with the
+ Monday of the week containing the 4th of January, so in early
+ January or late December the ISO year may be
+ different from the Gregorian year. See the week
+ field for more information.
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');
week
- The number of the week of the year that the day is in. By definition
- (ISO 8601), weeks start on Mondays and the first
+ The number of the ISO 8601 week-numbering week of
+ 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
first Thursday of a year is in week 1 of that year.
- In the ISO definition, it is possible for early-January dates to be
- part of the 52nd or 53rd week of the previous year, and for
+ In the ISO week-numbering system, it is possible for early-January
+ 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.
For example, 2005-01-01 is part of the 53rd week of year
2004, and 2006-01-01 is part of the 52nd week of year
@@ -10305,7 +10322,7 @@ table2-mapping
from the type to json, the cast function will be used to
perform the conversion; otherwise, a scalar value is produced.
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 json or jsonb value.
to_json('Fred said "Hi."'::text)