Класс Calendar

public abstract class Calendar
extends Object
implements Serializable, Cloneable, Comparable<Calendar>

Класс Calendar — абстрактный класс, предоставляющий методы для преобразования между конкретным моментом времени и набором calendar fields, таких как YEAR, MONTH, DAY_OF_MONTH, HOUR, и так далее, а также для манипулирования полями календаря, например, для получения даты следующей недели. Момент времени можно представить в виде значения в миллисекундах, являющегося смещением от эпохи, 1 января 1970 года 00:00:00.000 GMT (григорианский календарь).

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

Подобно другим классам, зависящим от локали, Calendar предоставляет классный метод getInstance, для получения полезного объекта этого типа. Метод getInstance класса Calendar возвращает объект Calendar, поля календаря которого инициализированы текущей датой и временем:

Calendar rightNow = Calendar.getInstance();

Объект Calendar может генерировать все значения полей календаря, необходимые для реализации форматирования даты и времени для определенного языка и стиля календаря (например, японско-григорианский, японско-традиционный). Calendar определяет диапазон значений, возвращаемых определёнными полями календаря, а также их значение. Например, первый месяц системы календаря имеет значение MONTH == JANUARY для всех календарей. Другие значения определяются конкретным подклассом, например ERA. Подробности см. в документации по отдельным полям и документации подкласса.

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

Значения полей календаря можно установить, вызвав методы set. Любые значения полей, установленные в Calendar, не будут интерпретированы до тех пор, пока он не потребуется рассчитать своё значение времени (миллисекунды от эпохи) или значения полей календаря. Вызов get, getTimeInMillis, getTime, add и roll подразумевает такой расчёт.

Поведение

Calendar имеет два режима интерпретации полей календаря: мягкий и жёсткий. Когда Calendar находится в мягком режиме, он принимает более широкий диапазон значений полей календаря, чем генерирует. Когда Calendar пересчитывает значения полей календаря для возврата методом get(), все поля календаря нормализуются. Например, мягкий GregorianCalendar интерпретирует MONTH == JANUARY, DAY_OF_MONTH == 32 как 1 февраля.

Когда Calendar находится в жёстком режиме, он выбрасывает исключение, если в его полях календаря есть какие-либо несоответствия. Например, GregorianCalendar всегда генерирует значения DAY_OF_MONTH от 1 до длины месяца. Жёсткий GregorianCalendar выбрасывает исключение при вычислении своего значения времени или значений полей календаря, если установлено какое-либо значение поля, выходящее за пределы диапазона.

Первая неделя

Calendar определяет специфичную для локали семидневную неделю с помощью двух параметров: первого дня недели и минимального количества дней в первой неделе (от 1 до 7). Эти числа берутся из данных ресурсов локали или из самой локали при создании объекта Calendar. Если указанная локали содержит расширения Unicode "fw" и/или "rg", первый день недели будет получен в соответствии с этими расширениями. Если указаны как "fw", так и "rg", значение из расширения "fw" имеет приоритет над неявным значением из расширения "rg". Их также можно указать явно через методы для установки их значений.

При установке или получении полей WEEK_OF_MONTH или WEEK_OF_YEAR, Calendar должен определить первую неделю месяца или года в качестве точки отсчёта. Первая неделя месяца или года определяется как самый ранний семидневный период, начинающийся в getFirstDayOfWeek() и содержащий как минимум getMinimalDaysInFirstWeek() дней этого месяца или года. Недели с номерами ..., -1, 0 предшествуют первой неделе; недели с номерами 2, 3,... следуют за ней. Обратите внимание, что нормализованный номер, возвращаемый get(), может отличаться. Например, конкретный подкласс Calendar может обозначить неделю перед неделей 1 года как неделю n предыдущего года.

Разрешение полей календаря

При вычислении даты и времени по полям календаря может быть недостаточно информации для вычисления (например, только год и месяц без числа месяца) или может быть противоречивая информация (например, вторник, 15 июля 1996 года (григорианский) — 15 июля 1996 года на самом деле понедельник). Calendar будет разрешать значения полей календаря для определения даты и времени следующим образом.

При возникновении конфликта в значениях полей календаря, Calendar отдает приоритет полям календаря, которые были установлены позднее. Ниже приведены стандартные комбинации полей календаря. Будет использоваться комбинация, определённая последним из установленных полей.

Для полей даты:

YEAR + MONTH + DAY_OF_MONTH
YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
YEAR + DAY_OF_YEAR
YEAR + DAY_OF_WEEK + WEEK_OF_YEAR

Для полей времени суток:

HOUR_OF_DAY
AM_PM + HOUR

Если какие-либо поля календаря в выбранной комбинации полей не установлены, Calendar использует их значения по умолчанию. Значение по умолчанию для каждого поля может отличаться в зависимости от конкретной системы календаря. Например, в GregorianCalendar, значение по умолчанию для поля такое же, как и в начале эпохи: т.е. YEAR = 1970, MONTH = JANUARY, DAY_OF_MONTH = 1, и т.д.

Примечание: Существуют некоторые возможные неоднозначности в интерпретации отдельных моментов времени, которые разрешаются следующим образом:

1. 23:59 — последняя минута дня, а 00:00 — первая минута следующего дня. Таким образом, 23:59 31 декабря 1999 года < 00:00 1 января 2000 года < 00:01 1 января 2000 года.
2. Хотя исторически это неточно, полночь также относится к "am", а полдень — к "pm", поэтому в один и тот же день 12:00 am (полночь) < 12:01 am, и 12:00 pm (полдень) < 12:01 pm

Форматы строк даты или времени не являются частью определения календаря, так как их можно изменять или переопределять пользователем во время выполнения. Используйте DateFormat для форматирования дат.

Манипулирование полями

Поля календаря можно изменить с помощью трёх методов: set(), add(), и roll().

set(f, value) изменяет поле календаря f на value. Кроме того, он устанавливает внутреннюю переменную, чтобы указать, что поле календаря f было изменено. Хотя поле календаря f изменяется немедленно, значение времени календаря в миллисекундах пересчитывается только при следующем вызове get(), getTime(), getTimeInMillis(), add(), или roll(). Таким образом, многократные вызовы set() не вызывают многократных, нежелательных вычислений. В результате изменения поля календаря с помощью set(), другие поля календаря также могут измениться, в зависимости от поля календаря, значения поля календаря и системы календаря. Кроме того, get(f) не обязательно вернёт value установленное вызовом метода set после пересчёта полей календаря. Конкретика определяется конкретным классом календаря.

Пример: Рассмотрим GregorianCalendar, изначально установленный на 31 августа 1999 года. Вызов set(Calendar.MONTH, Calendar.SEPTEMBER) устанавливает дату на 31 сентября 1999 года. Это временное внутреннее представление, которое разрешается до 1 октября 1999 года, если затем вызывается getTime(). Однако вызов set(Calendar.DAY_OF_MONTH, 30) до вызова getTime() устанавливает дату на 30 сентября 1999 года, так как пересчёт не происходит после вызова set().

add(f, delta) добавляет delta к полю f. Это эквивалентно вызову set(f, get(f) + delta) с двумя корректировками:

Правило добавления 1. Значение поля f после вызова минус значение поля f до вызова равно delta, с учётом любого переполнения, произошедшего в поле f. Переполнение происходит, когда значение поля превышает свой диапазон, и в результате следующее большее поле увеличивается или уменьшается, а значение поля корректируется обратно в свой диапазон.

Правило добавления 2. Если ожидается, что меньшее поле останется неизменным, но это невозможно, потому что изменения в его минимуме или максимуме после изменения поля f или других ограничений, таких как изменение смещения часового пояса, то его значение корректируется, чтобы быть как можно ближе к его ожидаемому значению. Меньшее поле представляет меньшую единицу времени. HOUR является меньшим полем, чем DAY_OF_MONTH. Никакой корректировки не производится для меньших полей, которые не ожидаются неизменными. Система календаря определяет, какие поля ожидаются неизменными.

Кроме того, в отличие от set(), add() заставляет немедленно пересчитать миллисекунды календаря и все поля.

Пример: Рассмотрим GregorianCalendar, изначально установленный на 31 августа 1999 года. Вызов add(Calendar.MONTH, 13) устанавливает календарь на 30 сентября 2000 года. Правило добавления 1 устанавливает поле MONTH на сентябрь, так как добавление 13 месяцев к августу даёт сентябрь следующего года. Так как DAY_OF_MONTH не может быть 31 в сентябре в GregorianCalendar, правило добавления 2 устанавливает DAY_OF_MONTH на 30, ближайшее возможное значение. Хотя это меньшее поле, DAY_OF_WEEK не корректируется правилом 2, так как ожидается его изменение при изменении месяца в GregorianCalendar.

roll(f, delta) добавляет delta к полю f без изменения более крупных полей. Это эквивалентно вызову add(f, delta) с следующей корректировкой:

Правило циклического сдвига. Более крупные поля остаются неизменными после вызова. Более крупное поле представляет более крупную единицу времени. DAY_OF_MONTH является более крупным полем, чем HOUR.

Пример: См. GregorianCalendar.roll(int, int).