mirror of
https://github.com/ocaml-tracing/ocaml-opentelemetry.git
synced 2026-03-09 04:17:56 -04:00
3 lines
12 KiB
HTML
3 lines
12 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Span (ptime.Ptime.Span)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.1"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../index.html">ptime</a> » <a href="../index.html">Ptime</a> » Span</nav><header class="odoc-preamble"><h1>Module <code><span>Ptime.Span</span></code></h1><p>POSIX time spans.</p><p><b>WARNING.</b> A POSIX time span is not equal to an SI second based time span see the <a href="../index.html#basics" title="basics">basics</a>.</p></header><nav class="odoc-toc"><ul><li><a href="#spans">POSIX time spans</a></li><li><a href="#predicates">Predicates</a></li><li><a href="#arith">Arithmetic</a></li><li><a href="#rounding">Rounding</a></li><li><a href="#print">Pretty printing</a></li></ul></nav><div class="odoc-content"><h2 id="spans"><a href="#spans" class="anchor"></a>POSIX time spans</h2><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span><span> = <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p>The type for signed, picosecond precision, POSIX time spans.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-v"><a href="#val-v" class="anchor"></a><code><span><span class="keyword">val</span> v : <span><span>(int * int64)</span> <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>v s</code> is like <a href="#val-of_d_ps"><code>of_d_ps</code></a><code> s</code> but raises <code>Invalid_argument</code> if <code>s</code> is not in the right range. Use <a href="#val-of_d_ps"><code>of_d_ps</code></a> to deal with untrusted input.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-zero"><a href="#val-zero" class="anchor"></a><code><span><span class="keyword">val</span> zero : <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>zero</code> is the neutral element of <a href="#val-add"><code>add</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_d_ps"><a href="#val-of_d_ps" class="anchor"></a><code><span><span class="keyword">val</span> of_d_ps : <span><span>(int * int64)</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> option</span></span></code></div><div class="spec-doc"><p><code>of_d_ps (d, ps)</code> is a span for the signed POSIX picosecond span <code>d</code> * 86_400e12 + <code>ps</code>. <code>d</code> is a signed number of POSIX days and <code>ps</code> a number of picoseconds in the range [<code>0</code>;<code>86_399_999_999_999_999L</code>]. <code>None</code> is returned if <code>ps</code> is not in the right range.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_d_ps"><a href="#val-to_d_ps" class="anchor"></a><code><span><span class="keyword">val</span> to_d_ps : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> int * int64</span></code></div><div class="spec-doc"><p><code>to_d_ps d</code> is the span <code>d</code> as a pair <code>(d, ps)</code> expressing the POSIX picosecond span <code>d</code> * 86_400e12 + <code>ps</code> with <code>ps</code> in the range [<code>0</code>;<code>86_399_999_999_999_999L</code>]</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_int_s"><a href="#val-of_int_s" class="anchor"></a><code><span><span class="keyword">val</span> of_int_s : <span>int <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>of_int_s secs</code> is a span from the signed integer POSIX second span <code>secs</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_int_s"><a href="#val-to_int_s" class="anchor"></a><code><span><span class="keyword">val</span> to_int_s : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <span>int option</span></span></code></div><div class="spec-doc"><p><code>to_int_s d</code> is the span <code>d</code> as a signed integer POSIX second span, if <code>int</code>'s range can represent it (note that this depends on <code>Sys.word_size</code>). Subsecond precision numbers are truncated.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-of_float_s"><a href="#val-of_float_s" class="anchor"></a><code><span><span class="keyword">val</span> of_float_s : <span>float <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> option</span></span></code></div><div class="spec-doc"><p><code>of_float_s secs</code> is a span from the signed floating point POSIX second span <code>d</code>. Subpicosecond precision numbers are truncated.</p><p><code>None</code> is returned if <code>secs</code> cannot be represented as a span. This occurs on <a href="../../../ocaml/Stdlib/index.html#val-nan"><code>Stdlib.nan</code></a> or if the duration in POSIX days cannot fit on an <code>int</code> (on 32-bit platforms this means the absolute magnitude of the duration is greater than ~2'941'758 years).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_float_s"><a href="#val-to_float_s" class="anchor"></a><code><span><span class="keyword">val</span> to_float_s : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> float</span></code></div><div class="spec-doc"><p><code>to_float_s s</code> is the span <code>d</code> as floating point POSIX seconds.</p><p><b>Warning.</b> The magnitude of <code>s</code> may not be represented exactly by the floating point value.</p></div></div><h2 id="predicates"><a href="#predicates" class="anchor"></a>Predicates</h2><div class="odoc-spec"><div class="spec value anchored" id="val-equal"><a href="#val-equal" class="anchor"></a><code><span><span class="keyword">val</span> equal : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p><code>equal d d'</code> is <code>true</code> iff <code>d</code> and <code>d'</code> are the same time span.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-compare"><a href="#val-compare" class="anchor"></a><code><span><span class="keyword">val</span> compare : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>compare d d'</code> is a total order on durations that is compatible with signed time span order.</p></div></div><h2 id="arith"><a href="#arith" class="anchor"></a>Arithmetic</h2><p><b>Note.</b> The following functions rollover on overflows.</p><div class="odoc-spec"><div class="spec value anchored" id="val-neg"><a href="#val-neg" class="anchor"></a><code><span><span class="keyword">val</span> neg : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>neg d</code> is the span <code>d</code> negated.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-add"><a href="#val-add" class="anchor"></a><code><span><span class="keyword">val</span> add : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>add d d'</code> is <code>d</code> + <code>d'</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-sub"><a href="#val-sub" class="anchor"></a><code><span><span class="keyword">val</span> sub : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>sub d d'</code> is <code>d</code> - <code>d'</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-abs"><a href="#val-abs" class="anchor"></a><code><span><span class="keyword">val</span> abs : <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>abs d</code> is the absolute value of span <code>d</code>.</p></div></div><h2 id="rounding"><a href="#rounding" class="anchor"></a>Rounding</h2><div class="odoc-spec"><div class="spec value anchored" id="val-round"><a href="#val-round" class="anchor"></a><code><span><span class="keyword">val</span> round : <span><span class="label">frac_s</span>:int <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>round ~frac_s t</code> is <code>t</code> rounded to the <code>frac_s</code> decimal fractional second. Ties are rounded away from zero. <code>frac_s</code> is clipped to the range [<code>0</code>;<code>12</code>].</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-truncate"><a href="#val-truncate" class="anchor"></a><code><span><span class="keyword">val</span> truncate : <span><span class="label">frac_s</span>:int <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> <a href="../index.html#type-span">span</a></span></code></div><div class="spec-doc"><p><code>truncate ~frac_s t</code> is <code>t</code> truncated to the <code>frac_s</code> decimal fractional second. <code>frac_s</code> is clipped to the range [<code>0</code>;<code>12</code>].</p></div></div><h2 id="print"><a href="#print" class="anchor"></a>Pretty printing</h2><div class="odoc-spec"><div class="spec value anchored" id="val-pp"><a href="#val-pp" class="anchor"></a><code><span><span class="keyword">val</span> pp : <span><a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>pp ppf d</code> prints an unspecified, approximative, representation of <code>d</code> on <code>ppf</code>.</p><p>The representation is not fixed-width, depends on the magnitude of <code>d</code> and uses locale independent <a href="http://www.bipm.org/en/publications/si-brochure/chapter3.html">SI prefixes</a> on seconds and <a href="http://www.bipm.org/en/publications/si-brochure/table6.html">accepted non-SI units</a>. Years are counted in Julian years (365.25 SI-accepted days) as <a href="http://www.iau.org/publications/proceedings_rules/units/">defined</a> by the International Astronomical Union (IUA).</p><p>The representation is approximative. In particular beyond 60 seconds it only keeps the two most significant time units and rounds towards the infinity. The latter means that case arising, it always <em>over</em> approximates durations.</p><p><b>Warning</b> Becomes unprecise (but does not overflow) if the absolute number of POSIX days in the time span is greater than <code>max_int /
|
||
4</code> (on 32-bit platforms this is ~735'439 years)</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-dump"><a href="#val-dump" class="anchor"></a><code><span><span class="keyword">val</span> dump : <span><a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-span">span</a> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>dump ppf s</code> prints an unspecified raw representation of <code>d</code> on <code>ppf</code>.</p></div></div></div></body></html>
|