Retorna uma Variante (Longo) que especifica o número de intervalos de tempo entre as duas datas especificadas.
Sintaxe
DateDiff (interval, date1, date2 [, firstdayofweek] [, firstweekofyear] )
A sintaxe da função DateDiff tem esses argumentos:
| Argumento | Descrição |
|---|---|
| intervalo | Obrigatório. Expressão de cadeia de caracteres que é o intervalo de tempo que você usa para calcular a diferença entre date1 e date2. |
| date1, date2 | Obrigatório. Variant (Data). Duas datas que você deseja usar no cálculo. |
| primeirodiadasemana | Opcional. Uma constante que especifica o primeiro dia da semana. Se não especificado, será usado o domingo. |
| primeirasemanadoano | Opcional. Uma constante que especifica a primeira semana do ano. Se não especificado, será usada a semana em que ocorre 1 de janeiro. |
Configurações
O argumento de intervalo tem essas configurações:
| Configuração | Descrição |
|---|---|
| aaaa | Ano |
| q | Trimestre |
| m | Mês |
| nte misturada, | Dia do ano |
| d | Dia |
| w | Dia da semana |
| ss | Semana |
| h | Hora |
| n | Minuto |
| a a | Segundo |
O argumento firstdayofweek tem estas configurações:
| Constante | Valor | Descrição |
|---|---|---|
| vbUseSystem | 0 | Use a configuração da API NLS. |
| vbSunday | 1 | Domingo (padrão) |
| vbMonday | 2 | Segunda-feira |
| vbTuesday | 3 | Terça-feira |
| vbWednesday | 4 | Quarta-feira |
| vbThursday | 5 | Quinta-feira |
| vbFriday | 6 | Sexta-feira |
| vbSaturday | 7 | Sábado |
| Constante | Valor | Descrição |
|---|---|---|
| vbUseSystem | 0 | Use a configuração da API NLS. |
| vbFirstJan1 | 1 | Comece com a semana em que ocorre 1º de janeiro (padrão). |
| vbFirstFourDays | 2 | Comece com a primeira semana que tem pelo menos quatro dias no ano novo. |
| vbFirstFullWeek | 3 | Comece com a primeira semana completa do ano. |
Comentários
Você pode usar a função DateDiff para determinar quantos intervalos de tempo especificados existem entre duas datas. 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.
Para calcular o número de dias entre date1 e date2, você pode usar dia do ano ("y") ou Dia ("d"). Quando o intervalo é Dia da Semana ("w"), DateDiff retorna o número de semanas entre as duas datas. Se date1 cair em uma segunda-feira, DateDiff conta o número de segundas-feiras até a data2. Ele conta data2 , mas não date1. No entanto, se o intervalo for Semana ("ww"), a função DateDiff retornará o número de semanas de calendário entre as duas datas. Conta o número de domingos entre data1 e date2. DateDiff conta data2 se cair num domingo; mas não conta date1, mesmo que caia num domingo.
Se date1 se referir a um ponto posterior na hora do que date2, a função DateDiff devolve um número negativo.
O primeiro argumentodayofweek afeta os cálculos que utilizam os símbolos de intervalo "w" e "ww".
Se date1 ou date2 for um literal de data, o ano especificado torna-se uma parte permanente dessa data. No entanto, se date1 ou date2 estiverem entre aspas duplas (" "), e omitir o ano, o ano atual é inserido no seu código sempre que a expressão date1 ou date2 for avaliada. Isto permite escrever código que pode ser utilizado em anos diferentes.
Ao comparar 31 de dezembro a 1 de janeiro do ano imediatamente seguinte, DateDiff for Year ("aaaa") devolve 1, apesar de ter decorrido apenas um dia.
Observação
Para date1 e date2, se a definição da propriedade Calendar for Gregoriano, a data fornecida tem de ser Gregoriana. Se o calendário for Hijri, a data fornecida tem de ser Hijri.
Exemplos de Consulta DateDiff
| Expressão. | Resultados |
|---|---|
| SELECT DateDiff("aaaa",#01/01/2010#,[DateofSale]) AS Expr1 FROM ProductSales; | Devolve a diferença entre Date2 e Date1 (considere Date1 como a mais antiga e Date2 como a mais recente) como o número de "Anos". Resultado: diferença entre os valores no campo "DateofSale" e a data "01/01/2010" como o número de "Anos". |
| SELECT DateDiff("q",[DateofSale],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateofSale" como o número de "Trimestres" (com base no ano do calender) e é apresentada na coluna "DaysSinceSale". devolve a diferença entre a data do sistema e "DateofSale" como número de "Meses" e é apresentada na coluna "DaysSinceSale". |
| SELECT DateDiff("y",[DateofSale],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateofSale" como o número de "Dias" e é apresentada na coluna "DaysSinceSale". |
| SELECT DateDiff("d",[DateofSale],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateofSale" como o número de "Dias" e é apresentada na coluna "DaysSinceSale". |
| SELECT DateDiff("w",[DateofSale],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateofSale" como número de "Dias Úteis" e é apresentada na coluna "DaysSinceSale". Se "DateofSale" cair numa segunda-feira, DateDiff conta o número de segundas-feiras até à data do sistema. Conta a data do sistema, mas não o valor em "DateofSale". |
| SELECT DateDiff("ww",[DateofSale],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateofSale" como o número de "Semanas do Calender" e é apresentada na coluna "DaysSinceSale". Conta o número de domingos entre "DateofSale" e "data do sistema". Contará a data do sistema se cair num domingo; mas não conta "DateofSale", mesmo que caia num domingo. |
| SELECT DateDiff("h",[DateTime],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateTime" como número de "Horas" e é apresentada na coluna "DaysSinceSale". |
| SELECT DateDiff("n",[DateTime],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateTime" como o número de "Minutos" e é apresentada na coluna "DaysSinceSale". |
| SELECT DateDiff("s",[DateTime],Date()) AS DaysSinceSale FROM ProductSales; | Devolve a diferença entre a data do sistema e "DateTime" como número de "segundos" e é apresentada na coluna "DaysSinceSale". |
Utilizar a função DateDiff numa expressão
Pode utilizar a função DateDiff onde quer que possa utilizar expressões. Por exemplo, suponha que tem um formulário que utiliza para cumprir as encomendas dos clientes. Na tabela Encomendas, tem um campo denominado ReceiveBefore que contém a data pela qual o cliente precisa de receber a encomenda. Pode utilizar a função DateDiff com uma caixa de texto no formulário para apresentar o número de dias restantes antes de a encomenda ter de ser enviada.
Partindo do princípio de que demora dez dias a enviar qualquer encomenda, defina a propriedade Origem do Controlo da caixa de texto da seguinte forma:
=DateDiff("d", Now(), [Orders].[ ReceiveBefore])-10
Quando abre o formulário na vista Formulário, a caixa de texto apresenta o número de dias restantes antes do envio da encomenda. Se restam menos de 10 dias antes de o cliente precisar de receber a encomenda, o número na caixa de texto é negativo e indica quantos dias de atraso a encomenda terá se for enviada imediatamente.
Utilizar a função DateDiff no código VBA
Este exemplo utiliza a função DateDiff para apresentar o número de dias entre uma determinada data e hoje.
Dim TheDate As Date ' Declare variables.
Dim Msg
TheDate = InputBox("Enter a date")
Msg = "Days from today: " & DateDiff("d", Now, TheDate)
MsgBox Msg