diff --git a/includes/calendar-era.md b/includes/calendar-era.md index 7f890ad0235..ec55883eb7f 100644 --- a/includes/calendar-era.md +++ b/includes/calendar-era.md @@ -1,4 +1,3 @@ > [!IMPORTANT] -> A new era in the and 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. - +> Eras in the Japanese calendars are basaed on the emperor's reign and are therefore expected to change. For example, May 1, 2019 marked the beginning of the Reiwa era in the and . Such a change of era 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. diff --git a/xml/System.Globalization/Calendar.xml b/xml/System.Globalization/Calendar.xml index a7a56689f0b..c60015752c7 100644 --- a/xml/System.Globalization/Calendar.xml +++ b/xml/System.Globalization/Calendar.xml @@ -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 can map any date in the range of a specific calendar to a similar set of numeric values, and can map such sets of numeric values to a textual representation using information from and . 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. @@ -705,7 +705,7 @@ The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . - In all .NET Framework classes derived from the class, a week is defined as seven days. + In all .NET classes derived from the class, a week is defined as seven days. The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. @@ -861,7 +861,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in .NET and displays the value of its 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)] @@ -1059,8 +1059,10 @@ [!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] +The and classes support multiple eras. Most calendar implementations, on the other hand, support a single era. + ## Examples - The following code example displays the values contained in . + The following example displays the values contained in when the Heisei era (1989-2019) was the current era. [!code-cpp[System.Globalization.JapaneseCalendar.Eras#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.Eras/CPP/yslin_japanesecalendar_eras.cpp#1)] [!code-csharp[System.Globalization.JapaneseCalendar.Eras#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.Eras/CS/yslin_japanesecalendar_eras.cs#1)] @@ -1607,8 +1609,8 @@ The to read. - When overridden in a derived class, returns the era in the specified . - An integer that represents the era in . + When overridden in a derived class, returns the era of the specified . + An integer that represents the era of . [!NOTE] -> For information about using the 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 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)] @@ -58,7 +58,8 @@ |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| @@ -350,7 +351,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Class Library and displays the value of its 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)] @@ -399,7 +400,7 @@ [!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](/windows/desktop/Intl/era-handling-for-the-japanese-calendar). @@ -827,7 +829,7 @@ in terms of the Japanese calendar. + The following example displays the values of several components of a 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)] @@ -1036,11 +1039,11 @@ for five years in each era. + The following example calls for the first five years in each era. Because the class supports only 12-month years, it indicates that there are 12 months in each of the eras supported by the class. - [!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)] ]]> @@ -1257,14 +1260,13 @@ A leap day is a day that occurs only in a leap year. For example, the 29th day of Nigatsu (February) is the only leap day. - - -## Examples - The following example calls for the last day of the second month (February) for five years in each of the eras. +## Examples + +The following example calls for the last day of the second month (February) for five years in each of the eras. The current era in the example output is the Reiwa era. - [!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)] ]]> @@ -1342,10 +1344,8 @@ A leap month is an entire month that occurs only in a leap year. The Japanese calendar does not have any leap months. - - ## Examples - The following example calls for all the months in five years in the current era. + The following example calls 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)] @@ -1422,11 +1422,11 @@ ## Examples - The following example calls for five years in each of the eras. + The following example calls for five years in each of the eras. The current era in the example output is the Reiwa era. - [!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)] ]]> diff --git a/xml/System.Globalization/JapaneseLunisolarCalendar.xml b/xml/System.Globalization/JapaneseLunisolarCalendar.xml index 4237f2c3466..3da5dd835be 100644 --- a/xml/System.Globalization/JapaneseLunisolarCalendar.xml +++ b/xml/System.Globalization/JapaneseLunisolarCalendar.xml @@ -41,21 +41,22 @@ class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. + The class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. The method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. > [!NOTE] -> For information about using the 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 class and the other calendar classes in the .NET Class Library, see [Working with Calendars](~/docs/standard/datetime/working-with-calendars.md). - For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. - -The `JapaneseLuniSolarCalendar` class 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 `JapaneseLuniSolarCalendar` class recognizes one era for every emperor's reign. For example, 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)] +Unlike the class, the `JapaneseLunisolarCalendar` class does not support dates in the range of the Meiji and Taisho eras. + 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| @@ -191,6 +192,8 @@ The `JapaneseLuniSolarCalendar` class recognizes one era for every emperor's rei [!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] +While the defines the Meiji and Taisho eras (eras 1 and 2, respectively), the calendar does not support dates in their ranges. For example, a call to or with a date in those era ranges throws an . + The property returns the same values as the property. ]]>