Метод engulfs

Метод engulfs относится к объекту Interval в библиотеке Luxon и используется для определения того, полностью ли один временной интервал содержит другой. Речь идёт не о частичном пересечении, а именно о строгом включении границ одного интервала в границы другого.

Сигнатура метода

interval.engulfs(otherInterval)

Назначение

Метод возвращает логическое значение, отражающее факт полного «поглощения» одного интервала другим:

  • true — если текущий интервал полностью включает переданный
  • false — если хотя бы одна граница выходит за пределы или интервалы не пересекаются корректно

Под «включением» понимается ситуация, когда:

  • начало текущего интервала меньше или равно началу проверяемого
  • конец текущего интервала больше или равно концу проверяемого

Иными словами, проверяется условие:

текущий интервал охватывает другой целиком

Логическая модель сравнения

Пусть:

  • A = текущий интервал
  • B = проверяемый интервал

Тогда:

A.engulfs(B) ⇔ A.start ≤ B.start AND A.end ≥ B.end

Важно учитывать, что сравнение происходит с учётом временной зоны и нормализованных значений DateTime.

Особенности работы Interval в Luxon

Интервал в Luxon задаётся двумя объектами DateTime:

import { Interval, DateTime } from "luxon";

const start = DateTime.fromISO("2026-01-01T00:00:00");
const end = DateTime.fromISO("2026-01-10T00:00:00");

const interval = Interval.fromDateTimes(start, end);

Метод engulfs применяется именно к таким объектам.

Базовый пример использования

import { Interval, DateTime } from "luxon";

const outer = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-01"),
  DateTime.fromISO("2026-01-10")
);

const inner = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-03"),
  DateTime.fromISO("2026-01-05")
);

outer.engulfs(inner); // true

Здесь внутренний интервал полностью лежит внутри внешнего.

Случай частичного пересечения

const a = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-01"),
  DateTime.fromISO("2026-01-05")
);

const b = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-04"),
  DateTime.fromISO("2026-01-08")
);

a.engulfs(b); // false

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

Случай равных интервалов

const a = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-01"),
  DateTime.fromISO("2026-01-10")
);

const b = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-01"),
  DateTime.fromISO("2026-01-10")
);

a.engulfs(b); // true

Равенство границ считается полным включением.

Пограничные случаи

Включение на границе начала

const a = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-01"),
  DateTime.fromISO("2026-01-10")
);

const b = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-01"),
  DateTime.fromISO("2026-01-05")
);

a.engulfs(b); // true

Совпадение начала допустимо.

Включение на границе конца

const b = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-06"),
  DateTime.fromISO("2026-01-10")
);

a.engulfs(b); // true

Совпадение конца также допустимо.

Невалидные интервалы

Если хотя бы один интервал невалиден (isValid === false), результат всегда будет false:

const invalid = Interval.invalid("error");

a.engulfs(invalid); // false

Отличие от пересечения интервалов

Метод engulfs часто путают с проверкой пересечения (overlaps), но логика принципиально различается:

  • overlaps — есть ли хотя бы частичное пересечение
  • engulfs — полное включение одного интервала в другой

Пример:

a.overlaps(b); // true
a.engulfs(b);  // false

Использование с временными зонами

Luxon нормализует DateTime внутри интервалов, но важно, что:

  • сравнение идёт в абсолютном времени (UTC-эквивалент)
  • разные временные зоны не влияют на результат включения, если моменты времени совпадают по UTC
const a = Interval.fromDateTimes(
  DateTime.fromISO("2026-01-01T00:00:00+03:00"),
  DateTime.fromISO("2026-01-02T00:00:00+03:00")
);

const b = Interval.fromDateTimes(
  DateTime.fromISO("2025-12-31T21:00:00Z"),
  DateTime.fromISO("2026-01-01T21:00:00Z")
);

a.engulfs(b); // зависит от фактической нормализации, но сравнение идёт корректно по абсолютному времени

Практическая модель применения

Проверка в рамках расписаний

Метод используется для анализа вложенности временных блоков:

  • занятость календаря
  • резервирование ресурсов
  • проверка конфликтов расписаний

Пример логики:

if (workDay.engulfs(meeting)) {
  // встреча полностью укладывается в рабочий день
}

Фильтрация интервалов

const filtered = intervals.filter(i => mainRange.engulfs(i));

Результат — только те интервалы, которые полностью содержатся в заданном диапазоне.

Семантика границ

Поведение метода включает границы интервала:

  • начало включается
  • конец включается

То есть используется закрытый интервал [start, end].

Типичные ошибки при использовании

Ожидание частичного совпадения

a.engulfs(b) // не заменяет overlaps

Метод не предназначен для поиска пересечений.

Игнорирование направления проверки

a.engulfs(b); // не эквивалентно b.engulfs(a)

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

Неверная работа с незакрытыми интервалами

Если start > end, интервал считается невалидным, и результат будет false.

Итоговая логика метода

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

Оглавление