<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: 3a8c3e77df070a046c9d5b56b68926ca2d7e5ee3 Maintainer: Marqitos Status: ready -->

<!-- Reviewed: no -->

<refentry xml:id="datetime.diff" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>DateTimeInterface::diff</refname>

<refname>DateTimeImmutable::diff</refname>

<refname>DateTime::diff</refname>

<refname>date_diff</refname>

<refpurpose>Devuelve la diferencia entre dos objetos DateTime</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<para>&style.oop;</para>

<methodsynopsis role="DateTimeInterface">

<modifier>public</modifier> <type>DateInterval</type><methodname>DateTimeInterface::diff</methodname>

<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>

<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>

</methodsynopsis>

<methodsynopsis role="DateTimeImmutable">

<modifier>public</modifier> <type>DateInterval</type><methodname>DateTimeImmutable::diff</methodname>

<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>

<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>

</methodsynopsis>

<methodsynopsis role="DateTime">

<modifier>public</modifier> <type>DateInterval</type><methodname>DateTime::diff</methodname>

<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>

<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>

</methodsynopsis>

<para>&style.procedural;</para>

<methodsynopsis>

<type>DateInterval</type><methodname>date_diff</methodname>

<methodparam><type>DateTimeInterface</type><parameter>baseObject</parameter></methodparam>

<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>

<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>

</methodsynopsis>

<para>

Devuelve la diferencia entre dos objetos

<classname>DateTimeInterface</classname>.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>datetime</parameter></term>

<listitem>

<para>

La fecha a comparar.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>absolute</parameter></term>

<listitem>

<para>

¿Debería el intervalo forzado a ser positivo?

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

El objeto <classname>DateInterval</classname> que representa la

diferencia entre dos fechas.

</para>

<para>

El parámetro <parameter>absolute</parameter> solo afecta

a la propiedad <parameter>invert</parameter> de un

objeto <classname>DateInterval</classname>.

</para>

<para>

El valor devuelto más especificamente, representa el intervalo de tiempo

que habría que aplicar al objeto original (<parameter>$this</parameter> o

<parameter>$originObject</parameter>) para llegar a

<parameter>$targetObject</parameter>. Este proceso no siempre es

reversible.

</para>

<para>

El método tiene en cuenta los cambios de horario de verano y, por lo tanto,

puede devolver un intervalo de <literal>24 horas y 30 minutos</literal>,

como en uno de los ejemplos. Si quieres calcular un tiempo absoluto,

debes comvertir ambos <parameter>$this</parameter>/<parameter>$baseObject</parameter>,

y <parameter>$targetObject</parameter> primero a UTC.

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example>

<title>Ejemplo de <function>DateTime::diff</function></title>

<para>&style.oop;</para>

<programlisting role="php">

<![CDATA[

<?php

$origin = new DateTimeImmutable('2009-10-11');

$target = new DateTimeImmutable('2009-10-13');

$interval = $origin->diff($target);

echo $interval->format('%R%a days');

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

+2 days

]]>

</screen>

<para>&style.procedural;</para>

<programlisting role="php">

<![CDATA[

<?php

$origin = date_create('2009-10-11');

$target = date_create('2009-10-13');

$interval = date_diff($origin, $target);

echo $interval->format('%R%a days');

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

+2 days

]]>

</screen>

</example>

<example>

<title><methodname>DateTimeInterface::diff</methodname>

durante el cambio de horario de verano</title>

<programlisting role="php">

<![CDATA[

<?php

$originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");

$targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");

$interval = $originalTime->diff($targetTime);

echo $interval->format("%H:%I:%S (Días completos: %a)"), "\n";

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

24:30:00 (Días completos: 0)

]]>

</screen>

</example>

<example>

<title><methodname>DateTimeInterface::diff</methodname> range</title>

<para>

El valor devuelto es la cantidad de tiempo exacto entre

<parameter>$this</parameter> y <parameter>$targetObject</parameter>.

Comparando del 1 de enero al 31 de diciembre devuelve 364 días,

y no 365 (para años no bisiestos).

</para>

<programlisting role="php">

<![CDATA[

<?php

$originalTime = new DateTimeImmutable("2023-01-01 UTC");

$targetTime = new DateTimeImmutable("2023-12-31 UTC");

$interval = $originalTime->diff($targetTime);

echo "Días completos: ", $interval->format("%a"), "\n";

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Días completos: 364

]]>

</screen>

</example>

<example>

<title>Comparación de objetos <classname>DateTime</classname></title>

<note>

<para>

Los objetos DateTime se pueden comparar usando los

<link linkend="language.operators.comparison">operadores de comparación</link>.

</para>

</note>

<programlisting role="php">

<![CDATA[

<?php

$date1 = new DateTime("now");

$date2 = new DateTime("tomorrow");

var_dump($date1 == $date2);

var_dump($date1 < $date2);

var_dump($date1 > $date2);

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

bool(false)

bool(true)

bool(false)

]]>

</screen>

</example>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<simplelist>

<member><function>DateInterval::format</function></member>

<member><function>DateTime::add</function></member>

<member><function>DateTime::sub</function></member>

</simplelist>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->