Создание LocalTime

Концепция LocalTime

LocalTime в js-joda представляет собой неизменяемую модель времени без даты и без часового пояса. Объект описывает только часы, минуты, секунды и наносекунды, что делает его эквивалентом локального времени в формате настенных часов.

Основные свойства:

  • отсутствие даты
  • отсутствие часового пояса
  • неизменяемость (immutable)
  • высокая точность вплоть до наносекунд

Такая модель используется в сценариях, где важно именно время суток, а не абсолютная временная точка.

Создание через текущий момент времени

LocalTime.now()

Фабричный метод now() формирует объект на основе системных часов окружения выполнения.

import { LocalTime } from 'js-joda';

const time = LocalTime.now();

При создании используются часы системы, при этом дата игнорируется, а извлекается только компонент времени.

Сигнатура:

LocalTime.now()
LocalTime.now(clock)

Использование собственного Clock позволяет контролировать источник времени, что критично для тестирования.

import { LocalTime, Clock, ZoneOffset } from 'js-joda';

const clock = Clock.fixed(Instant.now(), ZoneOffset.UTC);
const time = LocalTime.now(clock);

Явное создание через of

Базовая форма

Метод of является основным способом явного создания времени:

LocalTime.of(hour, minute)
LocalTime.of(hour, minute, second)
LocalTime.of(hour, minute, second, nanoOfSecond)

Пример:

import { LocalTime } from 'js-joda';

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

Ограничения значений

Каждый компонент строго проверяется:

  • час: 0–23
  • минута: 0–59
  • секунда: 0–59
  • наносекунда: 0–999999999

Любое отклонение приводит к ошибке времени выполнения.

LocalTime.of(25, 10); // ошибка
LocalTime.of(10, 70); // ошибка

Перегрузки и нормализация

LocalTime не выполняет автоматическую нормализацию значений. Передача “переполненных” значений не преобразуется, а приводит к исключению.

Создание из секунд и наносекунд дня

ofSecondOfDay

Метод формирует время из количества секунд от начала суток:

LocalTime.ofSecondOfDay(secondOfDay)

Пример:

import { LocalTime } from 'js-joda';

const t = LocalTime.ofSecondOfDay(3600); // 01:00

Диапазон:

  • 0 ≤ secondOfDay ≤ 86399

ofNanoOfDay

Более точная версия, использующая наносекунды:

LocalTime.ofNanoOfDay(nanoOfDay)

Пример:

const t = LocalTime.ofNanoOfDay(3600n * 1_000_000_000n);

Используется для высокоточных измерений времени.

Парсинг строкового представления

parse

Строковое создание поддерживает ISO-8601 формат времени:

LocalTime.parse(text)
LocalTime.parse(text, formatter)

ISO-формат

Поддерживаемые строки:

import { LocalTime } from 'js-joda';

const t1 = LocalTime.parse('10:15');
const t2 = LocalTime.parse('10:15:30');
const t3 = LocalTime.parse('10:15:30.123');

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

const t = LocalTime.parse('10:15:30.123456789');

Использование DateTimeFormatter

Гибкий разбор через пользовательские шаблоны:

import { LocalTime, DateTimeFormatter } from 'js-joda';

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

const t = LocalTime.parse('10 20 30', formatter);

Предопределённые значения

Константы времени

LocalTime содержит фиксированные значения:

LocalTime.MIDNIGHT
LocalTime.NOON
LocalTime.MIN
LocalTime.MAX

Полночь и полдень

import { LocalTime } from 'js-joda';

const midnight = LocalTime.MIDNIGHT; // 00:00
const noon = LocalTime.NOON;         // 12:00

Границы диапазона

const min = LocalTime.MIN; // 00:00:00
const max = LocalTime.MAX; // 23:59:59.999999999

Эти значения полезны при вычислениях диапазонов времени внутри суток.

Создание через преобразование других типов

Из Instant через Clock

Хотя LocalTime не содержит даты, он может быть получен из временной точки:

import { Instant, ZoneId, LocalTime } from 'js-joda';

const instant = Instant.now();
const time = LocalTime.now(Clock.systemDefaultZone());

Из ZonedDateTime и LocalDateTime

Извлечение времени:

const time = zonedDateTime.toLocalTime();
const time = localDateTime.toLocalTime();

Работа с дробной частью времени

Наносекунды как отдельный компонент

При создании через of четвёртый параметр задаёт точность:

LocalTime.of(10, 30, 15, 123456789);

Структура хранения:

  • 1 секунда = 1 000 000 000 наносекунд
  • диапазон наносекунд строго ограничен

Особенности точности

LocalTime сохраняет полную точность без округления. При вычислениях сохраняется исходная шкала наносекунд.

Валидация и ошибки создания

Типы ошибок

Неправильные значения приводят к:

  • DateTimeException

Примеры:

LocalTime.of(-1, 0);       // ошибка
LocalTime.of(12, 60);      // ошибка
LocalTime.ofSecondOfDay(90000); // ошибка

Строгая модель данных

Отсутствует неявное приведение типов:

  • строки не интерпретируются как числа
  • числа не нормализуются
  • переполнение не допускается

Использование цепочек создания

Комбинированные подходы

Создание может комбинироваться с преобразованиями:

const time = LocalTime
  .of(10, 0)
  .plusMinutes(30)
  .plusSeconds(15);

Хотя это уже не создание, а модификация, базовый объект всегда создаётся через фабричные методы.

Типовые сценарии создания

Фиксированное расписание

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

Десериализация данных

const time = LocalTime.parse(json.time);

Нормализация секунд дня

const time = LocalTime.ofSecondOfDay(seconds % 86400);

Особенности внутренней модели

LocalTime хранит данные в виде:

  • часов
  • минут
  • секунд
  • наносекунд

Все представления приводятся к единой внутренней структуре, что обеспечивает быстрые операции сравнения и вычислений.

Сравнение способов создания

Способ Источник Точность Использование
now() системное время наносекунды текущее время
of() ручные значения наносекунды конструирование
parse() строка наносекунды десериализация
ofSecondOfDay() секунды суток секунды оптимизация
ofNanoOfDay() наносекунды суток наносекунды высокая точность
Оглавление