Funzione DateDiff (Visual Basic)

Articolo
09/12/2008

Aggiornamento: novembre 2007

Restituisce un valore Long corrispondente al numero di intervalli di tempo tra due valori Date.

Public Overloads Function DateDiff( _
    ByVal Interval As [ DateInterval | String ], _
    ByVal Date1 As DateTime, _
    ByVal Date2 As DateTime, _
    Optional ByVal DayOfWeek As FirstDayOfWeek = FirstDayOfWeek.Sunday, _
    Optional ByVal  WeekOfYear As FirstWeekOfYear = FirstWeekOfYear.Jan1 _
) As Long

Parametri

Interval
Obbligatorio. Valore di enumerazione DateInterval o espressione String che rappresenta l'intervallo di tempo da utilizzare come unità di misura della differenza tra Date1 e Date2.
Date1
Obbligatorio. Date. Primo valore di data/ora che si desidera utilizzare nel calcolo.
Date2
Obbligatorio. Date. Secondo valore di data/ora che si desidera utilizzare nel calcolo.
DayOfWeek
Facoltativo. Valore scelto dall'enumerazione FirstDayOfWeek che indica il primo giorno della settimana. Se non viene specificato, viene utilizzato FirstDayOfWeek.Sunday.
WeekOfYear
Facoltativo. Valore scelto dall'enumerazione FirstWeekOfYear che indica la prima settimana dell'anno. Se non viene specificato, viene utilizzato FirstWeekOfYear.Jan1.

Impostazioni

Di seguito sono indicate le possibili impostazioni dell'argomento Interval.

Valore di enumerazione	Valore stringa	Unità di misura della differenza temporale
DateInterval.Day	"d"	Giorno
DateInterval.DayOfYear	"y"	Giorno
DateInterval.Hour	"h"	Ora
DateInterval.Minute	"n"	Minuto
DateInterval.Month	"m"	Mese
DateInterval.Quarter	"q"	Trimestre
DateInterval.Second	"s"	Secondo
DateInterval.Weekday	"w"	Settimana
DateInterval.WeekOfYear	"ww"	Settimana del calendario
DateInterval.Year	"yyyy"	Anno

Di seguito sono indicate le possibili impostazioni dell'argomento DayOfWeek.

Valore di enumerazione	Valore	Descrizione
FirstDayOfWeek.System	0	Primo giorno della settimana specificato nelle impostazioni di sistema
FirstDayOfWeek.Sunday	1	Domenica (impostazione predefinita)
FirstDayOfWeek.Monday	2	Lunedì (conforme allo standard ISO 8601, sezione 3.17)
FirstDayOfWeek.Tuesday	3	Martedì
FirstDayOfWeek.Wednesday	4	Mercoledì
FirstDayOfWeek.Thursday	5	Giovedì
FirstDayOfWeek.Friday	6	Venerdì
FirstDayOfWeek.Saturday	7	Sabato

Di seguito sono indicate le possibili impostazioni dell'argomento WeekOfYear.

Valore di enumerazione	Valore	Descrizione
FirstWeekOfYear.System	0	Prima settimana dell'anno specificata nelle impostazioni di sistema
FirstWeekOfYear.Jan1	1	Settimana in cui cade l'1 gennaio (impostazione predefinita).
FirstWeekOfYear.FirstFourDays	2	Settimana in cui almeno quattro giorni cadono nel nuovo anno (conforme allo standard ISO 8601, sezione 3.17)
FirstWeekOfYear.FirstFullWeek	3	Prima settimana completa del nuovo anno

Eccezioni

Tipo di eccezione	Numero di errore	Condizione
ArgumentException	5	Interval non valido.
ArgumentException	5	Date1, Date2 o DayofWeek non è compreso nell'intervallo consentito.
InvalidCastException	13	Date1 o Date2 è di un tipo non valido.

Se si esegue l'aggiornamento delle applicazioni Visual Basic 6.0 che utilizzano la gestione degli errori non strutturata, vedere la colonna "Numero di errore". È possibile confrontare il numero di errore con la Proprietà Number (oggetto Err). Se possibile, tuttavia, si consiglia di sostituire il controllo dell'errore con la procedura illustrata nella sezione Cenni preliminari sulla gestione strutturata delle eccezioni per Visual Basic.

Note

Utilizzare la funzione DateDiff per determinare quanti intervalli temporali specifici vi sono tra due valori data/ora. Ad esempio, è possibile utilizzare DateDiff per calcolare il numero di giorni tra due date o il numero di settimane tra la data attuale e la fine dell'anno.

Comportamento

**Gestione dei parametri.**DateDiff sottrae il valore di Date1 da quello di Date2 per ottenere la differenza. Nessuno dei due valori viene modificato nel programma chiamante.
Valori restituiti. Poiché Date1 e Date2 sono del tipo di dati Date, contengono valori di data e ora con l'accuratezza di 100 nanosecondi propria del timer di sistema. DateDiff, tuttavia, restituisce sempre il numero di intervalli di tempo come valore Long.

Se Date1 rappresenta una data e un'ora successive rispetto a Date2, DateDiff restituirà un numero negativo.
Intervalli di giorni. Se Interval è impostato su DateInterval.DayOfYear, viene considerato come DateInterval.Day poiché DayOfYear non è un'unità di misura significativa per un intervallo di tempo.

Intervalli di settimane. Se Interval è impostato su DateInterval.WeekOfYear, il valore restituito rappresenta il numero di settimane comprese tra il primo giorno della settimana contenente Date1 e il primo giorno della settimana contenente Date2. Nell'esempio riportato di seguito viene illustrato come questo produca risultati diversi da 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)

Nell'esempio precedente DateDiff restituisce 0 per wD perché la differenza tra le due date è inferiore a sette giorni, mentre restituisce 1 per wY perché tra i primi giorni delle rispettive settimane di calendario vi è una differenza di sette giorni.

Attenzione:
Quando la parte relativa all'ora di Date1 è più grande di Date2 e Interval è impostato su DateInterval.WeekOfYear, la funzione DateDiff restituisce un valore inferiore di uno rispetto al valore corretto.

Intervalli maggiori. Se Interval è impostato su DateInterval.Year, il valore restituito viene calcolato solo dalle parti di Date1 e Date2 relative all'anno. In modo analogo, il valore restituito per DateInterval.Month viene calcolato unicamente dalle parti degli argomenti relative all'anno e al mese e per DateInterval.Quarter dai trimestri che contengono le due date.

Quando ad esempio si confrontano le date 31 dicembre e 1 gennaio dell'anno seguente, DateDiff restituisce 1 per DateInterval.Year, DateInterval.Quarter o DateInterval.Month, anche se è trascorso al massimo un solo giorno.
Altri intervalli. Poiché ogni valore di Date è supportato da una struttura DateTime, i relativi metodi offrono ulteriori opzioni per l'individuazione di intervalli di tempo. È ad esempio possibile utilizzare il metodo Subtract in una delle relative versioni di overload: DateTime.Subtract sottrae un oggetto TimeSpan da una variabile Date per restituire un altro valore Date, mentre il metodo DateTime.Subtract sottrae un valore Date per restituire un oggetto TimeSpan. È possibile cronometrare un processo per determinare il numero di millisecondi impiegato, come illustrato nel seguente esempio.
```
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 Integer = runLength.Milliseconds
```

Esempio

Nell'esempio riportato di seguito la funzione DateDiff viene utilizzata per visualizzare il numero di giorni compreso tra una determinata data e la data odierna.

Dim firstDate, msg As String
Dim secondDate As Date
firstDate = InputBox("Enter a date")
secondDate = CDate(firstDate)
msg = "Days from today: " & DateDiff(DateInterval.Day, Now, secondDate)
MsgBox(msg)