Função DateAdd (Visual Basic)

Artigo
08/25/2010

Retorna um valor Date contendo uma data e valor de tempo para o qual um intervalo de tempo especificado foi adicionado.

Public Overloads Function DateAdd( _
   ByVal Interval As DateInterval, _
   ByVal Number As Double, _
   ByVal DateValue As DateTime _
) As DateTime
' -or-
Public Overloads Function DateAdd( _
   ByVal Interval As String, _
   ByVal Number As Double, _
   ByVal DateValue As Object _
) As DateTime

Parâmetros

Interval
Obrigatório.DateInterval valor de enumeração ou String expressão de seqüência de caracteres que representa o intervalo de time que você deseja adicionar.
Number
Obrigatório.Double.Expressão de ponto flutuante que representa o número de intervalos que você deseja adicionar.Number pode ser positivo (para obter valores de data/time no futuro) ou negativo (para obter valores de data/time no passado). Qualquer parte fracionária do Number será ignorada.
DateValue
Obrigatório.Date.Uma expressão que representa a data e time para a qual o intervalo deve ser adicionado.DateValue propriamente dito não é alterado no programa de chamada.

Configurações

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

Valor de enumeração	String	Unidade de intervalo de tempo para adicionar
DateInterval.Day	d	Dia; truncado ao valor integral
DateInterval.DayOfYear	y	Dia; truncado ao valor integral
DateInterval.Hour	h	Hora; truncado ao valor integral
DateInterval.Minute	n	Minuto; truncado ao valor integral
DateInterval.Month	m	Mês; truncado ao valor integral
DateInterval.Quarter	q	Trimestre; truncado ao valor integral
DateInterval.Second	s	Segundo; truncado ao valor integral
DateInterval.Weekday	w	Dia; truncado ao valor integral
DateInterval.WeekOfYear	ww	Semana; truncado ao valor integral
DateInterval.Year	yyyy	Ano; truncado ao valor integral

Exceções

Tipo de exceção	Número de erro	Condição
InvalidCastException	13	DateValue é não conversível para Date.
ArgumentException	5	Intervalo é inválido.
ArgumentOutOfRangeException	9	Data calculada está antes 00: 00: 00 em 1 º de janeiro do ano 1, ou posterior que 23:59:59 em 31 de dezembro de 9999.

Ver a coluna " número de erro " se você estiver atualizando aplicativos Visual Basic 6.0 que usam manipulação de erros não estruturada.(Você pode comparar o número do erro com a Propriedade do Número (Erro de objeto).) Entretanto, quando for possivel, você pode considerar substituir tal controle de erro por Visão Geral sobre a Manipulação Estruturada de Exceções para o Visual Basic.

Comentários

Você pode usar a função DateAdd para adicionar ou subtrair um intervalo de tempo especificado a partir de uma data.Por exemplo, você pode calcular uma data 30 dias de hoje ou um tempo 45 minutos antes de agora.

Para adicionar dias ao DateValue, você pode usar DateInterval.Day, DateInterval.DayOfYear, ou DateInterval.Weekday.Esses são tratados como equivalente porque DayOfYear e Weekday são intervalos de tempo não significativos.

A função DateAdd nunca retorna uma data inválida.Se necessário, a parte dia da data resultante é ajustada para baixo para o último dia do mês resultante no ano resultante.O exemplo a seguir adiciona um mês a 31 de janeiro:

Dim NextMonth As Date = DateAdd(DateInterval.Month, 1, #1/31/1995#)

Nesse exemplo, DateAdd retorna #2/28/1995#, não #2/31/1995#.Se DateValue é #1/31/1996#, ele retornará #2/29/1996# porque 1996 é um ano bissexto.

Observação:
DateAdd utiliza a configuração atual de calendário da propriedade CurrentCulture da classe CultureInfo no namespace System.Globalization.Os valores CurrentCulture padrão são determinados por configurações do Painel de Controle.

Já que cada valor Date é suportado por uma estrutura DateTime, seus métodos oferecem opções adicionais ao adicionar intervalos de tempo.Por exemplo, você pode adicionar um número fracionário de dias, arredondado para o milissegundo mais próximo, a uma variável Date da seguinte maneira:

Dim NextTime As Date = Now        ' Current date and time.
NextTime = NextTime.AddDays(3.4)  ' Increment by 3 2/5 days.

Exemplo

Este exemplo pega uma data e, usando a função DateAdd, exibe uma data correspondente para um número especificado de meses no futuro.

Dim Msg, Number, StartDate As String   'Declare variables.
Dim Months As Double
Dim SecondDate As Date
Dim IntervalType As DateInterval
IntervalType = DateInterval.Month   ' Specifies months as interval.
StartDate = InputBox("Enter a date")
SecondDate = CDate(StartDate)
Number = InputBox("Enter number of months to add")
Months = Val(Number)
Msg = "New date: " & DateAdd(IntervalType, Months, SecondDate)
MsgBox(Msg)