Метод negate

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

Основной смысл операции инверсии длительности

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

Метод negate выполняет математическую операцию умножения всех полей длительности на -1, сохраняя структуру объекта:

  • положительные значения становятся отрицательными
  • отрицательные значения становятся положительными
  • нулевые значения остаются неизменными

При этом создаётся новый экземпляр Duration, исходный объект остаётся неизменным.

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

Duration#negate(): Duration

Метод не принимает аргументов и возвращает новый объект Duration.

Поведение метода

При вызове negate происходит построчное преобразование всех внутренних полей длительности:

  • years
  • months
  • days
  • hours
  • minutes
  • seconds
  • milliseconds

Каждое значение инвертируется по знаку, при этом структура объекта и его конфигурация сохраняются.

Пример базового использования

import { Duration } from "luxon";

const d1 = Duration.fromObject({
  hours: 5,
  minutes: 30
});

const d2 = d1.negate();

console.log(d2.toObject());
// { hours: -5, minutes: -30 }

Исходный объект d1 остаётся неизменным, что соответствует принципу иммутабельности Luxon.

Инверсия отрицательной длительности

Если исходная длительность уже отрицательная, negate преобразует её в положительную форму:

const d1 = Duration.fromObject({
  minutes: -15
});

const d2 = d1.negate();

console.log(d2.toObject());
// { minutes: 15 }

Таким образом, метод работает как универсальный переключатель знака.

Внутренние особенности работы

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

Пример:

const d = Duration.fromObject({
  hours: 1,
  minutes: 120
});

const neg = d.negate();

console.log(neg.toObject());
// { hours: -1, minutes: -120 }

Здесь не происходит преобразования 120 минут в 2 часа, поскольку negate работает на уровне уже заданных полей.

Иммутабельность и цепочки вызовов

Метод negate не изменяет исходный объект, а возвращает новый, что позволяет безопасно использовать цепочки методов:

const result = Duration.fromObject({
  days: 3,
  hours: 4
})
.negate()
.shiftTo("hours");

console.log(result.toObject());
// результат будет выражен в отрицательных часах

Каждый вызов создаёт новый объект, сохраняя предсказуемость вычислений.

Использование в арифметике длительностей

Метод negate часто применяется в сочетании с операциями сложения и вычитания длительностей. В Luxon отсутствует прямой оператор вычитания между Duration, поэтому отрицательная форма используется как инструмент моделирования разности:

const a = Duration.fromObject({ hours: 10 });
const b = Duration.fromObject({ hours: 3 });

const diff = a.plus(b.negate());

console.log(diff.toObject());
// { hours: 7 }

Такая конструкция эквивалентна вычитанию, реализованному через сложение отрицательной длительности.

Работа с нормализацией и единицами измерения

При использовании negate важно учитывать, что Luxon не изменяет структуру единиц. Если длительность содержит смешанные значения, например:

const d = Duration.fromObject({
  hours: 1,
  minutes: 90
});

После инверсии:

d.negate().toObject();
// { hours: -1, minutes: -90 }

Нормализация (например, преобразование 90 минут в 1 час 30 минут) выполняется отдельно через методы вроде normalize, но negate на это не влияет.

Поведение при нулевых значениях

Нулевые компоненты остаются неизменными:

const d = Duration.fromObject({
  hours: 0,
  minutes: 45
});

const neg = d.negate();

console.log(neg.toObject());
// { hours: 0, minutes: -45 }

Ноль рассматривается как нейтральный элемент и не изменяет знак.

Типичные сценарии применения

Метод negate используется в логике, где требуется:

  • инверсия временных интервалов
  • вычисление разницы между моментами через сложение
  • моделирование обратных временных сдвигов
  • построение симметричных интервалов относительно нуля

Особенно часто он встречается в алгоритмах планирования и расчётах временных отклонений.

Связь с другими методами Duration

negate логически связан с методами:

  • plus
  • minus
  • as
  • shiftTo
  • normalize

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

Оглавление