new repository

1 files changed, 53 insertions, 0 deletions

diff --git a/devdocs/elisp/time-conversion.html b/devdocs/elisp/time-conversion.html
new file mode 100644
index 00000000..45bdbacd
--- /dev/null
+++ b/devdocs/elisp/time-conversion.html
@@ -0,0 +1,53 @@
+ <h3 class="section">Time Conversion</h3>   <p>These functions convert time values (see <a href="time-of-day">Time of Day</a>) to Lisp timestamps, or into calendrical information and vice versa. </p> <p>Many 32-bit operating systems are limited to system times containing 32 bits of information in their seconds component; these systems typically handle only the times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 Universal Time. However, 64-bit and some 32-bit operating systems have larger seconds components, and can represent times far in the past or future. </p> <p>Calendrical conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers count the number of years since the year 1 BC, and do not skip zero as traditional Gregorian years do; for example, the year number -37 represents the Gregorian year 38 BC. </p> <dl> <dt id="time-convert">Function: <strong>time-convert</strong> <em>time &amp;optional form</em>
+</dt> <dd>
+<p>This function converts a time value into a Lisp timestamp. </p> <p>The optional <var>form</var> argument specifies the timestamp form to be returned. If <var>form</var> is the symbol <code>integer</code>, this function returns an integer count of seconds. If <var>form</var> is a positive integer, it specifies a clock frequency and this function returns an integer-pair timestamp <code>(<var>ticks</var>
+. <var>form</var>)</code>.<a id="DOCF29" href="#FOOT29"><sup>29</sup></a> If <var>form</var> is <code>t</code>, this function treats it as a positive integer suitable for representing the timestamp; for example, it is treated as 1000000000 if <var>time</var> is nil and the platform timestamp has nanosecond resolution. If <var>form</var> is <code>list</code>, this function returns an integer list <code>(<var>high</var> <var>low</var> <var>micro</var> <var>pico</var>)</code>. Although an omitted or <code>nil</code> <var>form</var> currently acts like <code>list</code>, this is planned to change in a future Emacs version, so callers requiring list timestamps should pass <code>list</code> explicitly. </p> <p>If <var>time</var> is infinite or a NaN, this function signals an error. Otherwise, if <var>time</var> cannot be represented exactly, conversion truncates it toward minus infinity. When <var>form</var> is <code>t</code>, conversion is always exact so no truncation occurs, and the returned clock resolution is no less than that of <var>time</var>. By way of contrast, <code>float-time</code> can convert any Lisp time value without signaling an error, although the result might not be exact. See <a href="time-of-day">Time of Day</a>. </p> <p>For efficiency this function might return a value that is <code>eq</code> to <var>time</var>, or that otherwise shares structure with <var>time</var>. </p> <p>Although <code>(time-convert nil nil)</code> is equivalent to <code>(current-time)</code>, the latter may be a bit faster. </p> <div class="example"> <pre class="example">(setq a (time-convert nil t))
+⇒ (1564826753904873156 . 1000000000)
+</pre>
+<pre class="example">(time-convert a 100000)
+⇒ (156482675390487 . 100000)
+</pre>
+<pre class="example">(time-convert a 'integer)
+⇒ 1564826753
+</pre>
+<pre class="example">(time-convert a 'list)
+⇒ (23877 23681 904873 156000)
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="decode-time">Function: <strong>decode-time</strong> <em>&amp;optional time zone form</em>
+</dt> <dd>
+<p>This function converts a time value into calendrical information. If you don’t specify <var>time</var>, it decodes the current time, and similarly <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> <p>The <var>form</var> argument controls the form of the returned <var>seconds</var> element, as described below. The return value is a list of nine elements, as follows: </p> <div class="example"> <pre class="example">(<var>seconds</var> <var>minutes</var> <var>hour</var> <var>day</var> <var>month</var> <var>year</var> <var>dow</var> <var>dst</var> <var>utcoff</var>)
+</pre>
+</div> <p>Here is what the elements mean: </p> <dl compact> <dt><var>seconds</var></dt> <dd><p>The number of seconds past the minute, with form described below. </p></dd> <dt><var>minutes</var></dt> <dd><p>The number of minutes past the hour, as an integer between 0 and 59. </p></dd> <dt><var>hour</var></dt> <dd><p>The hour of the day, as an integer between 0 and 23. </p></dd> <dt><var>day</var></dt> <dd><p>The day of the month, as an integer between 1 and 31. </p></dd> <dt><var>month</var></dt> <dd><p>The month of the year, as an integer between 1 and 12. </p></dd> <dt><var>year</var></dt> <dd><p>The year, an integer typically greater than 1900. </p></dd> <dt><var>dow</var></dt> <dd><p>The day of week, as an integer between 0 and 6, where 0 stands for Sunday. </p></dd> <dt><var>dst</var></dt> <dd><p><code>t</code> if daylight saving time is effect, <code>nil</code> if it is not in effect, and -1 if this information is not available. </p></dd> <dt><var>utcoff</var></dt> <dd><p>An integer indicating the Universal Time offset in seconds, i.e., the number of seconds east of Greenwich. </p></dd> </dl> <p>The <var>seconds</var> element is a Lisp timestamp that is nonnegative and less than 61; it is less than 60 except during positive leap seconds (assuming the operating system supports leap seconds). If the optional <var>form</var> argument is <code>t</code>, <var>seconds</var> uses the same precision as <var>time</var>; if <var>form</var> is <code>integer</code>, <var>seconds</var> is truncated to an integer. For example, if <var>time</var> is the timestamp <code>(1566009571321 . 1000)</code>, which represents 2019-08-17 02:39:31.321 UTC on typical systems that lack leap seconds, then <code>(decode-time <var>time</var> t t)</code> returns <code>((31321 . 1000)
+39 2 17 8 2019 6 nil 0)</code>, whereas <code>(decode-time <var>time</var> t
+'integer)</code> returns <code>(31 39 2 17 8 2019 6 nil 0)</code>. If <var>form</var> is omitted or <code>nil</code>, it currently defaults to <code>integer</code> but this default may change in future Emacs releases, so callers requiring a particular form should specify <var>form</var>. </p> <p><strong>Common Lisp Note:</strong> Common Lisp has different meanings for <var>dow</var> and <var>utcoff</var>, and its <var>second</var> is an integer between 0 and 59 inclusive. </p> <p>To access (or alter) the elements in the time value, the <code>decoded-time-second</code>, <code>decoded-time-minute</code>, <code>decoded-time-hour</code>, <code>decoded-time-day</code>, <code>decoded-time-month</code>, <code>decoded-time-year</code>, <code>decoded-time-weekday</code>, <code>decoded-time-dst</code> and <code>decoded-time-zone</code> accessors can be used. </p> <p>For instance, to increase the year in a decoded time, you could say: </p> <div class="lisp"> <pre class="lisp">(setf (decoded-time-year decoded-time)
+      (+ (decoded-time-year decoded-time) 4))
+</pre>
+</div> <p>Also see the following function. </p> </dd>
+</dl> <dl> <dt id="decoded-time-add">Function: <strong>decoded-time-add</strong> <em>time delta</em>
+</dt> <dd>
+<p>This function takes a decoded time structure and adds <var>delta</var> (also a decoded time structure) to it. Elements in <var>delta</var> that are <code>nil</code> are ignored. </p> <p>For instance, if you want “same time next month”, you could say: </p> <div class="lisp"> <pre class="lisp">(let ((time (decode-time nil nil t))
+      (delta (make-decoded-time :month 2)))
+   (encode-time (decoded-time-add time delta)))
+</pre>
+</div> <p>If this date doesn’t exist (if you’re running this on January 31st, for instance), then the date will be shifted back until you get a valid date (which will be February 28th or 29th, depending). </p> <p>Fields are added in a most to least significant order, so if the adjustment described above happens, it happens before adding days, hours, minutes or seconds. </p> <p>The values in <var>delta</var> can be negative to subtract values instead. </p> <p>The return value is a decoded time structure. </p>
+</dd>
+</dl> <dl> <dt id="make-decoded-time">Function: <strong>make-decoded-time</strong> <em>&amp;key second minute hour day month year dst zone</em>
+</dt> <dd>
+<p>Return a decoded time structure with only the given keywords filled out, leaving the rest <code>nil</code>. For instance, to get a structure that represents “two months”, you could say: </p> <div class="lisp"> <pre class="lisp">(make-decoded-time :month 2)
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="encode-time">Function: <strong>encode-time</strong> <em>time &amp;rest obsolescent-arguments</em>
+</dt> <dd>
+<p>This function converts <var>time</var> to a Lisp timestamp. It can act as the inverse of <code>decode-time</code>. </p> <p>Ordinarily the first argument is a list <code>(<var>second</var> <var>minute</var> <var>hour</var> <var>day</var> <var>month</var>
+<var>year</var> <var>ignored</var> <var>dst</var> <var>zone</var>)</code> that specifies a decoded time in the style of <code>decode-time</code>, so that <code>(encode-time (decode-time ...))</code> works. For the meanings of these list members, see the table under <code>decode-time</code>. </p> <p>As an obsolescent calling convention, this function can be given six or more arguments. The first six arguments <var>second</var>, <var>minute</var>, <var>hour</var>, <var>day</var>, <var>month</var>, and <var>year</var> specify most of the components of a decoded time. If there are more than six arguments the <em>last</em> argument is used as <var>zone</var> and any other extra arguments are ignored, so that <code>(apply
+#'encode-time (decode-time ...))</code> works. In this obsolescent convention, <var>zone</var> defaults to the current time zone rule (see <a href="time-zone-rules">Time Zone Rules</a>), and <var>dst</var> is treated as if it was -1. </p> <p>Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call <code>encode-time</code>. The operating system limits the range of time and zone values. </p> <p>The <code>encode-time</code> function acts as a rough inverse to <code>decode-time</code>. For example, you can pass the output of the latter to the former as follows: </p> <div class="example"> <pre class="example">(encode-time (decode-time …))
+</pre>
+</div> <p>You can perform simple date arithmetic by using out-of-range values for <var>seconds</var>, <var>minutes</var>, <var>hour</var>, <var>day</var>, and <var>month</var>; for example, day 0 means the day preceding the given month. </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-Conversion.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Time-Conversion.html</a>
+  </p>
+</div>