TimeSpan
in package
implements
Stringable
Длительность с наносекундной точностью — иммутабельный value object.
Хранит целые наносекунды (64-битный int: диапазон ±292 года), поэтому арифметика над целыми фабриками точна до наносекунды. Знак допустим: отрицательная длительность — направление в прошлое. Все операции возвращают новый экземпляр, исходный не меняется.
Table of Contents
Interfaces
- Stringable
Methods
- __toString() : string
- Человекочитаемая строка: `1h 30m 15.5s`; ноль — `0s`.
- abs() : self
- Модуль длительности.
- between() : self
- Длительность между двумя моментами: положительная, когда `$end` позже.
- compareTo() : int
- Сравнение длительностей: −1, 0 или 1.
- days() : float
- Длительность в сутках (сутки — ровно 24 часа).
- dividedBy() : self
- Длительность, делённая на делитель.
- equals() : bool
- Равенство длительностей с точностью до наносекунды.
- forHumans() : non-empty-string
- Локализованная длительность: «1 час 30 минут», «2 Stunden 5 Minuten».
- fromDateInterval() : self
- Длительность из {@see DateInterval}.
- fromDateString() : self
- Длительность из относительной строки формата PHP: `2 weeks 3 days`, `1 hour 30 minutes`.
- fromIso8601() : self
- Длительность из ISO 8601 (`P2DT3H4M5.5S`, `PT90S`, `P1W`, знак впереди).
- fromString() : self
- Длительность из человекочитаемой строки: `1h 30m`, `2d 4h`, `-1.5s 250ms`.
- hours() : float
- Длительность в часах.
- isNegative() : bool
- Отрицательная ли длительность.
- isPositive() : bool
- Положительная ли длительность.
- isZero() : bool
- Нулевая ли длительность.
- microseconds() : float
- Длительность в микросекундах.
- milliseconds() : float
- Длительность в миллисекундах.
- minus() : self
- Разность длительностей.
- minutes() : float
- Длительность в минутах.
- multipliedBy() : self
- Длительность, умноженная на множитель.
- nanoseconds() : int
- Длительность в целых наносекундах.
- negated() : self
- Длительность с противоположным знаком.
- ofDays() : self
- Длительность из суток (сутки — ровно 24 часа).
- ofHours() : self
- Длительность из часов.
- ofMicroseconds() : self
- Длительность из микросекунд.
- ofMilliseconds() : self
- Длительность из миллисекунд.
- ofMinutes() : self
- Длительность из минут.
- ofNanoseconds() : self
- Длительность из целых наносекунд.
- ofSeconds() : self
- Длительность из секунд.
- ofWeeks() : self
- Длительность из недель (неделя — ровно 7 суток по 24 часа).
- plus() : self
- Сумма длительностей.
- seconds() : float
- Длительность в секундах.
- toDateInterval() : DateInterval
- Интервал {@see DateInterval} с точностью до микросекунд.
- toIso8601() : non-empty-string
- Строка ISO 8601: `PT1H30M15.5S`; отрицательная — с ведущим минусом.
- zero() : self
- Нулевая длительность.
Methods
__toString()
Человекочитаемая строка: `1h 30m 15.5s`; ноль — `0s`.
public
__toString() : string
Attributes
- #[Override]
Return values
string —Человекочитаемая строка длительности
abs()
Модуль длительности.
public
abs() : self
Tags
Return values
self —Модуль длительности
between()
Длительность между двумя моментами: положительная, когда `$end` позже.
public
static between(DateTimeImmutable $start, DateTimeImmutable $end) : self
Точность ограничена микросекундами DateTimeImmutable.
Parameters
- $start : DateTimeImmutable
-
начальный момент
- $end : DateTimeImmutable
-
конечный момент
Return values
self —Длительность между двумя моментами
compareTo()
Сравнение длительностей: −1, 0 или 1.
public
compareTo(self $other) : int
Parameters
- $other : self
-
сравниваемая длительность
Return values
int —−1 когда текущая короче, 0 при равенстве, 1 когда длиннее
days()
Длительность в сутках (сутки — ровно 24 часа).
public
days() : float
Return values
float —Длительность в сутках
dividedBy()
Длительность, делённая на делитель.
public
dividedBy(int|float $divisor) : self
Результат округляется до ближайшей наносекунды; точность деления ограничена представлением double.
Parameters
- $divisor : int|float
-
ненулевой делитель, знак допустим
Tags
Return values
self —Длительность, делённая на делитель
equals()
Равенство длительностей с точностью до наносекунды.
public
equals(self $other) : bool
Parameters
- $other : self
-
сравниваемая длительность
Return values
bool —Равенство длительностей с точностью до наносекунды
forHumans()
Локализованная длительность: «1 час 30 минут», «2 Stunden 5 Minuten».
public
forHumans([string $locale = 'en' ][, int $parts = PHP_INT_MAX ]) : non-empty-string
Недели, дни, часы, минуты и секунды (доли секунды отбрасываются); знак не выводится. Нулевые единицы пропускаются, ноль — «0 секунд».
Parameters
- $locale : string = 'en'
-
код языка: ru, en, de, fr, es, it
- $parts : int = PHP_INT_MAX
-
максимум выводимых единиц, не меньше одной; по умолчанию — все
Tags
Return values
non-empty-string —длительность словами
fromDateInterval()
Длительность из {@see DateInterval}.
public
static fromDateInterval(DateInterval $interval) : self
Интервалы с годами/месяцами принимаются только от diff() (у них
заполнено суммарное поле days); синтетический P1M неоднозначен —
абсолютная длительность месяца не определена.
Parameters
- $interval : DateInterval
-
исходный интервал
Tags
Return values
self —Длительность из интервала
fromDateString()
Длительность из относительной строки формата PHP: `2 weeks 3 days`, `1 hour 30 minutes`.
public
static fromDateString(non-empty-string $relative) : self
Строки с календарными годами/месяцами (1 month) отклоняются: их
абсолютная длительность не определена.
Parameters
- $relative : non-empty-string
-
относительная строка дат PHP
Tags
Return values
self —Длительность из относительной строки
fromIso8601()
Длительность из ISO 8601 (`P2DT3H4M5.5S`, `PT90S`, `P1W`, знак впереди).
public
static fromIso8601(non-empty-string $iso) : self
Годы и месяцы не принимаются: их абсолютная длительность не определена.
Parameters
- $iso : non-empty-string
-
строка длительности ISO 8601
Tags
Return values
self —Длительность из строки ISO 8601
fromString()
Длительность из человекочитаемой строки: `1h 30m`, `2d 4h`, `-1.5s 250ms`.
public
static fromString(non-empty-string $value) : self
Единицы: w d h m s ms us ns; каждый токен может нести свой знак,
токены суммируются. Строка без единственного валидного токена отклоняется.
Parameters
- $value : non-empty-string
-
строка длительности
Tags
Return values
self —Суммарная длительность всех токенов строки
hours()
Длительность в часах.
public
hours() : float
Return values
float —Длительность в часах
isNegative()
Отрицательная ли длительность.
public
isNegative() : bool
Return values
bool —Отрицательная ли длительность
isPositive()
Положительная ли длительность.
public
isPositive() : bool
Return values
bool —Положительная ли длительность
isZero()
Нулевая ли длительность.
public
isZero() : bool
Return values
bool —Нулевая ли длительность
microseconds()
Длительность в микросекундах.
public
microseconds() : float
Return values
float —Длительность в микросекундах
milliseconds()
Длительность в миллисекундах.
public
milliseconds() : float
Return values
float —Длительность в миллисекундах
minus()
Разность длительностей.
public
minus(self $other) : self
Parameters
- $other : self
-
вычитаемая длительность
Tags
Return values
self —Разность длительностей
minutes()
Длительность в минутах.
public
minutes() : float
Return values
float —Длительность в минутах
multipliedBy()
Длительность, умноженная на множитель.
public
multipliedBy(int|float $factor) : self
Дробный множитель округляет результат до ближайшей наносекунды.
Parameters
- $factor : int|float
-
множитель, знак допустим
Tags
Return values
self —Длительность, умноженная на множитель
nanoseconds()
Длительность в целых наносекундах.
public
nanoseconds() : int
Return values
int —Длительность в целых наносекундах
negated()
Длительность с противоположным знаком.
public
negated() : self
Tags
Return values
self —Длительность с противоположным знаком
ofDays()
Длительность из суток (сутки — ровно 24 часа).
public
static ofDays(int|float $days) : self
Parameters
- $days : int|float
-
сутки, знак допустим
Tags
Return values
self —Длительность из суток
ofHours()
Длительность из часов.
public
static ofHours(int|float $hours) : self
Parameters
- $hours : int|float
-
часы, знак допустим
Tags
Return values
self —Длительность из часов
ofMicroseconds()
Длительность из микросекунд.
public
static ofMicroseconds(int|float $microseconds) : self
Parameters
- $microseconds : int|float
-
микросекунды, знак допустим
Tags
Return values
self —Длительность из микросекунд
ofMilliseconds()
Длительность из миллисекунд.
public
static ofMilliseconds(int|float $milliseconds) : self
Parameters
- $milliseconds : int|float
-
миллисекунды, знак допустим
Tags
Return values
self —Длительность из миллисекунд
ofMinutes()
Длительность из минут.
public
static ofMinutes(int|float $minutes) : self
Parameters
- $minutes : int|float
-
минуты, знак допустим
Tags
Return values
self —Длительность из минут
ofNanoseconds()
Длительность из целых наносекунд.
public
static ofNanoseconds(int $nanoseconds) : self
Parameters
- $nanoseconds : int
-
наносекунды, знак допустим
Return values
self —Длительность из целых наносекунд
ofSeconds()
Длительность из секунд.
public
static ofSeconds(int|float $seconds) : self
Parameters
- $seconds : int|float
-
секунды, знак допустим
Tags
Return values
self —Длительность из секунд
ofWeeks()
Длительность из недель (неделя — ровно 7 суток по 24 часа).
public
static ofWeeks(int|float $weeks) : self
Parameters
- $weeks : int|float
-
недели, знак допустим
Tags
Return values
self —Длительность из недель
plus()
Сумма длительностей.
public
plus(self $other) : self
Parameters
- $other : self
-
слагаемая длительность
Tags
Return values
self —Сумма длительностей
seconds()
Длительность в секундах.
public
seconds() : float
Return values
float —Длительность в секундах
toDateInterval()
Интервал {@see DateInterval} с точностью до микросекунд.
public
toDateInterval() : DateInterval
Компоненты плоские (сутки/часы/минуты/секунды, без календарных
годов/месяцев), отрицательная длительность отражается флагом invert:
интервал безопасно переносим между любыми датами через add()/sub().
Tags
Return values
DateInterval —Интервал с точностью до микросекунд
toIso8601()
Строка ISO 8601: `PT1H30M15.5S`; отрицательная — с ведущим минусом.
public
toIso8601() : non-empty-string
Return values
non-empty-string —Строка ISO 8601
zero()
Нулевая длительность.
public
static zero() : self
Return values
self —Нулевая длительность