Skip to content

Revised calendar classes for Reiwa era #2224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 4, 2019
Merged

Revised calendar classes for Reiwa era #2224

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bdf940b
Updated for Reiwa era
Apr 1, 2019
b83e4a1
Revised reference topics for Reiwa era
Apr 1, 2019
24348be
Addressed feedback
Apr 3, 2019
553f703
Fixed bad link
Apr 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions includes/calendar-era.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

> [!IMPORTANT]
> A new era in the <xref:System.Globalization.JapaneseCalendar> and <xref:System.Globalization.JapaneseLunisolarCalendar> begins on May 1, 2019. This change affects all applications that use these calendars. See [Handling a new era in the Japanese calendar in .NET](https://devblogs.microsoft.com/dotnet/handling-a-new-era-in-the-japanese-calendar-in-net/) for more information and to determine whether your applications are affected. See [Prepare your application for the Japanese era change](/windows/uwp/design/globalizing/japanese-era-change) for information on testing your applications on Windows systems to ensure their readiness for the era change.

> The Reiwa era, a new era in the <xref:System.Globalization.JapaneseCalendar> and <xref:System.Globalization.JapaneseLunisolarCalendar>, begins on May 1, 2019. This change affects all applications that use these calendars. See [Handling a new era in the Japanese calendar in .NET](https://devblogs.microsoft.com/dotnet/handling-a-new-era-in-the-japanese-calendar-in-net/) for more information and to determine whether your applications are affected. See [Prepare your application for the Japanese era change](/windows/uwp/design/globalizing/japanese-era-change) for information on testing your applications on Windows systems to ensure their readiness for the era change. See [Working with eras](~/docs/standard/datetime/working-with-calendars.md#working-with-eras) for features in .NET that support calendard with multiple eras and for best practices when working with calendars that support multiple eras.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Reiwa era, a new era in the [](start = 3, length = 31)

I would rephrase this part with something like:

Japanese calendars expected to new era every while. For example, on May 1, 2019 introduced a new era Reiwa.

then you can continue what you have wrote

This change affects all applications that use these calendars....

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

forgot to mention this will make us not changing this doc again (I guess)

In reply to: 271383644 [](ancestors = 271383644)

12 changes: 7 additions & 5 deletions xml/System.Globalization/Calendar.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
A calendar divides time into units, such as weeks, months, and years. The number, length, and start of the divisions vary in each calendar.

> [!NOTE]
> For information about using the calendar classes in the .NET Framework, see [Working with Calendars](~/docs/standard/datetime/working-with-calendars.md).
> For information about using the calendar classes in .NET, see [Working with Calendars](~/docs/standard/datetime/working-with-calendars.md).

Any moment in time can be represented as a set of numeric values using a particular calendar. For example, a vernal equinox occurred at (1999, 3, 20, 8, 46, 0, 0.0) in the Gregorian calendar, that is, March 20, 1999 C.E. at 8:46:00:0.0. An implementation of <xref:System.Globalization.Calendar> can map any date in the range of a specific calendar to a similar set of numeric values, and <xref:System.DateTime> can map such sets of numeric values to a textual representation using information from <xref:System.Globalization.Calendar> and <xref:System.Globalization.DateTimeFormatInfo>. The textual representation can be culture-sensitive, for example, "8:46 AM March 20th 1999 AD" for the en-US culture, or culture-insensitive, for example, "1999-03-20T08:46:00" in ISO 8601 format.

Expand Down Expand Up @@ -705,7 +705,7 @@

The month part of the resulting <xref:System.DateTime> is affected if the resulting day is outside the month of the specified <xref:System.DateTime>. The year part of the resulting <xref:System.DateTime> is affected if the resulting month is outside the year of the specified <xref:System.DateTime>. The era part of the resulting <xref:System.DateTime> is affected if the resulting year is outside the era of the specified <xref:System.DateTime>. The time-of-day part of the resulting <xref:System.DateTime> remains the same as the specified <xref:System.DateTime>.

In all .NET Framework classes derived from the <xref:System.Globalization.Calendar> class, a week is defined as seven days.
In all .NET classes derived from the <xref:System.Globalization.Calendar> class, a week is defined as seven days.

The <xref:System.DateTime.Kind%2A> property of the returned <xref:System.DateTime> value always equals <xref:System.DateTimeKind.Unspecified?displayProperty=nameWithType>. You can preserve the <xref:System.DateTime.Kind%2A> property of the `time` parameter by calling the <xref:System.DateTime.SpecifyKind%2A?displayProperty=nameWithType> method, as the following example shows.

Expand Down Expand Up @@ -861,7 +861,7 @@
<format type="text/markdown"><![CDATA[

## Examples
The following example uses reflection to instantiate each <xref:System.Globalization.Calendar> type found in the .NET Framework and displays the value of its <xref:System.Globalization.Calendar.AlgorithmType%2A> property.
The following example uses reflection to instantiate each <xref:System.Globalization.Calendar> type found in .NET and displays the value of its <xref:System.Globalization.Calendar.AlgorithmType%2A> property.

[!code-csharp[System.Globalization.Calendar.AlgorithmType#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.algorithmtype/cs/algorithmtype1.cs#1)]
[!code-vb[System.Globalization.Calendar.AlgorithmType#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.algorithmtype/vb/algorithmtype1.vb#1)]
Expand Down Expand Up @@ -1059,6 +1059,8 @@

[!INCLUDE[japanese-era-note](~/includes/calendar-era.md)]

Of the calendar implementations in .NET, only the <xref:System.Globalization.JapaneseCalendar> and <xref:System.Globalization.JapaneseLunisolarCalendar> classes support multiple eras.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

only the [](start = 41, length = 9)

I would avoid telling "only" just in case in the future we can have more calendars have multiple eras. nobody knows :-)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But if new calendar with multiple eras are added, I guess you'd have to rewrite this anyway.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not really, the new calendars may not have anything related to Japanese calendars.


## Examples
The following code example displays the values contained in <xref:System.Globalization.JapaneseCalendar.Eras%2A?displayProperty=nameWithType>.

Expand Down Expand Up @@ -1607,8 +1609,8 @@
</Parameters>
<Docs>
<param name="time">The <see cref="T:System.DateTime" /> to read.</param>
<summary>When overridden in a derived class, returns the era in the specified <see cref="T:System.DateTime" />.</summary>
<returns>An integer that represents the era in <paramref name="time" />.</returns>
<summary>When overridden in a derived class, returns the era of the specified <see cref="T:System.DateTime" />.</summary>
<returns>An integer that represents the era of <paramref name="time" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Expand Down
43 changes: 23 additions & 20 deletions xml/System.Globalization/JapaneseCalendar.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,17 +48,18 @@
The Japanese calendar, which is also known as the Wareki calendar, works exactly like the Gregorian calendar, except that the year and era are different.

> [!NOTE]
> For information about using the <xref:System.Globalization.JapaneseCalendar> class and the other calendar classes in the .NET Framework, see [Working with Calendars](~/docs/standard/datetime/working-with-calendars.md).
> For information about using the <xref:System.Globalization.JapaneseCalendar> class and the other calendar classes in .NET, see [Working with Calendars](~/docs/standard/datetime/working-with-calendars.md).

The Japanese calendar recognizes one era for every emperor's reign. The current era is the Heisei era, which began in the Gregorian calendar year 1989. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen. By default, formatting operations with specified date and time format strings, such as "D", "F", and "Y", output Gannen rather than "1" in the result string.
The Japanese calendar recognizes one era for every emperor's reign. The two most recent eras are the Heisei era, beginning in the Gregorian calendar year 1989, and the Reiwa era, beginning in the Gregorian calendar year 2019. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen. By default, formatting operations with specified date and time format strings, such as "D", "F", and "Y", output Gannen rather than "1" in the result string.

[!INCLUDE[japanese-era-note](~/includes/calendar-era.md)]

This class assigns numbers to the eras as follows:

|GetEra value|Era Name|Era Abbreviation|Gregorian Dates|
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GetEra [](start = 1, length = 6)

This is a good doc we can reference in other related docs to mention the supported Japanese eras. so this doc would be the only doc we can touch in the future when getting the new era.

|------------------|--------------|----------------------|---------------------|
|4|平成 (Heisei)|平 (H, h)|January 8, 1989 to present|
|5|令和 (Reiwa)|令和 (R, r)|May 1, 2019 to present|
|4|平成 (Heisei)|平 (H, h)|January 8, 1989 to April 30, 2019|
|3|昭和 (Showa)|昭 (S, s)|December 25, 1926 to January 7, 1989|
|2|大正 (Taisho)|大 (T, t)|July 30, 1912 to December 24, 1926|
|1|明治 (Meiji)|明 (M, m)|September 8, 1868 to July 29, 1912|
Expand Down Expand Up @@ -350,7 +351,7 @@
<format type="text/markdown"><![CDATA[

## Examples
The following example uses reflection to instantiate each <xref:System.Globalization.Calendar> type found in the .NET Framework and displays the value of its <xref:System.Globalization.Calendar.AlgorithmType%2A> property.
The following example uses reflection to instantiate each <xref:System.Globalization.Calendar> type found in the .NET Class Library and displays the value of its <xref:System.Globalization.Calendar.AlgorithmType%2A> property.

[!code-csharp[System.Globalization.Calendar.AlgorithmType#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.algorithmtype/cs/algorithmtype1.cs#1)]
[!code-vb[System.Globalization.Calendar.AlgorithmType#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.algorithmtype/vb/algorithmtype1.vb#1)]
Expand Down Expand Up @@ -399,14 +400,15 @@
<format type="text/markdown"><![CDATA[

## Remarks
The Japanese calendar recognizes one era for every emperor's reign. The current era is the Heisei era, which began in the Gregorian calendar year 1989. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen.
The Japanese calendar recognizes one era for every emperor's reign. The two most recent eras are the Heisei era, beginning in the Gregorian calendar year 1989, and the Reiwa era, beginning in the Gregorian calendar year 2019. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen.

[!INCLUDE[japanese-era-note](~/includes/calendar-era.md)]

This class assigns numbers to the eras as follows:

|GetEra value|Era Name|Era Abbreviation|Gregorian Dates|
|------------------|--------------|----------------------|---------------------|
|5|令和 (Reiwa)|令和 (R, r)|May 1, 2019 to present|
|4|平成 (Heisei)|平 (H, h)|January 8, 1989 to present|
|3|昭和 (Showa)|昭 (S, s)|December 25, 1926 to January 7, 1989|
|2|大正 (Taisho)|大 (T, t)|July 30, 1912 to December 24, 1926|
Expand All @@ -415,7 +417,7 @@
This class handles dates from September 8 in the year Meiji 1 (January 1, 1868 of the Gregorian calendar). Although the Japanese calendar was switched from a lunar calendar to a solar calendar in the year Meiji 6 (1873 of the Gregorian calendar), this implementation is based on the solar calendar only.

> [!NOTE]
> Should additional eras be added in the future, applications may encounter more than the expected four eras for the Japanese calendar. Applications should be tested to ensure that they continue to work in such an event; see [Era Handling for the Japanese Calendar](https://go.microsoft.com/fwlink/p/?LinkId=239618).
> Should additional eras be added in the future, applications may encounter more than the expected five eras for the Japanese calendar. Your applications should be tested to ensure that they continue to work in such an event; see [Era Handling for the Japanese Calendar](https://go.microsoft.com/fwlink/p/?LinkId=239618).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> Should additional eras be added in the future, applications may encounter more than the expected five eras for the Japanese calendar. Your applications should be tested to ensure that they continue to work in such an event; see [Era Handling for the Japanese Calendar](https://go.microsoft.com/fwlink/p/?LinkId=239618).
> Should additional eras be added in the future, applications may encounter more than the expected five eras for the Japanese calendar. Your applications should be tested to ensure that they continue to work in such an event; see [Era Handling for the Japanese Calendar](/windows/desktop/Intl/era-handling-for-the-japanese-calendar).




Expand Down Expand Up @@ -827,15 +829,16 @@
<format type="text/markdown"><![CDATA[

## Remarks
The Japanese calendar recognizes one era for every emperor's reign. The current era is the Heisei era, which began in the Gregorian calendar year 1989. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen.
The Japanese calendar recognizes one era for every emperor's reign. The two most recent eras are the Heisei era, beginning in the Gregorian calendar year 1989, and the Reiwa era, beginning in the Gregorian calendar year 2019. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen.

[!INCLUDE[japanese-era-note](~/includes/calendar-era.md)]

This class assigns numbers to the eras as follows:

|GetEra value|Era Name|Era Abbreviation|Gregorian Dates|
|------------------|--------------|----------------------|---------------------|
|4|平成 (Heisei)|平 (H, h)|January 8, 1989 to present|
|5|令和 (Reiwa)|令和 (R, r)|May 1, 2019 to present|
|4|平成 (Heisei)|平 (H, h)|January 8, 1989 to April 30, 2019|
|3|昭和 (Showa)|昭 (S, s)|December 25, 1926 to January 7, 1989|
|2|大正 (Taisho)|大 (T, t)|July 30, 1912 to December 24, 1926|
|1|明治 (Meiji)|明 (M, m)|September 8, 1868 to July 29, 1912|
Expand Down Expand Up @@ -969,7 +972,7 @@
<format type="text/markdown"><![CDATA[

## Examples
The following code example displays the values of several components of a <xref:System.DateTime> in terms of the Japanese calendar.
The following example displays the values of several components of a <xref:System.DateTime> in terms of the Japanese calendar.

[!code-cpp[System.Globalization.JapaneseCalendar_AddGet#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar_AddGet/CPP/japanesecalendar_addget.cpp#1)]
[!code-csharp[System.Globalization.JapaneseCalendar_AddGet#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar_AddGet/CS/japanesecalendar_addget.cs#1)]
Expand Down Expand Up @@ -1036,11 +1039,11 @@
<format type="text/markdown"><![CDATA[

## Examples
The following code example calls <xref:System.Globalization.JapaneseCalendar.GetMonthsInYear%2A> for five years in each era.
The following example calls <xref:System.Globalization.JapaneseCalendar.GetMonthsInYear%2A> for the first five years in each era.

[!code-cpp[System.Globalization.JapaneseCalendar.GetMonthsInYear#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.GetMonthsInYear/CPP/japanesecalendar_getmonthsinyear.cpp#1)]
[!code-csharp[System.Globalization.JapaneseCalendar.GetMonthsInYear#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.GetMonthsInYear/CS/japanesecalendar_getmonthsinyear.cs#1)]
[!code-vb[System.Globalization.JapaneseCalendar.GetMonthsInYear#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.GetMonthsInYear/VB/japanesecalendar_getmonthsinyear.vb#1)]
[!code-cpp[System.Globalization.JapaneseCalendar.GetMonthsInYear#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.GetMonthsInYear/CPP/japanesecalendar_getmonthsinyear.cpp)]
[!code-csharp[System.Globalization.JapaneseCalendar.GetMonthsInYear#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.GetMonthsInYear/CS/japanesecalendar_getmonthsinyear.cs)]
[!code-vb[System.Globalization.JapaneseCalendar.GetMonthsInYear#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.GetMonthsInYear/VB/japanesecalendar_getmonthsinyear.vb)]

]]></format>
</remarks>
Expand Down Expand Up @@ -1262,9 +1265,9 @@
## Examples
The following example calls <xref:System.Globalization.JapaneseCalendar.IsLeapDay%2A> for the last day of the second month (February) for five years in each of the eras.

[!code-cpp[System.Globalization.JapaneseCalendar.IsLeapDay#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapDay/CPP/japanesecalendar_isleapday.cpp#1)]
[!code-csharp[System.Globalization.JapaneseCalendar.IsLeapDay#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapDay/CS/japanesecalendar_isleapday.cs#1)]
[!code-vb[System.Globalization.JapaneseCalendar.IsLeapDay#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapDay/VB/japanesecalendar_isleapday.vb#1)]
[!code-cpp[System.Globalization.JapaneseCalendar.IsLeapDay#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapDay/CPP/japanesecalendar_isleapday.cpp)]
[!code-csharp[System.Globalization.JapaneseCalendar.IsLeapDay#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapDay/CS/japanesecalendar_isleapday.cs)]
[!code-vb[System.Globalization.JapaneseCalendar.IsLeapDay#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapDay/VB/japanesecalendar_isleapday.vb)]

]]></format>
</remarks>
Expand Down Expand Up @@ -1345,7 +1348,7 @@


## Examples
The following example calls <xref:System.Globalization.JapaneseCalendar.IsLeapMonth%2A> for all the months in five years in the current era.
The following example calls <xref:System.Globalization.JapaneseCalendar.IsLeapMonth%2A> for all the months in the first five years in the current era.

[!code-cpp[System.Globalization.JapaneseCalendar.IsLeapMonth#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapMonth/CPP/japanesecalendar_isleapmonth.cpp#1)]
[!code-csharp[System.Globalization.JapaneseCalendar.IsLeapMonth#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapMonth/CS/japanesecalendar_isleapmonth.cs#1)]
Expand Down Expand Up @@ -1424,9 +1427,9 @@
## Examples
The following example calls <xref:System.Globalization.JapaneseCalendar.IsLeapYear%2A> for five years in each of the eras.

[!code-cpp[System.Globalization.JapaneseCalendar.IsLeapYear#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapYear/CPP/japanesecalendar_isleapyear.cpp#1)]
[!code-csharp[System.Globalization.JapaneseCalendar.IsLeapYear#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapYear/CS/japanesecalendar_isleapyear.cs#1)]
[!code-vb[System.Globalization.JapaneseCalendar.IsLeapYear#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapYear/VB/japanesecalendar_isleapyear.vb#1)]
[!code-cpp[System.Globalization.JapaneseCalendar.IsLeapYear#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapYear/CPP/japanesecalendar_isleapyear.cpp)]
[!code-csharp[System.Globalization.JapaneseCalendar.IsLeapYear#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapYear/CS/japanesecalendar_isleapyear.cs)]
[!code-vb[System.Globalization.JapaneseCalendar.IsLeapYear#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.IsLeapYear/VB/japanesecalendar_isleapyear.vb)]

]]></format>
</remarks>
Expand Down
Loading