/ 
Date-Darian-Mars-0.004
River stage zero No dependents
/ Date::Darian::Mars

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. 669-day 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 odd-numbered years are leap years. Even-numbered 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 0209-23-18 or 0209-631 in the Darian calendar, and CMSDN 546236.

FUNCTIONS

Numbers in this API may be native Perl integers, Math::BigInt objects, or integer-valued Math::BigRat objects. All three types are acceptable for all parameters, in any combination. In all conversion functions, the most-significant part of the result (which is the only part with unlimited range) is of the same type as the most-significant part of the input. Less-significant 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 minimum-length 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.