Compartilhar via

Analisar cadeias de caracteres de data e hora no .NET

Analisar cadeias de caracteres para convertê-las em DateTime objetos exige que você especifique informações sobre como as datas e horas são representadas como texto. Diferentes culturas adotam ordens diferentes para dia, mês e ano. Algumas representações de tempo usam um relógio de 24 horas, outras especificam "AM" e "PM". Alguns aplicativos precisam apenas da data. Outros só precisam de tempo. Outros ainda precisam especificar a data e a hora. Os métodos que convertem cadeias de caracteres em DateTime objetos permitem que você forneça informações detalhadas sobre os formatos esperados e os elementos de uma data e hora que seu aplicativo precisa. Há três subtarefas para converter o texto corretamente em um DateTime:

  1. Você deve especificar o formato esperado do texto que representa uma data e hora.
  2. Você pode especificar a cultura para definir o formato de data e hora.
  3. Você pode especificar como os componentes ausentes na representação de texto são definidos na data e hora.

Os Parse métodos e os TryParse métodos convertem muitas representações comuns de uma data e hora. Os métodos ParseExact e TryParseExact convertem uma cadeia de caracteres que segue o padrão especificado por uma string de formato de data e hora. Para obter mais informações, consulte os artigos sobre cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres personalizadas de formato de data e hora.

O objeto atual DateTimeFormatInfo fornece mais controle sobre como o texto deve ser interpretado como uma data e hora. As propriedades de um DateTimeFormatInfo descrevem os separadores de data e de hora, os nomes de meses, dias e eras e o formato das designações "AM" e "PM". O CultureInfo retornado por CultureInfo.CurrentCulture tem uma propriedade CultureInfo.DateTimeFormat que representa a cultura atual. Se você quiser uma cultura específica ou configurações personalizadas, especifique o IFormatProvider parâmetro de um método de análise. Para o IFormatProvider parâmetro, especifique um CultureInfo objeto, que representa uma cultura ou um DateTimeFormatInfo objeto.

O texto que representa uma data ou hora pode estar faltando algumas informações. Por exemplo, a maioria das pessoas assumiria que a data "12 de março" representa o ano atual. Da mesma forma, "março de 2018" representa o mês de março do ano de 2018. O texto que representa o tempo geralmente inclui apenas horas, minutos e uma designação AM/PM. Os métodos de análise lidam com essas informações ausentes usando padrões razoáveis:

  • Quando apenas a hora estiver presente, a parte de data usará a data atual.
  • Quando apenas a data estiver presente, o horário será à meia-noite.
  • Quando o ano não é especificado em uma data, o ano atual é usado.
  • Quando o dia do mês não é especificado, o primeiro dia do mês é usado.

Se a data estiver presente na cadeia de caracteres, ela deverá incluir o mês e um do dia ou ano. Se a hora estiver presente, ela deverá incluir a hora e os minutos ou o designador AM/PM.

Você pode especificar a NoCurrentDateDefault constante para substituir esses padrões. Quando você usa essa constante, todas as propriedades de ano, mês ou dia ausentes são definidas como o valor 1. O último exemplo usando Parse demonstra esse comportamento.

Além de um componente de data e hora, a representação de cadeia de caracteres de uma data e hora pode incluir um deslocamento que indica quanto a hora difere da UTC (Tempo Universal Coordenado). Por exemplo, a cadeia de caracteres "14/2/2007 5:32:00 -7:00" define uma hora sete horas antes da UTC. Se um deslocamento for omitido da representação de uma string de um tempo, a interpretação retornará um objeto DateTime com sua propriedade Kind definida como DateTimeKind.Unspecified. Se um deslocamento for especificado, a análise retornará um objeto DateTime com a propriedade Kind definida para DateTimeKind.Local. Seu valor também é ajustado para o fuso horário local do computador. Você pode modificar esse comportamento usando um DateTimeStyles valor com o método de análise.

O provedor de formato também é usado para interpretar uma data numérica ambígua. Não está claro quais componentes da data representada pela cadeia de caracteres "03/02/04" são o mês, o dia e o ano. Os componentes são interpretados de acordo com a ordem de formatos de data semelhantes no provedor de formato.

Parse

O exemplo a seguir ilustra o uso do DateTime.Parse método para converter um string em um DateTime. Este exemplo usa a cultura associada ao thread atual. Se o CultureInfo associado à cultura atual não puder analisar a cadeia de caracteres de entrada, um FormatException será gerado.

Observação

Esses exemplos estão disponíveis no repositório de documentos do GitHub para C# e Visual Basic.

string dateInput = "Jan 1, 2009";
var parsedDate = DateTime.Parse(dateInput);
Console.WriteLine(parsedDate);
// Displays the following output on a system whose culture is en-US:
//       1/1/2009 00:00:00

Dim MyString As String = "Jan 1, 2009"
Dim MyDateTime As DateTime = DateTime.Parse(MyString)
Console.WriteLine(MyDateTime)
' Displays the following output on a system whose culture is en-US:
'       1/1/2009 00:00:00

Você também pode definir explicitamente a cultura cujas convenções de formatação são usadas ao analisar uma cadeia de caracteres. Especifique um dos objetos padrão DateTimeFormatInfo retornados pela CultureInfo.DateTimeFormat propriedade. O exemplo a seguir usa um provedor de formato para analisar uma cadeia de caracteres alemã em um DateTime. Ele cria uma CultureInfo representação da de-DE cultura. Esse CultureInfo objeto garante a análise bem-sucedida dessa cadeia de caracteres específica. Esse processo exclui qualquer configuração que esteja em CurrentCulture do CurrentThread.

var cultureInfo = new CultureInfo("de-DE");
string dateString = "12 Juni 2008";
var dateTime = DateTime.Parse(dateString, cultureInfo);
Console.WriteLine(dateTime);
// The example displays the following output:
//       6/12/2008 00:00:00

Dim MyCultureInfo As New CultureInfo("de-DE")
Dim MyString As String = "12 Juni 2008"
Dim MyDateTime As DateTime = DateTime.Parse(MyString, MyCultureInfo)
Console.WriteLine(MyDateTime)
' The example displays the following output:
'       6/12/2008 00:00:00

No entanto, você pode usar sobrecargas do método Parse para especificar provedores de formatos personalizados. O Parse método não dá suporte à análise de formatos não padrão. Para analisar uma data e hora expressas em um formato não padrão, use o ParseExact método em vez disso.

O exemplo a seguir usa a DateTimeStyles enumeração para especificar que as informações atuais de data e hora não devem ser adicionadas aos DateTime campos não especificados.

var cultureInfo = new CultureInfo("de-DE");
string dateString = "12 Juni 2008";
var dateTime = DateTime.Parse(dateString, cultureInfo,
                                DateTimeStyles.NoCurrentDateDefault);
Console.WriteLine(dateTime);
// The example displays the following output if the current culture is en-US:
//      6/12/2008 00:00:00

Dim MyCultureInfo As New CultureInfo("de-DE")
Dim MyString As String = "12 Juni 2008"
Dim MyDateTime As DateTime = DateTime.Parse(MyString, MyCultureInfo,
                           DateTimeStyles.NoCurrentDateDefault)
Console.WriteLine(MyDateTime)
' The example displays the following output if the current culture is en-US:
'       6/12/2008 00:00:00

ParseExact

O DateTime.ParseExact método converte uma cadeia de caracteres em um DateTime objeto se estiver em conformidade com um dos padrões de cadeia de caracteres especificados. Quando uma cadeia de caracteres que não é um dos formulários especificados é passada para esse método, uma FormatException é gerada. Você pode especificar um dos especificadores de formato de data e hora padrão ou uma combinação dos especificadores de formato personalizado. Usando os especificadores de formato personalizado, é possível construir uma cadeia de caracteres de reconhecimento personalizada. Para obter uma explicação dos especificadores, consulte os artigos sobre cadeias de caracteres de formato de data e hora padrão e cadeias de caracteres de formato de data e hora personalizadas.

No exemplo a seguir, o método DateTime.ParseExact recebe um objeto string para analisar, seguido por um especificador de formato, seguido por o objeto CultureInfo. Esse ParseExact método só pode analisar cadeias de caracteres que seguem o padrão de data longa na cultura en-US.

var cultureInfo = new CultureInfo("en-US");
string[] dateStrings = { " Friday, April 10, 2009", "Friday, April 10, 2009" };
foreach (string dateString in dateStrings)
{
    try
    {
        var dateTime = DateTime.ParseExact(dateString, "D", cultureInfo);
        Console.WriteLine(dateTime);
    }
    catch (FormatException)
    {
        Console.WriteLine($"Unable to parse '{dateString}'");
    }
}
// The example displays the following output:
//       Unable to parse ' Friday, April 10, 2009'
//       4/10/2009 00:00:00

Dim MyCultureInfo As New CultureInfo("en-US")
Dim MyString() As String = {" Friday, April 10, 2009", "Friday, April 10, 2009"}
For Each dateString As String In MyString
    Try
        Dim MyDateTime As DateTime = DateTime.ParseExact(dateString, "D",
                                                     MyCultureInfo)
        Console.WriteLine(MyDateTime)
    Catch e As FormatException
        Console.WriteLine("Unable to parse '{0}'", dateString)
    End Try
Next
' The example displays the following output:
'       Unable to parse ' Friday, April 10, 2009'
'       4/10/2009 00:00:00

Cada sobrecarga dos métodos Parse e ParseExact também tem um parâmetro IFormatProvider que fornece informações específicas da cultura sobre a formatação da string. O IFormatProvider objeto é um CultureInfo objeto que representa uma cultura padrão ou um DateTimeFormatInfo objeto que é retornado pela CultureInfo.DateTimeFormat propriedade. ParseExact também usa um argumento de cadeia de caracteres ou matriz de cadeia de caracteres adicional que define um ou mais formatos personalizados de data e hora.

Consulte também

  • Last updated on