Skip to content

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

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
+171 −133
Open

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

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
33 changes: 20 additions & 13 deletions reference/datetime/dateinterval.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 4d17b7b4947e7819ff5036715dd706be87ae4def Maintainer: Marqitos Status: ready -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: Marqitos Status: ready -->
<!-- Reviewed: no Maintainer: seros -->
<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">

Expand All @@ -9,7 +9,6 @@

<partintro>

<!-- {{{ DateInterval intro -->
<section xml:id="dateinterval.intro">
&reftitle.intro;
<para>
Expand All @@ -31,18 +30,31 @@
es calculando la diferencia entre dos objetos de fecha/hora a través de
<methodname>DateTimeInterface::diff</methodname>.
</para>
<simpara>
La forma en que se aplica la parte horaria de un intervalo, es decir horas,
minutos, segundos y microsegundos, cuando el intervalo se suma a, o se
resta de, un objeto de fecha/hora depende de cómo se creó el intervalo.
Para un intervalo creado con
<methodname>DateInterval::__construct</methodname> la parte horaria
representa tiempo transcurrido, mientras que para un intervalo creado con
<methodname>DateInterval::createFromDateString</methodname>, o devuelto por
<methodname>DateTimeInterface::diff</methodname>, incrementa o decrementa
los valores de cada componente. La parte de fecha, es decir años, meses y
días, siempre incrementa o decrementa los valores de cada componente. Por
lo tanto, ambos solo dan un resultado distinto cuando una transición de
zona horaria cae dentro de la parte horaria del intervalo; véase
<link linkend="datetime.examples-arithmetic">Aritmética con DateTime</link>.
</simpara>
<para>
Dado que no hay una forma bien definida de comparar intervalos de fechas,
las instancias de <classname>DateInterval</classname> son
<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 @@ -106,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 +238,7 @@
</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 +281,7 @@
</tgroup>
</informaltable>
</para>
</section><!-- }}} -->
</section>

</partintro>

Expand Down
108 changes: 56 additions & 52 deletions reference/datetime/dateinterval/createfromdatestring.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 911fe79de766ef4475bf22446903667a0f3a24d3 Maintainer: lacatoire Status: ready -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: lacatoire Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="dateinterval.createfromdatestring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand Down Expand Up @@ -30,26 +30,24 @@

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>datetime</parameter></term>
<listitem>
<para>
Una fecha con partes relativas. Específicamente, los
<link linkend="datetime.formats.relative">formatos relativos</link>
admitidos por el analizador utilizados por <classname>DateTimeImmutable</classname>,
<classname>DateTime</classname>, y <function>strtotime</function>
serán los empleados para construir el objeto DateInterval
</para>
<para>
Para usar un string con formato ISO-8601 como <literal>P7D</literal>, debes
usar <methodname>DateInterval::__construct</methodname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term><parameter>datetime</parameter></term>
<listitem>
<simpara>
Una fecha con partes relativas. Específicamente, los
<link linkend="datetime.formats.relative">formatos relativos</link>
admitidos por el analizador utilizados por <classname>DateTimeImmutable</classname>,
<classname>DateTime</classname>, y <function>strtotime</function>
serán los empleados para construir el objeto DateInterval
</simpara>
<simpara>
Para usar un string con formato ISO-8601 como <literal>P7D</literal>, debes
usar <methodname>DateInterval::__construct</methodname>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

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

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Analizando intervalos de fechas válidos</title>
<programlisting role="php" annotations="non-interactive">
<example>
<title>Analizando intervalos de fechas válidos</title>
<programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
// Cada conjunto de intervalos es equivalente.
// Cada conjunto de intervalos describe la misma duración.
$i = new DateInterval('P1D');
$i = DateInterval::createFromDateString('1 day');

Expand All @@ -140,13 +137,23 @@ $i = DateInterval::createFromDateString('1 day + 12 hours');
$i = new DateInterval('PT3600S');
$i = DateInterval::createFromDateString('3600 seconds');
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Analizando combinaciones e intervalos negativos</title>
<programlisting role="php">
</programlisting>
</example>
<note>
<simpara>
Los intervalos de un conjunto que tienen una parte horaria, como
<literal>P1DT12H</literal> y <literal>1 day + 12 hours</literal>, no son
intercambiables cuando se suman a un objeto de fecha/hora y una transición
de zona horaria cae dentro de esa parte horaria: para un intervalo creado
con <methodname>DateInterval::__construct</methodname> la parte horaria
representa tiempo transcurrido, mientras que para un intervalo creado con
este método incrementa o decrementa los valores de cada componente. Véase
<link linkend="datetime.examples-arithmetic">Aritmética con DateTime</link>.
</simpara>
</note>
<example>
<title>Analizando combinaciones e intervalos negativos</title>
<programlisting role="php">
<![CDATA[
<?php
$i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
Expand All @@ -155,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>Analizando intervalos de fechas relativas especiales</title>
<programlisting role="php">
</screen>
</example>
<example>
<title>Analizando intervalos de fechas relativas especiales</title>
<programlisting role="php">
<![CDATA[
<?php
$i = DateInterval::createFromDateString('last day of next month');
Expand All @@ -177,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 @@ -194,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 @@ -267,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,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 726154e3c846bc0e16c60542377ea806df32e55d Maintainer: Marqitos Status: ready -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: Marqitos Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="datetimeimmutable.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand Down Expand Up @@ -118,6 +118,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">Aritmética con DateTime</link></member>
</simplelist>
</refsect1>
</refentry>
Expand Down
3 changes: 2 additions & 1 deletion reference/datetime/datetimeimmutable/sub.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 726154e3c846bc0e16c60542377ea806df32e55d Maintainer: Marqitos Status: ready -->
<!-- EN-Revision: 18c0977d5ec59f4207cb0b306c5473508bf640ed Maintainer: Marqitos Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="datetimeimmutable.sub" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand Down Expand Up @@ -156,6 +156,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">Aritmética con DateTime</link></member>
</simplelist>
</refsect1>

Expand Down
Loading