NAME
Date::Darian::Mars  the Darian calendar for Mars
SYNOPSIS
use Date::Darian::Mars qw(present_y);
print present_y($y);
use Date::Darian::Mars qw(
month_days cmsdn_to_ymd ymd_to_cmsdn present_ymd);
$md = month_days(209, 23);
($y, $m, $d) = cmsdn_to_ymd(546236);
$cmsdn = ymd_to_cmsdn(209, 23, 18);
print present_ymd(546236);
print present_ymd(209, 23, 18);
use Date::Darian::Mars qw(
year_days cmsdn_to_yd yd_to_cmsdn present_yd);
$yd = year_days(209);
($y, $d) = cmsdn_to_yd(546236);
$cmsdn = yd_to_cmsdn(209, 631);
print present_yd(546236);
print present_yd(209, 631);
DESCRIPTION
The Darian calendar for Mars is a mechanism by which Martian solar days (also known as "sols") can be labelled in a manner useful to inhabitants of Mars. This module provides functions to convert dates between the Darian calendar and Chronological Mars Solar Day Numbers, which is a suitable format to do arithmetic with. It also supplies functions that describe the shape of the Darian calendar, to assist in calendrical calculations. It also supplies functions to represent Darian dates textually in a conventional format.
The Darian calendar divides time up into years, months, and days. This module also supports dividing the Darian year directly into days, with no months.
The Chronological Mars Solar Day Number is an integral number labelling each Martian day, where the day extends from midnight to midnight in whatever time zone is of interest. It is a linear count of days, where each day's number is one greater than the previous day's number.
This module places no limit on the range of dates to which it may be applied. All function arguments are permitted to be Math::BigInt
or Math::BigRat
objects in order to achieve arbitrary range. Native Perl integers are also permitted, as a convenience when the range of dates being handled is known to be sufficiently small.
DARIAN CALENDAR FOR MARS
The main cycle in the Darian calendar is the year. It approximates the length of a Martian tropical year (specifically, the northward equinoctal year), and the year starts approximately on the northward equinox. Years are either 668 or 669 Martian solar days long. 669day years are referred to as "leap years".
Each year is divided into 24 months, of nearly equal length. The months are purely nominal: they do not correspond to any astronomical cycle. Each quarter of the year consists of five months of 28 days followed by one month of 27 days, except that the last month of a leap year contains 28 days instead of 27.
All oddnumbered years are leap years. Evennumbered years are not leap years, except for years divisible by ten which are leap years, except for years divisible by 100 which are not, except for years divisible by 500 which are.
Days within each month are numbered sequentially, starting at 1. The months have names (in fact several competing sets of names), but this module does not deal with the names. In this module, months within each year are numbered sequentially from 1.
Years are numbered sequentially. Year 0 is the year in which the first known telescopic observations of Mars occurred. Specifically, year 0 started at the midnight that occurred on the Airy meridian (the Martian prime meridian) at approximately MJD 91195.22 in Terrestrial Time.
The calendar is described canonically, and in more detail, at http://pweb.jps.net/~tgangale/mars/converter/calendar_clock.htm.
The day when Mars Exploration Rover "Opportunity" landed in Meridiani Planum was 02092318 or 0209631 in the Darian calendar, and CMSDN 546236.
FUNCTIONS
Numbers in this API may be native Perl integers, Math::BigInt
objects, or integervalued Math::BigRat
objects. All three types are acceptable for all parameters, in any combination. In all conversion functions, the mostsignificant part of the result (which is the only part with unlimited range) is of the same type as the mostsignificant part of the input. Lesssignificant parts of results (which have a small range) are consistently native Perl integers.
All functions die
if given invalid parameters.
Years
 present_y(YEAR)

Puts the given year number into the conventional textual presentation format. For years [0, 9999] this is simply four digits. For years outside that range it is a sign followed by at least four digits.
This is the minimumlength presentation format. If it is desired to use a form that is longer than necessary, such as to use at least five digits for all year numbers, then the right tool is
sprintf
(see "sprintf" in perlfunc).
Darian calendar
Each year is divided into 24 months, numbered [1, 24]. Each month is divided into days, numbered sequentially from 1. The month lengths are irregular. The year numbers have unlimited range.
 month_days(YEAR, MONTH)

The parameters identify a month, and the function returns the number of days in that month as a native Perl integer.
 cmsdn_to_ymd(CMSDN)

This function takes a Chronological Mars Solar Day Number and returns a list of a year, month, and day.
 ymd_to_cmsdn(YEAR, MONTH, DAY)

This performs the reverse of the translation that
cmsdn_to_ymd
does. It takes year, month, and day numbers, and returns the corresponding CMSDN.  present_ymd(CMSDN)
 present_ymd(YEAR, MONTH, DAY)

Puts the given date into conventional Darian textual presentation format.
If the date is given as a (YEAR, MONTH, DAY) triplet then these are not checked for consistency. The MONTH and DAY values are only checked to ensure that they fit into the fixed number of digits. This allows the use of this function on data other than actual Darian dates.
Ordinal dates
Each year is divided into days, numbered sequentially from 1. The year lengths are irregular. The years correspond exactly to those of the Darian calendar.
 year_days(YEAR)

The parameter identifies a year, and the function returns the number of days in that year as a native Perl integer.
 cmsdn_to_yd(CMSDN)

This function takes a Chronological Mars Solar Day Number and returns a list of a year and ordinal day.
 yd_to_cmsdn(YEAR, DAY)

This performs the reverse of the translation that
cmsdn_to_yd
does. It takes year and ordinal day numbers, and returns the corresponding CMSDN.  present_yd(CMSDN)
 present_yd(YEAR, DAY)

Puts the given date into the conventional ordinal textual presentation format.
If the date is given as a (YEAR, DAY) pair then these are not checked for consistency. The DAY value is only checked to ensure that it fits into the fixed number of digits. This allows the use of this function on data other than actual ordinal dates.
SEE ALSO
Date::MSD, http://pweb.jps.net/~tgangale/mars/converter/calendar_clock.htm, http://www.fysh.org/~zefram/time/define_cmsd.txt
AUTHOR
Andrew Main (Zefram) <zefram@fysh.org>
COPYRIGHT
Copyright (C) 2007, 2009, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>
LICENSE
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.