{"id":18573613,"url":"https://github.com/soroush/libcalendars","last_synced_at":"2025-04-10T07:32:17.002Z","repository":{"id":141416214,"uuid":"101681860","full_name":"soroush/libcalendars","owner":"soroush","description":"Collection of calendar arithmetic algorithms","archived":false,"fork":false,"pushed_at":"2025-01-03T14:44:48.000Z","size":24276,"stargazers_count":46,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2025-03-24T18:12:15.809Z","etag":null,"topics":["calendar","calendar-library","gregorian","hijri","hijri-calendar","jalali","jalali-calendar","shamsi"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soroush.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-28T19:51:36.000Z","updated_at":"2025-01-03T14:44:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"743f0dd7-1afe-429b-80e4-444892d860f8","html_url":"https://github.com/soroush/libcalendars","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soroush%2Flibcalendars","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soroush%2Flibcalendars/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soroush%2Flibcalendars/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soroush%2Flibcalendars/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soroush","download_url":"https://codeload.github.com/soroush/libcalendars/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248176460,"owners_count":21060068,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","calendar-library","gregorian","hijri","hijri-calendar","jalali","jalali-calendar","shamsi"],"created_at":"2024-11-06T23:11:13.973Z","updated_at":"2025-04-10T07:32:16.986Z","avatar_url":"https://github.com/soroush.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"A calendar implementation library\n*********************************\n\n   `libcalendar' is an experimental C library to provide arithmentic for \nseveral calendars.\n\nWhy?\n====\n\n   Why implement yet another calendaring library? Well, there are plenty of \nexcellent implementations out there, though it seems there is no free, \nGPL-compliant, C implementation. Besides there is no precise implementation of \nnon-gregorian calendars, most importantly Solar Hijri and Islamic Civil \ncalendars.\n\nAPI Design Philosophy\n=====================\n\n    This library is API-less by design. This means the library is not intended\nto be used directly as a standalone API. Instead, it only provides arithmetic\nimplementations meant to be integrated into existing date-time APIs or utilized\nby developers when creating their own APIs for handling date-time\noperations.\n\nKey Principles:\n\n* No Custom Data Structures: The library\ndeliberately avoids introducing structures for representing calendar components\n(e.g., `year`, `month`, `day`). Instead, it operates exclusively on Plain Data\nTypes (PDTs), such as integers or other native types, ensuring simplicity and\ncompatibility with diverse applications.\n\n* Flexibility: By focusing solely on\nthe arithmetic logic, the library provides a robust foundation for building or\nextending higher-level APIs. This design empowers developers to adapt the\nlibrary seamlessly to their specific domain requirements without being\nconstrained by predefined abstractions.\n\n* Integration-Ready: The library\ncomplements existing date-time APIs by adding precise calendar arithmetic\ncapabilities without altering their design philosophy. It can also be used to\nprototype and implement custom solutions efficiently.\n\nHow to use libcalendar?\n=======================\n\nAlmost all algorithms in libcalendar are implemented using Julian Day \ncalculations. You can convert any date on supported calendars to JDN and vice \nversa. For example:\n\n    uint32_t jdn = 0;\n    sh_to_jdn(\u0026jdn, 1392, 04, 15);\n    printf(\"Julian Day for 1392/04/15 AP is: %l\\n\", jdn);\n    \nWhich prints:\n\n    $ Julian Day for 1392/04/15 AP is: 2456480\n\n   You can also use non-jdn broken-down date API. For example you can check if a \nyear in Solar Hijri calendar is leap or not:\n\n\n   if(sh_is_leap(1395)) /* returns 0 for regular years and 1 for leap years */\n       printf(\"Yep\\n\");\n\nOr convert calendar dates to/from Gregorian calendar:\n\n    int16_t y;\n    uint8_t m;\n    uint16_t d;\n    sh_to_gr(1369, 06, 20, \u0026y, \u0026m, \u0026d);\n    printf(\"1369/06/20 AP is %04d-%02d-%02d\\n\", y, m, d);\n    gr_to_sh(2017, 09, 11, \u0026y, \u0026m, \u0026d); \n    printf(\"2017-09-11 is %04d-%02d-%02d AP\\n\", y, m, d);\n\nwhich will print:\n\n    $ 1369/06/20 AP is 2017-09-11\n    $ 2017-09-11 is 1369/06/18 AP \n\nAlgorithms\n==========\n\n   This library is imolemented in C programming language, using no external \ndependecies. The C standard library used in libcalendar is C11. Though it \nshould be possible to compile this library with a C99 compiler.\n\n   Most of the conversion algorithms for JDN to calendar and vice versa are \nimplemented based on Dr. Louis Strous's work. (available online on \"Astronomy \nPage\" at `http://aa.quae.nl/en/reken/juliaansedag.html') Namely Gregorian, \nJulian, Milankovic and Islamic Civil calendars and their JDN calculations are \nadopted from above page. \n\n   Solar Hijri (Shamsi) and Jalali calendar calculations are implemented based \non Dr. Mousa Akrami's work on median year length for Persian calendar. (See \nnotes on Solar Hijri calendar).\n\nCalendars\n=========\n\nFollowing is a list of supported calendars, and a short description (mostly \nfrom wikipedia) about them.\n\nGregorian\n---------\n\n   The Gregorian calendar is internationally the most widely used civil \ncalendar.\nIt is named after Pope Gregory XIII, who introduced it in October 1582.\n\n   The calendar was a refinement to the Julian calendar involving a 0.002% \ncorrection in the length of the year. The motivation for the reform was to stop \nthe drift of the calendar with respect to the equinoxes and solstices - \nparticularly the northern vernal equinox, which helps set the date for Easter. \nTransition to the Gregorian calendar would restore the holiday to the time of \nthe year in which it was celebrated when introduced by the early Church. The \nreform was adopted initially by the Catholic countries of Europe. Protestants \nand Eastern Orthodox countries continued to use the traditional Julian calendar \nand adopted the Gregorian reform after a time, at least for civil purposes and \nfor the sake of convenience in international trade. The last European country \nto adopt the reform was Greece, in 1923. Many (but not all) countries that have \ntraditionally used the Islamic and other religious calendars have come to adopt \nthis calendar for civil purposes.\n\nJulian\n------\n\n   The Julian calendar, proposed by Julius Caesar in 46 BC (708 AUC), was a \nreform\nof the Roman calendar. It took effect on 1 January 45 BC (AUC 709), by edict.\nIt was the predominant calendar in the Roman world, most of Europe, and in\nEuropean settlements in the Americas and elsewhere, until it was refined and\ngradually replaced by the Gregorian calendar, promulgated in 1582 by Pope\nGregory XIII. The Julian calendar gains against the mean tropical year at the\nrate of one day in 128 years. For the Gregorian the figure is one day in 3,030\nyears. The difference in the average length of the year between Julian (365.25\ndays) and Gregorian (365.2425 days) is 0.002%.\n\nMilankovic\n----------\n\n   The Revised Julian calendar, also known as the Milankovic calendar, or, less\nformally, new calendar, is a calendar, developed and proposed by the Serbian\nscientist Milutin Milankovic in 1923, which effectively discontinued the 340\nyears of divergence between the naming of dates sanctioned by those Eastern\nOrthodox churches adopting it and the Gregorian calendar that has come to\npredominate worldwide. This calendar was intended to replace the ecclesiastical\ncalendar based on the Julian calendar hitherto in use by all of the Eastern\nOrthodox Church. The Revised Julian calendar temporarily aligned its dates with\nthe Gregorian calendar proclaimed in 1582 by Pope Gregory XIII for adoption by\nthe Christian world. The calendar has been adopted by the Orthodox churches of\nConstantinople, Albania, Alexandria, Antioch, Bulgaria, Cyprus, Greece, Poland,\nand Romania.\n\nSolar Hijri\n-----------\n\n   The Solar Hijri calendar, also called the Solar Hejri calendar or Shamsi \nHijri calendar, and abbreviated as SH, is the official calendar of Iran and \nAfghanistan. It begins on the vernal equinox (Nowruz) as determined by \nastronomical calculation for the Iran Standard Time meridian (52.5°E or \nGMT+3.5h). This determination of starting moment is more accurate than the \nGregorian calendar for predicting the date of the vernal equinox, because it \nuses astronomical observations rather than mathematical rules.\n\n   Each of the twelve months corresponds with a zodiac sign. The first six \nmonths have 31 days, the next five have 30 days, and the last month has 29 days \nin usual years but 30 days in leap years. The New Year's Day always falls on \nthe March equinox.\n\nNotes on Solar Hijri\n--------------------\n\n   My implementation of Solar Hijri (Shamsi) calendar is based on median year \ncalculation obtained from Muousa Akrami's work: `The development of Iranian \ncalendar: historical and astronomical foundations - 2014` (available online at \n`https://arxiv.org/pdf/1111.4926.pdf') This method is more accurate than \n33-year algorithm and supports a wider range of dates, both in Solar Hijri \u003c-\u003e \nGregorian comversions, and in JDN calculations.\n\nEgyptian\n--------\n\nThe Egyptian calendar is one of the earliest known timekeeping systems,\ndeveloped in ancient Egypt to align with the Nile's annual flood cycles. It\nplayed a vital role in organizing agricultural activities and religious\nfestivals. This calendar is notable for its remarkable simplicity and its\ninfluence on later timekeeping systems, including the Julian and Gregorian\ncalendars.\n\nThe Egyptian calendar was based on a solar year divided into three\nseasons of four months each, reflecting the natural cycles of the Nile:\n\n* Akhet (Inundation): The flood season, when the Nile overflowed, \n  replenishing the\n  soil.\n* Peret (Emergence): The growing season, when crops were planted and \n  cultivated.\n* Shemu (Harvest): The dry season, when crops were harvested.\n\nEach of the twelve months contained 30 days, making up a total of 360 days in\nthe year. To reconcile this structure with the solar year of approximately\n365.25 days, the Egyptians added five additional days, known as the \"epagomenal\ndays,\" at the end of the year. These days were considered outside the normal\ncalendar and were dedicated to the birthdays of key deities, including Osiris,\nIsis, and Horus.\n\nThe calendar was not leap-adjusted, meaning it gradually drifted out\nof sync with the solar year over centuries. However, its consistency made it\nhighly practical for everyday use and administrative tasks. This robust\nsimplicity, combined with its cultural significance, helped the Egyptian\ncalendar endure for millennia and leave a lasting legacy on the history of\ntimekeeping.\n\nBabylonian\n----------\nThe Babylonian calendar, developed in ancient Mesopotamia, is one of the\nearliest recorded lunar calendars. It played a crucial role in the\nadministrative, agricultural, and religious life of the Babylonians. Rooted in\nastronomical observations, this calendar reflects the sophisticated\nunderstanding of celestial movements by Babylonian scholars.\n\nThe calendar was a lunisolar system, aligning months with the lunar cycle and\nyears with the solar cycle. It relied on the Metonic Cycle, which states that\n235 synodical months are equal to 19 tropical years. These 19 years alternated\nbetween 12 and 13 months, with long years (13 months) occurring in the 1st,\n4th, 7th, 9th, 12th, 15th, and 18th years of the cycle. This structure included\n125 months of 30 days and 110 months of 29 days, adding up to 6,940 days in\ntotal. In most long years, the 12th month was doubled, but in the 18th year,\nthe 6th month was doubled instead. Day 1 of month 1 (Nisannu) of year 1 in the\nEra of Seleukos corresponded to 3 April 310 BCE in the Julian Calendar (CJDN\n1607558).\n\nThe Babylonians determined the beginning of each month by observing the phases\nof the moon. Since the calendar was partly based on direct observations, the\nlength of months and years was not entirely fixed. Factors such as weather\nconditions could delay the official start of a month if the moon was obscured\nby clouds. This variability meant the distribution of months into years\noperated independently from the distribution of days into months.\n\nTo reconstruct the Babylonian calendar predictably, we can use a mathematically\nderived version that closely approximates the historical system. Such a version\nwould differ from the original calendar by at most one day, capturing its\nstructure while avoiding the unpredictability of direct lunar observations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoroush%2Flibcalendars","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoroush%2Flibcalendars","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoroush%2Flibcalendars/lists"}