SetUTCDate: примеры (JAVASCRIPT)

Простые примеры применения

Установка корректного дня месяца.

const date = new Date('2023-08-15T12:00:00Z');
console.log(date.toISOString());
date.setUTCDate(25);
console.log(date.toISOString());

2023-08-15T12:00:00.000Z
2023-08-25T12:00:00.000Z

Использование значения 0 для получения последнего дня предыдущего месяца.

const date = new Date('2023-03-15T12:00:00Z');
date.setUTCDate(0);
console.log(date.toISOString());

2023-02-28T12:00:00.000Z

Переполнение дня для перехода на следующий месяц.

const date = new Date('2023-01-31T12:00:00Z');
date.setUTCDate(32);
console.log(date.toISOString());

2023-02-01T12:00:00.000Z

Похожие функции в JavaScript

В JavaScript существует несколько методов для изменения компонентов даты.

• setDate(): Устанавливает день месяца, но использует местное время системы, а не UTC. Предпочтительнее использовать, когда операции с датой должны учитывать локальный часовой пояс пользователя.
• setUTCMonth(): Позволяет установить месяц и, опционально, день месяца по UTC. Удобен для комплексного изменения месяца и дня.
• setTime(): Устанавливает дату и время, используя количество миллисекунд с начала эпохи Unix. Более низкоуровневый метод, полезен для точных вычислений или копирования временных меток.

Выбор между setUTCDate и setDate зависит от задачи. Для согласованного хранения и передачи данных между разными часовыми поясами подходит UTC-вариант. Для отображения даты в интерфейсе, привязанного к местоположению пользователя, может быть удобнее setDate().

Типичные ошибки

Частой ошибкой является путаница между методами, работающими с местным временем и UTC.

const date = new Date('2023-08-15T12:00:00Z');
// Разный результат, если локальный часовой пояс не UTC
date.setUTCDate(20);
console.log('UTC:', date.toISOString());
date.setDate(20); // Использует локальное время
console.log('Local adjust:', date.toISOString());

Результат зависит от локального часового пояса. При UTC+3, например, вывод может быть:

UTC: 2023-08-20T12:00:00.000Z
Local adjust: 2023-08-19T21:00:00.000Z

Другая ошибка - игнорирование возвращаемого значения. Метод возвращает timestamp, а не новый объект Date.

const date = new Date();
const timestamp = date.setUTCDate(10);
console.log(timestamp); // Число, а не объект Date
console.log(date); // Измененный объект Date

История изменений

Метод setUTCDate() был стандартизирован в спецификации ECMAScript 1 (ES1) 1997 года. С тех пор его поведение остается стабильным и совместимым.

Значительных изменений в последних версиях ECMAScript (ES6/ES2015 и новее) не было. Все текущие реализации в браузерах и средах, таких как Node.js, следуют единой спецификации.

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

Расширенные примеры использования

Вычисление последнего дня месяца по UTC.

function getLastUTCDayOfMonth(year, month) {
    // month: 0-11 (январь-декабрь)
    const date = new Date(Date.UTC(year, month + 1, 0));
    return date.getUTCDate();
}
console.log(getLastUTCDayOfMonth(2023, 1)); // Февраль 2023
console.log(getLastUTCDayOfMonth(2024, 1)); // Февраль 2024 (високосный)

28
29

Добавление определенного количества дней к дате по UTC с учетом переполнения месяцев.

function addUTCDays(startDate, daysToAdd) {
    const newDate = new Date(startDate);
    // Получаем текущий день по UTC и добавляем нужное количество
    newDate.setUTCDate(newDate.getUTCDate() + daysToAdd);
    return newDate;
}
const start = new Date('2023-12-28T00:00:00Z');
console.log(addUTCDays(start, 10).toISOString());

2024-01-07T00:00:00.000Z

Циклическая обработка дат в массиве с изменением дня.

const dates = [
    new Date('2023-01-10T00:00:00Z'),
    new Date('2023-02-15T00:00:00Z'),
    new Date('2023-03-20T00:00:00Z')
];
// Установить для всех дат 1-е число месяца
const firstDayDates = dates.map(date => {
    const newDate = new Date(date);
    newDate.setUTCDate(1);
    return newDate;
});
console.log(firstDayDates.map(d => d.toISOString()));

["2023-01-01T00:00:00.000Z", "2023-02-01T00:00:00.000Z", "2023-03-01T00:00:00.000Z"]

Корректировка даты с проверкой на валидность после изменения.

function safeSetUTCDate(date, day) {
    const tempDate = new Date(date);
    tempDate.setUTCDate(day);
    // Проверка, что дата осталась валидной и день соответствует установленному (обработка NaN)
    if (isNaN(tempDate.getTime()) || tempDate.getUTCDate() !== day) {
        throw new Error('Invalid date resulting from setUTCDate');
    }
    return tempDate;
}
try {
    console.log(safeSetUTCDate(new Date(), 31).toISOString());
} catch (e) {
    console.error(e.message);
}

Аналоги в других языках программирования

В других языках существуют похожие механизмы работы с UTC-датами.

Python (datetime, pytz):

from datetime import datetime, timezone
# Создание даты с UTC
utc_date = datetime(2023, 8, 15, 12, 0, 0, tzinfo=timezone.utc)
# Замена дня. Объекты datetime неизменяемы, создается новый.
new_date = utc_date.replace(day=25)
print(utc_date.isoformat())
print(new_date.isoformat())

2023-08-15T12:00:00+00:00
2023-08-25T12:00:00+00:00

PHP:

$date = new DateTime('2023-08-15 12:00:00', new DateTimeZone('UTC'));
echo $date->format('Y-m-d\TH:i:s\Z') . "\n";
$date->setDate($date->format('Y'), $date->format('m'), 25);
echo $date->format('Y-m-d\TH:i:s\Z');

2023-08-15T12:00:00Z
2023-08-25T12:00:00Z

MySQL (использование функций даты):

SELECT DATE_ADD('2023-08-15', INTERVAL (25 - DAY('2023-08-15')) DAY) as new_date;

new_date: 2023-08-25

Отличие JavaScript в том, что метод setUTCDate() изменяет исходный объект, в то время как во многих других языках (например, Python) даты являются неизменяемыми, и операции возвращают новый объект.