Calculates the serial date from the parameters \b day, \b month and \b year. Excel: DATE

Contents

Interface Function Documentation Page Comments

Group Description

This function converts a date (with day, month and year specified separately) into a single serial value known as the Julian date (sometimes also referred to as the Julian number). It is a single number that represents the number of days between the date specified and the 24 November 4714BC (or 1 January 4713 BC in the Julian calendar). Therefore the 24 November 4714BC corresponds to 0 in the serial Julian date form. Dates in this form are extremely easy to manipulate, for example:

To add seven days to a serial date you merely add 7,

int nextweek=date("25/Feb/04") + 7;                       // the same as date("3/March/04")

To find the number of days between two dates you subtract one from the other,

int milleniumdays=date("10/10/2004")-date("1 Jan 2000");  // 1744 days

The serial Julian date is one of the most recognised standards for collapsing any date into a single number and is the standard that has been adopted for most calculations.

However, any point in time can also be represented by a variety of different date styles or calendars. We currently recognise these standards (though we hope to expand this range):

Interface

#include <codecogs/units/date/date.h>

using namespace Units::Date;

	int	date (int Year, int Month, int Day, calendar DateSystem=cal_Gregorian) Calculates the serial date from the parameters day, month and year. Excel: DATE
	int	date (const char* Date, calendar DateSystem=cal_Gregorian, int Century21st=30) Converts a date string into a serial date. Excel: DATEVALUE

Function Documentation

Returns the serial Julian date, the number of days between the specified date (Year, Month and Day) and the 24 November 4714BC (in the Gregorian Calendar). The calculation of the serial Julian date is: where all divisions are an integer divisions (rounding down). Clearly solution perfectly accounts for all leap years and varying month lengths to produce a unique serial number for each and every day. The limitation are bound by the numerical accuracy of your computer.

See:

The opposite function is dateYMD

References:

Tondering, C. 2003. www.tondering.dk/claus/cal/node3.html

Example 1:

To compute the serial number for 1st February 2005

int gregorianNo  =date(2005, 2, 1, cal_Gregorian);
  int JulianNo     =date(2005, 2, 1, cal_Julian);
  int ExcelNo      =date(105,  2, 1, cal_Excel);

• In Gregorian or Julian mode, an AD date is expected, so BC dates must be expressed as negative years (e.g. 20 BC=-19). The minimum value for Year is therefore -4799.
• In the cal_Excel modes, any Year < 1900, is adjusted by adding 1900 (This is standard Excel behaviour for DATE). For example date(04,1,1,cal_Excel) is equivalent to date(1904,1,1,cal_Excel). Therefore the minimum value is -6699.

• cal_Gregorian (default)
• cal_Julian
• cal_Excel (Gregorian with a year offset of 1900 for Year values<1900)

Parameters:

Year	can be any integer greater than 4800 BC. The format to achieve this varies with the DateSystem in use:
Month	contains the month of the year. This value must be within the range -9 to 14 (inclusive), though value outside the range 1-12 will be divided by by 12, such that the Year incremented by the quotient and the Month set to the remainder. For example date(2000,13,1) is equivalent to date(2001,1,1).
Day	contains the day of the month. If day is greater than the number of days in the month specified, then the difference cascades through the first days of subsequent months. For example date(2000,1,32) is equivalent to date(2000,2,1).
DateSystem	selects which date system should be used (see constants):

Authors:

Will Bateman (Sep 2004)

This function uses dateYMD to extract the most likely date elements from Date. This is converted into a Julian Date (number of days) using date.

Todo:

• Anyone wanting a challenge can try optimising this function and including an option to allow alternative defaults.
• Write a strict date function, where the user specifies the format and the function complains when the syntax is not suitable.

Example 2:

#include <stdio.h>
#include <codecogs/units/date/date.h>
using namespace Units::Date;
 
int main()
{
  // Using Gregorian calendar with cal_Excel modification
  printf("\n Julian date=%d",date("2232/4 20", cal_Excel));    // 119910  = 20 April 2232
  printf("\n Julian date=%d",date("4February 4", cal_Excel));  // 36559   = 4 February 2004
  printf("\n Julian date=%d",date("30 feb 1974", cal_Excel));  // 25628   = 2 march 1974
  printf("\n Julian date=%d",date("22%12&40", cal_Excel));     // 13505   = 22 December 1940
  printf("\n Julian date=%d",date("12|31#4", cal_Excel));      // 9963    = 12 April 1931
  printf("\n Julian date=%d",date("12 4 march", cal_Excel));   // 36596   = 12 March 2004
  printf("\n Julian date=%d",date("deCeMbeR4 80", cal_Excel)); // 28097   = 4 December 1980
  printf("\n Julian date=%d",date("jan$80 4", cal_Excel));     // 27762   = 4 January 1980
  printf("\n Julian date=%d",date("FEBR+4", cal_Excel));       // 36559   = 4 February 2004
 
  // Using the Gregorian calendar
  printf("\n Julian date=%d",date("jul/1100/4"));              // 2123011 = 4 July 1100
  printf("\n Julian date=%d",date("12FEBR-354"));              // 1850398 = 12 February 354
 
  // Using the Julian calendar
  printf("\n Julian date=%d",date("June 4 56", cal_Julian));   // 36596   = 12 March 2004
  printf("\n Julian date=%d",date("sep 2 3", cal_Julian));     // 28097   = 4 December 1980
  return 0;
}

• Any separator that isn't numeric or alphabetic can be used (i.e. non alphanumeric). So you can not have negative years, because '-' is often used as a separator.
• Only the first 3 terms will be processed. If only 2 terms are specified, today's year is added to the end.
• All things being equal the default date order is: day, month, year. However:
• if the Year is definitely first, the default becomes year, month, day.
• if the Month is definitely first, the default becomes month, day, year.
• Any number>31 is assumed to be year. So "1985/3/4' is the 4 March 1985 (N.B. in this example date order is now year/month/day)
• Numbers less than or equal to 12 get a higher 'month' weighting, so "3/30/12" will be assumed to the 3 December 1930.
• If the month is obvious then the function checks the remaining numbers against possible length for that month. So "31 February 2" is 2 February 1931, because February doesn't have 31 days. However, "31 February 2002" will return 2 March 2002, because neither 31 nor 2002 are valid days for February, so the system switchs to the default format of day/month/year - advancing the excess 2 days in February into March.
• Only the first 3 characters of a text month description are used, the rest are ignored.

• cal_Gregorian (default)
• cal_Julian
• cal_Excel (Gregorian with a year offset of 1900 for Year values<1900)

Parameters:

Date	is a text string containing a date, with the following attributes (also see dateYMD):.
DateSystem	selects which date system should be used (see constants):
Century21st	defines the two digit years that occur in the 21st century, as opposed to the 20th Century. In the Julian DateSystem this parameter is ignored, otherwise the 2000 is added to any year values below Century21st, while 1900 is added to years equal to and above Century21st (Within Excel this variable is set once for all sheets via the options panel).

Authors:

Will Bateman (Sep 2004)