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 5e55381bf62..c9af36d5506 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
--
GitLab