From ce4d01d96b7e41cf61b8ee3ab4018e15e01dc872 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 23 Dec 2001 20:22:49 +0000
Subject: [PATCH] Update description of CURRENT_TIMESTAMP and friends.

---
 doc/src/sgml/func.sgml | 57 ++++++++++++++++++++++++++----------------
 1 file changed, 36 insertions(+), 21 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 5e55381bf6..c9af36d550 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.87 2001/12/01 04:19:20 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.88 2001/12/23 20:22:49 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -2732,7 +2732,7 @@ PostgreSQL documentation
        <row>
 	<entry><function>timeofday()</function></entry>
 	<entry><type>text</type></entry>
-	<entry>High-precision date and time; see also <link
+	<entry>Current date and time; see <link
 	 linkend="functions-datetime-current">below</link>
 	</entry>
 	<entry><literal>timeofday()</literal></entry>
@@ -3208,25 +3208,50 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
     The following functions are available to obtain the current date and/or
     time:
 <synopsis>
-CURRENT_TIME
 CURRENT_DATE
+CURRENT_TIME
 CURRENT_TIMESTAMP
+CURRENT_TIME ( <replaceable>precision</> )
+CURRENT_TIMESTAMP ( <replaceable>precision</> )
 </synopsis>
-    Note that because of the requirements of the
-    <acronym>SQL</acronym> standard, these functions must not be
-    called with trailing parentheses.
+    <function>CURRENT_TIME</function> and
+    <function>CURRENT_TIMESTAMP</function> can optionally be given
+    a precision parameter, which causes the result to be rounded
+    to that many fractional digits.  Without a precision parameter,
+    the result is given to full available precision.
    </para>
 
+   <note>
+    <para>
+     Prior to <productname>PostgreSQL</> 7.2, the precision parameters
+     were unimplemented, and the result was always given in integer
+     seconds.
+    </para>
+   </note>
+
+   <note>
+    <para>
+     The <acronym>SQL99</acronym> standard requires these functions to
+     be written without any parentheses, unless a precision parameter
+     is given.  As of <productname>PostgreSQL</> 7.2, an empty pair of
+     parentheses can be written, but this is deprecated and may be
+     removed in a future release.
+    </para>
+   </note>
+
    <informalexample>
 <screen>
 SELECT CURRENT_TIME;
-<computeroutput>19:07:32</computeroutput>
+<computeroutput>14:39:53.662522-05</computeroutput>
 
 SELECT CURRENT_DATE;
-<computeroutput>2001-02-17</computeroutput>
+<computeroutput>2001-12-23</computeroutput>
 
 SELECT CURRENT_TIMESTAMP;
-<computeroutput>2001-02-17 19:07:32-05</computeroutput>
+<computeroutput>2001-12-23 14:39:53.662522-05</computeroutput>
+
+SELECT CURRENT_TIMESTAMP(2);
+<computeroutput>2001-12-23 14:39:53.66-05</computeroutput>
 </screen>
    </informalexample>
 
@@ -3237,9 +3262,8 @@ SELECT CURRENT_TIMESTAMP;
    </para>
 
    <para>
-    There is also <function>timeofday()</function>, which returns current
-    time to higher precision than the <function>CURRENT_TIMESTAMP</function>
-    family does:
+    There is also <function>timeofday()</function>, which for historical
+    reasons returns a text string rather than a <type>timestamp</type> value:
    </para>
 
    <informalexample>
@@ -3249,15 +3273,6 @@ SELECT timeofday();
 </screen>
    </informalexample>
 
-   <para>
-    <function>timeofday()</function> uses the operating system call
-    <function>gettimeofday(2)</function>, which may have resolution as
-    good as microseconds (depending on your platform); the other functions
-    rely on <function>time(2)</function> which is restricted to one-second
-    resolution.  For historical reasons, <function>timeofday()</function>
-    returns its result as a text string rather than a <type>timestamp</type> value.
-   </para>
-
    <para>
     It is quite important to realize that
     <function>CURRENT_TIMESTAMP</function> and related functions all return
-- 
2.40.0