Методы LocalTime

LocalTime — класс библиотеки js-joda, предназначенный для хранения времени без даты и часового пояса. Объект содержит:

часы;
минуты;
секунды;
наносекунды.

LocalTime идеально подходит для описания:

времени начала рабочего дня;
расписаний;
времени отправки уведомлений;
времени открытия магазинов;
повторяющихся ежедневных событий.

const { LocalTime } = require('@js-joda/core');

const time = LocalTime.of(14, 30);

console.log(time.toString()); 
// 14:30

Создание времени

Метод `of()`

Основной способ создания объекта времени.

Часы и минуты

const time = LocalTime.of(9, 15);

console.log(time.toString());
// 09:15

Часы, минуты и секунды

const time = LocalTime.of(9, 15, 45);

console.log(time.toString());
// 09:15:45

Полная версия с наносекундами

const time = LocalTime.of(9, 15, 45, 123456789);

console.log(time.toString());
// 09:15:45.123456789

Метод `now()`

Возвращает текущее локальное время.

const current = LocalTime.now();

console.log(current.toString());

Метод `parse()`

Преобразует строку в объект LocalTime.

const time = LocalTime.parse('18:45');

console.log(time.hour());
// 18

Секунды также поддерживаются:

const time = LocalTime.parse('18:45:30');

Получение компонентов времени

Метод `hour()`

Возвращает часы.

const time = LocalTime.of(16, 20);

console.log(time.hour());
// 16

Метод `minute()`

Возвращает минуты.

console.log(time.minute());
// 20

Метод `second()`

Возвращает секунды.

const time = LocalTime.of(16, 20, 45);

console.log(time.second());
// 45

Метод `nano()`

Возвращает наносекунды.

const time = LocalTime.of(16, 20, 45, 987654321);

console.log(time.nano());
// 987654321

Изменение времени

Объекты LocalTime неизменяемы. Каждый метод возвращает новый объект.

Метод `withHour()`

Изменяет часы.

const time = LocalTime.of(10, 30);

const updated = time.withHour(18);

console.log(updated.toString());
// 18:30

Метод `withMinute()`

Изменяет минуты.

const updated = time.withMinute(45);

console.log(updated.toString());
// 10:45

Метод `withSecond()`

Изменяет секунды.

const updated = time.withSecond(59);

console.log(updated.toString());
// 10:30:59

Метод `withNano()`

Изменяет наносекунды.

const updated = time.withNano(500000000);

console.log(updated.toString());
// 10:30:00.500

Добавление времени

Метод `plusHours()`

Добавляет часы.

const time = LocalTime.of(22, 15);

const result = time.plusHours(3);

console.log(result.toString());
// 01:15

Метод автоматически переходит через полночь.

Метод `plusMinutes()`

Добавляет минуты.

const time = LocalTime.of(10, 50);

const result = time.plusMinutes(20);

console.log(result.toString());
// 11:10

Метод `plusSeconds()`

Добавляет секунды.

const time = LocalTime.of(23, 59, 50);

const result = time.plusSeconds(15);

console.log(result.toString());
// 00:00:05

Метод `plusNanos()`

Добавляет наносекунды.

const time = LocalTime.of(12, 0, 0, 0);

const result = time.plusNanos(1000);

console.log(result.nano());
// 1000

Вычитание времени

Метод `minusHours()`

const time = LocalTime.of(2, 0);

const result = time.minusHours(5);

console.log(result.toString());
// 21:00

Метод `minusMinutes()`

const time = LocalTime.of(0, 10);

const result = time.minusMinutes(30);

console.log(result.toString());
// 23:40

Метод `minusSeconds()`

const time = LocalTime.of(0, 0, 10);

const result = time.minusSeconds(15);

console.log(result.toString());
// 23:59:55

Метод `minusNanos()`

const time = LocalTime.of(12, 0, 0, 1000);

const result = time.minusNanos(500);

console.log(result.nano());
// 500

Сравнение времени

Метод `equals()`

Проверяет равенство времени.

const t1 = LocalTime.of(10, 30);
const t2 = LocalTime.of(10, 30);

console.log(t1.equals(t2));
// true

Метод `isBefore()`

Проверяет, находится ли время раньше другого.

const start = LocalTime.of(8, 0);
const end = LocalTime.of(18, 0);

console.log(start.isBefore(end));
// true

Метод `isAfter()`

Проверяет, находится ли время позже другого.

console.log(end.isAfter(start));
// true

Работа с наносекундами

LocalTime хранит время с точностью до наносекунд.

Пример высокой точности

const time = LocalTime.of(
    12,
    30,
    15,
    123456789
);

console.log(time.toString());
// 12:30:15.123456789

Форматирование времени

Метод `toString()`

Стандартное строковое представление.

const time = LocalTime.of(9, 5);

console.log(time.toString());
// 09:05

Работа с `DateTimeFormatter`

Для гибкого форматирования используется DateTimeFormatter.

const {
    LocalTime,
    DateTimeFormatter
} = require('@js-joda/core');

const time = LocalTime.of(14, 30, 15);

const formatter =
    DateTimeFormatter.ofPattern('HH:mm:ss');

console.log(time.format(formatter));
// 14:30:15

Основные шаблоны форматирования

Шаблон	Описание	Пример
`HH`	Часы	09
`mm`	Минуты	05
`ss`	Секунды	45
`SSS`	Миллисекунды	123

Формат без секунд

const formatter =
    DateTimeFormatter.ofPattern('HH:mm');

console.log(time.format(formatter));
// 14:30

Формат 12-часового времени

const formatter =
    DateTimeFormatter.ofPattern('hh:mm a');

console.log(time.format(formatter));
// 02:30 PM

Преобразование в количество секунд

Метод `toSecondOfDay()`

Возвращает количество секунд с начала суток.

const time = LocalTime.of(1, 1, 1);

console.log(time.toSecondOfDay());
// 3661

Расчёт:

1 час = 3600
1 минута = 60
1 секунда = 1

Итого: 3661

Преобразование в наносекунды

Метод `toNanoOfDay()`

Возвращает количество наносекунд с начала суток.

const time = LocalTime.of(0, 0, 1);

console.log(time.toNanoOfDay());
// 1000000000

Создание времени из секунд

Метод `ofSecondOfDay()`

const time =
    LocalTime.ofSecondOfDay(3600);

console.log(time.toString());
// 01:00

Создание времени из наносекунд

Метод `ofNanoOfDay()`

const time =
    LocalTime.ofNanoOfDay(1_000_000_000);

console.log(time.toString());
// 00:00:01

Поддержка объекта `Temporal`

При использовании современных сред выполнения возможно взаимодействие с API Temporal.

const temporalTime = Temporal.PlainTime.from(
    '12:30:45'
);

LocalTime и Temporal.PlainTime решают схожие задачи, однако относятся к разным библиотекам и стандартам.

Практические примеры

Проверка рабочего времени

const start = LocalTime.of(9, 0);
const end = LocalTime.of(18, 0);

const current = LocalTime.now();

const isWorkingTime =
    !current.isBefore(start) &&
    !current.isAfter(end);

console.log(isWorkingTime);

Расчёт длительности между временем

const {
    LocalTime,
    ChronoUnit
} = require('@js-joda/core');

const start = LocalTime.of(10, 0);
const end = LocalTime.of(12, 45);

const minutes =
    start.until(end, ChronoUnit.MINUTES);

console.log(minutes);
// 165

Генерация расписания

let lesson = LocalTime.of(8, 30);

for (let i = 0; i < 5; i++) {
    console.log(lesson.toString());

    lesson = lesson.plusMinutes(45);
}

Особенности `LocalTime`

Отсутствие даты

LocalTime хранит только время.

const time = LocalTime.of(15, 30);

Информация о:

годе;
месяце;
дне;
часовом поясе

отсутствует.

Неизменяемость

Все операции возвращают новый объект.

const original = LocalTime.of(10, 0);

const updated =
    original.plusHours(2);

console.log(original.toString());
// 10:00

console.log(updated.toString());
// 12:00

Автоматическая нормализация

Переполнение времени обрабатывается автоматически.

const time = LocalTime.of(23, 50);

const result =
    time.plusMinutes(20);

console.log(result.toString());
// 00:10

Распространённые ошибки

Использование несуществующих значений

LocalTime.of(25, 0);

Ошибка:

DateTimeException:
Invalid value for HourOfDay

Неверный формат строки

LocalTime.parse('99:99');

Ошибка разбора:

DateTimeParseException

Производительность

LocalTime:

быстрее и безопаснее стандартного Date для операций со временем;
не зависит от часовых поясов;
исключает множество ошибок, связанных с локализацией;
предоставляет точную арифметику времени.

Сравнение `LocalTime` и `Date`

Возможность	LocalTime	Date
Только время	Да	Нет
Поддержка часовых поясов	Нет	Да
Неизменяемость	Да	Нет
Наносекунды	Да	Нет
Безопасная арифметика	Да	Частично

Основные методы `LocalTime`

Метод	Назначение
`of()`	Создание времени
`now()`	Текущее время
`parse()`	Разбор строки
`hour()`	Получение часов
`minute()`	Получение минут
`second()`	Получение секунд
`nano()`	Получение наносекунд
`withHour()`	Изменение часов
`withMinute()`	Изменение минут
`plusHours()`	Добавление часов
`minusHours()`	Вычитание часов
`isBefore()`	Проверка порядка
`isAfter()`	Проверка порядка
`equals()`	Проверка равенства
`format()`	Форматирование
`toSecondOfDay()`	Секунды с начала суток
`toNanoOfDay()`	Наносекунды с начала суток

Методы LocalTime

Создание времени

Метод of()

Часы и минуты

Часы, минуты и секунды

Полная версия с наносекундами

Метод now()

Метод parse()

Получение компонентов времени

Метод hour()

Метод minute()

Метод second()

Метод nano()

Изменение времени

Метод withHour()

Метод withMinute()

Метод withSecond()

Метод withNano()