La clase Time\Duration

Introducción

Representa una duración fija de tiempo transcurrido, como un tiempo de espera o el tiempo medido por un cronómetro, con una precisión de nanosegundos. Una duración consta de un número no negativo de Time\Duration::$seconds enteros, un número de Time\Duration::$nanoseconds inferior a un segundo, y un signo almacenado en Time\Duration::$negative.

A diferencia de DateInterval, una Time\Duration no tiene unidades de calendario como días, meses o años, porque estas no equivalen a un número fijo de segundos: un día puede durar 23 o 25 horas en una transición de DST (horario de verano), y los meses tienen duraciones diferentes. Por lo tanto, la unidad más grande a partir de la cual se puede crear una duración es la hora. Utilice DateInterval para la aritmética de calendario sobre objetos DateTimeImmutable, y Time\Duration para cantidades de tiempo inequívocas, por ejemplo el timeout de la API de sondeo de E/S.

Los objetos de esta clase son inmutables. Se crean con uno de los métodos de fábrica Time\Duration::from*(), y cada operación como Time\Duration::add() o Time\Duration::multiplyBy() devuelve un nuevo objeto en lugar de modificar el existente. Una duración puede ser negativa, lo que suele ser el resultado de Time\Duration::sub() o Time\Duration::negate(). Una duración de cero nunca es negativa.

Dos duraciones pueden compararse con los operadores de comparación (<, <=, ==, !=, >=, > y <=>), así como con Time\Duration::compare(). Los operadores aritméticos no están soportados; utilice en su lugar los métodos de esta clase.

La longitud máxima de una duración es de 9223372035 segundos, aproximadamente 292 años, en plataformas de 64 bits, y de 2147483647 segundos, aproximadamente 68 años, en plataformas de 32 bits. Cualquier operación cuyo resultado exceda este rango lanza una Time\TimeException.

Sinopsis de la clase

Propiedades

seconds

El número de segundos enteros, sin el signo. Siempre es mayor o igual que 0, y como máximo 9223372035 en plataformas de 64 bits o 2147483647 en plataformas de 32 bits.

nanoseconds

La fracción de segundo en nanosegundos, sin el signo. Siempre está entre 0 y 999999999, ambos inclusive.

negative

Indica si la duración es negativa. El signo se aplica a la duración en su conjunto, por lo que una duración negativa de un segundo y medio tiene seconds con el valor 1, nanoseconds con el valor 500000000, y negative con el valor true. Una duración de cero siempre tiene este valor en false.

Ejemplos

<?php
$timeout = \Time\Duration::fromMinutes(1)->add(\Time\Duration::fromMilliseconds(1500));

var_dump($timeout);
printf("%d.%09d seconds\n", $timeout->seconds, $timeout->nanoseconds);

object(Time\Duration)#3 (3) {
  ["seconds"]=>
  int(61)
  ["nanoseconds"]=>
  int(500000000)
  ["negative"]=>
  bool(false)
}
61.500000000 seconds

<?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));

0.250000000
5.000000000
120.000000000
bool(true)
bool(true)

Véase también

• DateInterval
• hrtime()