Skip to content

[Sync-En] ext/date: document that DateInterval addition depends on how the interval was created #3501

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[Sync-En] ext/date: document that DateInterval addition depends on how the interval was created #3501

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 21 additions & 15 deletions reference/datetime/dateinterval.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 4d17b7b4947e7819ff5036715dd706be87ae4def Maintainer: victor-prdh Status: ready -->
<!-- Reviewed: no -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: victor-prdh Status: ready -->
<reference xml:id="class.dateinterval" 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>La classe <classname>DateInterval</classname></title>
<titleabbrev>DateInterval</titleabbrev>

<partintro>

<!-- {{{ DateInterval intro -->
<section xml:id="dateinterval.intro">
&reftitle.intro;
<para>
Expand All @@ -32,18 +29,32 @@
est en calculant la différence entre deux objets dates/moments à travers
<methodname>DateTimeInterface::diff</methodname>.
</para>
<simpara>
La façon dont la partie horaire d'un intervalle, c'est-à-dire les heures,
les minutes, les secondes et les microsecondes, est appliquée lorsque
l'intervalle est ajouté à un objet date/heure, ou soustrait de celui-ci,
dépend de la manière dont l'intervalle a été créé. Pour un intervalle créé
avec <methodname>DateInterval::__construct</methodname>, la partie horaire
correspond au temps écoulé, tandis que pour un intervalle créé avec
<methodname>DateInterval::createFromDateString</methodname>, ou retourné
par <methodname>DateTimeInterface::diff</methodname>, elle incrémente ou
décrémente les valeurs individuelles des composants. La partie date,
c'est-à-dire les années, les mois et les jours, incrémente ou décrémente
toujours les valeurs individuelles des composants. Les deux ne donnent donc
un résultat différent que lorsqu'une transition de fuseau horaire tombe
dans la partie horaire de l'intervalle ; voir
<link linkend="datetime.examples-arithmetic">Arithmétique avec DateTime</link>.
</simpara>
<para>
Comme il n'y a pas une manière bien définie pour comparer les intervalles,
les instances de <classname>DateInterval</classname> sont
<link linkend="language.operators.comparison.incomparable">incomparables</link>.
</para>
</section>
<!-- }}} -->

<section xml:id="dateinterval.synopsis">
&reftitle.classsynopsis;

<!-- {{{ Synopsis -->
<classsynopsis class="class">
<ooclass>
<classname>DateInterval</classname>
Expand Down Expand Up @@ -107,14 +118,9 @@
</fieldsynopsis>

<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='DateInterval'])">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DateInterval'])">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='DateInterval'])"/>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DateInterval'])"/>
</classsynopsis>
<!-- }}} -->

</section>

Expand Down Expand Up @@ -231,7 +237,7 @@
</varlistentry>
</variablelist>
</section>
<section role="changelog" xml:id="dateinterval.changelog"><!-- {{{ -->
<section role="changelog" xml:id="dateinterval.changelog">
&reftitle.changelog;
<para>
<informaltable>
Expand Down Expand Up @@ -274,7 +280,7 @@
</tgroup>
</informaltable>
</para>
</section><!-- }}} -->
</section>
</partintro>

&reference.datetime.entities.dateinterval;
Expand Down
111 changes: 58 additions & 53 deletions reference/datetime/dateinterval/createfromdatestring.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 911fe79de766ef4475bf22446903667a0f3a24d3 Maintainer: lacatoire Status: ready -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: lacatoire Status: ready -->
<refentry xml:id="dateinterval.createfromdatestring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>DateInterval::createFromDateString</refname>
Expand Down Expand Up @@ -28,27 +28,25 @@

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>datetime</parameter></term>
<listitem>
<para>
Une date avec des parties relatives. Spécifiquement, le
<link linkend="datetime.formats.relative">format relatif</link>
supporté par l'analyseur utilisé pour les classes
<classname>DateTimeImmutable</classname>,
<classname>DateTime</classname>, et <function>strtotime</function>
sera utilisé pour construire le DateInterval.
</para>
<para>
Pour utiliser une chaîne au format ISO-8601 comme <literal>P7D</literal>, il faut
utiliser <methodname>DateInterval::__construct</methodname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term><parameter>datetime</parameter></term>
<listitem>
<simpara>
Une date avec des parties relatives. Spécifiquement, le
<link linkend="datetime.formats.relative">format relatif</link>
supporté par l'analyseur utilisé pour les classes
<classname>DateTimeImmutable</classname>,
<classname>DateTime</classname>, et <function>strtotime</function>
sera utilisé pour construire le DateInterval.
</simpara>
<simpara>
Pour utiliser une chaîne au format ISO-8601 comme <literal>P7D</literal>,
il faut utiliser <methodname>DateInterval::__construct</methodname>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
Expand Down Expand Up @@ -111,13 +109,12 @@

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Analyse d'intervalles de dates valides</title>
<programlisting role="php" annotations="non-interactive">
<example>
<title>Analyse d'intervalles de dates valides</title>
<programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
// Chacun de ces intervalles est égal.
// Chaque ensemble d'intervalles décrit la même durée.
$i = new DateInterval('P1D');
$i = DateInterval::createFromDateString('1 day');

Expand All @@ -139,13 +136,24 @@ $i = DateInterval::createFromDateString('1 day + 12 hours');
$i = new DateInterval('PT3600S');
$i = DateInterval::createFromDateString('3600 seconds');
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Analyse des combinaisons et des intervalles négatifs</title>
<programlisting role="php">
</programlisting>
</example>
<note>
<simpara>
Les intervalles d'un ensemble qui comportent une partie horaire, tels que
<literal>P1DT12H</literal> et <literal>1 day + 12 hours</literal>, ne sont
pas interchangeables lorsqu'ils sont ajoutés à un objet date/heure et
qu'une transition de fuseau horaire tombe dans cette partie horaire : pour
un intervalle créé avec <methodname>DateInterval::__construct</methodname>,
la partie horaire correspond au temps écoulé, tandis que pour un intervalle
créé avec cette méthode, elle incrémente ou décrémente les valeurs
individuelles des composants. Voir
<link linkend="datetime.examples-arithmetic">Arithmétique avec DateTime</link>.
</simpara>
</note>
<example>
<title>Analyse des combinaisons et des intervalles négatifs</title>
<programlisting role="php">
<![CDATA[
<?php
$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
Expand All @@ -154,20 +162,18 @@ echo $i->format('%d %h %i'), "\n";
$i = DateInterval::createFromDateString('1 year - 10 days');
echo $i->format('%y %d'), "\n";
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
449 2 70
1 -10
]]>
</screen>
</example>
</para>
<para>
<example>
<title>Analyse des intervalles de dates relatifs spéciaux</title>
<programlisting role="php">
</screen>
</example>
<example>
<title>Analyse des intervalles de dates relatifs spéciaux</title>
<programlisting role="php">
<![CDATA[
<?php
$i = DateInterval::createFromDateString('last day of next month');
Expand All @@ -176,9 +182,9 @@ var_dump($i);
$i = DateInterval::createFromDateString('last weekday');
var_dump($i);
]]>
</programlisting>
&example.outputs.82;
<screen role="php">
</programlisting>
&example.outputs.82;
<screen role="php">
<![CDATA[
object(DateInterval)#1 (2) {
["from_string"]=>
Expand All @@ -193,9 +199,9 @@ object(DateInterval)#2 (2) {
string(12) "last weekday"
}
]]>
</screen>
&example.outputs.8.similar;
<screen role="php">
</screen>
&example.outputs.8.similar;
<screen role="php">
<![CDATA[
object(DateInterval)#1 (16) {
["y"]=>
Expand Down Expand Up @@ -266,9 +272,8 @@ object(DateInterval)#2 (16) {
int(1)
}
]]>
</screen>
</example>
</para>
</screen>
</example>
</refsect1>

</refentry>
Expand Down
3 changes: 2 additions & 1 deletion reference/datetime/datetimeimmutable/add.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 726154e3c846bc0e16c60542377ea806df32e55d Maintainer: lacatoire Status: ready -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: lacatoire Status: ready -->
<refentry xml:id="datetimeimmutable.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>DateTimeImmutable::add</refname>
Expand Down Expand Up @@ -117,6 +117,7 @@ echo $newDate2->format('Y-m-d') . "\n";
<member><function>DateTimeImmutable::sub</function></member>
<member><function>DateTimeImmutable::diff</function></member>
<member><function>DateTimeImmutable::modify</function></member>
<member><link linkend="datetime.examples-arithmetic">Arithmétique avec DateTime</link></member>
</simplelist>
</refsect1>
</refentry>
Expand Down
8 changes: 5 additions & 3 deletions reference/datetime/datetimeimmutable/sub.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 726154e3c846bc0e16c60542377ea806df32e55d Maintainer: lacatoire Status: ready -->
<!-- Reviewed: yes -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: lacatoire Status: ready -->
<refentry xml:id="datetimeimmutable.sub" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>DateTimeImmutable::sub</refname>
<refpurpose>Soustrait un nombre de jours, mois, années, heures et secondes</refpurpose>
<refpurpose>
Soustrait un nombre de jours, mois, années, heures, minutes et secondes
</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand Down Expand Up @@ -153,6 +154,7 @@ echo $newDate2->format('Y-m-d') . "\n";
<member><function>DateTimeImmutable::add</function></member>
<member><function>DateTimeImmutable::diff</function></member>
<member><function>DateTimeImmutable::modify</function></member>
<member><link linkend="datetime.examples-arithmetic">Arithmétique avec DateTime</link></member>
</simplelist>
</refsect1>

Expand Down
Loading
Loading