DateAndTime.DateDiff Método

Referência

Definição

Namespace:: Microsoft.VisualBasic

Assembly:: Microsoft.VisualBasic.Core.dll

Assembly:: Microsoft.VisualBasic.dll

Importante

Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

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

Int64

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

Exceções

ArgumentException

Date1, Date2ou DayofWeek está fora do intervalo.

InvalidCastException

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

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

Int64

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

Exceções

ArgumentException

Date1, Date2ou DayofWeek está fora do intervalo.

InvalidCastException

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

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

Partilhar via

DateAndTime.DateDiff Método

Definição

Sobrecargas

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

Parâmetros

Retornos

Exceções

Exemplos

Comentários

Comportamento

Confira também

Aplica-se a

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

Parâmetros

Retornos

Exceções

Exemplos

Comentários

Comportamento

Confira também

Aplica-se a

Recursos adicionais