AUC

NAME

Date::Calendar::Julian::AUC - Julian calendar based on the foundation of Rome

SYNOPSIS

Converting a Gregorian date (e.g. 14 January 2021) into Julian, using the foundation of Rome for the epoch


use Date::Calendar::Julian::AUC;

my Date $jan14-grg;
my Date::Calendar::Julian::AUC $jan14-jul;

$jan14-grg .= new(2021, 1, 14);
$jan14-jul .= new-from-date($jan14-grg);

say $jan14-jul;
# --> 2774-01-01 AUC

$jan14-jul.locale = 'nl';
say $jan14-jul.strftime("%A %e %B %Y");
# --> donderdag  1 januari 2774

Converting a Julian date (e.g. 1st August 2773 AUC) into Gregorian

use Date::Calendar::Julian::AUC;

my  Date::Calendar::Julian::AUC
        $TPRC-Amsterdam-jul;
my Date $TPRC-Amsterdam-grg;

$TPRC-Amsterdam-jul .= new(year  => 2773
                         , month =>    8
                         , day   =>    1);
$TPRC-Amsterdam-grg = $TPRC-Amsterdam-jul.to-date;

say "The Perl and Raku conference was scheduled to end on ", $TPRC-Amsterdam-grg;
# --> The Perl and Raku conference was scheduled to end on 2020-08-14

DESCRIPTION

Date::Calendar::Julian::AUC is a class representing the Julian calendar, the forerunner of the Gregorian calendar. Contrary to the Date::Calendar::Julian class, years are numbered from the foundation of Rome instead of from the approximate year of the birth of Christ.

AUC is a latin abbreviation for Ab Urbe Condita, that is, "Since the foundation of the City" (the City with a capital "C" being, of course, Rome).

The module allows you to convert Julian dates into other calendars and to convert other dates into the Julian calendar.

The Julian differ from the Gregorian calendar only on the leap year rule. For the Julian calendar, leap years follow a 4-year cycle. For the AUC variant, leap years are years following a multiple of 4, such as 5 or 9. There is no adjustment on a century year.

This module adopts a simplified point of view about the Julian calendar. Except for the leap year rule and for the epoch, everything in the module is similar to the Gregorian calendar. Days are midnight to midnight, weeks are Monday to Sunday, years are 1st January to 31st December. Historically, the rules were not as rigid as that, especially the rule defining the beginning of the year.

Another simplification is that there is a year zero. With the AUC epoch, we do not usually consider dates before the foundation of Rome. Yet the class allows the creation of dates before the epoch and, if you count backwards in time, the years are numbered 2, 1, 0, -1, -2 and so on. So the day before 1st January 1 AUC is 31st December 0 AUC. This is the point of view adopted by this module. And also by the core module Date (which implements the Gregorian calendar).

Warning

This module is NOT an implementation of the early Roman calendar. It is an implementation of the Julian calendar, which was in effect from 45 BC (or -44, or 709 AUC). The real early Roman calendar was a very complicated matter, with a leap month instead of a leap day. The rules for including the leap month were mixing astronomy and politics. The consuls were taking office on January 1st and leaving office on the following January 1st. So when the calendar keepers did not like a consul, they would shorten the year even if the astronomical situation would require adding a leap month. And when they liked the consul (or were bribed by him), they would lengthen the year by including a leap month, even if the astronomical situation did not require it.

The Julian reform, taking effect on 45 BC, would give years of nearly equal lengths: 365 or 366 days. But there was still a problem with it. At first, leap years were following a 3-year cycle. This was fixed after a few decades, around year 12 AD (765 AUC). The module Date::Calendar::Julian::AUC (and its companion module Date::Calendar::Julian) represent the dates after this fix.

The module does not implement Nones, Ides and Calends. Dates are given with weekdays from Monday to Sunday.

METHODS

Constructors

new

Create a Julian date by giving the year, month and day numbers and optionally the locale and the daypart.

new-from-date

Build a Julian date by cloning an object from another class. This other class can be the core class Date or any Date::Calendar::xxx class with a daycount method and hopefully a daypart method.

This method does not allow a locale build parameter. The object is built with the default locale, 'en'.

new-from-daycount

Build a Julian date from the Modified Julian Day number and from the daypart parameter (optional).

This method does not allow a locale build parameter. The object is built with the default locale, 'en'.

Accessors

gist

Gives a short string representing the date, in YYYY-MM-DD format with an "AUC" postfix to prevent confusion with the main Julian calendar module.

year, month, day

The numbers defining the date.

daycount

The MJD (Modified Julian Date) number for the date.

daypart

A number indicating which part of the day. This number should be filled and compared with the following subroutines, with self-documenting names:

before-sunrise
daylight
after-sunset

locale

The two-char string defining the locale used for the date. Use any value allowed by the module Date::Names.

This attribute can be updated after build time.

month-name

The month of the date, as a string. This depends on the date's current locale.

month-abbr

The abbreviated month of the date.

Depending on the locale, it may be a 3-char string, a 2-char or a short code of variable length. Please refer to the documentation of Date::Names for the availability of mon3, mon2 and mona.

day-name

The name of the day within the week. It depends on the date's current locale.

day-abbr

The abbreviated day name of the date.

Depending on the locale, it may be a 3-char string, a 2-char string or a short code of variable length. Please refer to the documentation of Date::Names for the availability of dow3, dow2 and dowa.

day-of-week

The day of the week, as a number (1 for Monday, 7 for Sunday).

week-number

The number of the week within the year, 1 to 52 or 1 to 53. Similar to the "ISO date" as defined for Gregorian date. Week number 1 is the Mon→Sun span that contains the first Thursday of the year, week number 2 is the Mon→Sun span that contains the second Thursday of the year and so on.

week-year

Mostly similar to the year attribute. Yet, the last days of the year and the first days of the following year can be sort-of transferred to the other year. The week-year attribute reflects this transfer. While the real year always begins on 1st January and ends on the 31st December, the week-year always begins on Monday and it always ends on Sunday.

day-of-year

How many days since the beginning of the year. 1 to 365 on normal years, 1 to 366 on leap years.

daycount

Convert the date to Modified Julian Day Number (a day-only scheme based on Gregorian 17 November 1858).

Other Methods

to-date

Clones the date into a core class Date object or some Date::Calendar::xxx compatible calendar class. The target class name is given as a positional parameter. This parameter is optional, the default value is "Date" for the Gregorian calendar.

To convert a date from a calendar to another, you have two conversion styles, a "push" conversion and a "pull" conversion. For example, while converting "31st October 2777" to the French Revolutionary calendar, you can code:


use Date::Calendar::Julian::AUC;
use Date::Calendar::FrenchRevolutionary;

my  Date::Calendar::Julian::AUC         $d-orig;
my  Date::Calendar::FrenchRevolutionary $d-dest-push;
my  Date::Calendar::FrenchRevolutionary $d-dest-pull;

$d-orig .= new(year  => 2777
             , month =>   10
             , day   =>   31);
$d-dest-push  = $d-orig.to-date("Date::Calendar::FrenchRevolutionary");
$d-dest-pull .= new-from-date($d-orig);
say $d-orig, ' ', $d-dest-push, ' ', $d-dest-pull;
# --> "2777-10-31 AUC 0233-02-23 0233-02-23"

And the dates $d-dest-push and $d-dest-pull are identical.

When converting from the core class Date, use the pull style. When converting to the core class Date, use the push style. When converting from any class other than the core class Date to any other class other than the core class Date, use the style you prefer. This includes the class Date::Calendar::Gregorian inheriting from Date and implementing the Gregorian calendar.

Even if both calendars use a locale attribute, when a date is created by the conversion of another date, it is created with the default locale. If you want the locale to be transmitted in the conversion, you should add a line such as:


$d-dest-pull.locale = $d-orig.locale;

strftime

This method is very similar to the homonymous functions you can find in several languages (C, shell, etc). It also takes some ideas from printf-similar functions. For example


$df.strftime("%04d blah blah blah %-25B")

will give the day number padded on the left with 2 or 3 zeroes to produce a 4-digit substring, plus the substring " blah blah blah ", plus the month name, padded on the right with enough spaces to produce a 25-char substring. Thus, the whole string will be at least 42 chars long.

A strftime specifier consists of:

A percent sign,
An optional minus sign, to indicate on which side the padding occurs. If the minus sign is present, the value is aligned to the left and the padding spaces are added to the right. If it is not there, the value is aligned to the right and the padding chars (spaces or zeroes) are added to the left.
An optional zero digit, to choose the padding char for right-aligned values. If the zero char is present, padding is done with zeroes. Else, it is done wih spaces.
An optional length, which specifies the minimum length of the result substring.
An optional "E" or "O" modifier. On some older UNIX system, these were used to give the extended or localized version of the date attribute. Here, they rather give alternate variants of the date attribute. Not used with the Julian calendar.
A mandatory type code.

The allowed type codes are:

%a

The day of week name, abbreviated to 3 chars.

%A

The full day of week name.

%b

The abbreviated month name.

%B

The full month name.

%d

The day of the month as a decimal number (range 01 to 31).

%e

Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.

%f

The month as a decimal number (1 to 12). Unlike %m, a leading zero is replaced by a space.

%F

Equivalent to %Y-%m-%d (the ISO 8601 date format)

%G

The "week year" as a decimal number. Mostly similar to %Y, but it may differ on the very first days of the year or on the very last days. Analogous to the year number in the so-called "ISO date" format for Gregorian dates.

%j

The day of the year as a decimal number (range 001 to 366).

%L

Redundant with %Y and strongly discouraged: the year number.

Since 2024 and the release of Date::Calendar::Strfrtime version 0.0.4, this strftime specifier is deprecated.

%m

The month as a two-digit decimal number (range 01 to 12), including a leading zero if necessary.

%n

A newline character.

%Ep

Gives a 1-char string representing the day part:

☾ or U+263E before sunrise,
☼ or U+263C during daylight,
☽ or U+263D after sunset.

Rationale: in C or in other programming languages, when strftime deals with a date-time object, the day is split into two parts, before noon and after noon. The %p specifier reflects this by giving a "AM" or "PM" string.

The 3-part splitting in the Date::Calendar::xxx may be considered as an alternate splitting of a day. To reflect this in strftime, we use an alternate version of %p, therefore %Ep.

%t

A tab character.

%u

The day of week as a 1..7 number.

%V

The week number as defined above, similar to the week number in the so-called "ISO date" format for Gregorian dates.

%Y

The year as a decimal number.

%%

A literal `%' character.

AUTHOR

Jean Forget <J2N-FORGET at orange dot fr>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

NAME

SYNOPSIS

DESCRIPTION

Warning

METHODS

Constructors

new

new-from-date

new-from-daycount

Accessors

gist

year, month, day

daycount

daypart

locale

month-name

month-abbr

day-name

day-abbr

day-of-week

week-number

week-year

day-of-year

daycount

Other Methods

to-date

strftime

SEE ALSO

Raku Software

Perl 5 Software

Other Software

Books

AUTHOR

COPYRIGHT AND LICENSE

Date::Calendar::Julian v0.1.0

Authors

License

Dependencies

Test Dependencies

Provides

Documentation