Etape 2 – Dates et heures

Pour passer d'une date grégorienne exprimée sous la forme d'un triplet (jour, mois, année), ici anglicisé et abrégé \((d, m, y)\), en un nombre de jour \(n\), on utilise la fonction \(g\) définie ainsi :

\[g(d, m, y) = 365\cdot y_0 + y_0 \bdiv 4 - y_0 \bdiv 100 + y_0 \bdiv 400\\ + (367\cdot m - 362) \bdiv 12 + c + d \] où \(y_0 = y - 1\) et \(c\) est un terme correctif défini ainsi :

Notez que l'expression \(l\) est vraie si et seulement si l'année \(y\) est bissextile.

Au moyen de la formule ci-dessus, on peut aisément calculer l'entier correspondant au 17 février 2014, \(g(17, 2, 2014)\), qui vaut 735281.

Pour passer d'un nombre de jours \(n\) en une date grégorienne exprimée sous la forme d'un triplet \((d, m, y)\), on utilise les formules ci-dessous.

Pour commencer, l'année \(y\) se calcule ainsi :

\[y = \begin{cases} y_0 & \text{si } n_{100} = 4 \text{ ou } n_1 = 4\\ y_0 + 1 & \text{sinon} \end{cases} \] où :

Le mois \(m\) du calendrier grégorien peut être calculé au moyen de la formule suivante :

\[ m = \left(12\cdot(p + c) + 373\right) \bdiv 367 \] où \(p\) est le nombre de jours écoulés depuis le début de l'année, et \(c\) est un terme correctif, calculés ainsi :

Notez l'utilisation dans ces formules de la fonction \(g\) définie dans la section précédente.

Finalement, le jour \(d\) peut être calculé au moyen de la formule suivante :

\[ d = n - g(1, m, y) + 1 \]

Au moyen de ces formules, on peut calculer les valeurs de \(d\), \(m\) et \(y\) lorsque \(n\) vaut 735281 et vérifier qu'on obtient bien 17, 2 et 2014 (dans cet ordre).

Comme mentionné brièvement plus haut, il existe plusieurs définitions possibles de la division entière, et donc de son reste. Deux d'entre-elles doivent être mentionnées ici : la division tronquée et la division par défaut.

La division (entière) tronquée d'un numérateur \(n\) par un dénominateur \(d\), notée \(n \bdiv_{\rm T} d\), et son reste, noté \(n \bmod_{\rm T} d\), sont définis ainsi :

où \(\trunc(x)\) est la troncature de \(x\), c-à-d \(x\) amputé de ses décimales.

La division (entière) par défaut d'un numérateur \(n\) par un dénominateur \(d\), notée \(n\bdiv_{\rm F} d\), et son reste, noté \(n \bmod_{\rm F} d\), sont définis quant à eux ainsi :

où \(\left\lfloor x\right\rfloor\) est la partie entière par défaut (floor en anglais) de \(x\).

Comme on le voit, la seule différence entre les deux formes de division est la fonction utilisée pour transformer le résultat de la division réelle en un entier. Pour les nombres positifs, les deux donnent le même résultat. Par contre, pour les nombres négatifs, ce n'est pas le cas puisque la troncation et la partie entière par défaut diffèrent. Par exemple, \(\trunc(-1.9) = -1\) alors que \(\left\lfloor -1.9\right\rfloor = -2\).

La division par défaut est mathématiquement supérieure à la division tronquée, dans le sens où elle possède plus de propriétés intéressantes. Toutes les formules de calcul de dates données plus haut tirent justement parti de ces propriétés, et ne sont correctes que si la division par défaut, et son reste, sont utilisés.

Malheureusement, comme on le verra plus loin, Java n'offre que la division tronquée. Cela n'est toutefois pas très problématique car il est facile de calculer le quotient \(q_F\) de la division par défaut d'un numérateur \(n\) par un dénominateur \(d\), de même que son reste \(r_F\), en fonction du quotient de la division tronquée, \(q_T\), et de son reste \(r_T\) :

où :

La fonction \(\sgn\) est la fonction signe, définie ainsi :

Assez logiquement, les fonctions liées à la division entière par défaut s'ajoutent comme méthodes publiques statiques à la classe Math commencée lors de la séance précédente :

• int divF(int n, int d) retourne le quotient de la division par défaut de n par d.
• int modF(int n, int d) retourne le reste de la division par défaut de n par d.

Java fournit déjà les opérateurs / et % pour calculer le quotient et le reste de la division tronquée, respectivement. En les utilisant, il est facile d'écrire les deux méthodes sus-mentionnées.

A noter que la fonction signe (notée \(\sgn\) plus haut) est fournie en Java sous la forme de la fonction (statique) signum de la classe Integer.

La classe Date contient deux énumérations publiques :

• DayOfWeek, qui énumère les jours de la semaine, du lundi au dimanche, en anglais et en majuscules (MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY).
• Month, qui énumère les mois de l'année du calendrier grégorien, de janvier à décembre, en anglais et en majuscules (JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER).

La classe Date possède trois constructeurs publics :

• Date(int day, Month month, int year), qui construit une date du calendrier grégorien étant donnés un jour, un mois et une année. Lève l'exception IllegalArgumentException si le jour est invalide, c-à-d inférieur à 1 ou supérieur au nombre de jours dans le mois donné.
• Date(int day, int month, int year), qui construit une date du calendrier grégorien étant donnés un jour, un numéro de mois et une année. Lève l'exception IllegalArgumentException si le jour est invalide (voir ci-dessus) ou si le numéro de mois est invalide, c-à-d hors de l'intervalle [1;12].
• Date(java.util.Date date), qui construit une date en fonction d'une date Java, c-à-d d'une instance de la classe java.util.Date.

Le premier de ces trois constructeurs est le constructeur principal, ce qui signifie que les deux autres ne doivent rien faire d'autre que de l'appeler avec les bons paramètres.

En plus de ces trois constructeurs, la classe Date possède les méthodes publiques suivantes :

• int day(), qui retourne le jour du mois de la date, compris entre 1 et 31.
• Month month(), qui retourne le mois de la date.
• int intMonth(), qui retourne le mois de la date sous forme d'entier (1 pour janvier, 2 pour février, etc.).
• int year(), qui retourne l'année de la date.
• DayOfWeek dayOfWeek(), qui retourne le jour de la semaine de la date.
• Date relative(int daysDiff), qui retourne la date distante du nombre de jours donnés de la date à laquelle on l'applique. Par exemple, en appelant relative avec le paramètre 1 on obtient la date du lendemain, avec -1 celle du jour précédent, etc.
• java.util.Date toJavaDate(), qui retourne la date Java (c-à-d une instance de java.util.Date) correspondant à cette date.
• String toString(), qui retourne la représentation textuelle de la date, qui doit être formée de l'année, du numéro du mois (sur deux chiffres) et du jour (sur deux chiffres), séparés par un tiret (-). Par exemple, la représentation textuelle du 17 février 2014 doit être 2014-02-17. Redéfinit la méthode toString héritée de Object.
• boolean equals(Object that), qui compare la date à laquelle on l'applique avec l'objet passé en argument et qui retourne vrai si et seulement si cet objet est une date (c-à-d une instance de ch.epfl.isochrone.timetable.Date) désignant le même jour. Redéfinit la méthode equals héritée de Object.
• int hashCode(), qui retourne l'entier correspondant à la date. (Comme nous n'avons pas encore examiné les tables de hachage dans le cours, il est difficile d'expliquer ici l'utilité de cette méthode. Contentez-vous pour l'instant de l'écrire, vous comprendrez son but dans quelques semaines.) Redéfinit la méthode hashCode héritée de Object.
• int compareTo(Date that), qui compare la date à laquelle on l'applique avec la date passée en argument et qui retourne -1 lorsque la première est strictement inférieure à la seconde, 0 lorsque les deux sont égales, et 1 lorsque la première est strictement supérieure à la seconde.

En interne, la classe Date doit bien entendu stocker une représentation du jour qu'elle désigne. Comme dit plus haut, cela peut se faire de différentes manières : on peut soit stocker les trois valeurs (jour, mois, année), ou alors un simple entier représentant le nombre de jours écoulés depuis le 1^er janvier de l'an 1.

Nous vous conseillons ici de choisir la première de ces deux solutions, et donc d'équiper la classe Date de trois champs privés et finaux contenant le jour (type int), le mois (type Month) et l'année (type int). Mais vous êtes libres de choisir l'autre représentation interne si vous le préférez, la seule chose qui importe est que l'interface publique de votre classe soit conforme à la description ci-dessus.

A noter que, quelle que soit la solution que vous choisissez, vous devrez à un moment ou à un autre effectuer la transformation entre les deux représentations. En effet, certaines méthodes (p.ex. day ou month) requièrent la représentation (jour, mois, année), tandis que d'autres (p.ex. relative, equals ou compareTo) sont beaucoup plus simples à écrire avec la représentation sous forme d'entier.

Indépendemment de la représentation interne que vous choisissez, nous vous suggérons d'ajouter les méthodes statiques privées suivantes à votre classe. Elles facilitent grandement l'écriture des constructeurs et/ou méthodes publiques :

• Month intToMonth(int m), qui transforme un numéro de mois en mois, avec la convention que l'entier 1 correspond au mois de janvier, l'entier 2 au mois de février, et ainsi de suite. Lève l'exception IllegalArgumentException si le numéro de mois est invalide, c-à-d hors de l'intervalle [1;12].
• int monthToInt(Month m), l'inverse de la méthode intToMonth, qui transforme un mois en numéro de mois.
• boolean isLeapYear(int y), qui retourne vrai si et seulement si l'année passée en argument est bissextile (voir la formule pour \(l\) donnée plus haut).
• int daysInMonth(Month m, int y), qui retourne le nombre de jours dans le mois m de l'année y. Attention à bien retourner 29 pour le mois de février des années bissextiles !
• int dateToFixed(int d, Month m, int y), qui transforme un triplet de valeurs (jour, mois, année) en un entier. Il s'agit simplement de la fonction \(g\) décrites plus haut.
• Date fixedToDate(int n), l'inverse de la méthode dateToFixed, qui transforme un entier en date du calendrier grégorien.

En plus de ces méthodes statiques, il est recommandé d'offrir la méthode privée suivante :

• int fixed(), qui retourne la date sous forme d'un entier. Cette méthode consiste en un simple appel à la méthode dateToFixed décrite ci-dessus, mais s'avère bien utile en pratique.

En écrivant le code qui manipule les dates Java (java.util.Date), vous constaterez que plusieurs méthodes et constructeurs de cette classe, p.ex. la méthode getYear, sont marqués deprecated. Cela signifie que ces entités sont obsolètes et que leur utilisation est désormais déconseillée, ce qu'Eclipse indique en raturant leur nom. Nous vous conseillons néanmoins de les utiliser ici, exceptionnellement, dans le but de simplifier les choses.

La classe SecondsPastMidnight possède un champ public statique final :

• int INFINITE, qui contient la valeur 200000, un nombre de secondes après minuit qui est garanti plus grand que toutes les valeurs valides. En effet, les fonctions ci-dessous bornent l'heure à 30, donc le plus grand nombre de secondes après minuit valide est 29 h 59 min 59 s, soit 107999 secondes.

Cette classe possède de plus les méthodes publiques et statiques suivantes :

• int fromHMS(int hours, int minutes, int seconds), qui convertit un triplet (heure, minutes, secondes) en un nombre de secondes après minuit. Par exemple, le triplet (9, 15, 33), à savoir 9 h 15 min 33 s, est converti en l'entier 33333. Lève l'exception IllegalArgumentException si l'une des trois valeurs est invalide. Les secondes et les minutes sont valides si elles sont comprises dans l'intervalle [0;60[. Quant aux heures, elles sont valides si elles sont comprises dans l'intervalle [0;30[ (la borne supérieure de cet intervalle est quelque peu arbitraire).
• int fromJavaDate(java.util.Date date), qui convertit l'heure d'une date Java (c-à-d une instance de java.util.Date) en un nombre de secondes après minuit.
• int hours(int spm), qui retourne le nombre d'heures de l'heure (représentée par un nombre de secondes après minuit) passée en argument. Par exemple, appliqué à 33333, cette méthode retourne 9. Lève l'exception IllegalArgumentException si le nombre de secondes après minuit passé en argument est négatif ou représente une heure au-delà de 29 h 59 min 59 s.
• int minutes(int spm), qui retourne le nombre de minutes de l'heure (représentée par un nombre de secondes après minuit) passée en argument. Par exemple, appliqué à 33333, cette méthode retourne 15. Lève l'exception IllegalArgumentException si le nombre de secondes après minuit passé en argument est négatif ou représente une heure au-delà de 29 h 59 min 59 s.
• int seconds(int spm), qui retourne le nombre de secondes de l'heure (représentée par un nombre de secondes après minuit) passée en argument. Par exemple, appliqué à 33333, cette méthode retourne 33. Lève l'exception IllegalArgumentException si le nombre de secondes après minuit passé en argument est négatif ou représente une heure au-delà de 29 h 59 min 59 s.
• String toString(int spm), qui retourne la représentation textuelle du nombre de secondes après minuit passé en argument. Cette représentation consiste en un nombre d'heures, de minutes et de secondes, chacun représenté par deux chiffres, séparés par un double point (:). Par exemple, appliquée à 33333, cette méthode doit retourner la chaîne 09:15:33. Lève l'exception IllegalArgumentException si le nombre de secondes après minuit passé en argument est négatif ou représente une heure au-delà de 29 h 59 min 59 s.

Tout comme la classe Math de l'étape précédente, la classe SecondsPastMidnight ne doit pas être instantiable, et il faut donc également l'équiper d'un constructeur par défaut vide et privé.

Pour écrire la méthode toString, il faut pouvoir formatter un nombre sur deux chiffres, avec un éventuel zéro en tête. La manière la plus simple de faire cela consiste à utiliser la méthode statique format de la classe String. Le premier argument de cette méthode est une chaîne de formattage qui décrit comment représenter la valeur des arguments qui suivent. La syntaxe de cette chaîne de formattage est documentée, mais comme elle est assez complexe, voici un exemple d'utilisation qui devrait vous aider :

String.format("%02d:%02d:%02d", 3, 8, 11);

Cet appel produit la chaîne 03:08:11, car chacune des trois occurrences du texte %02d dans la chaîne de formattage spécifie que le prochain argument doit être représentée sous forme décimale (le d), sur une largeur de 2 caractères et avec un éventuel 0 au début.