4f140a4628b9b0361e2dbf3550335f67dd52e831
[scilab.git] / scilab / modules / time / help / en_US / getdate.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2020 - Samuel GOUGEON 
5  *
6  * This file is hereby licensed under the terms of the GNU GPL v2.0,
7  * pursuant to article 5.3.4 of the CeCILL v.2.1.
8  * This file was originally licensed under the terms of the CeCILL v2.1,
9  * and continues to be available under such terms.
10  * For more information, see the COPYING file which you should have received
11  * along with this program.
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
15           xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
16           xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="getdate">
17     <refnamediv>
18         <refname>getdate</refname>
19         <refpurpose>
20             Current datetime or POSIX timestamp from computer's clock. Datetimes from given timestamps
21         </refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>
26            curDatetime = getdate()
27            timeStamp = getdate("s")
28            dateTimes = getdate(timeStamps)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>curDatetime</term>
36                 <listitem>
37                     vector of integers with
38                     <table>
39                         <tr><td>Index</td>
40                             <th>1</th><th>2</th><th>3</th><th>4</th><th>5</th>
41                             <th>6</th><th>7</th><th>8</th><th>9</th><th>10</th>
42                         </tr>
43                         <tr><td>Content</td>
44                             <th>year</th><th>month</th><th>week</th><th>yearday</th><th>weekday</th>
45                             <th>monthday</th><th>hour</th><th>minute</th><th>second</th><th>millisecond</th>
46                         </tr>
47                         <tr><td>Range</td>
48                             <td>≥ 1970</td><td>[1,12]</td><td>[1,53]</td><td>[1,366]</td><td>[1,7] 1=sunday</td>
49                             <td>[1,31]</td><td>[0,23]</td><td>[0,59]</td><td>[0,59]</td><td>[0,999]</td>
50                         </tr>
51                     </table>
52                     <para/>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>timeStamp</term>
57                 <listitem>
58                     integer number of seconds elapsed since 1970-01-01 00:00:00 UTC,
59                     excluding leap seconds, as defined by the POSIX standard (see description).
60                     <para/>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>timeStamps</term>
65                 <listitem>
66                     Array of positive decimal numbers representing POSIX timestamps.
67                     Negative timestamps are not accepted.
68                     <para/>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>dateTimes</term>
73                 <listitem>
74                     length(timeStamps)-by-10 Matrix: The row #i elements are datetime data
75                     corresponding to timeStamps(i), as documented for <varname>curDatetime</varname>,
76                     except that <literal>dateTimes(:,10)</literal> are fractions of second in [0,1)
77                     instead of milliseconds. dateTimes are expressed in the current computer's time
78                     zone.
79                     <para/>
80                 </listitem>
81             </varlistentry>
82         </variablelist>
83     </refsection>
84     <refsection>
85         <title>Description</title>
86         <para>
87             <emphasis role="bold">getdate()</emphasis> returns the current datetime of the
88             computer's clock, expressed in the Gregorian calendar, and for the computer's
89             time zone + possible daylight saving offset.
90         </para>
91         <para>
92             Nowadays, most of computers are automatically synchronized with the legal time
93             for the considered time zone, through time servers. Legal datetimes are
94             synchronized on the Coordinated Universal Time (UTC), by a known time zone
95             (and daylight saving) offset.
96         </para>
97         <para>
98             <emphasis role="bold">getdate("s")</emphasis> reads the computer's clock
99             and returns the corresponding POSIX timestamp. This corresponds to the number
100             of seconds elapsed since 1970-01-01 00:00:00 UTC, except that leap seconds
101             are not counted. Hence, if <literal>n = getdate("s")</literal> is run at an
102             exact round hour, <literal>modulo(n, 3600)</literal> will return 0 instead
103             of <ulink url="http://en.wikipedia.org/wiki/Leap_second">cumulated leap seconds</ulink>
104             added since 1972 (27s, up to 2020).
105         </para>
106         <para>
107             <emphasis role="bold">getdate(timeStamps)</emphasis> returns the status of the
108             local computer's clock for the given POSIX time stamps, that may include fractional
109             seconds. If any, the computer's current Daylight Saving offset is never considered.
110             <literal>getdate(0)</literal> will return 1970-01-01 00:00:00
111             only if the clock is set for the time zone = 0. Otherwise, for instance for
112             Scilab users living in Bélem, Brazil, UTC-3, <literal>getdate(0)</literal> returns
113             1969-12-31 21:00:00, actually corresponding to 1970-01-01 00:00:00 POSIX.
114         </para>
115     </refsection>
116     <refsection>
117         <title>Examples</title>
118         <programlisting role="example"><![CDATA[
119 D = getdate()
120 mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
121
122 x = getdate("s");
123 mprintf("%.2f\n", x)
124
125 D = getdate(0)
126 mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
127      ]]></programlisting>
128         <screen><![CDATA[
129 --> D = getdate()
130  D  = 
131    2020.   7.   30.   208.   1.   26.   23.   8.   28.   474.
132
133 --> mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
134 2020-07-26 23:08:28.474
135
136 --> x = getdate("s");
137 --> mprintf("%.2f\n", x)
138 1595797708.00
139
140 --> D = getdate(0)
141  D  = 
142    1970.   1.   1.   1.   5.   1.   1.   0.   0.   0.
143
144 --> mprintf("%d-%02d-%02d %02d:%02d:%06.3f\n", D(1), D(2), D(6:8), D(9)+D(10)/1000);
145 1970-01-01 01:00:00.000
146 ]]></screen>
147         <para>
148             <literal>getdate("s") ignores leap seconds:</literal>
149         </para>
150         <programlisting role="example"><![CDATA[
151 s = 1;
152 // Expecting the next round minute @ your clock. Please be patient..
153 while s <> 0
154     D = getdate();
155     x = getdate("s");
156     s = D(9);
157     sleep(300) // ms. To not use 100% of your processor
158 end
159 // If leap seconds are taken into account, they would appear here (27, in 2020):
160 modulo(x, 60) 
161  ]]></programlisting>
162         <screen><![CDATA[
163 --> modulo(x, 60)
164  ans  =
165    0.
166 ]]></screen>
167     <para/>
168         <programlisting role="example"><![CDATA[
169 getdate([1e9, 2e9, 3e9] + 0.21) // Note the fractional seconds
170  ]]></programlisting>
171         <screen><![CDATA[
172 --> getdate([1e9, 2e9, 3e9] + 0.21)
173  ans  =
174    2001.   9.   36.   252.   1.   9.    3.   46.   40.   0.21
175    2033.   5.   20.   138.   4.   18.   5.   33.   20.   0.21
176    2065.   1.   4.    24.    7.   24.   6.   20.   0.    0.21
177 ]]></screen>
178     </refsection>
179     <refsection role="see also">
180         <title>See also</title>
181         <simplelist type="inline">
182             <member>
183                 <link linkend="calendar">calendar</link>
184             </member>
185             <member>
186                 <link linkend="date">date</link>
187             </member>
188             <member>
189                 <link linkend="clock">clock</link>
190             </member>
191             <member>
192                 <link linkend="timer">timer</link>
193             </member>
194             <member>
195                 <link linkend="datenum">datenum</link>
196             </member>
197         </simplelist>
198     </refsection>
199 </refentry>