La classe Time\Duration

Introduction

Représente une durée fixe de temps écoulé, comme un timeout ou le temps mesuré par un chronomètre, avec une précision à la nanoseconde. Une durée se compose d'un nombre non négatif de secondes entières, Time\Duration::$seconds, d'un nombre de nanosecondes inférieur à une seconde, Time\Duration::$nanoseconds, et d'un signe stocké dans Time\Duration::$negative.

Contrairement à DateInterval, une Time\Duration n'a pas d'unités calendaires comme les jours, les mois ou les années, car celles-ci ne correspondent pas à un nombre fixe de secondes : un jour peut durer 23 ou 25 heures lors d'un passage à l'heure d'été (DST), et les mois n'ont pas tous la même longueur. La plus grande unité à partir de laquelle une durée peut être créée est donc l'heure. Il convient d'utiliser DateInterval pour les calculs calendaires sur des objets DateTimeImmutable, et Time\Duration pour des quantités de temps non ambiguës, par exemple le paramètre timeout de l'API d'interrogation des E/S.

Les objets de cette classe sont immuables. Ils sont créés avec l'une des méthodes de fabrique Time\Duration::from*(), et chaque opération, comme Time\Duration::add() ou Time\Duration::multiplyBy(), retourne un nouvel objet au lieu de modifier l'objet existant. Une durée peut être négative, ce qui est généralement le résultat de Time\Duration::sub() ou de Time\Duration::negate(). Une durée nulle n'est jamais négative.

Deux durées peuvent être comparées avec les opérateurs de comparaison (<, <=, ==, !=, >=, > et <=>) ainsi qu'avec Time\Duration::compare(). Les opérateurs arithmétiques ne sont pas supportés ; il faut utiliser les méthodes de cette classe à la place.

La durée maximale est de 9223372035 secondes, soit environ 292 ans, sur les plateformes 64 bits, et de 2147483647 secondes, soit environ 68 ans, sur les plateformes 32 bits. Toute opération dont le résultat dépasserait cette plage lève une Time\TimeException.

Synopsis de la classe

Propriétés

seconds

Le nombre de secondes entières, sans le signe. Cette valeur est toujours supérieure ou égale à 0, et au plus égale à 9223372035 sur les plateformes 64 bits ou à 2147483647 sur les plateformes 32 bits.

nanoseconds

La fraction de seconde en nanosecondes, sans le signe. Cette valeur est toujours comprise entre 0 et 999999999, inclus.

negative

Indique si la durée est négative. Le signe s'applique à la durée dans son ensemble : une durée négative d'une seconde et demie a donc seconds défini à 1, nanoseconds défini à 500000000, et negative défini à true. Une durée nulle a toujours cette propriété définie à false.

Exemples

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

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

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

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

Voir aussi

• DateInterval
• hrtime()