new repository

1 files changed, 24 insertions, 0 deletions

diff --git a/devdocs/elisp/time-of-day.html b/devdocs/elisp/time-of-day.html
new file mode 100644
index 00000000..636ae8fe
--- /dev/null
+++ b/devdocs/elisp/time-of-day.html
@@ -0,0 +1,24 @@
+ <h3 class="section">Time of Day</h3>  <p>This section explains how to determine the current time and time zone. </p>   <p>Many functions like <code>current-time</code> and <code>file-attributes</code> return <em>Lisp timestamp</em> values that count seconds, and that can represent absolute time by counting seconds since the <em>epoch</em> of 1970-01-01 00:00:00 UTC. </p> <p>Although traditionally Lisp timestamps were integer pairs, their form has evolved and programs ordinarily should not depend on the current default form. If your program needs a particular timestamp form, you can use the <code>time-convert</code> function to convert it to the needed form. See <a href="time-conversion">Time Conversion</a>. </p>  <p>There are currently three forms of Lisp timestamps, each of which represents a number of seconds: </p> <ul> <li> An integer. Although this is the simplest form, it cannot represent subsecond timestamps. </li>
+<li> A pair of integers <code>(<var>ticks</var> . <var>hz</var>)</code>, where <var>hz</var> is positive. This represents <var>ticks</var>/<var>hz</var> seconds, which is the same time as plain <var>ticks</var> if <var>hz</var> is 1. A common value for <var>hz</var> is 1000000000, for a nanosecond-resolution clock.<a id="DOCF28" href="#FOOT28"><sup>28</sup></a> </li>
+<li> A list of four integers <code>(<var>high</var> <var>low</var> <var>micro</var>
+<var>pico</var>)</code>, where 0≤<var>low</var>&lt;65536, 0≤<var>micro</var>&lt;1000000, and 0≤<var>pico</var>&lt;1000000. This represents the number of seconds using the formula: <var>high</var> * 2**16 + <var>low</var> + <var>micro</var> * 10**-6 + <var>pico</var> * 10**-12. In some cases, functions may default to returning two- or three-element lists, with omitted <var>micro</var> and <var>pico</var> components defaulting to zero. On all current machines <var>pico</var> is a multiple of 1000, but this may change as higher-resolution clocks become available. </li>
+</ul>  <p>Function arguments, e.g., the <var>time</var> argument to <code>current-time-string</code>, accept a more-general <em>time value</em> format, which can be a Lisp timestamp, <code>nil</code> for the current time, a single floating-point number for seconds, or a list <code>(<var>high</var> <var>low</var> <var>micro</var>)</code> or <code>(<var>high</var>
+<var>low</var>)</code> that is a truncated list timestamp with missing elements taken to be zero. </p>  <p>Time values can be converted to and from calendrical and other forms. Some of these conversions rely on operating system functions that limit the range of possible time values, and signal an error such as ‘<samp>"Specified time is not representable"</samp>’ if the limits are exceeded. For instance, a system may not support years before 1970, or years before 1901, or years far in the future. You can convert a time value into a human-readable string using <code>format-time-string</code>, into a Lisp timestamp using <code>time-convert</code>, and into other forms using <code>decode-time</code> and <code>float-time</code>. These functions are described in the following sections. </p> <dl> <dt id="current-time-string">Function: <strong>current-time-string</strong> <em>&amp;optional time zone</em>
+</dt> <dd>
+<p>This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day in that order: the number of characters used for these fields is always the same, although (unless you require English weekday or month abbreviations regardless of locale) it is typically more convenient to use <code>format-time-string</code> than to extract fields from the output of <code>current-time-string</code>, as the year might not have exactly four digits, and additional information may some day be added at the end. </p> <p>The argument <var>time</var>, if given, specifies a time to format, instead of the current time. The optional argument <var>zone</var> defaults to the current time zone rule. See <a href="time-zone-rules">Time Zone Rules</a>. The operating system limits the range of time and zone values. </p> <div class="example"> <pre class="example">(current-time-string)
+     ⇒ "Fri Nov  1 15:59:49 2019"
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="current-time">Function: <strong>current-time</strong>
+</dt> <dd><p>This function returns the current time as a Lisp timestamp. Although the timestamp takes the form <code>(<var>high</var> <var>low</var>
+<var>micro</var> <var>pico</var>)</code> in the current Emacs release, this is planned to change in a future Emacs version. You can use the <code>time-convert</code> function to convert a timestamp to some other form. See <a href="time-conversion">Time Conversion</a>. </p></dd>
+</dl> <dl> <dt id="float-time">Function: <strong>float-time</strong> <em>&amp;optional time</em>
+</dt> <dd>
+<p>This function returns the current time as a floating-point number of seconds since the epoch. The optional argument <var>time</var>, if given, specifies a time to convert instead of the current time. </p> <p><em>Warning</em>: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required. For example, on typical systems <code>(float-time '(1 . 10))</code> displays as ‘<samp>0.1</samp>’ but is slightly greater than 1/10. </p> <p><code>time-to-seconds</code> is an alias for this function. </p>
+</dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Time-of-Day.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Time-of-Day.html</a>
+  </p>
+</div>