Draft

Date

Author

Martin Laptev

Published

2024+236

My website serves as a demonstration of both the Quarto publishing system and the Dec measurement system. I use several clever hacks to get Quarto to display all of the dates on my website in the Dec year+day format. Knowing the basics of Dec dates will help you to understand the Quarto filter, render script, and include file examples in my Quarto article.

The year+day format is based on the Dec date equation: \(\lfloor\colorbox{yellow}{y}\rfloor{+}\colorbox{cyan}{d}{\div}\colorbox{orange}{n}{=}\colorbox{yellow}{y}\), where \(\lfloor\colorbox{yellow}{y}\rfloor{+}\colorbox{cyan}{d}\) is the Dec date, \(\lfloor\colorbox{yellow}{y}\rfloor\) is the year obtained by flooring \(\colorbox{yellow}{y}\), the decimal years that have passed since the Dec epoch (Year 0 Day 0 Dot 0), \(\colorbox{cyan}{d}\) is the zero-based day of the year, and \(\colorbox{orange}{n}\) is the number of days in \(\lfloor\colorbox{yellow}{y}\rfloor\). The Dec date equation for today is .

Dec dates only include the first two terms from the left-hand side of the Dec date equation: \(\lfloor\colorbox{yellow}{y}\rfloor\) and \(\colorbox{cyan}{d}\). The right-hand side of the equation, \(\colorbox{yellow}{y}\), can also be used as a date. We need \(\colorbox{orange}{n}\) to calculate \(\colorbox{yellow}{y}\) via the Dec date equation above and to obtain \(\colorbox{cyan}{d}\) using the Dec day of the year equation: \(\colorbox{cyan}{d}{=}\colorbox{yellow}{y}\vcenter{\text{\%}}1{\times}\colorbox{orange}{n}\). In simple terms, \(\colorbox{cyan}{d}\) is the decimal part of \(\colorbox{yellow}{y}\) multiplied by \(\colorbox{orange}{n}\).

To find \(\colorbox{orange}{n}\), we plug \(\lfloor\colorbox{yellow}{y}\rfloor\) into the Dec year length equation below, where \(\vcenter{\text\%}\) is the modulo operator, \(\land\) is the logical conjunction operator (and), and \(\lor\) is the logical disjunction operator (or). According to this equation, \(\colorbox{orange}{n}\) is 366 if the subsequent year (Year \(\lfloor\colorbox{yellow}{y}\rfloor{+}1\)) is a Gregorian calendar leap year and 365 if Year \(\lfloor\colorbox{yellow}{y}\rfloor{+}1\) is a Gregorian calendar common year.

\[\colorbox{orange}{n}=\begin{cases} 366&{\begin{align}\text{if } (\lfloor \colorbox{yellow}{y}\rfloor+1)\vcenter{\text{ \% }}4=0\\ \land(\lfloor \colorbox{yellow}{y}\rfloor+1)\vcenter{\text{ \% }}100\neq0\\ \lor(\lfloor \colorbox{yellow}{y}\rfloor+1)\vcenter{\text{ \% }}400=0\end{align}}\\\\ 365&{\text{otherwise.}}\end{cases}\]

In addition to calculating \(\colorbox{yellow}{y}\), \(\colorbox{orange}{n}\) is needed to convert between year+day and year-day Dec dates. The year-day version of the Dec date equation is \(\lfloor\colorbox{yellow}{y}\rfloor{+}1{-}(\colorbox{orange}{n}{-}\colorbox{cyan}{d}){\div}\colorbox{orange}{n}{=}\colorbox{yellow}{y}\). In essence, \(\colorbox{orange}{n}{-}\colorbox{cyan}{d}\) is a “T-minus” countdown of the days until the start of Year \(\lfloor\colorbox{yellow}{y}\rfloor{+}1\). The current year-day date, , tells us that Year will begin in days.

The difference between \(\colorbox{cyan}{d}\) and \(\colorbox{orange}{n}{-}\colorbox{cyan}{d}\) can also be explained in terms of computer programming. If we think of years as arrays, \(\colorbox{cyan}{d}\) and \(\colorbox{orange}{n}{-}\colorbox{cyan}{d}\) are like array indexes that can be used to identify array elements or combine them via slicing. In this analogy, \(\colorbox{cyan}{d}\) is a positive index with a range of \(0\) to \(\colorbox{orange}{n}{-}1\) and \(\colorbox{orange}{n}{-}\colorbox{cyan}{d}\) is a negative index that ranges from \({-}\colorbox{orange}{n}\) to \({-}1\).

To extend the array index analogy, imagine that we can use a single number to look up all of the required information for any day in the current year.

The Play▶️button below cycles🔄the range inputs beneath it through every day of the year (doty), month, and day of the month. The calendar plot beneath the range inputs highlights the doty in the top range input with a red box, distinguishes months with color, and shows the days of the week and ISO week numbers of the current year on its x- and y-axes, respectively.

First day of the week of the year

Dec dates and slices are similar to, but immeasurably more useful than, ISO 8601 ordinal dates and time intervals.

Both Dec and ISO ordinal dates consist of a year and a day of the year separated by a delimiter. ISO dates use Dec dates differ from ISO ordinal dates in their first day of the year value (0 versus 1), epoch (0000+000 versus 00-1+306), and method for determining the length of a year (applying the Gregorian calendar leap year rule to the subsequent year versus the given year).

The Dec epoch and year length determination method allow Dec days of the year to function as the equivalent of months and days of the month. Notably, Dec days of the year can represent annual events, such as birthdays. In contrast, ISO 8601 does not allow the year to be omitted and thus clumsily expresses annual events as intervals that include the full start date.

Even though some its features are incompatible with ISO 8601, Dec supports round-trip conversion to all three ISO 8601 date formats. The Mermaid flowchart below shows how the Dec date 2029+226 can be converted into many different formats. You can jump to the section dedicated to a given format by clicking on its corresponding rectangle in the flowchart.

flowchart LR
   A[UNIX time\n1890000000]<-->B[dote\n741343]
   C[Rata Die\n741038]<-->B
   D[Julian date\n2462462.5]<-->B
   subgraph ana[dote analogs]
   A
   C
   D
   end
   subgraph decalendar[Dec]
   B<-->E[date\n2029+266]
   H
   I
   end
   E<-->F[month date\n2029-11-22]
   E<-->G[ordinal date\n2029-326]
   B~~~H((leap\n0)):::empty-->B
   H---G
   B~~~I((dotw\n4)):::empty-->B
   I-->J[week date\n2029-W47-4]
   subgraph iso[ISO 8601]
   F
   G
   J
   end
   classDef empty stroke:none,fill:none;
   %% B-->H[HH:MM:SS\n00:00:00]
   style decalendar y:50px,x:190px,width:270px,height:250px;
   click A "#unix-time"
   click B "#dote"
   click C "#rata-die"
   click D "#julian-date"
   click E "#date"
   click F "#month"
   click G "#ordinal"
   click J "#week"

It is easy to convert a dote into a day of the week (dotw), UNIX timestamp, Julian date, or Rata Die fractional day.

Each of the Dec and ISO 8601 subsections showcases a function that converts one of three possible inputs, typically dote, Dec date, or ISO month date, into its eponymous format using algorithms developed by Howard Hinnant. Dote analogs, like UNIX time and Julian dates, do not have their own function because they can be created from dotes via simple arithmetic.

Dote analogs

UNIX time

UNIX time is the number of seconds since the UNIX epoch. Dec uses days instead of seconds and has a different epoch. To work with UNIX timestamps, Dec converts them into days of the era (dotes) by first turning seconds into days and then shifting the epoch to 0000+000. The reverse conversion first shifts the epoch to 1969+306 and then turns days into seconds.

\[\text{dote} = \text{UNIX} \div 86400 + 719468\]

\[\text{UNIX} = (\text{dote} - 719468) \times 86400\]

Rata Die

Rata Die (RD) fractional days are almost identical to dotes. The only difference is that the RD epoch, 0000+305, is 305 days after the Dec epoch, 0000+000. Therefore, conversion between dotes and RD fractional days is as simple as adding or subtracting 305. For more information on RD fractional days, take a look at the book entitled “Calendrical Calculations”.

\[\text{RD} = \text{dote} - 305\]

\[\text{dote} = \text{RD} + 305\]

Julian date

A Julian date is a continuous count of days since -4713+298.5. Julian dates are commonly used in astronomy. To convert a dote to a Julian date, we add 1721119.5 days to the dote to shift the epoch to Year -4713 Day 298 Dot 5. To convert a dote to a Julian date, we subtract 1721119.5 days from the Julian date to shift the epoch to Year 0 Day 0 Dot 0.

\[\text{JD} = \text{dote} + 1721119.5\]

\[\text{dote} = \text{JD} - 1721119.5\]

Dec

Dote

Dec days of the era (dotes) are useful for calendrical calculations such as obtaining the number of days in between two dates. To create a dote from a UNIX timestamp, Dec date, or ISO month date, we can use the dote function shown below. Unlike the dote function, the isow2dote and isoo2dote functions can create dotes from ISO week and ordinal dates, respectively.

Date

As shown in the code above and the equations below, the date function uses a dote to determine the cycle of the era (cote). The cote is used to calculated the day of the cycle (dotc), year of the cycle (yotc), year, and day of the year (doty). Head to the month and ordinal sections to see how the year and doty can be used to obtain ISO month and ordinal dates.

\[\text{cote} = \Biggl \lfloor \frac{\begin{cases}\text{dote}&{\text{if } \text{dote} \geq 0;}\\\text{dote}-146096&{\text{otherwise.}}\end{cases}}{146097} \Biggr \rfloor\]

\[\text{dotc} = \text{dote} - \text{cote} \cdot 146097\]

\[\text{yotc} = \biggl \lfloor \frac{\text{dotc} - \lfloor \text{dotc}{\div}{1460} \rfloor + \lfloor \text{dotc}{\div}{36524} \rfloor - \lfloor \text{dotc}{\div}{146096} \rfloor}{365} \biggr \rfloor\]

\[\text{year} = \text{yotc} + \text{cote} * 400\]

\[\text{doty} = \text{dotc} - (365 \cdot \text{yotc} + \lfloor \text{yotc}{\div}{4} \rfloor - \lfloor \text{yotc}{\div}{100} \rfloor + \lfloor \text{yotc}{\div}{400} \rfloor)\]

ISO 8601

Ordinal

On the surface, the only difference between Dec and ISO ordinal dates appears to be their delimiters (+ versus -), but they also have different first day of the year values ([0 versus 1](https://en.wikipedia.org/wiki/Zero-based_numbering#:~:h

Week

In addition to calculating \(\colorbox{orange}{n}\), Dec uses the Gregorian calendar leap year rule to convert Dec dates to and from ordinal dates, as shown in the code below.

Dec dates can also be easily converted to and from ISO 8601 month dates.

Week and dotw values vary from year to year in a pattern called the solar cycle. Dec has no need for weeks, but uses solar cycles to convert Dec dates into days of the era (dotes). A day of the era (dote) is a continuous count of days since the Dec epoch which can be used for calendrical calculations or converted into a dotw or an ISO 8601 week date as shown below.

function unix2date(unix) {
  const dote = unix / 86400 + 719468,
    socy = Math.floor((
      dote >= 0 ? dote
      : dote - 146096
    ) / 146097),
  dotc = dote - socy * 146097,
  yotc = Math.floor((dotc
    - Math.floor(dotc / 1460)
    + Math.floor(dotc / 36524)
    - Math.floor(dotc / 146096)
  ) / 365);
  return [
    yotc + socy * 400,
    dotc - (yotc * 365
      + Math.floor(yotc / 4)
      - Math.floor(yotc / 100)
  )]}
unix2date(1728000000)
unix2date(1890000000)
function unix2date(unix)
    dote = unix / 86400 + 719468
    socy = (
        dote >= 0 ? dote
        : dote - 146096
        ) ÷ 146097
    dotc = dote - socy * 146097
    yotc = (
        dotc - dotc ÷ 1460
        + dotc ÷ 36524
        - dotc ÷ 146096
    ) ÷ 365
    return Int(
        yotc + socy * 400),
    dotc - (yotc * 365
        + yotc ÷ 4
        - yotc ÷ 100)
end
unix2date(1728000000)
unix2date(1890000000)
(2029, 266.0)
function unix2date(unix)
  local dote = unix / 86400 + 719468
  local socy = (
    dote >= 0 and dote
    or dote - 146096
  ) // 146097
  local dotc = dote - socy * 146097
  local yotc = (
    dotc - dotc // 1460
    + dotc // 36524
    - dotc // 146096
  ) // 365
  return {
    math.floor(yotc + socy * 400),
    dotc - (yotc * 365
      + yotc // 4
      - yotc // 100
  )}
end
unix2date(1728000000)
unix2date(1890000000)
def unix2date(unix):
    dote = unix / 86400 + 719468
    socy = (
        dote if dote >= 0
        else dote - 146096
    ) // 146097
    dotc = dote - socy * 146097
    yotc = (dotc
        - dotc // 1460
        + dotc // 36524
        - dotc // 146096
    ) // 365
    return [
        int(yotc + socy * 400),
        dotc - (yotc * 365
            + yotc // 4
            - yotc // 100
    )]
unix2date(1728000000)
unix2date(1890000000)
unix2date <- function(unix) {
  dote = unix / 86400 + 719468
  socy = ifelse(
    dote >= 0, dote,
    dote - 146096
  ) %/% 146097
  dotc = dote - socy * 146097
  yotc = (
    dotc - dotc %/% 1460
    + dotc %/% 36524
    - dotc %/% 146096
  ) %/% 365
  c(
    yotc + socy * 400,
    dotc - (yotc * 365
      + yotc %/% 4
      - yotc %/% 100
))}
unix2date(1728000000)
unix2date(1890000000)

If we ever need to convert between a doty and a Gregorian calendar month and day of the month without any conversion tools, we can use the Dec finger mnemonic, which is similar to the knuckle mnemonic. The numbers above the fingers in the image below indicate the doty of the last day of each Gregorian calendar month. The thumb, middle finger, and pinky represent months with 31 days, whereas the index and ring fingers stand for 30-day months.

Dec finger mnemonic

Dec finger mnemonic

The southward equinox falls on Day 205 in Year 2024, 2025, 2028, and 2029. We can determine that Day 205 is September 22 by subtracting the Dec date of the last day of August (Day 183), the month preceding September, from the southward equinox doty: \(205{-}183{=}22\). To convert in the other direction, we would sum the doty and the day of the month: \(183{+}22{=}205\).

The finger mnemonic highlights a major difference between Dec and the Gregorian calendar: the Dec year starts on Day 0 just like the Roman calendar, the predecessor of the Gregorian and Julian calendars. For this reason, the Latin numeral prefixes in the names of the months of September, October, November, and December match their one-based indexes (7, 8, 9, and 10) in Dec and the Roman calendar, but not in the Julian or Gregorian calendars.

The knuckle and finger mnemonics attempt to make sense of the irregular pattern of month lengths in the Gregorian calendar. Rather than replace variable-length months with fixed-length months, Dec forgoes the use of months entirely and instead uses groups of ten days called deks.

I generate all of the dates on my site from UNIX time using calculations that I adapted from the civil_from_days function in Howard Hinnant’s date library. Each tab in the tabset panel below shows a different implementation of a function called unix2date which converts UNIX time into year+day dates.

In this function, socy is an abbreviation for solar cycle and dote, dotc, and yotc are acronyms for “day of the era”, “day of the cycle”, and “day of the cycle”, respectively. A solar cycle in the Gregorian calendar is 400 years. A calendar era is the time that has passed since a starting point called a calendar epoch. The Dec epoch is Year 0 Day 0.

I use different programming languages to convert UNIX time in various places on my site. More specifically, I use a Python post-render script (date.py) for the dates on the page that lists all of the articles on my site, a Lua filter (date.lua) for the PUBLISHED date at the top of each article, and an include-after-body file that sources a JavaScript file (stamp.js) for the date in the above. citation information at the bottom of each article.

Back to top

Citation

BibTeX citation:
@online{laptev2024,
  author = {Laptev, Martin},
  title = {Date},
  date = {2024},
  urldate = {2024},
  url = {https://maptv.github.io/dec/date},
  langid = {en}
}
For attribution, please cite this work as:
Laptev, Martin. 2024. “Date.” 2024. https://maptv.github.io/dec/date.