Trabalhar com calendários
Embora um valor de data e hora representem um momento, sua representação de cadeia de caracteres depende da cultura e também das convenções usadas para exibir valores de data e hora por uma cultura específica e do calendário usado por essa cultura. Este tópico explora o suporte a calendários no .NET e discute o uso de classes de calendário ao trabalhar com valores de data.
Calendários no .NET
Todos os calendários no .NET derivam da classe System.Globalization.Calendar, a qual fornece a implementação do calendário base. Uma das classes que herda da classe Calendar é a classe EastAsianLunisolarCalendar, a qual é a classe base para todos os calendários lunissolares. O .NET inclui as seguintes implementações de calendários:
ChineseLunisolarCalendar, que representa o calendário lunissolar chinês.
GregorianCalendar, que representa o calendário gregoriano. Esse calendário é particionado em subtipos adicionais (como árabe e francês do Oriente Médio) que são definidos pela enumeração System.Globalization.GregorianCalendarTypes. A propriedade GregorianCalendar.CalendarType especifica o subtipo do calendário gregoriano.
HebrewCalendar, que representa o calendário hebraico.
HijriCalendar, que representa o calendário islâmico.
JapaneseCalendar, que representa o calendário japonês.
JapaneseLunisolarCalendar, que representa o calendário lunissolar japonês.
JulianCalendar, que representa o calendário juliano.
KoreanCalendar, que representa o calendário coreano.
KoreanLunisolarCalendar, que representa o calendário lunissolar coreano.
PersianCalendar, que representa o calendário persa.
TaiwanCalendar, que representa o calendário de Taiwan.
TaiwanLunisolarCalendar, que representa o calendário lunissolar de Taiwan.
ThaiBuddhistCalendar, que representa o calendário tailandês budista.
UmAlQuraCalendar, que representa o calendário Um Al Qura.
Um calendário pode ser usado em uma de duas formas:
Como o calendário usado por uma cultura específica. Cada objeto CultureInfo contém um calendário atual, que é o calendário que o objeto está usando no momento. As representações de cadeia de caracteres de todos os valores de data e hora refletem automaticamente a cultura e seu calendário atual. Normalmente, o calendário atual é o calendário padrão da cultura. Os objetos CultureInfo também possuem calendários opcionais, que incluem os calendários adicionais que a cultura pode usar.
Como calendário autônomo independente de uma cultura específica. Nesse caso, os métodos Calendar são usados para expressar datas como os valores que refletem o calendário.
Observe que seis classes de calendário – ChineseLunisolarCalendar, JapaneseLunisolarCalendar, JulianCalendar, KoreanLunisolarCalendar, PersianCalendar e TaiwanLunisolarCalendar – podem ser usadas apenas como calendários autônomos. Elas não são usadas por nenhuma cultura, seja como o calendário padrão ou como um calendário opcional.
Calendários e culturas
Cada cultura tem um calendário padrão, o qual é definido pela propriedade CultureInfo.Calendar. A propriedade CultureInfo.OptionalCalendars retorna uma matriz de objetos Calendar que especifica todos os calendários suportados por uma cultura específica, inclusive o calendário padrão da cultura.
O exemplo a seguir ilustra as propriedades CultureInfo.Calendar e CultureInfo.OptionalCalendars. Ele cria objetos CultureInfo para as culturas Tailandês (Tailândia) e Japonês (Japão) e exibe seus calendários padrão e opcionais. Observe que, em ambos os casos, o calendário padrão da cultura também é incluído na coleção CultureInfo.OptionalCalendars.
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
// Create a CultureInfo for Thai in Thailand.
CultureInfo th = CultureInfo.CreateSpecificCulture("th-TH");
DisplayCalendars(th);
// Create a CultureInfo for Japanese in Japan.
CultureInfo ja = CultureInfo.CreateSpecificCulture("ja-JP");
DisplayCalendars(ja);
}
static void DisplayCalendars(CultureInfo ci)
{
Console.WriteLine("Calendars for the {0} culture:", ci.Name);
// Get the culture's default calendar.
Calendar defaultCalendar = ci.Calendar;
Console.Write(" Default Calendar: {0}", GetCalendarName(defaultCalendar));
if (defaultCalendar is GregorianCalendar)
Console.WriteLine(" ({0})",
((GregorianCalendar) defaultCalendar).CalendarType);
else
Console.WriteLine();
// Get the culture's optional calendars.
Console.WriteLine(" Optional Calendars:");
foreach (var optionalCalendar in ci.OptionalCalendars) {
Console.Write("{0,6}{1}", "", GetCalendarName(optionalCalendar));
if (optionalCalendar is GregorianCalendar)
Console.Write(" ({0})",
((GregorianCalendar) optionalCalendar).CalendarType);
Console.WriteLine();
}
Console.WriteLine();
}
static string GetCalendarName(Calendar cal)
{
return cal.ToString().Replace("System.Globalization.", "");
}
}
// The example displays the following output:
// Calendars for the th-TH culture:
// Default Calendar: ThaiBuddhistCalendar
// Optional Calendars:
// ThaiBuddhistCalendar
// GregorianCalendar (Localized)
//
// Calendars for the ja-JP culture:
// Default Calendar: GregorianCalendar (Localized)
// Optional Calendars:
// GregorianCalendar (Localized)
// JapaneseCalendar
// GregorianCalendar (USEnglish)
Imports System.Globalization
Public Module Example
Public Sub Main()
' Create a CultureInfo for Thai in Thailand.
Dim th As CultureInfo = CultureInfo.CreateSpecificCulture("th-TH")
DisplayCalendars(th)
' Create a CultureInfo for Japanese in Japan.
Dim ja As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
DisplayCalendars(ja)
End Sub
Sub DisplayCalendars(ci As CultureInfo)
Console.WriteLine("Calendars for the {0} culture:", ci.Name)
' Get the culture's default calendar.
Dim defaultCalendar As Calendar = ci.Calendar
Console.Write(" Default Calendar: {0}", GetCalendarName(defaultCalendar))
If TypeOf defaultCalendar Is GregorianCalendar Then
Console.WriteLine(" ({0})",
CType(defaultCalendar, GregorianCalendar).CalendarType)
Else
Console.WriteLine()
End If
' Get the culture's optional calendars.
Console.WriteLine(" Optional Calendars:")
For Each optionalCalendar In ci.OptionalCalendars
Console.Write("{0,6}{1}", "", GetCalendarName(optionalCalendar))
If TypeOf optionalCalendar Is GregorianCalendar Then
Console.Write(" ({0})",
CType(optionalCalendar, GregorianCalendar).CalendarType)
End If
Console.WriteLine()
Next
Console.WriteLine()
End Sub
Function GetCalendarName(cal As Calendar) As String
Return cal.ToString().Replace("System.Globalization.", "")
End Function
End Module
' The example displays the following output:
' Calendars for the th-TH culture:
' Default Calendar: ThaiBuddhistCalendar
' Optional Calendars:
' ThaiBuddhistCalendar
' GregorianCalendar (Localized)
'
' Calendars for the ja-JP culture:
' Default Calendar: GregorianCalendar (Localized)
' Optional Calendars:
' GregorianCalendar (Localized)
' JapaneseCalendar
' GregorianCalendar (USEnglish)
O calendário em uso no momento por um objeto CultureInfo específico é definido pela propriedade DateTimeFormatInfo.Calendar da cultura. O objeto DateTimeFormatInfo de uma cultura é retornado pela propriedade CultureInfo.DateTimeFormat. Quando uma cultura é criada, o valor padrão é o mesmo valor da propriedade CultureInfo.Calendar. No entanto, você pode mudar o calendário atual da cultura para qualquer calendário contido na matriz retornada pela propriedade CultureInfo.OptionalCalendars. Se você tentar definir o calendário atual como um calendário que não está incluído no valor da propriedade CultureInfo.OptionalCalendars, uma ArgumentException será gerada.
O exemplo a seguir altera o calendário usado pela cultura Árabe (Arábia Saudita). Ele primeiro cria uma instância de um valor DateTime e o exibe usando a cultura atual – que, nesse caso, é Inglês (Estados Unidos) – e o calendário atual da cultura (que, nesse caso, é o calendário gregoriano). Em seguida, ele muda a cultura atual para Árabe (Arábia Saudita) e exibe a data usando seu calendário padrão Um Al Qura. Finalmente, ele chama o método CalendarExists para determinar se o calendário islâmico é suportado pela cultura Árabe (Arábia Saudita). Como o calendário é suportado, ele muda o calendário atual para Hijri e, novamente, exibe a data. Observe que, em cada caso, a data é exibida usando o calendário atual da cultura atual.
using System;
using System.Globalization;
using System.Threading;
public class Example
{
public static void Main()
{
DateTime date1 = new DateTime(2011, 6, 20);
DisplayCurrentInfo();
// Display the date using the current culture and calendar.
Console.WriteLine(date1.ToString("d"));
Console.WriteLine();
CultureInfo arSA = CultureInfo.CreateSpecificCulture("ar-SA");
// Change the current culture to Arabic (Saudi Arabia).
Thread.CurrentThread.CurrentCulture = arSA;
// Display date and information about the current culture.
DisplayCurrentInfo();
Console.WriteLine(date1.ToString("d"));
Console.WriteLine();
// Change the calendar to Hijri.
Calendar hijri = new HijriCalendar();
if (CalendarExists(arSA, hijri)) {
arSA.DateTimeFormat.Calendar = hijri;
// Display date and information about the current culture.
DisplayCurrentInfo();
Console.WriteLine(date1.ToString("d"));
}
}
private static void DisplayCurrentInfo()
{
Console.WriteLine("Current Culture: {0}",
CultureInfo.CurrentCulture.Name);
Console.WriteLine("Current Calendar: {0}",
DateTimeFormatInfo.CurrentInfo.Calendar);
}
private static bool CalendarExists(CultureInfo culture, Calendar cal)
{
foreach (Calendar optionalCalendar in culture.OptionalCalendars)
if (cal.ToString().Equals(optionalCalendar.ToString()))
return true;
return false;
}
}
// The example displays the following output:
// Current Culture: en-US
// Current Calendar: System.Globalization.GregorianCalendar
// 6/20/2011
//
// Current Culture: ar-SA
// Current Calendar: System.Globalization.UmAlQuraCalendar
// 18/07/32
//
// Current Culture: ar-SA
// Current Calendar: System.Globalization.HijriCalendar
// 19/07/32
Imports System.Globalization
Imports System.Threading
Module Example
Public Sub Main()
Dim date1 As Date = #6/20/2011#
DisplayCurrentInfo()
' Display the date using the current culture and calendar.
Console.WriteLine(date1.ToString("d"))
Console.WriteLine()
Dim arSA As CultureInfo = CultureInfo.CreateSpecificCulture("ar-SA")
' Change the current culture to Arabic (Saudi Arabia).
Thread.CurrentThread.CurrentCulture = arSA
' Display date and information about the current culture.
DisplayCurrentInfo()
Console.WriteLine(date1.ToString("d"))
Console.WriteLine()
' Change the calendar to Hijri.
Dim hijri As Calendar = New HijriCalendar()
If CalendarExists(arSA, hijri) Then
arSA.DateTimeFormat.Calendar = hijri
' Display date and information about the current culture.
DisplayCurrentInfo()
Console.WriteLine(date1.ToString("d"))
End If
End Sub
Private Sub DisplayCurrentInfo()
Console.WriteLine("Current Culture: {0}",
CultureInfo.CurrentCulture.Name)
Console.WriteLine("Current Calendar: {0}",
DateTimeFormatInfo.CurrentInfo.Calendar)
End Sub
Private Function CalendarExists(ByVal culture As CultureInfo,
cal As Calendar) As Boolean
For Each optionalCalendar As Calendar In culture.OptionalCalendars
If cal.ToString().Equals(optionalCalendar.ToString()) Then Return True
Next
Return False
End Function
End Module
' The example displays the following output:
' Current Culture: en-US
' Current Calendar: System.Globalization.GregorianCalendar
' 6/20/2011
'
' Current Culture: ar-SA
' Current Calendar: System.Globalization.UmAlQuraCalendar
' 18/07/32
'
' Current Culture: ar-SA
' Current Calendar: System.Globalization.HijriCalendar
' 19/07/32
Datas e calendários
Com exceção dos construtores que incluem um parâmetro de tipo Calendar e permitem que os elementos de uma data (ou seja, mês, dia e ano), reflitam valores em um calendário designado, os valores de DateTime e DateTimeOffset sempre são baseados no calendário gregoriano. Isso significa, por exemplo, que a propriedade DateTime.Year retorna o ano no calendário gregoriano e que a propriedade DateTime.Day retorna o dia do mês no calendário gregoriano.
Importante
É importante lembrar que há uma diferença entre um valor de data e sua representação de cadeia de caracteres. O primeiro baseia-se no calendário gregoriano; o último baseia-se no calendário atual de uma determinada cultura.
O exemplo a seguir ilustra a diferença entre as propriedades DateTime e seus métodos Calendar correspondentes. No exemplo, a cultura atual é Árabe (Egito), e o calendário atual é Um Al Qura. Um valor de DateTime é definido como o décimo quinto dia do sétimo mês de 2011. Está claro que esse é interpretado como uma data gregoriana, pois esses mesmos valores são retornados pelo método DateTime.ToString(String, IFormatProvider) quando as convenções da cultura invariável são usadas. A representação de cadeia de caracteres da data que é formatada usando as convenções de cultura atual é 14/08/32, que é a data equivalente no calendário Um Al Qura. Em seguida, membros de DateTime e Calendar são usados para retornar o dia, mês e o ano do valor de DateTime. Em cada caso, os valores retornados pelos membros de DateTime refletem os valores do calendário gregoriano, enquanto que os valores retornados pelos membros de UmAlQuraCalendar refletem os valores do calendário Um Al Qura.
using System;
using System.Globalization;
using System.Threading;
public class Example
{
public static void Main()
{
// Make Arabic (Egypt) the current culture
// and Umm al-Qura calendar the current calendar.
CultureInfo arEG = CultureInfo.CreateSpecificCulture("ar-EG");
Calendar cal = new UmAlQuraCalendar();
arEG.DateTimeFormat.Calendar = cal;
Thread.CurrentThread.CurrentCulture = arEG;
// Display information on current culture and calendar.
DisplayCurrentInfo();
// Instantiate a date object.
DateTime date1 = new DateTime(2011, 7, 15);
// Display the string representation of the date.
Console.WriteLine("Date: {0:d}", date1);
Console.WriteLine("Date in the Invariant Culture: {0}",
date1.ToString("d", CultureInfo.InvariantCulture));
Console.WriteLine();
// Compare DateTime properties and Calendar methods.
Console.WriteLine("DateTime.Month property: {0}", date1.Month);
Console.WriteLine("UmAlQura.GetMonth: {0}",
cal.GetMonth(date1));
Console.WriteLine();
Console.WriteLine("DateTime.Day property: {0}", date1.Day);
Console.WriteLine("UmAlQura.GetDayOfMonth: {0}",
cal.GetDayOfMonth(date1));
Console.WriteLine();
Console.WriteLine("DateTime.Year property: {0:D4}", date1.Year);
Console.WriteLine("UmAlQura.GetYear: {0}",
cal.GetYear(date1));
Console.WriteLine();
}
private static void DisplayCurrentInfo()
{
Console.WriteLine("Current Culture: {0}",
CultureInfo.CurrentCulture.Name);
Console.WriteLine("Current Calendar: {0}",
DateTimeFormatInfo.CurrentInfo.Calendar);
}
}
// The example displays the following output:
// Current Culture: ar-EG
// Current Calendar: System.Globalization.UmAlQuraCalendar
// Date: 14/08/32
// Date in the Invariant Culture: 07/15/2011
//
// DateTime.Month property: 7
// UmAlQura.GetMonth: 8
//
// DateTime.Day property: 15
// UmAlQura.GetDayOfMonth: 14
//
// DateTime.Year property: 2011
// UmAlQura.GetYear: 1432
Imports System.Globalization
Imports System.Threading
Module Example
Public Sub Main()
' Make Arabic (Egypt) the current culture
' and Umm al-Qura calendar the current calendar.
Dim arEG As CultureInfo = CultureInfo.CreateSpecificCulture("ar-EG")
Dim cal As Calendar = New UmAlQuraCalendar()
arEG.DateTimeFormat.Calendar = cal
Thread.CurrentThread.CurrentCulture = arEG
' Display information on current culture and calendar.
DisplayCurrentInfo()
' Instantiate a date object.
Dim date1 As Date = #07/15/2011#
' Display the string representation of the date.
Console.WriteLine("Date: {0:d}", date1)
Console.WriteLine("Date in the Invariant Culture: {0}",
date1.ToString("d", CultureInfo.InvariantCulture))
Console.WriteLine()
' Compare DateTime properties and Calendar methods.
Console.WriteLine("DateTime.Month property: {0}", date1.Month)
Console.WriteLine("UmAlQura.GetMonth: {0}",
cal.GetMonth(date1))
Console.WriteLine()
Console.WriteLine("DateTime.Day property: {0}", date1.Day)
Console.WriteLine("UmAlQura.GetDayOfMonth: {0}",
cal.GetDayOfMonth(date1))
Console.WriteLine()
Console.WriteLine("DateTime.Year property: {0:D4}", date1.Year)
Console.WriteLine("UmAlQura.GetYear: {0}",
cal.GetYear(date1))
Console.WriteLine()
End Sub
Private Sub DisplayCurrentInfo()
Console.WriteLine("Current Culture: {0}",
CultureInfo.CurrentCulture.Name)
Console.WriteLine("Current Calendar: {0}",
DateTimeFormatInfo.CurrentInfo.Calendar)
End Sub
End Module
' The example displays the following output:
' Current Culture: ar-EG
' Current Calendar: System.Globalization.UmAlQuraCalendar
' Date: 14/08/32
' Date in the Invariant Culture: 07/15/2011
'
' DateTime.Month property: 7
' UmAlQura.GetMonth: 8
'
' DateTime.Day property: 15
' UmAlQura.GetDayOfMonth: 14
'
' DateTime.Year property: 2011
' UmAlQura.GetYear: 1432
Criar uma instância de datas com base em um calendário
Como os valores DateTime e DateTimeOffset baseiam-se no calendário gregoriano, você deve chamar um construtor sobrecarregado que inclua um parâmetro do tipo Calendar para criar uma instância de um valor de data se você quiser usar os valores de dia, mês ou ano em um calendário diferente. Você também pode chamar uma das sobrecargas do método Calendar.ToDateTime de um calendário específico para criar uma instância de um objeto DateTime com base nos valores de um calendário específico.
O exemplo a seguir cria uma instância de um valor de DateTime ao passar um objeto HebrewCalendar para um construtor de DateTime e cria uma instância de um segundo valor DateTime ao chamar o método HebrewCalendar.ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32). Como os dois valores são criados com valores idênticos do calendário hebraico, a chamada ao método DateTime.Equals mostra que os dois valores de DateTime são iguais.
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
HebrewCalendar hc = new HebrewCalendar();
DateTime date1 = new DateTime(5771, 6, 1, hc);
DateTime date2 = hc.ToDateTime(5771, 6, 1, 0, 0, 0, 0);
Console.WriteLine("{0:d} (Gregorian) = {1:d2}/{2:d2}/{3:d4} ({4}): {5}",
date1,
hc.GetMonth(date2),
hc.GetDayOfMonth(date2),
hc.GetYear(date2),
GetCalendarName(hc),
date1.Equals(date2));
}
private static string GetCalendarName(Calendar cal)
{
return cal.ToString().Replace("System.Globalization.", "").
Replace("Calendar", "");
}
}
// The example displays the following output:
// 2/5/2011 (Gregorian) = 06/01/5771 (Hebrew): True
Imports System.Globalization
Module Example
Public Sub Main()
Dim hc As New HebrewCalendar()
Dim date1 As New Date(5771, 6, 1, hc)
Dim date2 As Date = hc.ToDateTime(5771, 6, 1, 0, 0, 0, 0)
Console.WriteLine("{0:d} (Gregorian) = {1:d2}/{2:d2}/{3:d4} ({4}): {5}",
date1,
hc.GetMonth(date2),
hc.GetDayOfMonth(date2),
hc.GetYear(date2),
GetCalendarName(hc),
date1.Equals(date2))
End Sub
Private Function GetCalendarName(cal As Calendar) As String
Return cal.ToString().Replace("System.Globalization.", "").
Replace("Calendar", "")
End Function
End Module
' The example displays the following output:
' 2/5/2011 (Gregorian) = 06/01/5771 (Hebrew): True
Representar datas no calendário atual
Os métodos de formatação de data e hora sempre usam o calendário atual ao converter datas em cadeias de caracteres. Isso significa que a representação de cadeia de caracteres do ano, mês e dia do mês reflete o calendário atual, e não necessariamente o calendário gregoriano.
O exemplo a seguir mostra como o calendário atual afeta a representação de cadeia de caracteres de uma data. Ele muda a cultura atual de Chinês (Tradicional, Taiwan) e cria uma instância de um valor de data. Ele então exibe o calendário e a data atuais, altera o calendário atual para TaiwanCalendar e exibe o calendário e a data atuais mais uma vez. Na primeira vez que a data é exibida, ela é representada como uma data no calendário gregoriano. Na segunda vez que a data é exibida, ela é representada como uma data no calendário de Taiwan.
using System;
using System.Globalization;
using System.Threading;
public class Example
{
public static void Main()
{
// Change the current culture to zh-TW.
CultureInfo zhTW = CultureInfo.CreateSpecificCulture("zh-TW");
Thread.CurrentThread.CurrentCulture = zhTW;
// Define a date.
DateTime date1 = new DateTime(2011, 1, 16);
// Display the date using the default (Gregorian) calendar.
Console.WriteLine("Current calendar: {0}",
zhTW.DateTimeFormat.Calendar);
Console.WriteLine(date1.ToString("d"));
// Change the current calendar and display the date.
zhTW.DateTimeFormat.Calendar = new TaiwanCalendar();
Console.WriteLine("Current calendar: {0}",
zhTW.DateTimeFormat.Calendar);
Console.WriteLine(date1.ToString("d"));
}
}
// The example displays the following output:
// Current calendar: System.Globalization.GregorianCalendar
// 2011/1/16
// Current calendar: System.Globalization.TaiwanCalendar
// 100/1/16
Imports System.Globalization
Imports System.Threading
Module Example
Public Sub Main()
' Change the current culture to zh-TW.
Dim zhTW As CultureInfo = CultureInfo.CreateSpecificCulture("zh-TW")
Thread.CurrentThread.CurrentCulture = zhTW
' Define a date.
Dim date1 As Date = #1/16/2011#
' Display the date using the default (Gregorian) calendar.
Console.WriteLine("Current calendar: {0}",
zhTW.DateTimeFormat.Calendar)
Console.WriteLine(date1.ToString("d"))
' Change the current calendar and display the date.
zhTW.DateTimeFormat.Calendar = New TaiwanCalendar()
Console.WriteLine("Current calendar: {0}",
zhTW.DateTimeFormat.Calendar)
Console.WriteLine(date1.ToString("d"))
End Sub
End Module
' The example displays the following output:
' Current calendar: System.Globalization.GregorianCalendar
' 2011/1/16
' Current calendar: System.Globalization.TaiwanCalendar
' 100/1/16
Representar datas em um calendário diferente do atual
Para representar uma data usando um calendário que não é o calendário atual de uma cultura específica, você deve chamar métodos do objeto Calendar. Por exemplo, os métodos Calendar.GetYear, Calendar.GetMonth e Calendar.GetDayOfMonth convertem o ano, o mês e o dia para valores que refletem um calendário específico.
Aviso
Como alguns calendários são calendários não opcionais de qualquer cultura, representar datas nesses calendários sempre exige que você chame métodos de calendário. Isso é verdadeiro para todos os calendários que derivam das classes EastAsianLunisolarCalendar, de JulianCalendar e PersianCalendar.
O exemplo a seguir usa um objeto JulianCalendar para criar uma instância de uma data, 9 de janeiro de 1905, no calendário juliano. Quando essa data é exibida no calendário gregoriano (padrão), ela é representada como 22 de janeiro de 1905. Chamadas para métodos JulianCalendar individuais permitem que a data seja representada no calendário juliano.
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
JulianCalendar julian = new JulianCalendar();
DateTime date1 = new DateTime(1905, 1, 9, julian);
Console.WriteLine("Date ({0}): {1:d}",
CultureInfo.CurrentCulture.Calendar,
date1);
Console.WriteLine("Date in Julian calendar: {0:d2}/{1:d2}/{2:d4}",
julian.GetMonth(date1),
julian.GetDayOfMonth(date1),
julian.GetYear(date1));
}
}
// The example displays the following output:
// Date (System.Globalization.GregorianCalendar): 1/22/1905
// Date in Julian calendar: 01/09/1905
Imports System.Globalization
Module Example
Public Sub Main()
Dim julian As New JulianCalendar()
Dim date1 As New Date(1905, 1, 9, julian)
Console.WriteLine("Date ({0}): {1:d}",
CultureInfo.CurrentCulture.Calendar,
date1)
Console.WriteLine("Date in Julian calendar: {0:d2}/{1:d2}/{2:d4}",
julian.GetMonth(date1),
julian.GetDayOfMonth(date1),
julian.GetYear(date1))
End Sub
End Module
' The example displays the following output:
' Date (System.Globalization.GregorianCalendar): 1/22/1905
' Date in Julian calendar: 01/09/1905
Calendários e intervalos de datas
A data mais antiga suportada por um calendário é indicada pela propriedade Calendar.MinSupportedDateTime desse calendário. Para a classe GregorianCalendar, essa data é 1º de janeiro de 0001. C.E. A maioria dos outros calendários no .NET dá suporte a uma data posterior. Tentar trabalhar com um valor de data e hora que antecedem a data com suporte mais antiga de um calendário gerará uma exceção ArgumentOutOfRangeException.
Porém, há uma exceção importante. O valor padrão (não inicializado) de um objeto DateTime e um objeto DateTimeOffset é igual ao valor de GregorianCalendar.MinSupportedDateTime. Se você tentar formatar essa data em um calendário que não ofereça suporte a 1º de janeiro de 0001. C.E e não fornecer um especificador de formato, o método de formatação usará o especificador de formato “s” (padrão de data/hora classificável) em vez do especificador de formato “G” (padrão geral de data/hora). Como resultado, a operação de formatação não gerará uma exceção ArgumentOutOfRangeException. Em vez disso, retornará uma data sem suporte. Isso é ilustrado no exemplo a seguir, que exibe o valor de DateTime.MinValue quando a cultura atual é configurada para Japonês (Japão) com o calendário japonês, e para Árabe (Egito) com o calendário Um Al Qura. Ela também define a cultura atual como Inglês (Estados Unidos) e chama o método DateTime.ToString(IFormatProvider) com cada um desses objetos CultureInfo. Em cada caso, a data é exibida usando o padrão classificável de data/hora.
using System;
using System.Globalization;
using System.Threading;
public class Example
{
public static void Main()
{
DateTime dat = DateTime.MinValue;
// Change the current culture to ja-JP with the Japanese Calendar.
CultureInfo jaJP = CultureInfo.CreateSpecificCulture("ja-JP");
jaJP.DateTimeFormat.Calendar = new JapaneseCalendar();
Thread.CurrentThread.CurrentCulture = jaJP;
Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
jaJP.DateTimeFormat.Calendar.MinSupportedDateTime,
GetCalendarName(jaJP));
// Attempt to display the date.
Console.WriteLine(dat.ToString());
Console.WriteLine();
// Change the current culture to ar-EG with the Um Al Qura calendar.
CultureInfo arEG = CultureInfo.CreateSpecificCulture("ar-EG");
arEG.DateTimeFormat.Calendar = new UmAlQuraCalendar();
Thread.CurrentThread.CurrentCulture = arEG;
Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
arEG.DateTimeFormat.Calendar.MinSupportedDateTime,
GetCalendarName(arEG));
// Attempt to display the date.
Console.WriteLine(dat.ToString());
Console.WriteLine();
// Change the current culture to en-US.
Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("en-US");
Console.WriteLine(dat.ToString(jaJP));
Console.WriteLine(dat.ToString(arEG));
Console.WriteLine(dat.ToString("d"));
}
private static string GetCalendarName(CultureInfo culture)
{
Calendar cal = culture.DateTimeFormat.Calendar;
return cal.GetType().Name.Replace("System.Globalization.", "").Replace("Calendar", "");
}
}
// The example displays the following output:
// Earliest supported date by Japanese calendar: 明治 1/9/8
// 0001-01-01T00:00:00
//
// Earliest supported date by UmAlQura calendar: 01/01/18
// 0001-01-01T00:00:00
//
// 0001-01-01T00:00:00
// 0001-01-01T00:00:00
// 1/1/0001
Imports System.Globalization
Imports System.Threading
Module Example
Public Sub Main()
Dim dat As Date = DateTime.MinValue
' Change the current culture to ja-JP with the Japanese Calendar.
Dim jaJP As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
jaJP.DateTimeFormat.Calendar = New JapaneseCalendar()
Thread.CurrentThread.CurrentCulture = jaJP
Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
jaJP.DateTimeFormat.Calendar.MinSupportedDateTime,
GetCalendarName(jaJP))
' Attempt to display the date.
Console.WriteLine(dat.ToString())
Console.WriteLine()
' Change the current culture to ar-EG with the Um Al Qura calendar.
Dim arEG As CultureInfo = CultureInfo.CreateSpecificCulture("ar-EG")
arEG.DateTimeFormat.Calendar = New UmAlQuraCalendar()
Thread.CurrentThread.CurrentCulture = arEG
Console.WriteLine("Earliest supported date by {1} calendar: {0:d}",
arEG.DateTimeFormat.Calendar.MinSupportedDateTime,
GetCalendarName(arEG))
' Attempt to display the date.
Console.WRiteLine(dat.ToString())
Console.WRiteLine()
' Change the current culture to en-US.
Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("en-US")
Console.WriteLine(dat.ToString(jaJP))
Console.WriteLine(dat.ToString(arEG))
Console.WriteLine(dat.ToString("d"))
End Sub
Private Function GetCalendarName(culture As CultureInfo) As String
Dim cal As Calendar = culture.DateTimeFormat.Calendar
Return cal.GetType().Name.Replace("System.Globalization.", "").Replace("Calendar", "")
End Function
End Module
' The example displays the following output:
' Earliest supported date by Japanese calendar: 明治 1/9/8
' 0001-01-01T00:00:00
'
' Earliest supported date by UmAlQura calendar: 01/01/18
' 0001-01-01T00:00:00
'
' 0001-01-01T00:00:00
' 0001-01-01T00:00:00
' 1/1/0001
Trabalhar com eras
Os calendários normalmente dividem as datas em eras. No entanto, as classes Calendar no .NET não oferecem suporte a cada era definida por um calendário, e a maioria das classes Calendar oferecem suporte a uma única era. Somente as classes JapaneseCalendar e JapaneseLunisolarCalendar oferecem suporte a várias eras.
Importante
A era Reiwa, uma nove era no JapaneseCalendar e no JapaneseLunisolarCalendar começa em 1º de maio de 2019. Essa alteração afeta todos os aplicativos que usam esses calendários. Confira os artigos a seguir para saber mais:
- Tratamento de uma nova era no calendário japonês no .NET, que documenta recursos adicionados ao .NET para dar suporte a calendários com várias eras e discute as práticas recomendadas a serem usadas ao tratar calendários de várias eras.
- Preparar seu aplicativo para a mudança de era no calendário japonês, que fornece informações sobre como testar seus aplicativos no Windows para assegurar que eles estejam preparados para a alteração de era.
- Resumo das novas atualizações da era japonesa no .NET Framework, que lista as atualizações no .NET Framework para versões individuais do Windows relacionadas à nova era do calendário japonês, observa novos recursos do .NET Framework para suporte de várias eras e inclui itens a serem buscados no teste de seus aplicativos.
Uma era na maioria dos calendários indica um período de tempo extremamente longo. No calendário gregoriano, por exemplo, a era atual abrange mais de dois milênios. Isso não ocorre em JapaneseCalendar e JapaneseLunisolarCalendar, os dois calendários que dão suporte a várias eras. Uma era corresponde ao período do reinado de um imperador. O suporte a várias eras, especialmente quando o limite superior da era atual é desconhecido, apresenta desafios especiais.
Eras e nomes de eras
No .NET, inteiros que representam as eras com suporte em uma implementação específica do calendário são armazenadas em ordem inversa na matriz Calendar.Eras. A era atual (que é a era com o intervalo de tempo mais recente) está no índice zero. Para classes Calendar que oferecem suporte a várias eras, cada índice sucessivo reflete a era anterior. A propriedade estática Calendar.CurrentEra define o índice de era atual na matriz Calendar.Eras ; ela é uma constante cujo valor é sempre zero. As classes Calendar individuais também incluem os campos estáticos que retornam o valor da era atual. Elas são listadas na tabela a seguir.
O nome que corresponde a um número de era específico não pode ser recuperado com a passagem do número da era para o método DateTimeFormatInfo.GetEraName ou DateTimeFormatInfo.GetAbbreviatedEraName. O exemplo a seguir chama esses métodos para recuperar informações sobre o suporte a eras na classe GregorianCalendar. Exibe a data do calendário gregoriano que corresponde a 1º de janeiro do segundo ano da era atual, bem como a data do calendário gregoriano que corresponde a 1º de janeiro do segundo ano de cada era do calendário japonês com suporte.
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
int year = 2;
int month = 1;
int day = 1;
Calendar cal = new JapaneseCalendar();
Console.WriteLine("\nDate instantiated without an era:");
DateTime date1 = new DateTime(year, month, day, 0, 0, 0, 0, cal);
Console.WriteLine("{0}/{1}/{2} in Japanese Calendar -> {3:d} in Gregorian",
cal.GetMonth(date1), cal.GetDayOfMonth(date1),
cal.GetYear(date1), date1);
Console.WriteLine("\nDates instantiated with eras:");
foreach (int era in cal.Eras) {
DateTime date2 = cal.ToDateTime(year, month, day, 0, 0, 0, 0, era);
Console.WriteLine("{0}/{1}/{2} era {3} in Japanese Calendar -> {4:d} in Gregorian",
cal.GetMonth(date2), cal.GetDayOfMonth(date2),
cal.GetYear(date2), cal.GetEra(date2), date2);
}
}
}
Imports System.Globalization
Module Example
Public Sub Main()
Dim year As Integer = 2
Dim month As Integer = 1
Dim day As Integer = 1
Dim cal As New JapaneseCalendar()
Console.WriteLine("Date instantiated without an era:")
Dim date1 As New Date(year, month, day, 0, 0, 0, 0, cal)
Console.WriteLine("{0}/{1}/{2} in Japanese Calendar -> {3:d} in Gregorian",
cal.GetMonth(date1), cal.GetDayOfMonth(date1),
cal.GetYear(date1), date1)
Console.WriteLine()
Console.WriteLine("Dates instantiated with eras:")
For Each era As Integer In cal.Eras
Dim date2 As Date = cal.ToDateTime(year, month, day, 0, 0, 0, 0, era)
Console.WriteLine("{0}/{1}/{2} era {3} in Japanese Calendar -> {4:d} in Gregorian",
cal.GetMonth(date2), cal.GetDayOfMonth(date2),
cal.GetYear(date2), cal.GetEra(date2), date2)
Next
End Sub
End Module
Além disso, a cadeia de caracteres de formato de data e hora personalizado "g" inclui o nome da era na representação de cadeia de caracteres de uma data e hora. Para obter mais informações, consulte Cadeias de caracteres personalizadas de formato data e hora.
Criar uma instância de uma data com uma era
Para as duas classes Calendar que oferecem suporte a várias eras, uma data que consiste em um determinado valor de ano, mês, dia e dia do mês pode ser ambígua. Por exemplo, todas as quatro eras do JapaneseCalendar têm os anos numerados como 1. Normalmente, se uma era não é especificada, os métodos de data e hora e calendário assumem que os valores pertencem à era atual. Isso se aplica aos construtores DateTime e DateTimeOffset que incluem parâmetros do tipo Calendar, bem como aos métodos JapaneseCalendar.ToDateTime e JapaneseLunisolarCalendar.ToDateTime. O exemplo a seguir cria uma data que representa 1º de janeiro do segundo ano de uma era não especificada. Se você executar o exemplo quando a era Reiwa for a era atual, a data será interpretada como o segundo ano da era Reiwa. A era, 令和, precede o ano na cadeia de caracteres retornada pelo método DateTime.ToString(String, IFormatProvider) e corresponde a 1º de janeiro de 2020, no calendário gregoriano. (A era Reiwa começa no ano de 2019 do calendário gregoriano.)
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
var japaneseCal = new JapaneseCalendar();
var jaJp = new CultureInfo("ja-JP");
jaJp.DateTimeFormat.Calendar = japaneseCal;
var date = new DateTime(2, 1, 1, japaneseCal);
Console.WriteLine($"Gregorian calendar date: {date:d}");
Console.WriteLine($"Japanese calendar date: {date.ToString("d", jaJp)}");
}
}
Imports System.Globalization
Public Module Example
Public Sub Main()
Dim japaneseCal = New JapaneseCalendar()
Dim jaJp = New CultureInfo("ja-JP")
jaJp.DateTimeFormat.Calendar = japaneseCal
Dim dat = New DateTime(2, 1, 1, japaneseCal)
Console.WriteLine($"Gregorian calendar dat: {dat:d}")
Console.WriteLine($"Japanese calendar dat: {dat.ToString("d", jaJp)}")
End Sub
End Module
No entanto, se a era for alterada, a intenção desse código se tornará ambígua. A data destina-se a representar o segundo ano da era atual ou o segundo ano da era Heisei? Há duas formas de evitar essa ambiguidade:
Crie uma instância do valor de data e hora usando a classe padrão GregorianCalendar. Em seguida, você pode usar o calendário japonês ou o calendário lunissolar japonês para representação da cadeia de caracteres de datas, como mostra o exemplo a seguir.
using System; using System.Globalization; public class Example { public static void Main() { var japaneseCal = new JapaneseCalendar(); var jaJp = new CultureInfo("ja-JP"); jaJp.DateTimeFormat.Calendar = japaneseCal; var date = new DateTime(1905, 2, 12); Console.WriteLine($"Gregorian calendar date: {date:d}"); // Call the ToString(IFormatProvider) method. Console.WriteLine($"Japanese calendar date: {date.ToString("d", jaJp)}"); // Use a FormattableString object. FormattableString fmt = $"{date:d}"; Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}"); // Use the JapaneseCalendar object. Console.WriteLine($"Japanese calendar date: {jaJp.DateTimeFormat.GetEraName(japaneseCal.GetEra(date))}" + $"{japaneseCal.GetYear(date)}/{japaneseCal.GetMonth(date)}/{japaneseCal.GetDayOfMonth(date)}"); // Use the current culture. CultureInfo.CurrentCulture = jaJp; Console.WriteLine($"Japanese calendar date: {date:d}"); } } // The example displays the following output: // Gregorian calendar date: 2/12/1905 // Japanese calendar date: 明治38/2/12 // Japanese calendar date: 明治38/2/12 // Japanese calendar date: 明治38/2/12 // Japanese calendar date: 明治38/2/12Imports System.Globalization Public Module Example Public Sub Main() Dim japaneseCal = New JapaneseCalendar() Dim jaJp = New CultureInfo("ja-JP") jaJp.DateTimeFormat.Calendar = japaneseCal Dim dat = New DateTime(1905, 2, 12) Console.WriteLine($"Gregorian calendar date: {dat:d}") ' Call the ToString(IFormatProvider) method. Console.WriteLine($"Japanese calendar date: {dat.ToString("d", jaJp)}") ' Use a FormattableString object. Dim fmt As FormattableString = $"{dat:d}" Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}") ' Use the JapaneseCalendar object. Console.WriteLine($"Japanese calendar date: {jaJp.DateTimeFormat.GetEraName(japaneseCal.GetEra(dat))}" + $"{japaneseCal.GetYear(dat)}/{japaneseCal.GetMonth(dat)}/{japaneseCal.GetDayOfMonth(dat)}") ' Use the current culture. CultureInfo.CurrentCulture = jaJp Console.WriteLine($"Japanese calendar date: {dat:d}") End Sub End Module ' The example displays the following output: ' Gregorian calendar date: 2/12/1905 ' Japanese calendar date: 明治38/2/12 ' Japanese calendar date: 明治38/2/12 ' Japanese calendar date: 明治38/2/12 ' Japanese calendar date: 明治38/2/12Chame um método de data e hora que especifique explicitamente uma era. Entre elas estão os seguintes métodos:
O método ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32) da classe JapaneseCalendar ou JapaneseLunisolarCalendar.
Um método de análise DateTime ou DateTimeOffset, como Parse, TryParse, ParseExact ou TryParseExact, que inclui a cadeia de caracteres a ser analisada e, opcionalmente, um argumento DateTimeStyles se a cultura atual for Japonesa - Japão ("ja-JP") e o calendário dessa cultura é JapaneseCalendar. A cadeia de caracteres a ser analisada deve incluir a era.
Um método de análise DateTime ou DateTimeOffset que inclui um parâmetro
providerdo tipo IFormatProvider.providerdeve ser um objeto CultureInfo que representa a cultura Japonesa - Japão ("ja-JP") cujo calendário atual é JapaneseCalendar ou um objeto DateTimeFormatInfo cuja propriedade Calendar é JapaneseCalendar. A cadeia de caracteres a ser analisada deve incluir a era.
O exemplo a seguir usa três desses métodos para criar uma instância de data e hora na era Meiji, que começou em 8 de setembro de 1868 e terminou em 29 de julho de 1912.
using System; using System.Globalization; public class Example { public static void Main() { var japaneseCal = new JapaneseCalendar(); var jaJp = new CultureInfo("ja-JP"); jaJp.DateTimeFormat.Calendar = japaneseCal; // We can get the era index by calling DateTimeFormatInfo.GetEraName. int eraIndex = 0; for (int ctr = 0; ctr < jaJp.DateTimeFormat.Calendar.Eras.Length; ctr++) if (jaJp.DateTimeFormat.GetEraName(ctr) == "明治") eraIndex = ctr; var date1 = japaneseCal.ToDateTime(23, 9, 8, 0, 0, 0, 0, eraIndex); Console.WriteLine($"{date1.ToString("d", jaJp)} (Gregorian {date1:d})"); try { var date2 = DateTime.Parse("明治23/9/8", jaJp); Console.WriteLine($"{date2.ToString("d", jaJp)} (Gregorian {date2:d})"); } catch (FormatException) { Console.WriteLine("The parsing operation failed."); } try { var date3 = DateTime.ParseExact("明治23/9/8", "gyy/M/d", jaJp); Console.WriteLine($"{date3.ToString("d", jaJp)} (Gregorian {date3:d})"); } catch (FormatException) { Console.WriteLine("The parsing operation failed."); } } } // The example displays the following output: // 明治23/9/8 (Gregorian 9/8/1890) // 明治23/9/8 (Gregorian 9/8/1890) // 明治23/9/8 (Gregorian 9/8/1890)Imports System.Globalization Public Module Example Public Sub Main() Dim japaneseCal = New JapaneseCalendar() Dim jaJp = New CultureInfo("ja-JP") jaJp.DateTimeFormat.Calendar = japaneseCal ' We can get the era index by calling DateTimeFormatInfo.GetEraName. Dim eraIndex As Integer = 0 For ctr As Integer = 0 To jaJp.DateTimeFormat.Calendar.Eras.Length - 1 If jaJp.DateTimeFormat.GetEraName(ctr) = "明治" Then eraIndex = ctr Next Dim date1 = japaneseCal.ToDateTime(23, 9, 8, 0, 0, 0, 0, eraIndex) Console.WriteLine($"{date1.ToString("d", jaJp)} (Gregorian {date1:d})") Try Dim date2 = DateTime.Parse("明治23/9/8", jaJp) Console.WriteLine($"{date2.ToString("d", jaJp)} (Gregorian {date2:d})") Catch e As FormatException Console.WriteLine("The parsing operation failed.") End Try Try Dim date3 = DateTime.ParseExact("明治23/9/8", "gyy/M/d", jaJp) Console.WriteLine($"{date3.ToString("d", jaJp)} (Gregorian {date3:d})") Catch e As FormatException Console.WriteLine("The parsing operation failed.") End Try End Sub End Module ' The example displays the following output: ' 明治23/9/8 (Gregorian 9/8/1890) ' 明治23/9/8 (Gregorian 9/8/1890) ' 明治23/9/8 (Gregorian 9/8/1890)
Dica
Ao trabalhar com calendários que dão suporte a várias eras, sempre use a data gregoriana para criar uma instância de data ou especifique a era ao criar uma instância de data e hora com base nesse calendário.
Ao especificar uma era para o método ToDateTime(Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32), você fornece o índice da era na propriedade Eras do calendário. Para calendários cujas eras estão sujeitas a alterações, no entanto, esses índices não são valores constantes; a era atual está no índice 0 e a era mais antiga está no índice Eras.Length - 1. Quando uma nova era é adicionada a um calendário, os índices das eras anteriores aumentam em um. É possível fornecer o índice de era apropriado da seguinte maneira:
Para datas na era atual, sempre use a propriedade CurrentEra do calendário.
Para datas em uma era especificada, use o método DateTimeFormatInfo.GetEraName para recuperar o índice que corresponde a um nome de era especificado. Isso requer que JapaneseCalendar seja o calendário atual do objeto CultureInfo que representa a cultura ja-JP. (Essa técnica também funciona para JapaneseLunisolarCalendar, pois dá suporte às mesmas eras que JapaneseCalendar.) O exemplo anterior ilustra essa abordagem.
Calendários, eras e intervalos de datas: verificações de intervalo reduzidas
Assim como os calendários individuais têm suporte para intervalos de datas, as eras nas classes JapaneseCalendar e JapaneseLunisolarCalendar também têm intervalos com suporte. Anteriormente, o .NET usava verificações estritas de intervalo de era para garantir que uma data específica da era estivesse no intervalo daquela época. Ou seja, se uma data estiver fora do intervalo da era especificada, o método gerará um ArgumentOutOfRangeException. Atualmente, o .NET usa a verificação de intervalo reduzida por padrão. As atualizações a todas as versões do .NET introduziram verificações reduzidas de intervalo de era; a tentativa de criar uma instância de data específica da era que está fora do intervalo da era especificada "estoura" para a era seguinte e nenhuma exceção é lançada.
O exemplo a seguir tenta instanciar uma data no 65º ano da era Showa, que começou em 25 de dezembro de 1926 e terminou em 7 de janeiro de 1989. Essa data corresponde a 9 de janeiro de 1990, que está fora do intervalo da era Showa no JapaneseCalendar. Como ilustrado pela saída do exemplo, a data exibida pelo exemplo é 9 de janeiro de 1990, no segundo ano da era Heisei.
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
var jaJp = new CultureInfo("ja-JP");
var cal = new JapaneseCalendar();
jaJp.DateTimeFormat.Calendar = cal;
string showaEra = "昭和";
var dt = cal.ToDateTime(65, 1, 9, 15, 0, 0, 0, GetEraIndex(showaEra));
FormattableString fmt = $"{dt:d}";
Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}");
Console.WriteLine($"Gregorian calendar date: {fmt}");
int GetEraIndex(string eraName)
{
foreach (var ctr in cal.Eras)
if (jaJp.DateTimeFormat.GetEraName(ctr) == eraName)
return ctr;
return 0;
}
}
}
// The example displays the following output:
// Japanese calendar date: 平成2/1/9
// Gregorian calendar date: 1/9/1990
Imports System.Globalization
Public Module Example
Dim jaJp As CultureInfo
Dim cal As Calendar
Public Sub Main()
jaJp = New CultureInfo("ja-JP")
cal = New JapaneseCalendar()
jaJp.DateTimeFormat.Calendar = cal
Dim showaEra = "昭和"
Dim dt = cal.ToDateTime(65, 1, 9, 15, 0, 0, 0, GetEraIndex(showaEra))
Dim fmt As FormattableString = $"{dt:d}"
Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)}")
Console.WriteLine($"Gregorian calendar date: {fmt}")
End Sub
Private Function GetEraIndex(eraName As String) As Integer
For Each ctr As Integer In cal.Eras
If jaJp.DateTimeFormat.GetEraName(ctr) = eraName Then Return ctr
Next
Return 0
End Function
End Module
' The example displays the following output:
' Japanese calendar date: 平成2/1/9
' Gregorian calendar date: 1/9/1990
Se as verificações de intervalo reduzidas forem indesejáveis, você poderá restaurar as verificações de intervalo estritas de várias maneiras, dependendo da versão do .NET na qual seu aplicativo está em execução:
.NET Core: adicione o seguinte ao arquivo de configuração .netcore.runtime.json:
"runtimeOptions": { "configProperties": { "Switch.System.Globalization.EnforceJapaneseEraYearRanges": true } }.NET Framework 4.6 ou posterior: defina a seguinte opção AppContext no arquivo app.config:
<?xml version="1.0" encoding="utf-8"?> <configuration> <runtime> <AppContextSwitchOverrides value="Switch.System.Globalization.EnforceJapaneseEraYearRanges=true" /> </runtime> </configuration>.NET Framework 4.5.2 ou anterior: defina o seguinte valor de registro:
Valor Chave HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext Entry Switch.System.Globalization.EnforceJapaneseEraYearRanges Tipo REG_SZ Valor true
Com as verificações de intervalo estritas habilitadas, o exemplo anterior gera um ArgumentOutOfRangeException e exibe a seguinte saída:
Unhandled Exception: System.ArgumentOutOfRangeException: Valid values are between 1 and 64, inclusive.
Parameter name: year
at System.Globalization.GregorianCalendarHelper.GetYearOffset(Int32 year, Int32 era, Boolean throwOnError)
at System.Globalization.GregorianCalendarHelper.ToDateTime(Int32 year, Int32 month, Int32 day, Int32 hour, Int32 minute, Int32 second, Int32 millisecond, Int32 era)
at Example.Main()
Representar datas em calendários com várias eras
Se um objeto Calendar oferece suporte a eras e é o calendário atual de um objeto CultureInfo, a era está incluída na representação de cadeia de caracteres de um valor de data e hora para os padrões de data e hora completa, data completa e data abreviada. O exemplo a seguir exibe esses padrões de data quando a cultura atual é Japão (japanese) e o calendário atual é o calendário japonês.
using System;
using System.Globalization;
using System.IO;
using System.Threading;
public class Example
{
public static void Main()
{
StreamWriter sw = new StreamWriter(@".\eras.txt");
DateTime dt = new DateTime(2012, 5, 1);
CultureInfo culture = CultureInfo.CreateSpecificCulture("ja-JP");
DateTimeFormatInfo dtfi = culture.DateTimeFormat;
dtfi.Calendar = new JapaneseCalendar();
Thread.CurrentThread.CurrentCulture = culture;
sw.WriteLine("\n{0,-43} {1}", "Full Date and Time Pattern:", dtfi.FullDateTimePattern);
sw.WriteLine(dt.ToString("F"));
sw.WriteLine();
sw.WriteLine("\n{0,-43} {1}", "Long Date Pattern:", dtfi.LongDatePattern);
sw.WriteLine(dt.ToString("D"));
sw.WriteLine("\n{0,-43} {1}", "Short Date Pattern:", dtfi.ShortDatePattern);
sw.WriteLine(dt.ToString("d"));
sw.Close();
}
}
// The example writes the following output to a file:
// Full Date and Time Pattern: gg y'年'M'月'd'日' H:mm:ss
// 平成 24年5月1日 0:00:00
//
// Long Date Pattern: gg y'年'M'月'd'日'
// 平成 24年5月1日
//
// Short Date Pattern: gg y/M/d
// 平成 24/5/1
Imports System.Globalization
Imports System.IO
Imports System.Threading
Module Example
Public Sub Main()
Dim sw As New StreamWriter(".\eras.txt")
Dim dt As Date = #05/01/2012#
Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
Dim dtfi As DateTimeFormatInfo = culture.DateTimeFormat
dtfi.Calendar = New JapaneseCalendar()
Thread.CurrentThread.CurrentCulture = culture
sw.WriteLine("{0,-43} {1}", "Full Date and Time Pattern:", dtfi.FullDateTimePattern)
sw.WriteLine(dt.ToString("F"))
sw.WriteLine()
sw.WriteLine("{0,-43} {1}", "Long Date Pattern:", dtfi.LongDatePattern)
sw.WriteLine(dt.ToString("D"))
sw.WriteLine()
sw.WriteLine("{0,-43} {1}", "Short Date Pattern:", dtfi.ShortDatePattern)
sw.WriteLine(dt.ToString("d"))
sw.WriteLine()
sw.Close()
End Sub
End Module
' The example writes the following output to a file:
' Full Date and Time Pattern: gg y'年'M'月'd'日' H:mm:ss
' 平成 24年5月1日 0:00:00
'
' Long Date Pattern: gg y'年'M'月'd'日'
' 平成 24年5月1日
'
' Short Date Pattern: gg y/M/d
' 平成 24/5/1
Aviso
A classe JapaneseCalendar é a única classe de calendário no .NET que oferece suporte a datas em mais de uma era e que pode ser o calendário atual de um objeto CultureInfo – especificamente, um objeto CultureInfo que representa a cultura Japonês (Japão).
Para todos os calendários, o especificador de formato personalizado “g” inclui a era na cadeia de caracteres de resultado. O exemplo a seguir usa a cadeia de caracteres de formato personalizado "MM-dd-aaaa g" para incluir a era na cadeia de caracteres de resultado quando o calendário atual é o calendário gregoriano.
DateTime dat = new DateTime(2012, 5, 1);
Console.WriteLine("{0:MM-dd-yyyy g}", dat);
// The example displays the following output:
// 05-01-2012 A.D.
Dim dat As Date = #05/01/2012#
Console.WriteLine("{0:MM-dd-yyyy g}", dat)
' The example displays the following output:
' 05-01-2012 A.D.
Em casos em que a representação de cadeia de caracteres de uma data é expressa em um calendário que não é o calendário atual, a classe Calendar inclui um método Calendar.GetEra que pode ser usado junto com Calendar.GetYear, Calendar.GetMonth e os métodos Calendar.GetDayOfMonth para indicar inequivocamente uma data e a era à qual ela pertence. O exemplo a seguir usa a classe JapaneseLunisolarCalendar para fornecer uma ilustração. No entanto, observe que incluir um nome ou abreviação significativa em vez de um inteiro para a era na cadeia de caracteres de resultado exige que você crie uma instância de um objeto DateTimeFormatInfo e faça de JapaneseCalendar o calendário atual. (O calendário JapaneseLunisolarCalendar não pode ser o calendário atual de qualquer cultura, mas, nesse caso, os dois calendários compartilham as mesmas eras.)
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
DateTime date1 = new DateTime(2011, 8, 28);
Calendar cal = new JapaneseLunisolarCalendar();
Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
cal.GetEra(date1),
cal.GetYear(date1),
cal.GetMonth(date1),
cal.GetDayOfMonth(date1));
// Display eras
CultureInfo culture = CultureInfo.CreateSpecificCulture("ja-JP");
DateTimeFormatInfo dtfi = culture.DateTimeFormat;
dtfi.Calendar = new JapaneseCalendar();
Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
dtfi.GetAbbreviatedEraName(cal.GetEra(date1)),
cal.GetYear(date1),
cal.GetMonth(date1),
cal.GetDayOfMonth(date1));
}
}
// The example displays the following output:
// 4 0023/07/29
// 平 0023/07/29
Imports System.Globalization
Module Example
Public Sub Main()
Dim date1 As Date = #8/28/2011#
Dim cal As New JapaneseLunisolarCalendar()
Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
cal.GetEra(date1),
cal.GetYear(date1),
cal.GetMonth(date1),
cal.GetDayOfMonth(date1))
' Display eras
Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture("ja-JP")
Dim dtfi As DateTimeFormatInfo = culture.DateTimeFormat
dtfi.Calendar = New JapaneseCalendar()
Console.WriteLine("{0} {1:d4}/{2:d2}/{3:d2}",
dtfi.GetAbbreviatedEraName(cal.GetEra(date1)),
cal.GetYear(date1),
cal.GetMonth(date1),
cal.GetDayOfMonth(date1))
End Sub
End Module
' The example displays the following output:
' 4 0023/07/29
' 平 0023/07/29
Nos calendários japoneses, o primeiro ano de uma era é chamado Gannen (元年). Por exemplo, em vez de Heisei 1, o primeiro ano da era Heisei pode ser descrito como Heisei Gannen. O .NET adota essa convenção em operações de formatação para datas e horas formatadas com as seguintes cadeias de caracteres de formato de data e hora padrão ou personalizadas quando são usadas com um objeto CultureInfo que representa a cultura Japonesa-Japão ("ja-JP") com a classe JapaneseCalendar:
- O padrão de data longa, indicado pela cadeia de caracteres de formato de data e hora padrão "D".
- O padrão de data e hora completo, indicado pela cadeia de caracteres de formato de data e hora padrão "F".
- O padrão de data e hora curto, indicado pela cadeia de caracteres de formato de data e hora padrão "f".
- O padrão ano/mês, indicado pela cadeia de caracteres de formato de data e hora padrão "Y" ou "y".
- A cadeia de caracteres de formato de data e hora personalizado "ggy'年'" ou "ggy年".
Por exemplo, o exemplo a eguir exibe uma data no primeiro ano da era Heisei no JapaneseCalendar.
using System;
using System.Globalization;
public class Example
{
public static void Main()
{
var enUs = new CultureInfo("en-US");
var japaneseCal = new JapaneseCalendar();
var jaJp = new CultureInfo("ja-JP");
jaJp.DateTimeFormat.Calendar = japaneseCal;
string heiseiEra = "平成";
var date = japaneseCal.ToDateTime(1, 8, 18, 0, 0, 0, 0, GetEraIndex(heiseiEra));
FormattableString fmt = $"{date:D}";
Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)} (Gregorian: {fmt.ToString(enUs)})");
int GetEraIndex(string eraName)
{
foreach (var ctr in japaneseCal.Eras)
if (jaJp.DateTimeFormat.GetEraName(ctr) == eraName)
return ctr;
return 0;
}
}
}
// The example displays the following output:
// Japanese calendar date: 平成元年8月18日 (Gregorian: Friday, August 18, 1989)
Imports System.Globalization
Module Program
Dim jaJp As CultureInfo
Dim japaneseCal As Calendar
Sub Main()
Dim enUs = New CultureInfo("en-US")
japaneseCal = New JapaneseCalendar()
jaJp = New CultureInfo("ja-JP")
jaJp.DateTimeFormat.Calendar = japaneseCal
Dim heiseiEra = "平成"
Dim dat = japaneseCal.ToDateTime(1, 8, 18, 0, 0, 0, 0, GetEraIndex(heiseiEra))
Dim fmt As FormattableString = $"{dat:D}"
Console.WriteLine($"Japanese calendar date: {fmt.ToString(jaJp)} (Gregorian: {fmt.ToString(enUs)})")
End Sub
Private Function GetEraIndex(eraName As String) As Integer
For Each ctr In japaneseCal.Eras
If jaJp.DateTimeFormat.GetEraName(ctr) = eraName Then
Return ctr
End If
Next
Return 0
End Function
End Module
' The example displays the following output:
' Japanese calendar date: 平成元年8月18日 (Gregorian: Friday, August 18, 1989)
Se esse comportamento for indesejável em operações de formatação, você poderá restaurar o comportamento anterior, que sempre representa o primeiro ano de uma era como "1" em vez de "Gannen", fazendo o seguinte, dependendo da versão do .NET:
.NET Core: adicione o seguinte ao arquivo de configuração .netcore.runtime.json:
"runtimeOptions": { "configProperties": { "Switch.System.Globalization.FormatJapaneseFirstYearAsANumber": true } }.NET Framework 4.6 ou posterior: defina a seguinte opção AppContext no arquivo app.config:
<?xml version="1.0" encoding="utf-8"?> <configuration> <runtime> <AppContextSwitchOverrides value="Switch.System.Globalization.FormatJapaneseFirstYearAsANumber=true" /> </runtime> </configuration>.NET Framework 4.5.2 ou anterior: defina o seguinte valor de registro:
Valor Chave HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext Entry Switch.System.Globalization.FormatJapaneseFirstYearAsANumber Tipo REG_SZ Valor true
Com o suporte a Gannen em operações de formatação desabilitadas, o exemplo anterior exibe a seguinte saída:
Japanese calendar date: 平成1年8月18日 (Gregorian: Friday, August 18, 1989)
O .NET também foi atualizado para que as operações de análise de data e hora ofereçam suporte a cadeias de caracteres que contêm o ano representado como "1" ou Gannen. Embora você não precise fazer isso, você pode restaurar o comportamento anterior para reconhecer apenas "1" como o primeiro ano de uma era. Você pode fazer isso da seguinte maneira, dependendo da versão do .NET:
.NET Core: adicione o seguinte ao arquivo de configuração .netcore.runtime.json:
"runtimeOptions": { "configProperties": { "Switch.System.Globalization.EnforceLegacyJapaneseDateParsing": true } }.NET Framework 4.6 ou posterior: defina a seguinte opção AppContext no arquivo app.config:
<?xml version="1.0" encoding="utf-8"?> <configuration> <runtime> <AppContextSwitchOverrides value="Switch.System.Globalization.EnforceLegacyJapaneseDateParsing=true" /> </runtime> </configuration>.NET Framework 4.5.2 ou anterior: defina o seguinte valor de registro:
Valor Chave HKEY_LOCAL_MACHINE\Software\Microsoft\.NETFramework\AppContext Entry Switch.System.Globalization.EnforceLegacyJapaneseDateParsing Tipo REG_SZ Valor true
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de