DateDiff, fonction (Visual Basic)

Article
08/21/2008

Mise à jour : novembre 2007

Retourne une valeur de type Long spécifiant le nombre d'intervalles de temps entre deux valeurs 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

Paramètres

Interval
Requis. Valeur d'énumération DateInterval ou expression String représentant l'intervalle de temps que vous souhaitez utiliser comme unité de la différence entre Date1 et Date2.
Date1
Requis. Date. La première valeur de date/d'heure que vous souhaitez utiliser dans le calcul.
Date2
Requis. Date. La deuxième valeur de date/d'heure que vous souhaitez utiliser dans le calcul.
DayOfWeek
Facultatif. Valeur choisie dans l'énumération FirstDayOfWeek qui spécifie le premier jour de la semaine. Si elle n'est pas spécifiée, FirstDayOfWeek.Sunday est utilisé.
WeekOfYear
Facultatif. Valeur choisie dans l'énumération FirstWeekOfYear qui spécifie la première semaine de l'année. Si elle n'est pas spécifiée, FirstWeekOfYear.Jan1 est utilisé.

Paramètres

L'argument Interval peut prendre l'une des valeurs suivantes :

Valeur d'énumération	Valeur de chaîne	Unité de la différence de temps
DateInterval.Day	"d"	Jour
DateInterval.DayOfYear	"y"	Jour
DateInterval.Hour	"h"	Heure
DateInterval.Minute	"n"	Minute
DateInterval.Month	"m"	Mois
DateInterval.Quarter	"q"	Trimestre
DateInterval.Second	"s"	Seconde
DateInterval.Weekday	"w"	Semaine
DateInterval.WeekOfYear	"ww"	Semaine du calendrier
DateInterval.Year	"yyyy"	Année

L'argument DayOfWeek peut prendre l'une des valeurs suivantes :

Valeur d'énumération	Valeur	Description
FirstDayOfWeek.System	0	Premier jour de la semaine spécifiée dans les paramètres système
FirstDayOfWeek.Sunday	1	Dimanche (valeur par défaut)
FirstDayOfWeek.Monday	2	Lundi (conformément à la norme ISO 8601, section 3.17)
FirstDayOfWeek.Tuesday	3	Mardi
FirstDayOfWeek.Wednesday	4	Mercredi
FirstDayOfWeek.Thursday	5	Jeudi
FirstDayOfWeek.Friday	6	Vendredi
FirstDayOfWeek.Saturday	7	Samedi

L'argument WeekOfYear peut prendre l'une des valeurs suivantes :

Valeur d'énumération	Valeur	Description
FirstWeekOfYear.System	0	Première semaine de l'année spécifiée dans les paramètres système
FirstWeekOfYear.Jan1	1	Semaine comprenant le 1er janvier (valeur par défaut).
FirstWeekOfYear.FirstFourDays	2	Semaine comprenant au moins 4 jours de la nouvelle année (conformément à la norme ISO 8601, section 3.17)
FirstWeekOfYear.FirstFullWeek	3	Première semaine entière de la nouvelle année

Exceptions

Type d'exception	Numéro de l'erreur	Condition
ArgumentException	5	Interval non valide.
ArgumentException	5	Date1, Date2, or DayofWeek est hors limites.
InvalidCastException	13	Date1 ou Date2 est d'un type non valide.

Consultez la colonne « Numéro d'erreur » si vous mettez à niveau des applications Visual Basic 6.0 qui utilisent la gestion non structurée des erreurs. (Vous pouvez comparer le numéro d'erreur par rapport à Number, propriété (objet Err).) Toutefois, lorsque cela est possible, vous devez envisager de remplacer un tel contrôle d'erreur par Vue d'ensemble de la gestion structurée des exceptions pour Visual Basic.

Notes

Utilisez la fonction DateDiff pour déterminer le nombre d'intervalles de temps spécifiés entre deux valeurs date/heure. Par exemple, utilisez DateDiff pour calculer le nombre de jours entre deux dates ou le nombre de semaines entre la date d'aujourd'hui et la fin de l'année.

Comportement

**Traitement des paramètres.**DateDiff soustrait la valeur de Date1 de la valeur de Date2 pour obtenir la différence. Aucune de ces valeurs n'est modifiée dans le programme appelant.
Valeurs de retour Dans la mesure où Date1 et Date2 appartiennent au type de données Date, ils contiennent des valeurs de date et d'heure d'une précision de 100 nanosecondes par rapport à l'horloge système. Cependant, DateDiff retourne toujours le nombre d'intervalles de temps sous forme d'une valeur Long.

Si Date1 représente une date et une heure ultérieures à Date2, DateDiff retourne un nombre négatif.
Intervalles estimés en jours. Si Interval a la valeur DateInterval.DayOfYear, il est traité de la même façon que DateInterval.Day, parce que DayOfYear n'est pas une unité appropriée pour un intervalle de temps.

Intervalles estimés en semaines. Si Interval a la valeur DateInterval.WeekOfYear, la valeur de retour représente le nombre de semaines écoulées entre le premier jour de la semaine contenant Date1 et le premier jour de la semaine contenant Date2. L'exemple ci-dessous illustre les différents résultats obtenus 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)

Dans l'exemple précédent, DateDiff retourne 0 à wD parce que la différence entre les dates est inférieure à sept jours, mais retourne 1 à wY parce qu'il existe une différence de sept jours entre les premiers jours des semaines de calendrier respectives.

Attention :
Lorsque la partie d'heure de Date1 est supérieure à celle de Date2 et que Interval a la valeur DateInterval.WeekOfYear, la fonction DateDiff retourne une valeur qui est inférieure de un par rapport à la valeur correcte.

Intervalles plus grands. Si Interval a la valeur DateInterval.Year, la valeur de retour est calculée exclusivement à partir des parties année de Date1 et Date2. De la même façon, la valeur de retour de DateInterval.Month est calculée exclusivement à partir des parties année et des parties mois des arguments et de celles de DateInterval.Quarter à partir des trimestres qui contiennent les deux dates.

Par exemple, en comparant le 31 décembre au 1er janvier de l'année suivante, DateDiff retourne 1 pour DateInterval.Year, DateInterval.Quarter ou DateInterval.Month, bien qu'un seul jour se soit écoulé.
Autres intervalles. Étant donné que chaque valeur Date est prise en charge par une structure DateTime, ses méthodes vous donnent des possibilités supplémentaires pour déterminer des intervalles de temps. Par exemple, vous pouvez utiliser la méthode Subtract dans l'une ou l'autre de ses formes surchargés : DateTime.Subtract soustrait un TimeSpan d'une variable Date pour retourner une autre valeur Date et DateTime.Subtract soustrait une valeur Date pour retourner un TimeSpan. Vous pouvez mesurer la durée d'un processus en millisecondes, comme dans l'exemple suivant.
```
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
```

Exemple

Cet exemple utilise la fonction DateDiff pour afficher le nombre de jours entre une date donnée et la date du jour.

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)