* Bugs 15163 16496 fixed [doc]: getdate() page rewritten
[scilab.git] / scilab / modules / time / help / en_US / getdate.xml
index 8dade9c..4f140a4 100644 (file)
@@ -1,9 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) INRIA -
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON 
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="getdate">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="getdate">
     <refnamediv>
         <refname>getdate</refname>
-        <refpurpose>get date and time information</refpurpose>
+        <refpurpose>
+            Current datetime or POSIX timestamp from computer's clock. Datetimes from given timestamps
+        </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>dt=getdate()
-            x=getdate("s")
-            dt=getdate(x)
+        <synopsis>
+           curDatetime = getdate()
+           timeStamp = getdate("s")
+           dateTimes = getdate(timeStamps)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
-                <term>dt</term>
+                <term>curDatetime</term>
                 <listitem>
-                    <para>an integer vector with 10 entries (see below)</para>
+                    vector of integers with
+                    <table>
+                        <tr><td>Index</td>
+                            <th>1</th><th>2</th><th>3</th><th>4</th><th>5</th>
+                            <th>6</th><th>7</th><th>8</th><th>9</th><th>10</th>
+                        </tr>
+                        <tr><td>Content</td>
+                            <th>year</th><th>month</th><th>week</th><th>yearday</th><th>weekday</th>
+                            <th>monthday</th><th>hour</th><th>minute</th><th>second</th><th>millisecond</th>
+                        </tr>
+                        <tr><td>Range</td>
+                            <td>≥ 1970</td><td>[1,12]</td><td>[1,53]</td><td>[1,366]</td><td>[1,7] 1=sunday</td>
+                            <td>[1,31]</td><td>[0,23]</td><td>[0,59]</td><td>[0,59]</td><td>[0,999]</td>
+                        </tr>
+                    </table>
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>x</term>
-                <listitem>
-                    <para>an integer containing a date coded in second from 1 Jan 1970</para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Description</title>
-        <variablelist>
-            <varlistentry>
-                <term>dt=getdate()</term>
+                <term>timeStamp</term>
                 <listitem>
-                    <para> returns the current date in format given below:</para>
-                    <variablelist>
-                        <varlistentry>
-                            <term>dt(1)</term>
-                            <listitem>
-                                <para>The year  as a number (with the century) between 0000 and 9999.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(2)</term>
-                            <listitem>
-                                <para>The month of the year as a number between 01 and 12.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(3)</term>
-                            <listitem>
-                                <para>The ISO 8601  week  number  as  a   number between 01 and 53.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(4)</term>
-                            <listitem>
-                                <para>The Julian day of the year  as a number between 001 and 366.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(5)</term>
-                            <listitem>
-                                <para>Specifies the weekday as a decimal number [1,7], with 1 representing Sunday.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(6)</term>
-                            <listitem>
-                                <para>The day of the month as a number between 01 and 31.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(7)</term>
-                            <listitem>
-                                <para>The hour of the day is output as a number between 00 and 23.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(8)</term>
-                            <listitem>
-                                <para>The minute is output as a number between 00 and 59.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(9)</term>
-                            <listitem>
-                                <para>The second is output as a number between 00 and 59.</para>
-                            </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                            <term>dt(10)</term>
-                            <listitem>
-                                <para>The millisecond is output as a number between 000 and 999.</para>
-                            </listitem>
-                        </varlistentry>
-                    </variablelist>
+                    integer number of seconds elapsed since 1970-01-01 00:00:00 UTC,
+                    excluding leap seconds, as defined by the POSIX standard (see description).
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>x=getdate("s")</term>
+                <term>timeStamps</term>
                 <listitem>
-                    <para> returns a scalar with the number of seconds since Jan 1, 1970, 00:00 UTC (Unix Time Convention)</para>
-                    <para>
-                        Please note that the return value contains the <ulink url="http://en.wikipedia.org/wiki/Leap_second">leap seconds</ulink>.
-                    </para>
+                    Array of positive decimal numbers representing POSIX timestamps.
+                    Negative timestamps are not accepted.
+                    <para/>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>dt=getdate(x)</term>
+                <term>dateTimes</term>
                 <listitem>
-                    <para> formats the date given by x (number of seconds since Jan 1, 1970, 00:00 UTC) in format given above.
-                        In this case dt(10) is always equal to 0.
-                    </para>
-                    <para>
-                        <literal>getdate(0)</literal> will return Jan 1, 1970, 00:00 if the time zone concerned is UTC, but if the time zone is UTC+1, hour
-                        returned will be 01:00.
-                    </para>
+                    length(timeStamps)-by-10 Matrix: The row #i elements are datetime data
+                    corresponding to timeStamps(i), as documented for <varname>curDatetime</varname>,
+                    except that <literal>dateTimes(:,10)</literal> are fractions of second in [0,1)
+                    instead of milliseconds. dateTimes are expressed in the current computer's time
+                    zone.
+                    <para/>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
+        <title>Description</title>
+        <para>
+            <emphasis role="bold">getdate()</emphasis> returns the current datetime of the
+            computer's clock, expressed in the Gregorian calendar, and for the computer's
+            time zone + possible daylight saving offset.
+        </para>
+        <para>
+            Nowadays, most of computers are automatically synchronized with the legal time
+            for the considered time zone, through time servers. Legal datetimes are
+            synchronized on the Coordinated Universal Time (UTC), by a known time zone
+            (and daylight saving) offset.
+        </para>
+        <para>
+            <emphasis role="bold">getdate("s")</emphasis> reads the computer's clock
+            and returns the corresponding POSIX timestamp. This corresponds to the number
+            of seconds elapsed since 1970-01-01 00:00:00 UTC, except that leap seconds
+            are not counted. Hence, if <literal>n = getdate("s")</literal> is run at an
+            exact round hour, <literal>modulo(n, 3600)</literal> will return 0 instead
+            of <ulink url="http://en.wikipedia.org/wiki/Leap_second">cumulated leap seconds</ulink>
+            added since 1972 (27s, up to 2020).
+        </para>
+        <para>
+            <emphasis role="bold">getdate(timeStamps)</emphasis> returns the status of the
+            local computer's clock for the given POSIX time stamps, that may include fractional
+            seconds. If any, the computer's current Daylight Saving offset is never considered.
+            <literal>getdate(0)</literal> will return 1970-01-01 00:00:00
+            only if the clock is set for the time zone = 0. Otherwise, for instance for
+            Scilab users living in Bélem, Brazil, UTC-3, <literal>getdate(0)</literal> returns
+            1969-12-31 21:00:00, actually corresponding to 1970-01-01 00:00:00 POSIX.
+        </para>
+    </refsection>
+    <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-w=getdate()
-mprintf("Year:%d,Month:%d,Day:%d",w(1),w(2),w(6));
+D = getdate()
+mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
+
+x = getdate("s");
+mprintf("%.2f\n", x)
 
-x=getdate("s")
-getdate(x)
+D = getdate(0)
+mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
+     ]]></programlisting>
+        <screen><![CDATA[
+--> D = getdate()
+ D  = 
+   2020.   7.   30.   208.   1.   26.   23.   8.   28.   474.
+
+--> mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
+2020-07-26 23:08:28.474
+
+--> x = getdate("s");
+--> mprintf("%.2f\n", x)
+1595797708.00
+
+--> D = getdate(0)
+ D  = 
+   1970.   1.   1.   1.   5.   1.   1.   0.   0.   0.
+
+--> mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
+1970-01-01 01:00:00.000
+]]></screen>
+        <para>
+            <literal>getdate("s") ignores leap seconds:</literal>
+        </para>
+        <programlisting role="example"><![CDATA[
+s = 1;
+// Expecting the next round minute @ your clock. Please be patient..
+while s <> 0
+    D = getdate();
+    x = getdate("s");
+    s = D(9);
+    sleep(300) // ms. To not use 100% of your processor
+end
+// If leap seconds are taken into account, they would appear here (27, in 2020):
+modulo(x, 60) 
+ ]]></programlisting>
+        <screen><![CDATA[
+--> modulo(x, 60)
+ ans  =
+   0.
+]]></screen>
+    <para/>
+        <programlisting role="example"><![CDATA[
+getdate([1e9, 2e9, 3e9] + 0.21) // Note the fractional seconds
  ]]></programlisting>
+        <screen><![CDATA[
+--> getdate([1e9, 2e9, 3e9] + 0.21)
+ ans  =
+   2001.   9.   36.   252.   1.   9.    3.   46.   40.   0.21
+   2033.   5.   20.   138.   4.   18.   5.   33.   20.   0.21
+   2065.   1.   4.    24.    7.   24.   6.   20.   0.    0.21
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="calendar">calendar</link>
+            </member>
+            <member>
                 <link linkend="date">date</link>
             </member>
             <member>
+                <link linkend="clock">clock</link>
+            </member>
+            <member>
                 <link linkend="timer">timer</link>
             </member>
+            <member>
+                <link linkend="datenum">datenum</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>