Класс GregorianCalendar

public class GregorianCalendar
extends Calendar

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

GregorianCalendar — гибридный календарь, который поддерживает как юлианский, так и григорианский календари с поддержкой одной точки разрыва, которая по умолчанию соответствует григорианской дате, когда был введён григорианский календарь (15 октября 1582 года в некоторых странах, позже в других). Дата перехода может быть изменена вызывающей стороной с помощью вызова setGregorianChange().

Исторически в тех странах, которые первыми приняли григорианский календарь, 4 октября 1582 года (юлианский) следовало 15 октября 1582 года (григорианский). Этот календарь моделирует это корректно. До григорианского перехода GregorianCalendar реализует юлианский календарь. Единственное отличие между григорианским и юлианским календарями — правило високосных лет. Юлианский календарь указывает високосные года каждые четыре года, тогда как григорианский календарь пропускает столетия, которые не делятся на 400.

GregorianCalendar реализует пролептические григорианский и юлианский календари. То есть даты вычисляются путём экстраполяции текущих правил неограниченно вперёд и назад во времени. В результате GregorianCalendar может использоваться для всех лет, чтобы генерировать осмысленные и согласованные результаты. Однако даты, полученные с помощью GregorianCalendar, исторически точны только с 1 марта 4 г. н.э., когда были приняты современные правила юлианского календаря. До этой даты правила високосных лет применялись нерегулярно, а до 45 г. до н.э. юлианского календаря не существовало.

До принятия григорианского календаря Новый год отмечался 25 марта. Чтобы избежать путаницы, этот календарь всегда использует 1 января. Ручная корректировка может быть сделана при необходимости для дат, предшествующих григорианскому переходу и которые попадают между 1 января и 24 марта.

Неделя года и год недели

Значения, вычисленные для поля WEEK_OF_YEAR, находятся в диапазоне от 1 до 53. Первая неделя календарного года — это самый ранний семидневный период, начинающийся с getFirstDayOfWeek(), который содержит по крайней мере getMinimalDaysInFirstWeek() дней из этого года. Таким образом, он зависит от значений getMinimalDaysInFirstWeek(), getFirstDayOfWeek(), и дня недели 1 января. Недели между 1 неделей одного года и 1 неделей следующего года (исключая) нумеруются последовательно от 2 до 52 или 53 (за исключением года(ов), вовлечённых в переход из юлианского в григорианский).

Значения getFirstDayOfWeek() и getMinimalDaysInFirstWeek() инициализируются с помощью ресурсов, зависящих от локали, при создании GregorianCalendar. Определение недели совместимо со стандартом ISO 8601, когда getFirstDayOfWeek() равно MONDAY и getMinimalDaysInFirstWeek() равно 4, которые используются в локалях, где предпочтительно использовать стандарт. Эти значения могут быть явно установлены путём вызова setFirstDayOfWeek() и setMinimalDaysInFirstWeek().

Год недели синхронизирован с циклом WEEK_OF_YEAR. Все недели между первой и последней (включая) имеют одинаковое значение года недели. Следовательно, первый и последний день года недели могут иметь разные значения календарного года.

Например, 1 января 1998 года — четверг. Если getFirstDayOfWeek() равно MONDAY и getMinimalDaysInFirstWeek() равно 4 (совместимая с ISO 8601 настройка), то неделя 1 1998 года начинается 29 декабря 1997 года и заканчивается 4 января 1998 года. Год недели — 1998 для последних трёх дней календарного года 1997. Однако, если getFirstDayOfWeek() равно SUNDAY, то неделя 1 1998 года начинается 4 января 1998 года и заканчивается 10 января 1998 года; первые три дня 1998 года затем входят в неделю 53 1997 года, и их год недели — 1997.

Неделя месяца

Значения, вычисленные для поля WEEK_OF_MONTH находятся в диапазоне от 0 до 6. Неделя 1 месяца (дни с WEEK_OF_MONTH = 1) — это самый ранний набор по крайней мере getMinimalDaysInFirstWeek() непрерывных дней в этом месяце, заканчивающийся днём перед getFirstDayOfWeek(). В отличие от недели 1 года, неделя 1 месяца может быть короче 7 дней, не обязательно начинаться с getFirstDayOfWeek(), и не будет включать дни предыдущего месяца. Дни месяца перед неделей 1 имеют значение WEEK_OF_MONTH равное 0.

Например, если getFirstDayOfWeek() равно SUNDAY и getMinimalDaysInFirstWeek() равно 4, то первой неделей января 1998 года являются воскресенье, 4 января, по субботу, 10 января. Эти дни имеют значение WEEK_OF_MONTH равное 1. Четверг, 1 января, по субботу, 3 января, имеют значение WEEK_OF_MONTH равное 0. Если getMinimalDaysInFirstWeek() изменено на 3, то с 1 по 3 января имеют значение WEEK_OF_MONTH равное 1.

Значения полей по умолчанию

Метод clear устанавливает неопределенные значения полей календаря. GregorianCalendar использует следующие значения по умолчанию для каждого поля календаря, если его значение не определено.

Поле	Значение по умолчанию
ERA	AD
YEAR	1970
MONTH	JANUARY
DAY_OF_MONTH	1
DAY_OF_WEEK	the first day of week
WEEK_OF_MONTH	0
DAY_OF_WEEK_IN_MONTH	1
AM_PM	AM
HOUR, HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND	0

Значения по умолчанию не применяются к полям, не указанным выше.

Пример:

// get the supported ids for GMT-08:00 (Pacific Standard Time)
String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
// if no ids were returned, something is wrong. get out.
if (ids.length == 0)
    System.exit(0);

 // begin output
System.out.println("Current Time");

// create a Pacific Standard Time time zone
SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);

// set up rules for Daylight Saving Time
pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);

// create a GregorianCalendar with the Pacific Daylight time zone
// and the current date and time
Calendar calendar = new GregorianCalendar(pdt);
Date trialTime = new Date();
calendar.setTime(trialTime);

// print out a bunch of interesting things
System.out.println("ERA: " + calendar.get(Calendar.ERA));
System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
System.out.println("DATE: " + calendar.get(Calendar.DATE));
System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
System.out.println("DAY_OF_WEEK_IN_MONTH: "
                   + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
System.out.println("ZONE_OFFSET: "
                   + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
System.out.println("DST_OFFSET: "
                   + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));

System.out.println("Current Time, with hour reset to 3");
calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
calendar.set(Calendar.HOUR, 3);
System.out.println("ERA: " + calendar.get(Calendar.ERA));
System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
System.out.println("DATE: " + calendar.get(Calendar.DATE));
System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
System.out.println("DAY_OF_WEEK_IN_MONTH: "
                   + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
System.out.println("ZONE_OFFSET: "
       + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
System.out.println("DST_OFFSET: "
       + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours

Поля

BC

public static final int BC

Значение поля ERA, указывающее на период до нашей эры (до Рождества Христова), также известный как до н.э. Последовательность лет при переходе от BC к AD — ..., 2 до н.э., 1 до н.э., 1 н.э., 2 н.э., ...

См. также:

Calendar.ERA, Значения постоянных полей

AD

public static final int AD

Значение поля ERA, указывающее на период нашей эры (Anno Domini), также известный как н.э. Последовательность лет при переходе от BC к AD — ..., 2 до н.э., 1 до н.э., 1 н.э., 2 н.э., ...

См. также:

Calendar.ERA, Значения постоянных полей

Конструкторы

GregorianCalendar

public GregorianCalendar()

Создаёт календарь GregorianCalendar по текущему времени в часовом поясе по умолчанию с локалью по умолчанию FORMAT.

GregorianCalendar

public GregorianCalendar(TimeZone zone)

Создаёт календарь GregorianCalendar на основе текущего времени в заданном часовом поясе с локалью по умолчанию FORMAT.

Параметры:

zone — заданный часовой пояс.

GregorianCalendar

public GregorianCalendar(Locale aLocale)

Создаёт календарь GregorianCalendar на основе текущего времени в часовом поясе по умолчанию с заданной локалью.

Параметры:

aLocale — заданная локаль.

GregorianCalendar

public GregorianCalendar(TimeZone zone,
                         Locale aLocale)

Создаёт календарь GregorianCalendar на основе текущего времени в заданном часовом поясе с заданной локалью.

Параметры:

zone — заданный часовой пояс.

aLocale — заданная локаль.

GregorianCalendar

public GregorianCalendar(int year,
                         int month,
                         int dayOfMonth)

Создаёт календарь GregorianCalendar с заданной датой в часовом поясе по умолчанию с локалью по умолчанию.

Параметры:

year — значение, используемое для установки поля календаря YEAR.

month — значение, используемое для установки поля календаря MONTH (значение месяца от 0 до 11, 0 — январь).

dayOfMonth — значение, используемое для установки поля календаря DAY_OF_MONTH.

GregorianCalendar

public GregorianCalendar(int year,
                         int month,
                         int dayOfMonth,
                         int hourOfDay,
                         int minute)

Создаёт календарь GregorianCalendar с заданной датой и временем в часовом поясе по умолчанию с локалью по умолчанию.

Параметры:

year — значение, используемое для установки поля календаря YEAR.

month — значение, используемое для установки поля календаря MONTH (значение месяца от 0 до 11, 0 — январь).

dayOfMonth — значение, используемое для установки поля календаря DAY_OF_MONTH.

hourOfDay — значение, используемое для установки поля календаря HOUR_OF_DAY.

minute — значение, используемое для установки поля календаря MINUTE.

GregorianCalendar

public GregorianCalendar(int year,
                         int month,
                         int dayOfMonth,
                         int hourOfDay,
                         int minute,
                         int second)

Создаёт календарь GregorianCalendar с заданной датой и временем в часовом поясе по умолчанию с локалью по умолчанию.

Параметры:

year — значение, используемое для установки поля календаря YEAR.

month — значение, используемое для установки поля календаря MONTH (значение месяца от 0 до 11, 0 — январь).

dayOfMonth — значение, используемое для установки поля календаря DAY_OF_MONTH.

hourOfDay — значение, используемое для установки поля календаря HOUR_OF_DAY.

minute — значение, используемое для установки поля календаря MINUTE.

second — значение, используемое для установки поля календаря SECOND.

Методы

setGregorianChange

public void setGregorianChange(Date date)

Параметры:

date — заданная дата перехода на григорианский календарь.

getGregorianChange

public final Date getGregorianChange()

Возвращает дату перехода на григорианский календарь. Это момент перехода от юлианского календаря к григорианскому. По умолчанию 15 октября 1582 года (григорианский). До этой даты даты будут в юлианском календаре.

Возвращает:

дата перехода на григорианский календарь для этого объекта GregorianCalendar.

isLeapYear

public boolean isLeapYear(int year)

Определяет, является ли данный год високосным. Возвращает true , если данный год високосный. Для указания годов до н.э., необходимо указать отрицательное значение. Например, год до н.э. 4 указывается как -3.

Параметры:

year — заданный год.

Возвращает:

true , если заданный год високосный; false в противном случае.

getCalendarType

public String getCalendarType()

Возвращает "gregory" в качестве типа календаря.

Переопределяет:

getCalendarType в классе Calendar

Возвращает:

"gregory"

С момента:

1.8

См. также:

Расширения локали, Locale.Builder.setLocale(Locale), Locale.Builder.setUnicodeLocaleKeyword(String, String)

equals

public boolean equals(Object obj)

Сравнивает этот GregorianCalendar с заданным Object. Результат равен true, только если аргумент является объектом GregorianCalendar, представляющим ту же временную метку (смещение в миллисекундах от эпохи эпохи) при тех же параметрах Calendar и дате перехода на григорианский календарь, что и этот объект.

Переопределяет:

equals в классе Calendar

Параметры:

obj — объект для сравнения.

Возвращает:

true , если этот объект равен obj; false в противном случае.

См. также:

Calendar.compareTo(Calendar)

hashCode

public int hashCode()

Генерирует код хэш для этого объекта GregorianCalendar.

Переопределяет:

hashCode в классе Calendar

Возвращает:

значение кода хэш для этого объекта.

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

add

public void add(int field,
                int amount)

Указано в:

add в классе Calendar

Параметры:

field — поле календаря.

amount — количество добавляемого времени.

Исключения:

IllegalArgumentException — если field равно ZONE_OFFSET, DST_OFFSET, или неизвестно, или если любое поле календаря имеет значение вне диапазона в режиме «не строгий».

См. также:

Calendar.roll(int,int), Calendar.set(int,int)

roll

public void roll(int field,
                 boolean up)

Указано в:

roll в классе Calendar

Параметры:

up — указывает, увеличивать или уменьшать значение указанного поля календаря. Используйте true для увеличения, false в противном случае.

field — поле времени.

Исключения:

IllegalArgumentException — если field равно ZONE_OFFSET, DST_OFFSET, или неизвестно, или если любое поле календаря имеет значение вне диапазона в режиме «не строгий».

См. также:

add(int,int), Calendar.set(int,int)

roll

public void roll(int field,
                 int amount)

Переопределяет:

roll в классе Calendar

Параметры:

field - поле календаря.

amount - подписанная сумма для добавления к field.

Исключения:

IllegalArgumentException - если field является ZONE_OFFSET, DST_OFFSET, или неизвестным, или если какие-либо поля календаря имеют значения вне диапазона в нестрогом режиме.

С версии:

1.2

См. также:

roll(int,boolean), add(int,int), Calendar.set(int,int)

getMinimum

public int getMinimum(int field)

Возвращает минимальное значение для данного поля календаря этого экземпляра GregorianCalendar. Минимальное значение определяется как наименьшее значение, возвращаемое методом get для любого возможного значения времени, с учетом текущих значений методов getFirstDayOfWeek, getMinimalDaysInFirstWeek, getGregorianChange и getTimeZone.

Указано в:

getMinimum в классе Calendar

Параметры:

field - поле календаря.

Возвращает:

минимальное значение для данного поля календаря.

См. также:

getMaximum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMinimum(int), getActualMaximum(int)

getMaximum

public int getMaximum(int field)

Возвращает максимальное значение для данного поля календаря этого экземпляра GregorianCalendar. Максимальное значение определяется как наибольшее значение, возвращаемое методом get для любого возможного значения времени, с учетом текущих значений методов getFirstDayOfWeek, getMinimalDaysInFirstWeek, getGregorianChange и getTimeZone.

Указано в:

getMaximum в классе Calendar

Параметры:

field - поле календаря.

Возвращает:

максимальное значение для данного поля календаря.

См. также:

getMinimum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMinimum(int), getActualMaximum(int)

getGreatestMinimum

public int getGreatestMinimum(int field)

Возвращает наибольшее минимальное значение для данного поля календаря этого экземпляра GregorianCalendar. Наибольшее минимальное значение определяется как наибольшее значение, возвращаемое методом getActualMinimum(int) для любого возможного значения времени, с учетом текущих значений методов getFirstDayOfWeek, getMinimalDaysInFirstWeek, getGregorianChange и getTimeZone.

Указано в:

getGreatestMinimum в классе Calendar

Параметры:

field - поле календаря.

Возвращает:

наибольшее минимальное значение для данного поля календаря.

См. также:

getMinimum(int), getMaximum(int), getLeastMaximum(int), getActualMinimum(int), getActualMaximum(int)

getLeastMaximum

public int getLeastMaximum(int field)

Возвращает наименьшее максимальное значение для данного поля календаря этого экземпляра GregorianCalendar. Наименьшее максимальное значение определяется как наименьшее значение, возвращаемое методом getActualMaximum(int) для любого возможного значения времени, с учетом текущих значений методов getFirstDayOfWeek, getMinimalDaysInFirstWeek, getGregorianChange и getTimeZone.

Указано в:

getLeastMaximum в классе Calendar

Параметры:

field - поле календаря

Возвращает:

наименьшее максимальное значение для данного поля календаря.

См. также:

getMinimum(int), getMaximum(int), getGreatestMinimum(int), getActualMinimum(int), getActualMaximum(int)

getActualMinimum

public int getActualMinimum(int field)

Переопределяет:

getActualMinimum в классе Calendar

Параметры:

field - поле календаря

Возвращает:

минимальное значение данного поля для значения времени этого экземпляра GregorianCalendar

С версии:

1.2

См. также:

getMinimum(int), getMaximum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMaximum(int)

getActualMaximum

public int getActualMaximum(int field)

Переопределяет:

getActualMaximum в классе Calendar

Параметры:

field - поле календаря

Возвращает:

максимальное значение данного поля для значения времени этого экземпляра GregorianCalendar

С версии:

1.2

См. также:

getMinimum(int), getMaximum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMinimum(int)

clone

public Object clone()

Описание скопировано из класса: Calendar

Создаёт и возвращает копию этого объекта.

Переопределяет:

clone в классе Calendar

Возвращает:

копию этого объекта.

См. также:

Cloneable

getTimeZone

public TimeZone getTimeZone()

Описание скопировано из класса: Calendar

Получает часовой пояс.

Переопределяет:

getTimeZone в классе Calendar

Возвращает:

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

setTimeZone

public void setTimeZone(TimeZone zone)

Описание скопировано из класса: Calendar

Устанавливает часовой пояс заданным значением часового пояса.

Переопределяет:

setTimeZone в классе Calendar

Параметры:

zone - заданный часовой пояс.

isWeekDateSupported

public final boolean isWeekDateSupported()

Возвращает true указывающее, поддерживает ли этот GregorianCalendar даты недели.

Переопределяет:

isWeekDateSupported в классе Calendar

Возвращает:

true (всегда)

С:

1.7

См. также:

getWeekYear(), setWeekDate(int,int,int), getWeeksInWeekYear()

getWeekYear

public int getWeekYear()

Переопределяет:

getWeekYear в классе Calendar

Возвращает:

год недели, представленный этим GregorianCalendar. Если значение ERA равно BC, год представлен 0 или отрицательным числом: до н. э. 1 — 0, до н. э. 2 — -1, до н. э. 3 — -2 и так далее.

Выбрасывает:

IllegalArgumentException - если любое из полей календаря является недопустимым в режиме без смягчения.

С:

1.7

См. также:

isWeekDateSupported(), getWeeksInWeekYear(), Calendar.getFirstDayOfWeek(), Calendar.getMinimalDaysInFirstWeek()

setWeekDate

public void setWeekDate(int weekYear,
                        int weekOfYear,
                        int dayOfWeek)

Переопределяет:

setWeekDate в классе Calendar

Параметры:

weekYear - год недели

weekOfYear - номер недели, основанный на weekYear

dayOfWeek - значение дня недели: одно из констант для поля DAY_OF_WEEK: SUNDAY, ..., SATURDAY.

Выбрасывает:

IllegalArgumentException - если любой из заданных спецификаторов даты является недопустимым или если любое из полей календаря несовместимо с заданными спецификаторами даты в режиме без смягчения

С:

1.7

См. также:

isWeekDateSupported(), Calendar.getFirstDayOfWeek(), Calendar.getMinimalDaysInFirstWeek()

getWeeksInWeekYear

public int getWeeksInWeekYear()

Переопределяет:

getWeeksInWeekYear в классе Calendar

Возвращает:

количество недель в году недели.

С:

1.7

См. также:

Calendar.WEEK_OF_YEAR, getWeekYear(), getActualMaximum(int)

computeFields

protected void computeFields()

Преобразует значение времени (смещение в миллисекундах от эпохи) в значения полей календаря. Время не перевычисляется; чтобы перевычислить время, а затем поля, вызовите метод complete.

Определено в:

computeFields в классе Calendar

См. также:

Calendar.complete()

computeTime

protected void computeTime()

Преобразует значения полей календаря в значение времени (смещение в миллисекундах от эпохи).

Определено в:

computeTime в классе Calendar

Выбрасывает:

IllegalArgumentException - если какие-либо поля календаря недопустимы.

См. также:

Calendar.complete(), Calendar.computeFields()

toZonedDateTime

public ZonedDateTime toZonedDateTime()

Возвращает:

объект даты и времени с часовым поясом, представляющий ту же точку на временной шкале, что и этот календарь Gregorian

С:

1.8

from

public static GregorianCalendar from(ZonedDateTime zdt)

Параметры:

zdt - объект даты и времени с часовым поясом для преобразования

Возвращает:

объект календаря Gregorian, представляющий ту же точку на временной шкале, что и предоставленное время с часовым поясом

Выбрасывает:

NullPointerException - если zdt равно null

IllegalArgumentException - если время с часовым поясом слишком велико для представления как GregorianCalendar

С:

1.8