As nossas ferramentas de data e hora apoiam-se no calendário gregoriano proléptico, na regra de Zeller para o dia da semana e na ISO 8601 para representação e numeração de semanas. Esta página documenta as fórmulas que aplicamos, as normas que seguimos e os casos extremos (dias bissextos, segundos intercalares, transições da hora de verão, convenções locais de dias da semana) que tratamos explicitamente, para que os resultados se mantenham reprodutíveis e verificáveis.
Um ano é bissexto se for divisível por 4, exceto os anos seculares, que têm também de ser divisíveis por 400. Por isso, 2000 é bissexto, mas 1900 e 2100 não. Aplicamos esta regra de forma proléptica, isto é, estendemo-la para trás de 1582, garantindo aritmética consistente em intervalos de datas longos.
Para mapear uma data gregoriana num dia da semana sem iteração, usamos a congruência de Zeller: h = (q + floor(13(m+1)/5) + K + floor(K/4) + floor(J/4) + 5J) mod 7, sendo janeiro e fevereiro tratados como meses 13 e 14 do ano anterior. O resultado é depois normalizado para a numeração ISO, em que segunda-feira é 1 e domingo é 7.
Apresentamos as datas canónicas como AAAA-MM-DD e as combinações data-hora como AAAA-MM-DDTHH:MM:SS com um desvio explícito (Z para UTC, ±HH:MM caso contrário). Este formato é inequívoco entre idiomas, ordena-se lexicograficamente em ordem cronológica e corresponde ao formato que a maioria das APIs e bases de dados armazena nativamente.
Os dias úteis excluem sábado e domingo. Permitimos ao utilizador excluir opcionalmente uma lista de feriados, aplicada após o filtro de fim de semana. Em intervalos que cobrem meses ou anos, contamos por iteração de semanas inteiras mais um resto, para que intervalos muito longos permaneçam em O(1) por cálculo, em vez de percorrer todos os dias.
As semanas ISO começam à segunda-feira e a semana 1 do ano é a que contém a primeira quinta-feira (de forma equivalente, a que contém o dia 4 de janeiro). Assim, os anos têm 52 ou 53 semanas ISO, e os primeiros ou últimos dias de um ano gregoriano podem pertencer a um ano-semana ISO adjacente. Identificamos tais datas como AAAA-Www-D usando o ano-semana ISO, e não o ano civil.
Todos os instantes são armazenados em UTC. O UTC é mantido pelo BIPM em cooperação com os laboratórios nacionais de tempo, e os segundos intercalares são anunciados pelo Boletim C do IERS quando necessário, para manter o UTC dentro de 0,9 segundos do UT1. A nossa aritmética de duração assume 86 400 segundos SI por dia e não insere segundos intercalares, o que está alinhado com o comportamento do tempo POSIX e da maioria dos sistemas operativos.
A lógica do calendário é coberta por testes unitários que incluem anos bissextos (1900, 2000, 2024), fronteiras de ano-semana ISO (29 de dezembro a 3 de janeiro) e dias de mudança da hora de verão em ambos os hemisférios. Quando o IERS anuncia um novo segundo intercalar, atualizamos a documentação interna, mas mantemos a aritmética UTC inalterada, porque a expectativa dos utilizadores para dias e horas decorridos coincide com o modelo POSIX. Reverificamos esta página de metodologia após cada alteração à ISO 8601 e, no mínimo, uma vez por ano civil.
