I nostri strumenti per date e ore si basano sul calendario gregoriano prolettico, sulla regola dei giorni della settimana di Zeller e sullo standard ISO 8601 per la rappresentazione e la numerazione delle settimane. Questa pagina documenta le formule applicate, gli standard seguiti e i casi limite (giorni bisestili, secondi intercalari, transizioni dell'ora legale, convenzioni locali per i giorni della settimana) che gestiamo esplicitamente perché i risultati restino riproducibili e verificabili.
Un anno è bisestile se è divisibile per 4, eccetto per gli anni di secolo, che devono essere divisibili anche per 400. Quindi il 2000 è bisestile, mentre il 1900 e il 2100 non lo sono. Applichiamo questa regola in modo prolettico, cioè la estendiamo all'indietro anche prima del 1582 per garantire coerenza aritmetica su lunghi intervalli temporali.
Per mappare una data gregoriana al giorno della settimana senza iterare, usiamo la congruenza di Zeller: h = (q + floor(13(m+1)/5) + K + floor(K/4) + floor(J/4) + 5J) mod 7, dove gennaio e febbraio sono trattati come mesi 13 e 14 dell'anno precedente. L'output è poi normalizzato alla numerazione dei giorni ISO, in cui lunedì è 1 e domenica è 7.
Mostriamo le date canoniche come YYYY-MM-DD e le date-ora combinate come YYYY-MM-DDTHH:MM:SS con offset esplicito (Z per UTC, ±HH:MM altrimenti). È un formato non ambiguo tra le diverse localizzazioni, si ordina lessicograficamente in ordine cronologico e corrisponde al formato che la maggior parte di API e database memorizza nativamente.
I giorni lavorativi escludono il sabato e la domenica. Permettiamo agli utenti di escludere facoltativamente un elenco di festività, applicato dopo il filtro del fine settimana. Per intervalli che attraversano mesi o anni contiamo iterando settimane intere più un resto, in modo che intervalli molto lunghi restino O(1) per calcolo invece di scorrere ogni singolo giorno.
Le settimane ISO iniziano di lunedì e la settimana 1 di un anno è quella che contiene il primo giovedì (equivalentemente, la settimana che contiene il 4 gennaio). Gli anni hanno quindi 52 o 53 settimane ISO e i primi o gli ultimi giorni di un anno gregoriano possono appartenere a una settimana-anno ISO adiacente. Etichettiamo queste date come YYYY-Www-D usando la settimana-anno ISO, non l'anno di calendario.
Tutti gli istanti sono memorizzati in UTC. UTC è mantenuto dal BIPM in cooperazione con i laboratori metrologici nazionali e i secondi intercalari sono annunciati dal Bollettino C dell'IERS quando necessario per mantenere UTC entro 0,9 secondi da UT1. La nostra aritmetica delle durate assume 86.400 secondi SI per giorno e non inserisce i secondi intercalari, in linea con il comportamento del tempo POSIX e della maggior parte dei sistemi operativi.
La logica del calendario è coperta da test automatici che includono anni bisestili (1900, 2000, 2024), confini di settimana-anno ISO (dal 29 dicembre al 3 gennaio) e giorni di transizione dell'ora legale in entrambi gli emisferi. Quando l'IERS annuncia un nuovo secondo intercalare, aggiorniamo la documentazione interna ma lasciamo invariata l'aritmetica UTC, perché le aspettative degli utenti sul calcolo di giorni e ore trascorse coincidono con il modello POSIX. Ricontrolliamo questa pagina di metodologia dopo ogni revisione di ISO 8601 e comunque almeno una volta all'anno.
