[doc-en] master: Document the Time/Duration class introduced in PHP 8.6 (#6026)

From:	Jordi Kroon via GitHub	Date:	Mon, 02 Nov 2026 16:51:06 +0000
Subject:	[doc-en] master: Document the Time/Duration class introduced in PHP 8.6 (#6026)
Groups:	php.doc.cvs
Request:	Send a blank email to doc-cvs+get-23908@lists.php.net to get a copy of this message

Author: Jordi Kroon (jordikroon) Committer: GitHub (web-flow) Pusher: jordikroon Date: 2026-11-02T17:51:02+01:00 Commit: https://github.com/php/doc-en/commit/09e39c586d1fa47d499807f911ff92d69d175db7 Raw diff: https://github.com/php/doc-en/commit/09e39c586d1fa47d499807f911ff92d69d175db7.diff Document the Time/Duration class introduced in PHP 8.6 (#6026) * Document the Time/Duration class introduced in PHP 8.6 Changed paths: A reference/datetime/entities.ent A reference/datetime/time.duration.xml A reference/datetime/time.timeexception.xml A reference/datetime/time/duration/absolute.xml A reference/datetime/time/duration/add.xml A reference/datetime/time/duration/compare.xml A reference/datetime/time/duration/construct.xml A reference/datetime/time/duration/divideby.xml A reference/datetime/time/duration/fromhours.xml A reference/datetime/time/duration/fromiso8601durationstring.xml A reference/datetime/time/duration/frommicroseconds.xml A reference/datetime/time/duration/frommilliseconds.xml A reference/datetime/time/duration/fromminutes.xml A reference/datetime/time/duration/fromnanoseconds.xml A reference/datetime/time/duration/fromseconds.xml A reference/datetime/time/duration/multiplyby.xml A reference/datetime/time/duration/negate.xml A reference/datetime/time/duration/sub.xml A reference/datetime/time/duration/unserialize.xml M appendices/migration86/new-features.xml M reference/datetime/book.xml M reference/datetime/dateinterval.xml M reference/datetime/versions.xml Diff: diff --git a/appendices/migration86/new-features.xml b/appendices/migration86/new-features.xml index 90c0e5946940..d584325195b2 100644 --- a/appendices/migration86/new-features.xml +++ b/appendices/migration86/new-features.xml @@ -263,10 +263,65 @@ var_dump(unpack('s>value', "\xff\xfe")); // ["value" => int(-2)] <title>Date</title> <simpara> - Added the <classname>Time\Duration</classname> class. + Added the <classname>Time\Duration</classname> class to represent a fixed + length of elapsed time, such as a timeout, with nanosecond precision. + Unlike <classname>DateInterval</classname>, it has no calendar units such + as days or months, so its length is unambiguous.  </simpara> + <para> + Durations are immutable and can be compared with the comparison + operators. The class provides: + <simplelist> + <member> + Factory methods such as + <methodname>Time\Duration::fromSeconds</methodname>, + <methodname>Time\Duration::fromMilliseconds</methodname> and + <methodname>Time\Duration::fromIso8601DurationString</methodname> + </member> + <member> + Arithmetic with <methodname>Time\Duration::add</methodname>, + <methodname>Time\Duration::sub</methodname>, + <methodname>Time\Duration::multiplyBy</methodname> and + <methodname>Time\Duration::divideBy</methodname> + </member> + <member> + <methodname>Time\Duration::negate</methodname> and + <methodname>Time\Duration::absolute</methodname> to change the sign + </member> + <member> + <methodname>Time\Duration::compare</methodname> for use as a sorting + callback + </member> + </simplelist> + </para> + + <simpara> + A <exceptionname>Time\TimeException</exceptionname> is thrown when a + duration exceeds the representable range of roughly 292 years, or when an + <acronym>ISO</acronym> 8601 duration string is invalid. + </simpara> + + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php +$timeout = \Time\Duration::fromSeconds(2)->add(\Time\Duration::fromMilliseconds(500)); + +printf("%d.%09d seconds\n", $timeout->seconds, $timeout->nanoseconds); +var_dump($timeout > \Time\Duration::fromSeconds(2)); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +2.500000000 seconds +bool(true) +]]> + </screen> + </informalexample> + </sect2> <sect2 xml:id="migration86.new-features.fileinfo"> diff --git a/reference/datetime/book.xml b/reference/datetime/book.xml index 31fef728e4dd..82ac772ce77b 100644 --- a/reference/datetime/book.xml +++ b/reference/datetime/book.xml @@ -52,6 +52,7 @@ &reference.datetime.datetimezone; &reference.datetime.dateinterval; &reference.datetime.dateperiod; + &reference.datetime.time.duration; &reference.datetime.reference; @@ -82,6 +83,9 @@ </listitem> </itemizedlist> </listitem> + <listitem> + <simpara><exceptionname>Time\TimeException</exceptionname> (extends <exceptionname>Exception</exceptionname>)</simpara> + </listitem> </itemizedlist> </article> @@ -97,6 +101,7 @@ &reference.datetime.datemalformedintervalstringexception; &reference.datetime.datemalformedperiodstringexception; &reference.datetime.datemalformedstringexception; + &reference.datetime.time.timeexception; </book> diff --git a/reference/datetime/dateinterval.xml b/reference/datetime/dateinterval.xml index e42ff185aef9..ddb586e947e5 100644 --- a/reference/datetime/dateinterval.xml +++ b/reference/datetime/dateinterval.xml @@ -47,6 +47,11 @@ <classname>DateInterval</classname> instances are <link linkend="language.operators.comparison.incomparable">incomparable</link>. </para> + <simpara> + For a fixed, comparable amount of elapsed time without calendar units, + such as a timeout, use <classname>Time\Duration</classname> instead, + which is available as of PHP 8.6.0. + </simpara> </section> <section xml:id="dateinterval.synopsis"> diff --git a/reference/datetime/entities.ent b/reference/datetime/entities.ent new file mode 100644 index 000000000000..7b287a94f1f9 --- /dev/null +++ b/reference/datetime/entities.ent @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<entities xmlns = "http://docbook.org/ns/docbook" + xmlns:xlink = "http://www.w3.org/1999/xlink" + translate = "yes"> + +<entity name="ext.datetime.duration-too-long"> + <listitem> + <simpara> + If the resulting duration exceeds the + <link linkend="time-duration.intro">maximum length of a duration</link>, + a <exceptionname>Time\TimeException</exceptionname> is thrown. + </simpara> + </listitem> +</entity> + +</entities> diff --git a/reference/datetime/time.duration.xml b/reference/datetime/time.duration.xml new file mode 100644 index 000000000000..077656f739a0 --- /dev/null +++ b/reference/datetime/time.duration.xml @@ -0,0 +1,238 @@ +<?xml version="1.0" encoding="utf-8"?> +<reference xml:id="class.time-duration" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>The Time\Duration class</title> + <titleabbrev>Time\Duration</titleabbrev> + + <partintro> + <section xml:id="time-duration.intro"> + &reftitle.intro; + <simpara> + Represents a fixed length of elapsed time, such as a timeout or the time + measured by a stopwatch, with nanosecond precision. + A duration consists of a non-negative number of whole + <property>Time\Duration::$seconds</property>, a number of + <property>Time\Duration::$nanoseconds</property> below one second, and a + sign stored in <property>Time\Duration::$negative</property>. + </simpara> + <simpara> + Unlike <classname>DateInterval</classname>, a + <classname>Time\Duration</classname> does not have calendar units such as + days, months or years, because those do not map to a fixed number of + seconds: a day can be 23 or 25 hours long across a <acronym>DST</acronym> + transition, and months have different lengths. + The largest unit a duration can be created from is therefore the hour. + Use <classname>DateInterval</classname> for calendar arithmetic on + <classname>DateTimeImmutable</classname> objects, and + <classname>Time\Duration</classname> for unambiguous amounts of time, + for example the <parameter>timeout</parameter> of the + <acronym>I/O</acronym> polling <acronym>API</acronym>. + </simpara> + <simpara> + Objects of this class are immutable. + They are created with one of the <literal>Time\Duration::from*()</literal> + factory methods, and every operation such as + <methodname>Time\Duration::add</methodname> or + <methodname>Time\Duration::multiplyBy</methodname> returns a new object + instead of modifying the existing one. + A duration can be negative, which is typically the result of + <methodname>Time\Duration::sub</methodname> or + <methodname>Time\Duration::negate</methodname>. + A duration of zero is never negative. + </simpara> + <simpara> + Two durations can be compared with the + <link linkend="language.operators.comparison">comparison operators</link> + (<literal><</literal>, <literal><=</literal>, + <literal>==</literal>, <literal>!=</literal>, <literal>>=</literal>, + <literal>></literal> and <literal><=></literal>) as well as + with <methodname>Time\Duration::compare</methodname>. + The <link linkend="language.operators.arithmetic">arithmetic + operators</link> are not supported; use the methods of this class + instead. + </simpara> + <simpara> + The maximum length of a duration is <literal>9223372035</literal> + seconds, roughly 292 years, on 64-bit platforms, and + <literal>2147483647</literal> seconds, roughly 68 years, on 32-bit + platforms. + Any operation whose result would exceed this range throws a + <exceptionname>Time\TimeException</exceptionname>. + </simpara> + </section> + + <section xml:id="time-duration.synopsis"> + &reftitle.classsynopsis; + + <packagesynopsis> + <package>Time</package> + + <classsynopsis class="class"> + <ooclass> + <modifier>final</modifier> + <modifier>readonly</modifier> + <classname>Duration</classname> + </ooclass> + + <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>readonly</modifier> + <type>int</type> + <varname linkend="time-duration.props.seconds">seconds</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>readonly</modifier> + <type>int</type> + <varname linkend="time-duration.props.nanoseconds">nanoseconds</varname> + </fieldsynopsis> + <fieldsynopsis> + <modifier>public</modifier> + <modifier>readonly</modifier> + <type>bool</type> + <varname linkend="time-duration.props.negative">negative</varname> + </fieldsynopsis> + + <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.time-duration')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='Time\\Duration'])"/> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.time-duration')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Time\\Duration'])"/> + </classsynopsis> + </packagesynopsis> + </section> + + <section xml:id="time-duration.props"> + &reftitle.properties; + <variablelist> + <varlistentry xml:id="time-duration.props.seconds"> + <term><varname>seconds</varname></term> + <listitem> + <simpara> + The number of whole seconds, without the sign. + This is always greater than or equal to <literal>0</literal>, and at + most <literal>9223372035</literal> on 64-bit platforms or + <literal>2147483647</literal> on 32-bit platforms. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="time-duration.props.nanoseconds"> + <term><varname>nanoseconds</varname></term> + <listitem> + <simpara> + The fraction of a second in nanoseconds, without the sign. + This is always between <literal>0</literal> and + <literal>999999999</literal>, inclusive. + </simpara> + </listitem> + </varlistentry> + <varlistentry xml:id="time-duration.props.negative"> + <term><varname>negative</varname></term> + <listitem> + <simpara> + Whether the duration is negative. + The sign applies to the duration as a whole, so a negative duration of + one and a half seconds has <varname>seconds</varname> set to + <literal>1</literal>, <varname>nanoseconds</varname> set to + <literal>500000000</literal>, and <varname>negative</varname> set to + &true;. + A duration of zero always has this set to &false;. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section xml:id="time-duration.examples"> + &reftitle.examples; + <example xml:id="time-duration.examples.basic"> + <title>Creating and combining durations</title> + <programlisting role="php"> +<![CDATA[ +<?php +$timeout = \Time\Duration::fromMinutes(1)->add(\Time\Duration::fromMilliseconds(1500)); + +var_dump($timeout); +printf("%d.%09d seconds\n", $timeout->seconds, $timeout->nanoseconds); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#3 (3) { + ["seconds"]=> + int(61) + ["nanoseconds"]=> + int(500000000) + ["negative"]=> + bool(false) +} +61.500000000 seconds +]]> + </screen> + </example> + <example xml:id="time-duration.examples.compare"> + <title>Comparing durations</title> + <programlisting role="php"> +<![CDATA[ +<?php +$durations = [ + \Time\Duration::fromMinutes(2), + \Time\Duration::fromMilliseconds(250), + \Time\Duration::fromSeconds(5), +]; + +usort($durations, \Time\Duration::compare(...)); + +foreach ($durations as $duration) { + printf("%d.%09d\n", $duration->seconds, $duration->nanoseconds); +} + +var_dump(\Time\Duration::fromMinutes(1) > \Time\Duration::fromSeconds(59)); +var_dump(\Time\Duration::fromSeconds(1) == \Time\Duration::fromMilliseconds(1000)); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +0.250000000 +5.000000000 +120.000000000 +bool(true) +bool(true) +]]> + </screen> + </example> + </section> + + <section xml:id="time-duration.seealso"> + &reftitle.seealso; + <simplelist> + <member><classname>DateInterval</classname></member> + <member><function>hrtime</function></member> + </simplelist> + </section> + + </partintro> + + &reference.datetime.time.entities.duration; + +</reference> + diff --git a/reference/datetime/time.timeexception.xml b/reference/datetime/time.timeexception.xml new file mode 100644 index 000000000000..cd8edbededb6 --- /dev/null +++ b/reference/datetime/time.timeexception.xml @@ -0,0 +1,60 @@ +<?xml version="1.0" encoding="utf-8"?> +<reference xml:id="class.time-timeexception" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>The Time\TimeException class</title> + <titleabbrev>Time\TimeException</titleabbrev> + + <partintro> + <section xml:id="time-timeexception.intro"> + &reftitle.intro; + <simpara> + The base exception for the <literal>Time</literal> namespace. + </simpara> + </section> + + <section xml:id="time-timeexception.synopsis"> + &reftitle.classsynopsis; + + <packagesynopsis> + <package>Time</package> + + <classsynopsis class="class"> + <ooexception> + <exceptionname>TimeException</exceptionname> + </ooexception> + + <ooclass> + <modifier>extends</modifier> + <classname>Exception</classname> + </ooclass> + + <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))"/> + + <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='Exception'])"/> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Exception'])"/> + </classsynopsis> + </packagesynopsis> + </section> + </partintro> +</reference> + diff --git a/reference/datetime/time/duration/absolute.xml b/reference/datetime/time/duration/absolute.xml new file mode 100644 index 000000000000..00ad7a54107a --- /dev/null +++ b/reference/datetime/time/duration/absolute.xml @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.absolute" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::absolute</refname> + <refpurpose>Returns the absolute value of the duration</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <type>Time\Duration</type><methodname>Time\Duration::absolute</methodname> + <void/> + </methodsynopsis> + <simpara> + Returns the absolute value of the duration, that is, a duration with the + same <property>Time\Duration::$seconds</property> and + <property>Time\Duration::$nanoseconds</property> values whose + <property>Time\Duration::$negative</property> property is &false;. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a non-negative <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.absolute.example.basic"> + <title><methodname>Time\Duration::absolute</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$difference = \Time\Duration::fromSeconds(10)->sub(\Time\Duration::fromSeconds(25)); + +var_dump($difference->negative); +var_dump($difference->absolute()); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +bool(true) +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(15) + ["nanoseconds"]=> + int(0) + ["negative"]=> + bool(false) +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::negate</methodname></member> + <member><methodname>Time\Duration::sub</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/add.xml b/reference/datetime/time/duration/add.xml new file mode 100644 index 000000000000..0701dd09cb1b --- /dev/null +++ b/reference/datetime/time/duration/add.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::add</refname> + <refpurpose>Adds a duration</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <type>Time\Duration</type><methodname>Time\Duration::add</methodname> + <methodparam><type>Time\Duration</type><parameter>duration</parameter></methodparam> + </methodsynopsis> + <simpara> + Returns the sum of this duration and <parameter>duration</parameter>. + The signs of both durations are taken into account, so adding a negative + duration shortens a positive one. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>duration</parameter></term> + <listitem> + <simpara> + The duration to add. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + &ext.datetime.duration-too-long; + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.add.example.basic"> + <title><methodname>Time\Duration::add</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$total = \Time\Duration::fromMinutes(1) + ->add(\Time\Duration::fromSeconds(30)) + ->add(\Time\Duration::fromMilliseconds(500)); + +var_dump($total); + +// Adding a negative duration subtracts it. +$result = \Time\Duration::fromSeconds(10) + ->add(\Time\Duration::fromSeconds(4)->negate()); + +var_dump($result->seconds); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#2 (3) { + ["seconds"]=> + int(90) + ["nanoseconds"]=> + int(500000000) + ["negative"]=> + bool(false) +} +int(6) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::sub</methodname></member> + <member><methodname>Time\Duration::multiplyBy</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/compare.xml b/reference/datetime/time/duration/compare.xml new file mode 100644 index 000000000000..eec1d80070fd --- /dev/null +++ b/reference/datetime/time/duration/compare.xml @@ -0,0 +1,150 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.compare" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::compare</refname> + <refpurpose>Compares two durations</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>int</type><methodname>Time\Duration::compare</methodname> + <methodparam><type>Time\Duration</type><parameter>a</parameter></methodparam> + <methodparam><type>Time\Duration</type><parameter>b</parameter></methodparam> + </methodsynopsis> + <simpara> + Compares the durations <parameter>a</parameter> and + <parameter>b</parameter>, taking their signs into account. + The return value is suitable as the result of a callback for + <function>usort</function>. + </simpara> + <simpara> + The same ordering is used by the + <link linkend="language.operators.comparison">comparison operators</link> + when both operands are <classname>Time\Duration</classname> objects. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>a</parameter></term> + <listitem> + <simpara> + The first duration. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>b</parameter></term> + <listitem> + <simpara> + The second duration. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a value less than <literal>0</literal> if + <parameter>a</parameter> is shorter than <parameter>b</parameter>, a value + greater than <literal>0</literal> if <parameter>a</parameter> is longer + than <parameter>b</parameter>, and <literal>0</literal> if both durations + are equal. + No particular meaning can be reliably inferred from the value aside from + its sign. + Negative durations are always smaller than positive ones. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.compare.example.basic"> + <title><methodname>Time\Duration::compare</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$oneSecond = \Time\Duration::fromSeconds(1); +$oneAndAHalfSeconds = \Time\Duration::fromMilliseconds(1500); +$billionNanoseconds = \Time\Duration::fromNanoseconds(1_000_000_000); + +var_dump(\Time\Duration::compare($oneSecond, $oneAndAHalfSeconds) < 0); +var_dump(\Time\Duration::compare($oneAndAHalfSeconds, $oneSecond) > 0); +var_dump(\Time\Duration::compare($oneSecond, $billionNanoseconds) === 0); + +// Negative durations are smaller than positive ones. +var_dump(\Time\Duration::compare($oneSecond->negate(), $oneSecond) < 0); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +bool(true) +bool(true) +bool(true) +bool(true) +]]> + </screen> + </example> + <example xml:id="time-duration.compare.example.usort"> + <title>Sorting durations with <methodname>Time\Duration::compare</methodname></title> + <programlisting role="php"> +<![CDATA[ +<?php +$durations = [ + \Time\Duration::fromMinutes(2), + \Time\Duration::fromMilliseconds(250), + \Time\Duration::fromSeconds(5), +]; + +usort($durations, \Time\Duration::compare(...)); + +foreach ($durations as $duration) { + printf("%d.%09d\n", $duration->seconds, $duration->nanoseconds); +} +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +0.250000000 +5.000000000 +120.000000000 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><link linkend="language.operators.comparison">Comparison Operators</link></member> + <member><function>usort</function></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/construct.xml b/reference/datetime/time/duration/construct.xml new file mode 100644 index 000000000000..102a6e7c8782 --- /dev/null +++ b/reference/datetime/time/duration/construct.xml @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::__construct</refname> + <refpurpose>Private constructor to disallow direct instantiation</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <constructorsynopsis role="Time\\Duration"> + <modifier>private</modifier> <methodname>Time\Duration::__construct</methodname> + <void/> + </constructorsynopsis> + <simpara> + This private constructor prevents <classname>Time\Duration</classname> + objects from being created with <literal>new</literal>. + Use one of the factory methods instead, which make the unit of the given + value explicit: + <methodname>Time\Duration::fromSeconds</methodname>, + <methodname>Time\Duration::fromNanoseconds</methodname>, + <methodname>Time\Duration::fromMicroseconds</methodname>, + <methodname>Time\Duration::fromMilliseconds</methodname>, + <methodname>Time\Duration::fromMinutes</methodname>, + <methodname>Time\Duration::fromHours</methodname>, or + <methodname>Time\Duration::fromIso8601DurationString</methodname>. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Attempting to instantiate the class with <literal>new</literal> throws an + <exceptionname>Error</exceptionname>. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromSeconds</methodname></member> + <member><methodname>Time\Duration::fromIso8601DurationString</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/divideby.xml b/reference/datetime/time/duration/divideby.xml new file mode 100644 index 000000000000..db467e7f9da8 --- /dev/null +++ b/reference/datetime/time/duration/divideby.xml @@ -0,0 +1,125 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.divideby" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::divideBy</refname> + <refpurpose>Divides the duration by an integer divisor</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <type>Time\Duration</type><methodname>Time\Duration::divideBy</methodname> + <methodparam><type>int</type><parameter>divisor</parameter></methodparam> + </methodsynopsis> + <simpara> + Returns a duration that is this duration divided by + <parameter>divisor</parameter>. + Any remaining fraction of a nanosecond is truncated, so the result is + rounded towards zero. + The sign of the duration is preserved. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>divisor</parameter></term> + <listitem> + <simpara> + The divisor. + Must be greater than <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>divisor</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + <listitem> + <simpara> + If <parameter>divisor</parameter> is <literal>0</literal>, a + <exceptionname>DivisionByZeroError</exceptionname> is thrown. + </simpara> + </listitem> + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.divideby.example.basic"> + <title><methodname>Time\Duration::divideBy</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +// Fractions of a nanosecond are truncated. +var_dump(\Time\Duration::fromSeconds(10)->divideBy(3)->multiplyBy(3)); + +try { + \Time\Duration::fromSeconds(10)->divideBy(0); +} catch (DivisionByZeroError $e) { + echo $e->getMessage(), PHP_EOL; +} +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#3 (3) { + ["seconds"]=> + int(9) + ["nanoseconds"]=> + int(999999999) + ["negative"]=> + bool(false) +} +Division by zero +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::multiplyBy</methodname></member> + <member><function>intdiv</function></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/fromhours.xml b/reference/datetime/time/duration/fromhours.xml new file mode 100644 index 000000000000..0935620f948f --- /dev/null +++ b/reference/datetime/time/duration/fromhours.xml @@ -0,0 +1,119 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.fromhours" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::fromHours</refname> + <refpurpose>Creates a duration from a number of hours</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>Time\Duration</type><methodname>Time\Duration::fromHours</methodname> + <methodparam><type>int</type><parameter>hours</parameter></methodparam> + </methodsynopsis> + <simpara> + Creates a non-negative duration of <parameter>hours</parameter> hours. + The value is normalized into whole seconds and nanoseconds, see the + <property>Time\Duration::$seconds</property> and + <property>Time\Duration::$nanoseconds</property> properties. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>hours</parameter></term> + <listitem> + <simpara> + The number of hours. + Must be greater than or equal to <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>hours</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + &ext.datetime.duration-too-long; + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.fromhours.example.basic"> + <title><methodname>Time\Duration::fromHours</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromHours(24)); + +try { + \Time\Duration::fromHours(PHP_INT_MAX); +} catch (\Time\TimeException $e) { + echo $e->getMessage(), PHP_EOL; +} +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(86400) + ["nanoseconds"]=> + int(0) + ["negative"]=> + bool(false) +} +The maximum representable range is 9_223_372_035 seconds (roughly 292 years) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromSeconds</methodname></member> + <member><methodname>Time\Duration::fromMinutes</methodname></member> + <member><methodname>Time\Duration::fromIso8601DurationString</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/fromiso8601durationstring.xml b/reference/datetime/time/duration/fromiso8601durationstring.xml new file mode 100644 index 000000000000..378d2d1c7b7e --- /dev/null +++ b/reference/datetime/time/duration/fromiso8601durationstring.xml @@ -0,0 +1,183 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.fromiso8601durationstring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::fromIso8601DurationString</refname> + <refpurpose>Creates a duration from an ISO 8601 duration string</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>Time\Duration</type><methodname>Time\Duration::fromIso8601DurationString</methodname> + <methodparam><type>string</type><parameter>specification</parameter></methodparam> + </methodsynopsis> + <simpara> + Creates a non-negative duration from the time part of an + <link xlink:href="&url.iso-8601.duration;"><acronym>ISO</acronym> 8601 + duration specification</link>, such as <literal>PT1H30M</literal>. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>specification</parameter></term> + <listitem> + <simpara> + An <acronym>ISO</acronym> 8601 duration specification. + The format starts with the letter <literal>P</literal>, for + <quote>period</quote>, followed by the letter <literal>T</literal>, + for <quote>time</quote>, and one or more integer values, each followed + by a period designator: + </simpara> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Period Designator</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>H</literal></entry> + <entry>hours</entry> + </row> + <row> + <entry><literal>M</literal></entry> + <entry>minutes</entry> + </row> + <row> + <entry><literal>S</literal></entry> + <entry>seconds</entry> + </row> + </tbody> + </tgroup> + </informaltable> + <simpara> + The designators must appear in this order, but each is optional. + A value may exceed the natural range of its unit, so + <literal>PT90M</literal> and <literal>PT1H30M</literal> describe the + same duration. + </simpara> + <simpara> + The date designators <literal>Y</literal>, <literal>M</literal>, + <literal>W</literal> and <literal>D</literal> are rejected, because + years, months, weeks and days do not have a fixed length. + Fractional values, such as <literal>PT0.5S</literal>, are not + supported either. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>specification</parameter> cannot be parsed as an + <acronym>ISO</acronym> 8601 duration, a + <exceptionname>Time\TimeException</exceptionname> is thrown. + </simpara> + </listitem> + <listitem> + <simpara> + If <parameter>specification</parameter> contains a date designator + (<literal>Y</literal>, <literal>M</literal>, <literal>W</literal> or + <literal>D</literal>), a + <exceptionname>Time\TimeException</exceptionname> is thrown. + </simpara> + </listitem> + <listitem> + <simpara> + If <parameter>specification</parameter> is a date/time or a time interval + rather than a duration, a + <exceptionname>Time\TimeException</exceptionname> is thrown. + </simpara> + </listitem> + &ext.datetime.duration-too-long; + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.fromiso8601durationstring.example.basic"> + <title><methodname>Time\Duration::fromIso8601DurationString</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromIso8601DurationString('PT1H30M')); + +var_dump(\Time\Duration::fromIso8601DurationString('PT90S')->seconds); + +try { + \Time\Duration::fromIso8601DurationString('P1D'); +} catch (\Time\TimeException $e) { + echo $e->getMessage(), PHP_EOL; +} + +try { + \Time\Duration::fromIso8601DurationString('PT0.5S'); +} catch (\Time\TimeException $e) { + echo $e->getMessage(), PHP_EOL; +} +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(5400) + ["nanoseconds"]=> + int(0) + ["negative"]=> + bool(false) +} +int(90) +The ISO 8601 duration string may only contain the time (T) aspect +The ISO 8601 duration string could not be parsed +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromSeconds</methodname></member> + <member><methodname>Time\Duration::fromHours</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/frommicroseconds.xml b/reference/datetime/time/duration/frommicroseconds.xml new file mode 100644 index 000000000000..ac9e4444ba1b --- /dev/null +++ b/reference/datetime/time/duration/frommicroseconds.xml @@ -0,0 +1,111 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.frommicroseconds" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::fromMicroseconds</refname> + <refpurpose>Creates a duration from a number of microseconds</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>Time\Duration</type><methodname>Time\Duration::fromMicroseconds</methodname> + <methodparam><type>int</type><parameter>microseconds</parameter></methodparam> + </methodsynopsis> + <simpara> + Creates a non-negative duration of <parameter>microseconds</parameter> microseconds. + The value is normalized into whole seconds and nanoseconds, see the + <property>Time\Duration::$seconds</property> and + <property>Time\Duration::$nanoseconds</property> properties. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>microseconds</parameter></term> + <listitem> + <simpara> + The number of microseconds. + Must be greater than or equal to <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>microseconds</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.frommicroseconds.example.basic"> + <title><methodname>Time\Duration::fromMicroseconds</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromMicroseconds(1_500_000)); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(1) + ["nanoseconds"]=> + int(500000000) + ["negative"]=> + bool(false) +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromSeconds</methodname></member> + <member><methodname>Time\Duration::fromNanoseconds</methodname></member> + <member><methodname>Time\Duration::fromMilliseconds</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/frommilliseconds.xml b/reference/datetime/time/duration/frommilliseconds.xml new file mode 100644 index 000000000000..2f5e063490f8 --- /dev/null +++ b/reference/datetime/time/duration/frommilliseconds.xml @@ -0,0 +1,111 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.frommilliseconds" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::fromMilliseconds</refname> + <refpurpose>Creates a duration from a number of milliseconds</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>Time\Duration</type><methodname>Time\Duration::fromMilliseconds</methodname> + <methodparam><type>int</type><parameter>milliseconds</parameter></methodparam> + </methodsynopsis> + <simpara> + Creates a non-negative duration of <parameter>milliseconds</parameter> milliseconds. + The value is normalized into whole seconds and nanoseconds, see the + <property>Time\Duration::$seconds</property> and + <property>Time\Duration::$nanoseconds</property> properties. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>milliseconds</parameter></term> + <listitem> + <simpara> + The number of milliseconds. + Must be greater than or equal to <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>milliseconds</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.frommilliseconds.example.basic"> + <title><methodname>Time\Duration::fromMilliseconds</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromMilliseconds(2500)); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(2) + ["nanoseconds"]=> + int(500000000) + ["negative"]=> + bool(false) +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromSeconds</methodname></member> + <member><methodname>Time\Duration::fromMicroseconds</methodname></member> + <member><methodname>Time\Duration::fromMinutes</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/fromminutes.xml b/reference/datetime/time/duration/fromminutes.xml new file mode 100644 index 000000000000..f2eb44c5c68e --- /dev/null +++ b/reference/datetime/time/duration/fromminutes.xml @@ -0,0 +1,119 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.fromminutes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::fromMinutes</refname> + <refpurpose>Creates a duration from a number of minutes</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>Time\Duration</type><methodname>Time\Duration::fromMinutes</methodname> + <methodparam><type>int</type><parameter>minutes</parameter></methodparam> + </methodsynopsis> + <simpara> + Creates a non-negative duration of <parameter>minutes</parameter> minutes. + The value is normalized into whole seconds and nanoseconds, see the + <property>Time\Duration::$seconds</property> and + <property>Time\Duration::$nanoseconds</property> properties. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>minutes</parameter></term> + <listitem> + <simpara> + The number of minutes. + Must be greater than or equal to <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>minutes</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + &ext.datetime.duration-too-long; + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.fromminutes.example.basic"> + <title><methodname>Time\Duration::fromMinutes</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromMinutes(90)); + +try { + \Time\Duration::fromMinutes(-1); +} catch (ValueError $e) { + echo $e->getMessage(), PHP_EOL; +} +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(5400) + ["nanoseconds"]=> + int(0) + ["negative"]=> + bool(false) +} +Time\Duration::fromMinutes(): Argument #1 ($minutes) must be greater than or equal to 0 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromSeconds</methodname></member> + <member><methodname>Time\Duration::fromHours</methodname></member> + <member><methodname>Time\Duration::fromIso8601DurationString</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/fromnanoseconds.xml b/reference/datetime/time/duration/fromnanoseconds.xml new file mode 100644 index 000000000000..520cc93c2dd8 --- /dev/null +++ b/reference/datetime/time/duration/fromnanoseconds.xml @@ -0,0 +1,138 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.fromnanoseconds" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::fromNanoseconds</refname> + <refpurpose>Creates a duration from a number of nanoseconds</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>Time\Duration</type><methodname>Time\Duration::fromNanoseconds</methodname> + <methodparam><type>int</type><parameter>nanoseconds</parameter></methodparam> + </methodsynopsis> + <simpara> + Creates a non-negative duration of <parameter>nanoseconds</parameter> nanoseconds. + The value is normalized into whole seconds and nanoseconds, see the + <property>Time\Duration::$seconds</property> and + <property>Time\Duration::$nanoseconds</property> properties. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>nanoseconds</parameter></term> + <listitem> + <simpara> + The number of nanoseconds. + Must be greater than or equal to <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>nanoseconds</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.fromnanoseconds.example.basic"> + <title><methodname>Time\Duration::fromNanoseconds</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromNanoseconds(1_500_000_000)); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(1) + ["nanoseconds"]=> + int(500000000) + ["negative"]=> + bool(false) +} +]]> + </screen> + </example> + <example xml:id="time-duration.fromnanoseconds.example.hrtime"> + <title>Measuring elapsed time with <function>hrtime</function></title> + <programlisting role="php"> +<![CDATA[ +<?php +$start = hrtime(true); +usleep(1000); +$elapsed = \Time\Duration::fromNanoseconds(hrtime(true) - $start); + +var_dump($elapsed); +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(0) + ["nanoseconds"]=> + int(1062541) + ["negative"]=> + bool(false) +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromSeconds</methodname></member> + <member><methodname>Time\Duration::fromMicroseconds</methodname></member> + <member><methodname>Time\Duration::fromMilliseconds</methodname></member> + <member><function>hrtime</function></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/fromseconds.xml b/reference/datetime/time/duration/fromseconds.xml new file mode 100644 index 000000000000..b53ad22b03ab --- /dev/null +++ b/reference/datetime/time/duration/fromseconds.xml @@ -0,0 +1,153 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.fromseconds" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::fromSeconds</refname> + <refpurpose>Creates a duration from a number of seconds and nanoseconds</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <modifier>static</modifier> <type>Time\Duration</type><methodname>Time\Duration::fromSeconds</methodname> + <methodparam><type>int</type><parameter>seconds</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>nanoseconds</parameter><initializer>0</initializer></methodparam> + </methodsynopsis> + <simpara> + Creates a non-negative duration of <parameter>seconds</parameter> seconds + plus <parameter>nanoseconds</parameter> nanoseconds. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>seconds</parameter></term> + <listitem> + <simpara> + The number of whole seconds. + Must be greater than or equal to <literal>0</literal>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>nanoseconds</parameter></term> + <listitem> + <simpara> + The fraction of a second, in nanoseconds. + Must be between <literal>0</literal> and <literal>999999999</literal>, + inclusive. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>seconds</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + <listitem> + <simpara> + If <parameter>nanoseconds</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + <listitem> + <simpara> + If <parameter>nanoseconds</parameter> is greater than or equal to + <literal>1000000000</literal>, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + &ext.datetime.duration-too-long; + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.fromseconds.example.basic"> + <title><methodname>Time\Duration::fromSeconds</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromSeconds(90)); +var_dump(\Time\Duration::fromSeconds(1, 500_000_000)); + +try { + \Time\Duration::fromSeconds(0, 1_000_000_000); +} catch (ValueError $e) { + echo $e->getMessage(), PHP_EOL; +} +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(90) + ["nanoseconds"]=> + int(0) + ["negative"]=> + bool(false) +} +object(Time\Duration)#2 (3) { + ["seconds"]=> + int(1) + ["nanoseconds"]=> + int(500000000) + ["negative"]=> + bool(false) +} +Time\Duration::fromSeconds(): Argument #2 ($nanoseconds) must be less than 1_000_000_000 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::fromNanoseconds</methodname></member> + <member><methodname>Time\Duration::fromMicroseconds</methodname></member> + <member><methodname>Time\Duration::fromMilliseconds</methodname></member> + <member><methodname>Time\Duration::fromMinutes</methodname></member> + <member><methodname>Time\Duration::fromHours</methodname></member> + <member><methodname>Time\Duration::fromIso8601DurationString</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/multiplyby.xml b/reference/datetime/time/duration/multiplyby.xml new file mode 100644 index 000000000000..a375da838ebd --- /dev/null +++ b/reference/datetime/time/duration/multiplyby.xml @@ -0,0 +1,118 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.multiplyby" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::multiplyBy</refname> + <refpurpose>Multiplies the duration by an integer factor</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <type>Time\Duration</type><methodname>Time\Duration::multiplyBy</methodname> + <methodparam><type>int</type><parameter>factor</parameter></methodparam> + </methodsynopsis> + <simpara> + Returns a duration that is <parameter>factor</parameter> times as long as + this duration. + The sign of the duration is preserved. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>factor</parameter></term> + <listitem> + <simpara> + The factor to multiply by. + Must be greater than or equal to <literal>0</literal>; a factor of + <literal>0</literal> results in a duration of zero. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + <listitem> + <simpara> + If <parameter>factor</parameter> is negative, a + <exceptionname>ValueError</exceptionname> is thrown. + </simpara> + </listitem> + &ext.datetime.duration-too-long; + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.multiplyby.example.basic"> + <title><methodname>Time\Duration::multiplyBy</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromMilliseconds(1500)->multiplyBy(4)); + +try { + \Time\Duration::fromHours(1)->multiplyBy(3_000_000); +} catch (\Time\TimeException $e) { + echo $e->getMessage(), PHP_EOL; +} +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#2 (3) { + ["seconds"]=> + int(6) + ["nanoseconds"]=> + int(0) + ["negative"]=> + bool(false) +} +The maximum representable range is 9_223_372_035 seconds (roughly 292 years) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::divideBy</methodname></member> + <member><methodname>Time\Duration::add</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/negate.xml b/reference/datetime/time/duration/negate.xml new file mode 100644 index 000000000000..fbd0215d6b3c --- /dev/null +++ b/reference/datetime/time/duration/negate.xml @@ -0,0 +1,89 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.negate" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::negate</refname> + <refpurpose>Returns the duration with the opposite sign</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <type>Time\Duration</type><methodname>Time\Duration::negate</methodname> + <void/> + </methodsynopsis> + <simpara> + Returns a duration of the same length with the opposite sign: a positive + duration becomes negative, and a negative duration becomes positive. + Negating a duration of zero returns a duration of zero, which is never + negative. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + &no.function.parameters; + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.negate.example.basic"> + <title><methodname>Time\Duration::negate</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$duration = \Time\Duration::fromSeconds(30); + +var_dump($duration->negate()->negative); +var_dump($duration->negate()->negate()->negative); + +// A zero duration has no sign. +var_dump(\Time\Duration::fromSeconds(0)->negate()->negative); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +bool(true) +bool(false) +bool(false) +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::absolute</methodname></member> + <member><methodname>Time\Duration::sub</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/sub.xml b/reference/datetime/time/duration/sub.xml new file mode 100644 index 000000000000..02a387b30279 --- /dev/null +++ b/reference/datetime/time/duration/sub.xml @@ -0,0 +1,118 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.sub" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::sub</refname> + <refpurpose>Subtracts a duration</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <type>Time\Duration</type><methodname>Time\Duration::sub</methodname> + <methodparam><type>Time\Duration</type><parameter>duration</parameter></methodparam> + </methodsynopsis> + <simpara> + Returns the difference between this duration and + <parameter>duration</parameter>. + The signs of both durations are taken into account, so subtracting a + negative duration lengthens a positive one. + If <parameter>duration</parameter> is longer than this duration, the + result is negative. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>duration</parameter></term> + <listitem> + <simpara> + The duration to subtract. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a new <classname>Time\Duration</classname> object. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <itemizedlist> + &ext.datetime.duration-too-long; + </itemizedlist> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="time-duration.sub.example.basic"> + <title><methodname>Time\Duration::sub</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +var_dump(\Time\Duration::fromSeconds(10)->sub(\Time\Duration::fromMilliseconds(2500))); + +// Subtracting a larger duration results in a negative duration. +var_dump(\Time\Duration::fromSeconds(1)->sub(\Time\Duration::fromSeconds(3))); +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +object(Time\Duration)#3 (3) { + ["seconds"]=> + int(7) + ["nanoseconds"]=> + int(500000000) + ["negative"]=> + bool(false) +} +object(Time\Duration)#1 (3) { + ["seconds"]=> + int(2) + ["nanoseconds"]=> + int(0) + ["negative"]=> + bool(true) +} +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Time\Duration::add</methodname></member> + <member><methodname>Time\Duration::negate</methodname></member> + <member><methodname>Time\Duration::absolute</methodname></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/time/duration/unserialize.xml b/reference/datetime/time/duration/unserialize.xml new file mode 100644 index 000000000000..4cd8e175536a --- /dev/null +++ b/reference/datetime/time/duration/unserialize.xml @@ -0,0 +1,80 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="time-duration.unserialize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>Time\Duration::__unserialize</refname> + <refpurpose>Restores a duration from serialized data</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Time\\Duration"> + <modifier>public</modifier> <type>void</type><methodname>Time\Duration::__unserialize</methodname> + <methodparam><type>array</type><parameter>data</parameter></methodparam> + </methodsynopsis> + <simpara> + Deserializes the &array; from the <parameter>data</parameter> parameter + into a <classname>Time\Duration</classname> object. + This method is called by <function>unserialize</function> and is not + meant to be called directly. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>data</parameter></term> + <listitem> + <simpara> + The serialized data as an <type>array</type>. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + &return.void; + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + If <parameter>data</parameter> does not describe a valid duration, an + <exceptionname>Exception</exceptionname> is thrown. + </simpara> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>serialize</function></member> + <member><function>unserialize</function></member> + <member><link linkend="language.oop5.magic">Magic Methods</link></member> + </simplelist> + </refsect1> + +</refentry> + diff --git a/reference/datetime/versions.xml b/reference/datetime/versions.xml index f01e5455e684..a5c4eb28ab41 100644 --- a/reference/datetime/versions.xml +++ b/reference/datetime/versions.xml @@ -94,6 +94,25 @@ <function name="dateperiod::getdateinterval" from="PHP 5 >= 5.6.5, PHP 7, PHP 8"/> <function name="dateperiod::getrecurrences" from="PHP 7 >= 7.2.17/7.3.4, PHP 8"/> +  + <function name="time\duration" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::__construct" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::__unserialize" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::fromseconds" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::fromnanoseconds" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::frommicroseconds" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::frommilliseconds" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::fromminutes" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::fromhours" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::fromiso8601durationstring" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::negate" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::absolute" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::add" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::sub" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::multiplyby" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::divideby" from="PHP 8 >= 8.6.0"/> + <function name="time\duration::compare" from="PHP 8 >= 8.6.0"/> +  <function name="dateerror" from="PHP 8 >= 8.3.0"/> <function name="dateobjecterror" from="PHP 8 >= 8.3.0"/> @@ -104,6 +123,7 @@ <function name="datemalformedintervalstringexception" from="PHP 8 >= 8.3.0"/> <function name="datemalformedperiodstringexception" from="PHP 8 >= 8.3.0"/> <function name="datemalformedstringexception" from="PHP 8 >= 8.3.0"/> + <function name="time\timeexception" from="PHP 8 >= 8.6.0"/>  <function name="checkdate" from="PHP 4, PHP 5, PHP 7, PHP 8"/>