DateAndTime.DateDiff Método

Definição

Retorna um valor que especifica o número de intervalos de tempo entre dois valores Date.

Sobrecargas

DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear)

Subtrai Date1 de Date2 para fornecer um valor longo especificando o número de intervalos de tempo entre os dois valores de Date.

DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear)

Subtrai Date1 de Date2 para fornecer um valor longo especificando o número de intervalos de tempo entre os dois valores de Date.

DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear)

Origem:
DateAndTime.vb
Origem:
DateAndTime.vb
Origem:
DateAndTime.vb

Subtrai Date1 de Date2 para fornecer um valor longo especificando o número de intervalos de tempo entre os dois valores de Date.

public static long DateDiff (Microsoft.VisualBasic.DateInterval Interval, DateTime Date1, DateTime Date2, Microsoft.VisualBasic.FirstDayOfWeek DayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Microsoft.VisualBasic.FirstWeekOfYear WeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1);
static member DateDiff : Microsoft.VisualBasic.DateInterval * DateTime * DateTime * Microsoft.VisualBasic.FirstDayOfWeek * Microsoft.VisualBasic.FirstWeekOfYear -> int64
Public Function DateDiff (Interval As DateInterval, Date1 As DateTime, Date2 As DateTime, Optional DayOfWeek As FirstDayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Optional WeekOfYear As FirstWeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1) As Long

Parâmetros

Interval
DateInterval

Necessário. Um valor de enumeração DateInterval ou uma expressão de cadeia de caracteres que representa o intervalo de tempo que você deseja usar como a unidade de diferença entre Date1 e Date2.

Date1
DateTime

Necessário. O primeiro valor de data/hora que você deseja usar no cálculo.

Date2
DateTime

Necessário. O segundo valor de data/hora que você deseja usar no cálculo.

DayOfWeek
FirstDayOfWeek

Opcional. Um valor escolhido da enumeração FirstDayOfWeek que especifica o primeiro dia da semana. Se não for especificado, Sunday será usado.

WeekOfYear
FirstWeekOfYear

Opcional. Um valor escolhido da enumeração FirstWeekOfYear que especifica a primeira semana do ano. Se não for especificado, Jan1 será usado.

Retornos

Um valor longo que especifica o número de intervalos de tempo entre dois valores Date.

Exceções

Date1, Date2ou DayofWeek está fora do intervalo.

Date1 ou Date2 é de um tipo inválido.

Exemplos

Este exemplo usa a função DateDiff para exibir o número de dias entre uma determinada data e hoje.

Dim date2Entered As String = InputBox("Enter a date")

Try
    Dim date2 As Date = Date.Parse(date2Entered)
    Dim date1 As Date = Now

    ' Determine the number of days between the two dates.
    Dim days As Long = DateDiff(DateInterval.Day, date1, date2)

    ' This statement has a string interval argument, and
    ' is equivalent to the above statement.
    'Dim days As Long = DateDiff("d", date1, date2)

    MessageBox.Show("Days from today: " & days.ToString)
Catch ex As Exception
    MessageBox.Show("Invalid Date: " & ex.Message)
End Try

Comentários

Você pode usar a função DateDiff para determinar quantos intervalos de tempo especificados existem entre dois valores de data/hora. Por exemplo, você pode usar DateDiff para calcular o número de dias entre duas datas ou o número de semanas entre hoje e o final do ano.

Comportamento

  • Tratamento de parâmetros. DateDiff subtrai o valor de Date1 do valor de Date2 para produzir a diferença. Nenhum valor é alterado no programa de chamada.

  • Valores retornados. Como Date1 e Date2 são do tipo de dados Date, eles contêm valores de data e hora precisos para tiques de 100 nanossegundos no temporizador do sistema. No entanto, DateDiff sempre retorna o número de intervalos de tempo como um valor Long.

    Se Date1 representar uma data e hora posteriores a Date2, DateDiff retornará um número negativo.

  • Intervalos de dia. Se Interval estiver definido como DateInterval.DayOfYear, ele será tratado da mesma forma que DateInterval.Day, porque DayOfYear não é uma unidade significativa para um intervalo de tempo.

  • Intervalos de semana. Se Interval estiver definido como DateInterval.WeekOfYear, o valor retornado representará o número de semanas entre o primeiro dia da semana que contém Date1 e o primeiro dia da semana que contém Date2. O exemplo a seguir mostra como isso produz resultados diferentes de DateInterval.Weekday.

    ' The following statements set datTim1 to a Thursday
    ' and datTim2 to the following Tuesday.
    Dim datTim1 As Date = #1/4/2001#
    Dim datTim2 As Date = #1/9/2001#
    ' Assume Sunday is specified as first day of the week.
    Dim wD As Long = DateDiff(DateInterval.Weekday, datTim1, datTim2)
    Dim wY As Long = DateDiff(DateInterval.WeekOfYear, datTim1, datTim2)
    

    No exemplo anterior, DateDiff retorna 0 a wD porque a diferença entre as duas datas é menor que sete dias, mas retorna de 1 a wY porque há uma diferença de sete dias entre os primeiros dias das respectivas semanas do calendário.

  • Intervalos maiores. Se Interval estiver definido como DateInterval.Year, o valor retornado será calculado somente a partir das partes do ano de Date1 e Date2. Da mesma forma, o valor retornado para DateInterval.Month é calculado puramente a partir das partes ano e mês dos argumentos e para DateInterval.Quarter dos trimestres que contêm as duas datas.

    Por exemplo, ao comparar 31 de dezembro a 1º de janeiro do ano seguinte, DateDiff retorna 1 para DateInterval.Year, DateInterval.Quarterou DateInterval.Month, embora no máximo apenas um dia tenha decorrido.

    Para culturas como japonês que têm várias eras, o método DateDiff não retorna uma diferença em anos se a diferença abrange duas ou mais eras. Em vez disso, você pode calcular a diferença de valores retornados pela propriedade Year, conforme mostrado no exemplo a seguir: date2.Year - date1.Year.

  • Outros intervalos. Como cada valor Date é suportado por uma estrutura DateTime, seus métodos oferecem opções adicionais para encontrar intervalos de tempo. Por exemplo, você pode usar o método Subtract em qualquer um de seus formulários sobrecarregados: DateTime.Subtract subtrai um TimeSpan de uma variável de Date para retornar outro valor Date e DateTime.Subtract subtrai um valor Date para retornar um TimeSpan. Você pode cronometrar um processo para descobrir quantos milissegundos são necessários, como mostra o exemplo a seguir.

    Dim startTime As Date = Now
    ' Run the process that is to be timed.
    Dim runLength As Global.System.TimeSpan = Now.Subtract(startTime)
    Dim millisecs As Double = runLength.TotalMilliseconds
    

O argumento Interval pode ter uma das seguintes configurações.

Valor de enumeração Valor da cadeia de caracteres Diferença de unidade de tempo
DateInterval.Day "d" Dia
DateInterval.DayOfYear "y" Dia
DateInterval.Hour "h" Hora
DateInterval.Minute "n" Minuto
DateInterval.Month "m" Mês
DateInterval.Quarter "q" Quarto
DateInterval.Second "s" Segundo
DateInterval.Weekday "w" Semana
DateInterval.WeekOfYear "ww" Semana do calendário
DateInterval.Year "yyyyy" Ano

O argumento DayOfWeek pode ter uma das seguintes configurações.

Valor de enumeração Valor Descrição
FirstDayOfWeek.System 0 Primeiro dia da semana especificado nas configurações do sistema
FirstDayOfWeek.Sunday 1 Domingo (padrão)
FirstDayOfWeek.Monday 2 Segunda-feira (em conformidade com o ISO standard 8601, seção 3.17)
FirstDayOfWeek.Tuesday 3 Terça-feira
FirstDayOfWeek.Wednesday 4 Quarta-feira
FirstDayOfWeek.Thursday 5 Quinta-feira
FirstDayOfWeek.Friday 6 Sexta-feira
FirstDayOfWeek.Saturday 7 Sábado

O argumento WeekOfYear pode ter uma das seguintes configurações.

Valor de enumeração Valor Descrição
FirstWeekOfYear.System 0 Primeira semana do ano especificada nas configurações do sistema
FirstWeekOfYear.Jan1 1 Semana em que 1º de janeiro ocorre (padrão)
FirstWeekOfYear.FirstFourDays 2 Semana que tem pelo menos quatro dias no ano novo (em conformidade com o ISO standard 8601, seção 3.17)
FirstWeekOfYear.FirstFullWeek 3 Primeira semana completa do ano novo

Confira também

Aplica-se a

DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear)

Origem:
DateAndTime.vb
Origem:
DateAndTime.vb
Origem:
DateAndTime.vb

Subtrai Date1 de Date2 para fornecer um valor longo especificando o número de intervalos de tempo entre os dois valores de Date.

public static long DateDiff (string Interval, object? Date1, object? Date2, Microsoft.VisualBasic.FirstDayOfWeek DayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Microsoft.VisualBasic.FirstWeekOfYear WeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1);
public static long DateDiff (string Interval, object Date1, object Date2, Microsoft.VisualBasic.FirstDayOfWeek DayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Microsoft.VisualBasic.FirstWeekOfYear WeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1);
static member DateDiff : string * obj * obj * Microsoft.VisualBasic.FirstDayOfWeek * Microsoft.VisualBasic.FirstWeekOfYear -> int64
Public Function DateDiff (Interval As String, Date1 As Object, Date2 As Object, Optional DayOfWeek As FirstDayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Optional WeekOfYear As FirstWeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1) As Long

Parâmetros

Interval
String

Necessário. Um valor de enumeração DateInterval ou uma expressão de cadeia de caracteres que representa o intervalo de tempo que você deseja usar como a unidade de diferença entre Date1 e Date2.

Date1
Object

Necessário. O primeiro valor de data/hora que você deseja usar no cálculo.

Date2
Object

Necessário. O segundo valor de data/hora que você deseja usar no cálculo.

DayOfWeek
FirstDayOfWeek

Opcional. Um valor escolhido da enumeração FirstDayOfWeek que especifica o primeiro dia da semana. Se não for especificado, Sunday será usado.

WeekOfYear
FirstWeekOfYear

Opcional. Um valor escolhido da enumeração FirstWeekOfYear que especifica a primeira semana do ano. Se não for especificado, Jan1 será usado.

Retornos

Um valor longo que especifica o número de intervalos de tempo entre dois valores Date.

Exceções

Date1, Date2ou DayofWeek está fora do intervalo.

Date1 ou Date2 é de um tipo inválido.

Exemplos

Este exemplo usa a função DateDiff para exibir o número de dias entre uma determinada data e hoje.

Dim date2Entered As String = InputBox("Enter a date")

Try
    Dim date2 As Date = Date.Parse(date2Entered)
    Dim date1 As Date = Now

    ' Determine the number of days between the two dates.
    Dim days As Long = DateDiff(DateInterval.Day, date1, date2)

    ' This statement has a string interval argument, and
    ' is equivalent to the above statement.
    'Dim days As Long = DateDiff("d", date1, date2)

    MessageBox.Show("Days from today: " & days.ToString)
Catch ex As Exception
    MessageBox.Show("Invalid Date: " & ex.Message)
End Try

Comentários

Você pode usar a função DateDiff para determinar quantos intervalos de tempo especificados existem entre dois valores de data/hora. Por exemplo, você pode usar DateDiff para calcular o número de dias entre duas datas ou o número de semanas entre hoje e o final do ano.

Comportamento

  • Tratamento de parâmetros. DateDiff subtrai o valor de Date1 do valor de Date2 para produzir a diferença. Nenhum valor é alterado no programa de chamada.

  • Valores retornados. Como Date1 e Date2 são do tipo de dados Date, eles contêm valores de data e hora precisos para tiques de 100 nanossegundos no temporizador do sistema. No entanto, DateDiff sempre retorna o número de intervalos de tempo como um valor Long.

    Se Date1 representar uma data e hora posteriores a Date2, DateDiff retornará um número negativo.

  • Intervalos de dia. Se Interval estiver definido como DateInterval.DayOfYear, ele será tratado da mesma forma que DateInterval.Day, porque DayOfYear não é uma unidade significativa para um intervalo de tempo.

  • Intervalos de semana. Se Interval estiver definido como DateInterval.WeekOfYear, o valor retornado representará o número de semanas entre o primeiro dia da semana que contém Date1 e o primeiro dia da semana que contém Date2. O exemplo a seguir mostra como isso produz resultados diferentes de DateInterval.Weekday.

    ' The following statements set datTim1 to a Thursday
    ' and datTim2 to the following Tuesday.
    Dim datTim1 As Date = #1/4/2001#
    Dim datTim2 As Date = #1/9/2001#
    ' Assume Sunday is specified as first day of the week.
    Dim wD As Long = DateDiff(DateInterval.Weekday, datTim1, datTim2)
    Dim wY As Long = DateDiff(DateInterval.WeekOfYear, datTim1, datTim2)
    

    No exemplo anterior, DateDiff retorna 0 a wD porque a diferença entre as duas datas é menor que sete dias, mas retorna de 1 a wY porque há uma diferença de sete dias entre os primeiros dias das respectivas semanas do calendário.

  • Intervalos maiores. Se Interval estiver definido como DateInterval.Year, o valor retornado será calculado somente a partir das partes do ano de Date1 e Date2. Da mesma forma, o valor retornado para DateInterval.Month é calculado puramente a partir das partes ano e mês dos argumentos e para DateInterval.Quarter dos trimestres que contêm as duas datas.

    Por exemplo, ao comparar 31 de dezembro a 1º de janeiro do ano seguinte, DateDiff retorna 1 para DateInterval.Year, DateInterval.Quarterou DateInterval.Month, embora no máximo apenas um dia tenha decorrido.

    Para culturas como japonês que têm várias eras, o método DateDiff não retorna uma diferença em anos se a diferença abrange duas ou mais eras. Em vez disso, você pode calcular a diferença de valores retornados pela propriedade Year, conforme mostrado no exemplo a seguir: date2.Year - date1.Year.

  • Outros intervalos. Como cada valor Date é suportado por uma estrutura DateTime, seus métodos oferecem opções adicionais para encontrar intervalos de tempo. Por exemplo, você pode usar o método Subtract em qualquer um de seus formulários sobrecarregados: DateTime.Subtract subtrai um TimeSpan de uma variável de Date para retornar outro valor Date e DateTime.Subtract subtrai um valor Date para retornar um TimeSpan. Você pode cronometrar um processo para descobrir quantos milissegundos são necessários, como mostra o exemplo a seguir.

    Dim startTime As Date = Now
    ' Run the process that is to be timed.
    Dim runLength As Global.System.TimeSpan = Now.Subtract(startTime)
    Dim millisecs As Double = runLength.TotalMilliseconds
    

O argumento Interval pode ter uma das seguintes configurações.

Valor de enumeração Valor da cadeia de caracteres Diferença de unidade de tempo
DateInterval.Day "d" Dia
DateInterval.DayOfYear "y" Dia
DateInterval.Hour "h" Hora
DateInterval.Minute "n" Minuto
DateInterval.Month "m" Mês
DateInterval.Quarter "q" Quarto
DateInterval.Second "s" Segundo
DateInterval.Weekday "w" Semana
DateInterval.WeekOfYear "ww" Semana do calendário
DateInterval.Year "yyyyy" Ano

O argumento DayOfWeek pode ter uma das seguintes configurações.

Valor de enumeração Valor Descrição
FirstDayOfWeek.System 0 Primeiro dia da semana especificado nas configurações do sistema
FirstDayOfWeek.Sunday 1 Domingo (padrão)
FirstDayOfWeek.Monday 2 Segunda-feira (em conformidade com o ISO standard 8601, seção 3.17)
FirstDayOfWeek.Tuesday 3 Terça-feira
FirstDayOfWeek.Wednesday 4 Quarta-feira
FirstDayOfWeek.Thursday 5 Quinta-feira
FirstDayOfWeek.Friday 6 Sexta-feira
FirstDayOfWeek.Saturday 7 Sábado

O argumento WeekOfYear pode ter uma das seguintes configurações.

Valor de enumeração Valor Descrição
FirstWeekOfYear.System 0 Primeira semana do ano especificada nas configurações do sistema
FirstWeekOfYear.Jan1 1 Semana em que 1º de janeiro ocorre (padrão)
FirstWeekOfYear.FirstFourDays 2 Semana que tem pelo menos quatro dias no ano novo (em conformidade com o ISO standard 8601, seção 3.17)
FirstWeekOfYear.FirstFullWeek 3 Primeira semana completa do ano novo

Confira também

Aplica-se a