Home License Awareness Highly Reusable Software By activity Professions, Sciences, Humanities, Business, ... User Interface Text-based, GUI, Audio, Video, Keyboards, Mouse, Images,... Text Strings Conversions, tests, processing, manipulation,... Math Integer, Floating point, Matrix, Statistics, Boolean, ... Processing Algorithms, Memory, Process control, Debugging, ... Stored Data Data storage, Integrity, Encryption, Compression, ... Communications Networks, protocols, Interprocess, Remote, Client Server, ... Hard World Timing, Calendar and Clock, Audio, Video, Printer, Controls... File System Management, Filtering, File & Directory access, Viewers, ...

NAME

SYNOPSIS

#include <librock/sdncalh.h>

void
librock_SdnToJewish(
     long int sdn,
     int *pYear,
     int *pMonth,
     int *pDay);

 /* Convert a SDN to a Jewish calendar date.  If the input SDN is before the
 * first day of year 1, the three output values will all be set to zero,
 * otherwise *pYear will be > 0; *pMonth will be in the range 1 to 13
 * inclusive; *pDay will be in the range 1 to 30 inclusive.  Note that Adar
 * II is assigned the month number 7 and Elul is always 13.
 */
long int
librock_JewishToSdn(
     int year,
     int month,
     int day);
 /*
 * Convert a Jewish calendar date to a SDN.  Zero is returned when the
 * input date is detected as invalid or out of the supported range.  The
 * return value will be > 0 for all valid, supported dates, but there are
 * some invalid dates that will return a positive value.  To verify that a
 * date is valid, convert it to SDN and then back and compare with the
 * original.
 */
char *librock_JewishMonthName[14];
 /*
 * Convert a Jewish month number (1 to 13) to the name of the Jewish month
 * (null terminated).  An index of zero will return a zero length string.
 */

DESCRIPTION

 * This package defines a set of routines that convert calendar dates to
 * and from a serial day number (SDN).  The SDN is a serial numbering of
 * days where SDN 1 is November 25, 4714 BC in the Gregorian calendar and
 * SDN 2447893 is January 1, 1990.  This system of day numbering is
 * sometimes referred to as Julian days, but to avoid confusion with the
 * Julian calendar, it is referred to as serial day numbers here.  The term
 * Julian days is also used to mean the number of days since the beginning
 * of the current year.
 *
 * The SDN can be used as an intermediate step in converting from one
 * calendar system to another (such as Gregorian to Jewish).  It can also
 * be used for date computations such as easily comparing two dates,
 * determining the day of the week, finding the date of yesterday or
 * calculating the number of days between two dates.
 *
 * SDN values less than one are not supported.  If a conversion routine
 * returns an SDN of zero, this means that the date given is either invalid
 * or is outside the supported range for that calendar.
 *
 * At least some validity checks are performed on input dates.  For
 * example, a negative month number will result in the return of zero for
 * the SDN.  A returned SDN greater than one does not necessarily mean that
 * the input date was valid.  To determine if the date is valid, convert it
 * to SDN, and if the SDN is greater than zero, convert it back to a date
 * and compare to the original.  For example:
 
     int y1, m1, d1;
     int y2, m2, d2;
     long int sdn;
     ...
     sdn = GregorianToSdn(y1, m1, d1);
     if (sdn > 0) {
         SdnToGregorian(sdn, &y2, &m2, &d2);
         if (y1 == y2 && m1 == m2 && d1 == d2) {
             ... date is valid ...
         }
     }

VALID RANGE

 *
 *     Although this software can handle dates all the way back to the year
 *     1 (3761 B.C.), such use may not be meaningful.
 *
 *     The Jewish calendar has been in use for several thousand years, but
 *     in the early days there was no formula to determine the start of a
 *     month.  A new month was started when the new moon was first
 *     observed.
 *
 *     It is not clear when the current rule based calendar replaced the
 *     observation based calendar.  According to the book "Jewish Calendar
 *     Mystery Dispelled" by George Zinberg, the patriarch Hillel II
 *     published these rules in 358 A.D.  But, according to The
 *     Encyclopedia Judaica, Hillel II may have only published the 19 year
 *     rule for determining the occurrence of leap years.
 *
 *     I have yet to find a specific date when the current set of rules
 *     were known to be in use.
 

CALENDAR OVERVIEW

 *
 *     The Jewish calendar is based on lunar as well as solar cycles.  A
 *     month always starts on or near a new moon and has either 29 or 30
 *     days (a lunar cycle is about 29 1/2 days).  Twelve of these
 *     alternating 29-30 day months gives a year of 354 days, which is
 *     about 11 1/4 days short of a solar year.
 *
 *     Since a month is defined to be a lunar cycle (new moon to new moon),
 *     this 11 1/4 day difference cannot be overcome by adding days to a
 *     month as with the Gregorian calendar, so an entire month is
 *     periodically added to the year, making some years 13 months long.
 *
 *     For astronomical as well as ceremonial reasons, the start of a new
 *     year may be delayed until a day or two after the new moon causing
 *     years to vary in length.  Leap years can be from 383 to 385 days and
 *     common years can be from 353 to 355 days.  These are the months of
 *     the year and their possible lengths:
 *
 *                       COMMON YEAR          LEAP YEAR
 *          1 Tishri    30   30   30         30   30   30
 *          2 Heshvan   29   29   30         29   29   30 (variable)
 *          3 Kislev    29   30   30         29   30   30 (variable)
 *          4 Tevet     29   29   29         29   29   29
 *          5 Shevat    30   30   30         30   30   30
 *          6 Adar I    29   29   29         30   30   30 (variable)
 *          7 Adar II   --   --   --         29   29   29 (optional)
 *          8 Nisan     30   30   30         30   30   30
 *          9 Iyyar     29   29   29         29   29   29
 *         10 Sivan     30   30   30         30   30   30
 *         11 Tammuz    29   29   29         29   29   29
 *         12 Av        30   30   30         30   30   30
 *         13 Elul      29   29   29         29   29   29
 *                     ---  ---  ---        ---  ---  ---
 *                     353  354  355        383  384  385
 *
 *     Note that the month names and other words that appear in this file
 *     have multiple possible spellings in the Roman character set.  I have
 *     chosen to use the spellings found in the Encyclopedia Judaica.
 *
 *     Adar II, the month added for leap years, is sometimes referred to as
 *     the 13th month, but I have chosen to assign it the number 7 to keep
 *     the months in chronological order.  This may not be consistent with
 *     other numbering schemes.
 *
 *     Leap years occur in a fixed pattern of 19 years called the metonic
 *     cycle.  The 3rd, 6th, 8th, 11th, 14th, 17th and 19th years of this
 *     cycle are leap years.  The first metonic cycle starts with Jewish
 *     year 1, or 3761/60 B.C.  This is believed to be the year of
 *     creation.
 *
 *     To construct the calendar for a year, you must first find the length
 *     of the year by determining the first day of the year (Tishri 1, or
 *     Rosh Ha-Shanah) and the first day of the following year.  This
 *     selects one of the six possible month length configurations listed
 *     above.
 *
 *     Finding the first day of the year is the most difficult part.
 *     Finding the date and time of the new moon (or molad) is the first
 *     step.  For this purpose, the lunar cycle is assumed to be 29 days 12
 *     hours and 793 halakim.  A halakim is 1/1080th of an hour or 3 1/3
 *     seconds.  (This assumed value is only about 1/2 second less than the
 *     value used by modern astronomers -- not bad for a number that was
 *     determined so long ago.)  The first molad of year 1 occurred on
 *     Sunday at 11:20:11 P.M.  This would actually be Monday, because the
 *     Jewish day is considered to begin at sunset.
 *
 *     Since sunset varies, the day is assumed to begin at 6:00 P.M.  for
 *     calendar calculation purposes.  So, the first molad was 5 hours 793
 *     halakim after the start of Tishri 1, 0001 (which was Monday
 *     September 7, 4761 B.C. by the Gregorian calendar).  All subsequent
 *     molads can be calculated from this starting point by adding the
 *     length of a lunar cycle.
 *
 *     Once the molad that starts a year is determined the actual start of
 *     the year (Tishri 1) can be determined.  Tishri 1 will be the day of
 *     the molad unless it is delayed by one of the following four rules
 *     (called dehiyyot).  Each rule can delay the start of the year by one
 *     day, and since rule #1 can combine with one of the other rules, it
 *     can be delayed as much as two days.
 *
 *         1.  Tishri 1 must never be Sunday, Wednesday or Friday.  (This
 *             is largely to prevent certain holidays from occurring on the
 *             day before or after the Sabbath.)
 *
 *         2.  If the molad occurs on or after noon, Tishri 1 must be
 *             delayed.
 *
 *         3.  If it is a common (not leap) year and the molad occurs on
 *             Tuesday at or after 3:11:20 A.M., Tishri 1 must be delayed.
 *
 *         4.  If it is the year following a leap year and the molad occurs
 *             on Monday at or after 9:32:43 and 1/3 sec, Tishri 1 must be
 *             delayed.
 

GLOSSARY

 *
 *     dehiyyot         The set of 4 rules that determine when the new year
 *                      starts relative to the molad.
 *
 *     halakim          1/1080th of an hour or 3 1/3 seconds.
 *
 *     lunar cycle      The period of time between mean conjunctions of the
 *                      sun and moon (new moon to new moon).  This is
 *                      assumed to be 29 days 12 hours and 793 halakim for
 *                      calendar purposes.
 *
 *     metonic cycle    A 19 year cycle which determines which years are
 *                      leap years and which are common years.  The 3rd,
 *                      6th, 8th, 11th, 14th, 17th and 19th years of this
 *                      cycle are leap years.
 *
 *     molad            The date and time of the mean conjunction of the
 *                      sun and moon (new moon).  This is the approximate
 *                      beginning of a month.
 *
 *     Rosh Ha-Shanah   The first day of the Jewish year (Tishri 1).
 *
 *     Tishri           The first month of the Jewish year.
 

ALGORITHMS

 *
 *     SERIAL DAY NUMBER TO JEWISH DATE
 *
 *     The simplest approach would be to use the rules stated above to find
 *     the molad of Tishri before and after the given day number.  Then use
 *     the molads to find Tishri 1 of the current and following years.
 *     From this the length of the year can be determined and thus the
 *     length of each month.  But this method is used as a last resort.
 *
 *     The first 59 days of the year are the same regardless of the length
 *     of the year.  As a result, only the day number of the start of the
 *     year is required.
 *
 *     Similarly, the last 6 months do not change from year to year.  And
 *     since it can be determined whether the year is a leap year by simple
 *     division, the lengths of Adar I and II can be easily calculated.  In
 *     fact, all dates after the 3rd month are consistent from year to year
 *     (once it is known whether it is a leap year).
 *
 *     This means that if the given day number falls in the 3rd month or on
 *     the 30th day of the 2nd month the length of the year must be found,
 *     but in no other case.
 *
 *     So, the approach used is to take the given day number and round it
 *     to the closest molad of Tishri (first new moon of the year).  The
 *     rounding is not really to the *closest* molad, but is such that if
 *     the day number is before the middle of the 3rd month the molad at
 *     the start of the year is found, otherwise the molad at the end of
 *     the year is found.
 *
 *     Only if the day number is actually found to be in the ambiguous
 *     period of 29 to 31 days is the other molad calculated.
 *
 *     JEWISH DATE TO SERIAL DAY NUMBER
 *
 *     The year number is used to find which 19 year metonic cycle contains
 *     the date and which year within the cycle (this is a division and
 *     modulus).  This also determines whether it is a leap year.
 *
 *     If the month is 1 or 2, the calculation is simple addition to the
 *     first of the year.
 *
 *     If the month is 8 (Nisan) or greater, the calculation is simple
 *     subtraction from beginning of the following year.
 *
 *     If the month is 4 to 7, it is considered whether it is a leap year
 *     and then simple subtraction from the beginning of the following year
 *     is used.
 *
 *     Only if it is the 3rd month is both the start and end of the year
 *     required.
 *

TESTING

 *
 *     This algorithm has been tested in two ways.  First, 510 dates from a
 *     table in "Jewish Calendar Mystery Dispelled" were calculated and
 *     compared to the table.  Second, the calculation algorithm described
 *     in "Jewish Calendar Mystery Dispelled" was coded and used to verify
 *     all dates from the year 1 (3761 B.C.) to the year 13760 (10000
 *     A.D.).
 *
 *     The source code of the verification program is included the sdncal
 *     package.
 *

REFERENCES

 *
 *     The Encyclopedia Judaica, the entry for "Calendar"
 *
 *     The Jewish Encyclopedia
 *
 *     Jewish Calendar Mystery Dispelled by George Zinberg, Vantage Press,
 *     1963
 *
 *     The Comprehensive Hebrew Calendar by Arthur Spier, Behrman House
 *
 *     The Book of Calendars [note that this work contains many typos]
 

USES

LICENSE

  Copyright 1993-1995, Scott E. Lee, all rights reserved.
  Licensed under BSD-ish license, NO WARRANTY. Copies must retain this block.
  License text in <librock/license/sdncal.txt> librock_LIDESC_HC=553e181388455f0eef17ccd9e2a51c1f3ae8daf0

Source Code

This software is part of Librock

• Source code which is Open-source, Free (Libre) and free (no cost)
• Namespace limited. All compile-time macros and names visible at link time are prefixed by "librock_". Integrate into your project and expect no name collisions.
• Stable API means new functions get new names so that there is no risk that updating a source file will break existing applications.
• Highly portable, cross-platform, and multithread compatible. Works with many machines, compilers, and operating systems (gcc/MSVC/Windows/Linux/BSD).

Verbatim copying and distribution of this generated page is permitted in any medium provided that no changes are made.
(The source of this manual page may be covered by a more permissive license which allows modifications.)

Want to help? We welcome comments, patches. -- Need help? Request paid support.