Fraction de l’année écoulée

Il convertit en UTC l’heure accompagnée de Z ou d’un décalage numérique, mesure exactement les millisecondes depuis le 1er janvier à 00:00:00 UTC, puis divise cette durée par celle de l’année UTC obtenue. Une année bissextile compte 366 jours, contre 365 pour une année commune. La date actuelle, le fuseau local, le réseau, le hasard et les valeurs implicites ne peuvent pas modifier le résultat.

Définition de la fraction d’année écoulée

La fraction renvoyée mesure en continu la progression dans une année civile UTC. Son numérateur est le nombre de millisecondes entre le 1er janvier à 00:00:00.000 UTC et l’instant fourni ; son dénominateur est le nombre de millisecondes de toute cette année UTC. Au premier instant du 1er janvier, le résultat vaut exactement zéro. Il augmente ensuite pendant l’année, tout en restant inférieur à un pour chaque date-heure valide de cette année. La valeur un correspond au premier instant de l’année suivante, qui appartient déjà à une nouvelle année et relance le calcul à zéro. Cette définition diffère d’un pourcentage fondé sur le rang du jour, qui compterait des dates entières ou considérerait la journée en cours comme terminée. Midi représente la moitié de la date, les secondes apportent leur part exacte et jusqu’à trois décimales de seconde sont conservées sous forme de millisecondes. Le dénominateur vaut 365 jours pour une année commune et 366 pour une année bissextile grégorienne. Le décalage étant normalisé avant le choix de l’année UTC, une heure écrite tard le 31 décembre dans un autre fuseau peut appartenir au 1er janvier UTC suivant.

Fournir une date-heure ISO sans ambiguïté

Envoyez datetime sous la forme YYYY-MM-DDTHH:mm:ssZ. Vous pouvez ajouter une à trois décimales de seconde ou remplacer Z par un décalage signé comme +05:30 ou -04:00. L’indication du fuseau est obligatoire, car une date-heure qui en est dépourvue ne désigne pas un instant unique. Les dates seules, les formats locaux, les noms de mois, les espaces à la place de T et les décalages sans deux-points sont refusés plutôt qu’interprétés arbitrairement. L’analyseur contrôle aussi la longueur des mois grégoriens, les jours bissextiles, les heures, les minutes, les secondes et les composantes du décalage. Les secondes intercalaires ne sont pas acceptées : les secondes vont de 00 à 59, conformément au modèle déterministe de minute civile. Après analyse, le décalage est appliqué par calcul entier et l’instant obtenu apparaît dans utc_datetime. La réponse fournit aussi utc_year, elapsed_milliseconds et year_milliseconds afin que vous puissiez vérifier la fraction sans réimplémenter le calendrier. Deux chaînes représentant le même instant avec des décalages différents donnent la même date normalisée et la même fraction. Une requête automatisée réussie coûte $0.002 ; le calcul peut également s’exécuter localement dans le navigateur.

Usages d’un rapport annuel déterministe

Utilisez cette capacité lorsqu’un modèle, une visualisation, un rapport ou un test exige une position stable dans l’année civile, et non une réponse dépendant de l’heure d’exécution d’une machine. Un tableau de bord peut convertir la fraction en pourcentage ou en barre de progression tout en conservant le numérateur et le dénominateur exacts pour les libellés et les audits. Un pipeline de données peut enrichir des enregistrements horodatés avec une coordonnée annuelle normalisée destinée à l’analyse saisonnière, à l’interpolation ou aux variables cycliques, puisque les entrées décalées sont comparées sur la même chronologie UTC. Les tests peuvent figer des cas limites au Nouvel An, le jour bissextile ou à la dernière milliseconde de décembre sans simuler d’horloge. Le résultat repose sur une durée écoulée : il ne convient donc pas au décompte des dates achevées, des jours ouvrés, des exercices fiscaux ou de mois supposés égaux. Il modélise volontairement les jours civils UTC comme 86 400 secondes et n’ajoute aucune seconde intercalaire, ce qui garantit sa portabilité. Pour obtenir un pourcentage, multipliez fraction par cent et n’arrondissez qu’à l’affichage. Pour un exercice fiscal, employez les bornes du calendrier concerné.