Time\Duration クラス

はじめに

タイムアウトや、ストップウォッチで計った時間のような、 長さが一定の経過時間をナノ秒の精度で表します。 期間は、負でない整数の秒数 (Time\Duration::$seconds)、1 秒未満のナノ秒数 (Time\Duration::$nanoseconds)、符号 (Time\Duration::$negative) で構成されます。

日、月、年などの暦の単位は一定の秒数に対応しないため、 Time\Duration は DateInterval とは異なり、これらの単位を持ちません。 DST (夏時間) の移行をまたぐと 1 日は 23 時間や 25 時間になることがあり、 月の長さもまちまちです。 そのため、期間の作成に使える最大の単位は時間です。 DateTimeImmutable オブジェクトで暦に基づいて計算するには DateInterval を、 I/O ポーリング API の timeout のように曖昧さのない時間の長さを扱うには Time\Duration を使ってください。

このクラスのオブジェクトは不変です。 作成には Time\Duration::from*() ファクトリメソッドのいずれかを使います。 Time\Duration::add や Time\Duration::multiplyBy などの操作はどれも、 既存のオブジェクトを変更せず、新しいオブジェクトを返します。 期間は負にもなりえます。 多くの場合、 Time\Duration::sub や Time\Duration::negate の結果として負になります。 長さ 0 の期間が負になることはありません。

2 つの期間は、 比較演算子 (<、<=、 ==、!=、>=、 >、<=>) でも Time\Duration::compare でも比較できます。 算術演算子 はサポートされていません。 代わりにこのクラスのメソッドを使ってください。

期間の最大長は、64 ビットプラットフォームでは 9223372035 秒 (約 292 年)、 32 ビットプラットフォームでは 2147483647 秒 (約 68 年) です。 結果がこの範囲を超える操作はどれも Time\TimeException をスローします。

クラス概要

Time
final readonly Duration
/* プロパティ */
public readonly int $seconds;
public readonly int $nanoseconds;
public readonly bool $negative;
/* メソッド */
private Time\Duration::__construct()
public Time\Duration Time\Duration::absolute()
public Time\Duration Time\Duration::add(Time\Duration $duration)
public static int Time\Duration::compare(Time\Duration $a, Time\Duration $b)
public Time\Duration Time\Duration::divideBy(int $divisor)
public static Time\Duration Time\Duration::fromHours(int $hours)
public static Time\Duration Time\Duration::fromIso8601DurationString(string $specification)
public static Time\Duration Time\Duration::fromMicroseconds(int $microseconds)
public static Time\Duration Time\Duration::fromMilliseconds(int $milliseconds)
public static Time\Duration Time\Duration::fromMinutes(int $minutes)
public static Time\Duration Time\Duration::fromNanoseconds(int $nanoseconds)
public static Time\Duration Time\Duration::fromSeconds(int $seconds, int $nanoseconds = 0)
public Time\Duration Time\Duration::multiplyBy(int $factor)
public Time\Duration Time\Duration::negate()
public Time\Duration Time\Duration::sub(Time\Duration $duration)
public void Time\Duration::__unserialize(array $data)

プロパティ

seconds
符号を除いた整数の秒数。 常に 0 以上で、最大値は 64 ビットプラットフォームでは 9223372035、32 ビットプラットフォームでは 2147483647 です。
nanoseconds
符号を除いた 1 秒未満の端数 (ナノ秒単位)。 常に 0 以上 999999999 以下です。
negative
期間が負かどうか。 符号は期間全体に適用されるため、-1.5 秒の期間では、 seconds が 1、 nanoseconds が 500000000、 negative が true になります。 長さ 0 の期間では、このプロパティは常に false です。

例

例1 期間の作成と足し合わせ

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

例2 期間の比較

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

参考

  • DateInterval
  • hrtime
目次