Класс Duration

java.lang.Object
- java.time.Duration

Все реализованные интерфейсы:: Serializable, Comparable<Duration>, TemporalAmount

public final class Duration
extends Object
implements TemporalAmount, Comparable<Duration>, Serializable

Время, представленное количеством, например, '34.5 секунды'.

Этот класс моделирует количество или величину времени в секундах и наносекундах. К нему можно получить доступ, используя другие единицы измерения времени, такие как минуты и часы. Кроме того, можно использовать единицу DAYS, которая рассматривается как точно равной 24 часам, игнорируя при этом переходы на летнее/зимнее время. Смотрите Period для эквивалента этого класса, основанного на датах.

Физическое время может быть бесконечным. Для практических целей время хранится с ограничениями, подобными Instant. Время использует разрешение в наносекундах с максимальным значением секунд, которое может хранить long. Это значение больше, чем текущий оценочный возраст Вселенной.

Диапазон времени требует хранения числа, большего, чем long. Для этого класс хранит long для секунд и int для наносекунд в секунде, которое всегда будет находиться в пределах от 0 до 999 999 999. Модель представляет направленное время, то есть время может быть отрицательным.

Время измеряется в секундах, но эти секунды не обязательно идентичны научному определению «секунды СИ», основанному на атомных часах. Это различие влияет только на время, измеренное близко к появлению дополнительной секунды, и не должно влиять на большинство приложений. Смотрите Instant для обсуждения значения секунды и временных масштабов.

Это значение-ориентированный класс; использование операций, чувствительных к идентификатору (включая равенство ссылок (==), идентификационный код хэша или синхронизацию) для экземпляров Duration может привести к непредсказуемым результатам и следует избегать. Для сравнения следует использовать метод equals.

Требования к реализации:: Этот класс неизменяем и потокобезопасен.
С:: 1.8
См. также:: Сериализованная форма

Поля

Модификатор и тип	Поле и описание
`static Duration`	`ZERO` Константа для значения нулевого времени.

Методы

Модификатор и тип	Метод и описание
`Duration`	`abs()` Возвращает копию этого времени с положительной длительностью.
`Temporal`	`addTo(Temporal temporal)` Добавляет это время к указанному объекту времени.
`static Duration`	`between(Temporal startInclusive, Temporal endExclusive)` Получает `Duration`, представляющее время между двумя объектами времени.
`int`	`compareTo(Duration otherDuration)` Сравнивает это время с указанным `Duration`.
`Duration`	`dividedBy(long divisor)` Возвращает копию этого времени, разделенную на указанное значение.
`boolean`	`equals(Object otherDuration)` Проверяет, равно ли это время указанному `Duration`.
`static Duration`	`from(TemporalAmount amount)` Получает экземпляр `Duration` из временного количества.
`long`	`get(TemporalUnit unit)` Получает значение запрошенной единицы.
`int`	`getNano()` Получает количество наносекунд в секунде в этом времени.
`long`	`getSeconds()` Получает количество секунд в этом времени.
`List<TemporalUnit>`	`getUnits()` Получает набор единиц, поддерживаемых этим временем.
`int`	`hashCode()` Хэш-код для этого времени.
`boolean`	`isNegative()` Проверяет, отрицательно ли это время, за исключением нуля.
`boolean`	`isZero()` Проверяет, имеет ли это время нулевую длительность.
`Duration`	`minus(Duration duration)` Возвращает копию этого времени с вычетом указанного времени.
`Duration`	`minus(long amountToSubtract, TemporalUnit unit)` Возвращает копию этого времени с вычетом указанного времени.
`Duration`	`minusDays(long daysToSubtract)` Возвращает копию этого времени с вычетом указанного времени в стандартных 24-часовых днях.
`Duration`	`minusHours(long hoursToSubtract)` Возвращает копию этого времени с вычетом указанного времени в часах.
`Duration`	`minusMillis(long millisToSubtract)` Возвращает копию этого времени с вычетом указанного времени в миллисекундах.
`Duration`	`minusMinutes(long minutesToSubtract)` Возвращает копию этого времени с вычетом указанного времени в минутах.
`Duration`	`minusNanos(long nanosToSubtract)` Возвращает копию этого времени с вычетом указанного времени в наносекундах.
`Duration`	`minusSeconds(long secondsToSubtract)` Возвращает копию этого времени с вычетом указанного времени в секундах.
`Duration`	`multipliedBy(long multiplicand)` Возвращает копию этого времени, умноженную на скаляр.
`Duration`	`negated()` Возвращает копию этого времени с обратным знаком длительности.
`static Duration`	`of(long amount, TemporalUnit unit)` Получает `Duration`, представляющее количество в указанной единице.
`static Duration`	`ofDays(long days)` Получает `Duration`, представляющее количество стандартных 24-часовых дней.
`static Duration`	`ofHours(long hours)` Получает `Duration`, представляющее количество стандартных часов.
`static Duration`	`ofMillis(long millis)` Получает `Duration`, представляющее количество миллисекунд.
`static Duration`	`ofMinutes(long minutes)` Получает `Duration`, представляющее количество стандартных минут.
`static Duration`	`ofNanos(long nanos)` Получает `Duration`, представляющее количество наносекунд.
`static Duration`	`ofSeconds(long seconds)` Получает `Duration`, представляющее количество секунд.
`static Duration`	`ofSeconds(long seconds, long nanoAdjustment)` Получает `Duration`, представляющее количество секунд и корректировку в наносекундах.
`static Duration`	`parse(CharSequence text)` Получает `Duration` из текстовой строки, например `PnDTnHnMn.nS`.
`Duration`	`plus(Duration duration)` Возвращает копию этого времени, к которому добавлено указанное время.
`Duration`	`plus(long amountToAdd, TemporalUnit unit)` Возвращает копию этого времени, к которому добавлено указанное время.
`Duration`	`plusDays(long daysToAdd)` Возвращает копию этого времени, к которому добавлено указанное время в стандартных 24-часовых днях.
`Duration`	`plusHours(long hoursToAdd)` Возвращает копию этого времени, к которому добавлено указанное время в часах.
`Duration`	`plusMillis(long millisToAdd)` Возвращает копию этого времени, к которому добавлено указанное время в миллисекундах.
`Duration`	`plusMinutes(long minutesToAdd)` Возвращает копию этого времени, к которому добавлено указанное время в минутах.
`Duration`	`plusNanos(long nanosToAdd)` Возвращает копию этого времени, к которому добавлено указанное время в наносекундах.
`Duration`	`plusSeconds(long secondsToAdd)` Возвращает копию этого времени, к которому добавлено указанное время в секундах.
`Temporal`	`subtractFrom(Temporal temporal)` Вычитает это время из указанного объекта времени.
`long`	`toDays()` Получает количество дней в этом времени.
`long`	`toHours()` Получает количество часов в этом времени.
`long`	`toMillis()` Преобразует это время в общую длительность в миллисекундах.
`long`	`toMinutes()` Получает количество минут в этом времени.
`long`	`toNanos()` Преобразует это время в полную длительность в наносекундах, представленную как `long`.
`String`	`toString()` Строковое представление этого времени с использованием ISO-8601, например `PT8H6M12.345S`.
`Duration`	`withNanos(int nanoOfSecond)` Возвращает копию этого времени с указанным значением наносекунд.
`Duration`	`withSeconds(long seconds)` Возвращает копию этого времени с указанным количеством секунд.

Методы, унаследованные от класса java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Поля

ZERO

public static final Duration ZERO

Константа для продолжительности ноль.

Методы

ofDays

public static Duration ofDays(long days)

Получает Duration , представляющий количество стандартных 24-часовых дней.

Секунды рассчитываются на основе стандартного определения дня, где каждый день составляет 86400 секунд, что подразумевает 24-часовой день. Наносекунды в поле секунд установлены в ноль.

Параметры:: days - количество дней, положительное или отрицательное
Возвращает:: a Duration, не null
Выбрасывает:: ArithmeticException - если входные дни превышают емкость Duration

ofHours

public static Duration ofHours(long hours)

Получает Duration , представляющий количество стандартных часов.

Секунды рассчитываются на основе стандартного определения часа, где каждый час составляет 3600 секунд. Наносекунды в поле секунд установлены в ноль.

Параметры:: hours - количество часов, положительное или отрицательное
Возвращает:: a Duration, не null
Выбрасывает:: ArithmeticException - если входные часы превышают емкость Duration

ofMinutes

public static Duration ofMinutes(long minutes)

Получает Duration , представляющий количество стандартных минут.

Секунды рассчитываются на основе стандартного определения минуты, где каждая минута составляет 60 секунд. Наносекунды в поле секунд установлены в ноль.

Параметры:: minutes - количество минут, положительное или отрицательное
Возвращает:: a Duration, не null
Выбрасывает:: ArithmeticException - если входные минуты превышают емкость Duration

ofSeconds

public static Duration ofSeconds(long seconds)

Получает Duration , представляющий количество секунд.

Наносекунды в поле секунд установлены в ноль.

Параметры:: seconds - количество секунд, положительное или отрицательное
Возвращает:: a Duration, не null

ofSeconds

public static Duration ofSeconds(long seconds,
                                 long nanoAdjustment)

Получает Duration , представляющий количество секунд и корректировку в наносекундах.

Этот метод позволяет передать произвольное количество наносекунд. Фабрика будет изменять значения секунд и наносекунд, чтобы гарантировать, что хранящиеся наносекунды находятся в диапазоне от 0 до 999 999 999. Например, следующее приведет к точно такому же интервалу:

Duration.ofSeconds(3, 1);
  Duration.ofSeconds(4, -999_999_999);
  Duration.ofSeconds(2, 1000_000_001);

Параметры:: seconds - количество секунд, положительное или отрицательное; nanoAdjustment - корректировка наносекунд к количеству секунд, положительная или отрицательная
Возвращает:: a Duration, не null
Выбрасывает:: ArithmeticException - если корректировка приводит к превышению емкости Duration

ofMillis

public static Duration ofMillis(long millis)

Получает Duration , представляющий количество миллисекунд.

Секунды и наносекунды извлекаются из указанных миллисекунд.

Параметры:: millis - количество миллисекунд, положительное или отрицательное
Возвращает:: a Duration, не null

ofNanos

public static Duration ofNanos(long nanos)

Получает Duration , представляющий количество наносекунд.

Секунды и наносекунды извлекаются из указанных наносекунд.

Параметры:: nanos - количество наносекунд, положительное или отрицательное
Возвращает:: a Duration, не null

of

public static Duration of(long amount,
                          TemporalUnit unit)

Получает Duration , представляющий количество в указанном блоке.

Параметры представляют две части фразы, такой как «6 часов». Например:

Duration.of(3, SECONDS);
  Duration.of(465, HOURS);

Только подмножество блоков принимается этим методом. Блок должен иметь либо точную продолжительность, либо быть ChronoUnit.DAYS, что обрабатывается как 24 часа. Другие блоки вызывают исключение.

Параметры:: amount - количество продолжительности, измеренное в терминах блока, положительное или отрицательное; unit - блок, в котором измеряется продолжительность, должен иметь точную продолжительность, не null
Возвращает:: a Duration, не null
Выбрасывает:: DateTimeException - если блок периода имеет приблизительную продолжительность; ArithmeticException - если происходит переполнение числовых данных

from

public static Duration from(TemporalAmount amount)

Получает экземпляр Duration из временного количества.

Это получает продолжительность на основе указанного количества. TemporalAmount представляет собой количество времени, которое может быть основано на дате или времени, которое эта фабрика извлекает в продолжительность.

Преобразование проходит по набору блоков из количества и использует продолжительность блока для расчета общего Duration. Только подмножество блоков принимается этим методом. Блок должен иметь либо точную продолжительность, либо быть ChronoUnit.DAYS, что обрабатывается как 24 часа. Если обнаруживаются какие-либо другие блоки, выбрасывается исключение.

Параметры:: amount - временное количество для преобразования, не null
Возвращает:: эквивалентная продолжительность, не null
Выбрасывает:: DateTimeException - если невозможно преобразовать в Duration; ArithmeticException - если происходит переполнение числовых данных

parse

public static Duration parse(CharSequence text)

Получает Duration из текстовой строки, такой как PnDTnHnMn.nS.

Это анализирует текстовое представление продолжительности, включая строку, созданную toString(). Принимаемые форматы основаны на формате продолжительности ISO-8601 PnDTnHnMn.nS с днями, рассматриваемыми как ровно 24 часа.

Строка начинается с необязательного знака, обозначаемого символом ASCII минус или плюс. Если отрицательный, весь период отрицается. Следующая буква ASCII «P» в верхнем или нижнем регистре. Затем идут четыре раздела, каждый из которых состоит из числа и суффикса. Разделы имеют суффиксы ASCII «D», «H», «M» и «S» для дней, часов, минут и секунд, принятые в верхнем или нижнем регистре. Суффиксы должны появляться в порядке. Буква ASCII «T» должна появляться перед первым появлением, если таковое есть, раздела часов, минут или секунд. Должен быть присутствовать по крайней мере один из четырех разделов, а если «T» есть, то должен быть по крайней мере один раздел после «T». Часть числа в каждом разделе должна состоять из одной или нескольких цифр ASCII. Число может быть снабжено префиксом ASCII минус или плюс. Количество дней, часов и минут должны быть проанализированы как long. Количество секунд должно быть проанализировано как long с необязательной дробью. Десятичная точка может быть либо точкой, либо запятой. Дробная часть может иметь от нуля до 9 цифр.

Лидирующий знак плюс/минус и отрицательные значения для других единиц не являются частью стандарта ISO-8601.

Примеры:

"PT20.345S" -- parses as "20.345 seconds"
    "PT15M"     -- parses as "15 minutes" (where a minute is 60 seconds)
    "PT10H"     -- parses as "10 hours" (where an hour is 3600 seconds)
    "P2D"       -- parses as "2 days" (where a day is 24 hours or 86400 seconds)
    "P2DT3H4M"  -- parses as "2 days, 3 hours and 4 minutes"
    "P-6H3M"    -- parses as "-6 hours and +3 minutes"
    "-P6H3M"    -- parses as "-6 hours and -3 minutes"
    "-P-6H+3M"  -- parses as "+6 hours and -3 minutes"

Параметры:: text - текст для анализа, не null
Возвращает:: проанализированная продолжительность, не null
Выбрасывает:: DateTimeParseException - если текст не может быть проанализирован как продолжительность

between

public static Duration between(Temporal startInclusive,
                               Temporal endExclusive)

Получает Duration , представляющий продолжительность между двумя временными объектами.

Это вычисляет продолжительность между двумя временными объектами. Если объекты имеют разные типы, продолжительность рассчитывается на основе типа первого объекта. Например, если первый аргумент является LocalTime , то второй аргумент преобразуется в LocalTime.

Указанные временные объекты должны поддерживать блок SECONDS. Для обеспечения точности необходимо, чтобы поддерживался блок NANOS или поле NANO_OF_SECOND.

Результат этого метода может быть отрицательным периодом, если конец предшествует началу. Для гарантии получения положительной продолжительности вызовите abs() на результате.

Параметры:: startInclusive - начальный момент, включительно, не null; endExclusive - конечный момент, исключая, не null
Возвращает:: a Duration, не null
Выбрасывает:: DateTimeException - если секунды между временными объектами получить нельзя; ArithmeticException - если вычисление превышает емкость Duration

get

public long get(TemporalUnit unit)

Получает значение запрошенного блока.

Это возвращает значение для каждого из двух поддерживаемых блоков, SECONDS и NANOS. Все остальные блоки вызывают исключение.

Указано в:: get в интерфейсе TemporalAmount
Параметры:: unit - TemporalUnit для возвращения значения
Возвращает:: значение типа long для блока
Выбрасывает:: DateTimeException - если блок не поддерживается; UnsupportedTemporalTypeException - если блок не поддерживается

getUnits

public List<TemporalUnit> getUnits()

Получает набор блоков, поддерживаемых этой продолжительностью.

Поддерживаемые блоки — SECONDS и NANOS. Они возвращаются в порядке секунды, наносекунды.

Этот набор можно использовать в сочетании с get(TemporalUnit) для доступа к всему состоянию продолжительности.

Указано в:: getUnits в интерфейсе TemporalAmount
Возвращает:: список, содержащий блоки секунд и наносекунд, не null

isZero

public boolean isZero()

Проверяет, имеет ли эта продолжительность нулевую длину.

A Duration представляет собой направленное расстояние между двумя точками на временной шкале и, следовательно, может быть положительным, нулевым или отрицательным. Этот метод проверяет, равна ли длина нулю.

Returns:: true, если эта продолжительность имеет общую длину, равную нулю

isNegative

public boolean isNegative()

Проверяет, является ли эта продолжительность отрицательной, исключая ноль.

Returns:: true, если эта продолжительность имеет общую длину меньше нуля

getSeconds

public long getSeconds()

Возвращает количество секунд в этой продолжительности.

Длина продолжительности хранится с помощью двух полей — секунд и наносекунд. Часть наносекунд — это значение от 0 до 999 999 999, которое является корректировкой длины в секундах. Общая продолжительность определяется вызовом этого метода и getNano().

A Duration представляет собой направленное расстояние между двумя точками на временной шкале. Отрицательная продолжительность выражается отрицательным знаком части секунд. Продолжительность в -1 наносекунду хранится как -1 секунда плюс 999 999 999 наносекунд.

Returns:: целая часть секунд длины продолжительности, положительная или отрицательная

getNano

public int getNano()

Возвращает количество наносекунд в секунде в этой продолжительности.

Returns:: наносекунды в части секунды длины продолжительности, от 0 до 999 999 999

withSeconds

public Duration withSeconds(long seconds)

Возвращает копию этой продолжительности с указанным количеством секунд.

Это возвращает продолжительность с указанными секундами, сохраняя часть наносекунд этой продолжительности.