DateAndTime.DateDiff Método

Definição

Espaço de Nomes:: Microsoft.VisualBasic

Assemblagem:: Microsoft.VisualBasic.dll

Importante

Algumas informações dizem respeito a um produto pré-lançado que pode ser substancialmente modificado antes de ser lançado. A Microsoft não faz garantias, de forma expressa ou implícita, em relação à informação aqui apresentada.

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

Sobrecargas

Name	Description
DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear)	Subtrai `Date1` de `Date2` para obter um valor longo que especifica o número de intervalos de tempo entre os dois `Date` valores.
DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear)	Subtrai `Date1` de `Date2` para obter um valor longo que especifica o número de intervalos de tempo entre os dois `Date` valores.

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

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

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

Required. Um valor de enumeração ou uma expressão string que DateInterval represente o intervalo de tempo que pretende usar como unidade de diferença entre Date1 e Date2.

Date1: DateTime

Required. O valor da primeira data/hora que queres usar no cálculo.

Date2: DateTime

Required. O segundo valor de data/hora que queres usar no cálculo.

DayOfWeek: FirstDayOfWeek

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

WeekOfYear: FirstWeekOfYear

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

Devoluções

Int64

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

Exceções

ArgumentException

Date1, Date2, ou DayofWeek está fora do alcance.

InvalidCastException

Date1 ou Date2 é de tipo inválido.

Exemplos

Este exemplo utiliza a DateDiff função para mostrar o número de dias entre uma dada 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

Observações

Pode usar a DateDiff função para determinar quantos intervalos de tempo especificados existem entre dois valores de data/hora. Por exemplo, 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 dos Parâmetros. DateDiff subtrai o valor de Date1 do valor de Date2 para produzir a diferença. Nenhum dos valores é alterado no programa de chamada.
Valores de devolução. Como Date1 e Date2 pertencem ao Date tipo de dados, mantêm valores de data e hora com precisão de 100 nanossegundos no temporizador do sistema. No entanto, DateDiff devolve sempre o número de intervalos de tempo como um Long valor.

Se Date1 representa uma data e hora posteriores a Date2, DateDiff devolve um número negativo.
Intervalos diurnos. Se Interval for definido como DateInterval.DayOfYear, é tratado da mesma forma que DateInterval.Day, porque DayOfYear não é uma unidade significativa para um intervalo de tempo.
Intervalos de semana. Se Interval for definido como DateInterval.WeekOfYear, o valor de retorno representa 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 seguinte mostra como isto produz resultados diferentes a partir 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 devolve 0 a wD porque a diferença entre as duas datas é inferior a sete dias, mas devolve 1 a wY porque há uma diferença de sete dias entre os primeiros dias das respetivas semanas do calendário.
Intervalos maiores. Se Interval for definido como DateInterval.Year, o valor de retorno é calculado puramente a partir das partes do ano de Date1 e Date2. De forma semelhante, o valor de retorno para DateInterval.Month é calculado puramente a partir das partes do ano e do mês dos argumentos, e para DateInterval.Quarter dos trimestres que contêm as duas datas.

Por exemplo, ao comparar 31 de dezembro com 1 de janeiro do ano seguinte, DateDiff retorna 1 para DateInterval.Year, DateInterval.Quarter, ou DateInterval.Month, mesmo que, no máximo, tenha decorrido apenas um dia.

Para culturas como a japonesa, que têm múltiplas eras, o DateDiff método não apresenta uma diferença em anos se a diferença abranger duas ou mais eras. Em vez disso, pode calcular a diferença de valores devolvidos pela Year propriedade, como mostrado no seguinte exemplo: date2.Year - date1.Year.
Outros Intervalos. Como cada Date valor é suportado por uma DateTime estrutura, os seus métodos dão-lhe opções adicionais para encontrar intervalos de tempo. Por exemplo, pode usar o Subtract método em qualquer uma das suas formas sobrecarregadas: DateTime.Subtract subtrai a TimeSpan de uma Date variável para devolver outro Date valor, e DateTime.Subtract subtrai um Date valor para devolver um TimeSpan. Pode cronometrar um processo para saber quantos milissegundos demora, como mostra o exemplo seguinte.
```
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 Interval argumento pode ter um dos seguintes contextos.

Valor de enumeração	Valor da cadeia de caracteres	Unidade de diferença horária
`DateInterval.Day`	"d"	Day
`DateInterval.DayOfYear`	"a"	Day
`DateInterval.Hour`	"h"	Hora
`DateInterval.Minute`	"n"	Minuto
`DateInterval.Month`	"m"	Mês
`DateInterval.Quarter`	“t”	Trimestre
`DateInterval.Second`	s	Segundo
`DateInterval.Weekday`	"w"	Semana
`DateInterval.WeekOfYear`	“ss”	Semana do calendário
`DateInterval.Year`	AAAA	Ano

O DayOfWeek argumento pode ter um dos seguintes contextos.

Valor de enumeração	Value	Description
`FirstDayOfWeek.System`	0	Primeiro dia da semana especificado nas definições do sistema
`FirstDayOfWeek.Sunday`	1	Domingo (predefinição)
`FirstDayOfWeek.Monday`	2	Segunda-feira (cumpre a norma ISO 8601, secção 3.17)
`FirstDayOfWeek.Tuesday`	3	Tuesday
`FirstDayOfWeek.Wednesday`	4	Quarta-feira
`FirstDayOfWeek.Thursday`	5	Quinta-feira
`FirstDayOfWeek.Friday`	6	Sexta-feira
`FirstDayOfWeek.Saturday`	7	Sábado

O WeekOfYear argumento pode ter um dos seguintes contextos.

Valor de enumeração	Value	Description
`FirstWeekOfYear.System`	0	A primeira semana do ano especificada nas definições do sistema
`FirstWeekOfYear.Jan1`	1	Semana em que ocorre 1 de janeiro (padrão)
`FirstWeekOfYear.FirstFourDays`	2	Semana que tenha pelo menos quatro dias no novo ano (cumpra a norma ISO 8601, secção 3.17)
`FirstWeekOfYear.FirstFullWeek`	3	Primeira semana completa do novo ano

Ver também

Aplica-se a

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