Armenian

NAME

Date::Calendar::Armenian - Conversions from / to the Armenian calendar

SYNOPSIS

Converting a Gregorian date (e.g. 13th November 2024) into Armenian


use Date::Calendar::Armenian;
my  Date                     $d-grg
my  Date::Calendar::Armenian $d-arm;

$d-grg .= new(2024, 11, 13);
$d-arm .= new-from-date($d-grg);

say $d-arm;
# --> 1474-04-26
say "{.day-name} {.day} {.month-name} {.year}" with $d-arm;
# --> čʿorekʿšabatʿi 26 trē 1474
say $d-arm.strftime("%A %d %B %Y");
# --> čʿorekʿšabatʿi 26 trē 1474

Converting a Armenian date (e.g. 16 ahekan 1474) into Gregorian


use Date::Calendar::Armenian;
my  Date::Calendar::Armenian $d-arm;
my  Date                     $d-grg;

$d-arm .= new(year  => 1474
            , month =>    9
            , day   =>   16);
$d-grg = $d-arm.to-date;

say $d-grg;
# ---> 2025-04-02

Converting a Armenian date to Gregorian, while paying attention to sunrise.


use Date::Calendar::Armenian;
use Date::Calendar::Strftime;
my  Date::Calendar::Armenian $d-arm;
my  Date                     $d-grg;

$d-arm .= new(year    => 1474
            , month   =>    9
            , day     =>   16
            , daypart => before-sunrise());
$d-grg = $d-arm.to-date;

say $d-grg;
# ---> 2025-04-03 instead of 2025-04-02

# on the other hand:
$d-arm .= new(year => 1474, month => 9, day => 16, daypart => daylight());
$d-grg  = $d-arm.to-date;
say $d-grg;
# --> '2025-04-02'

$d-arm .= new(year => 1474, month => 9, day => 16, daypart => after-sunset());
$d-grg  = $d-arm.to-date;
say $d-grg;
# --> '2025-04-02' also

DESCRIPTION

Date::Calendar::Armenian is a class representing dates in the Armenian calendar. It allows you to convert an Armenian date into Gregorian (or possibly other) calendar and the other way.

The Armenian calendar uses a vague year, that is, a year with 365 days and no leap adjustment. A year is divided into 12 months with 30 days each, plus 5 additional days which appear in this class as a short 13th month.

According to http://www.tacentral.com/astronomy.asp?story_no=3, the switch from a date to the next occurs at sunrise.

METHODS

Constructors

new

Create an Armenian date by giving the year, month and day numbers, plus the day part (before-sunrise, daylight or after-sunset).

new-from-date

Build an Armenian 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.

new-from-daycount

Build an Armenian date from the Modified Julian Day number and the daypart value.


use Date::Calendar::Armenian;
use Date::Calendar::Strftime;
my  Date::Calendar::Armenian $d-arm .= new(daycount => 60627
                                         , daypart  => after-sunset);

Accessors

gist

Gives a short string representing the date, in YYYY-MM-DD format.

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()

month-name

The month of the date, as a string.

month-abbr

The month of the date, as a 3-char string.

day-name

The name of the day within the week.

day-of-week

The number of the day within the week (1 for Sunday / kiraki, 7 for Saturday / šabatʿi).

week-number

The number of the week within the year, 1 to 52 or 1 to 53. Week number 1 is the Sun→Sat span that contains the first Wednesday / čʿorekʿšabatʿi of the year, week number 2 is the Sun→Sat span that contains the second Wednesday / čʿorekʿšabatʿi of the year and so on.

The week number and the week year (see below) are not a feature of the Armenian calendar. They are a feature of the Gregorian calendar (so-called "ISO date") ported to the Armenian calendar.

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 Navasard and ends on 5th Aveliats, the week-year always begins on Sunday / kiraki and it always ends on Saturday / šabatʿi.

day-of-year

How many days since the beginning of the year. 1 to 365.

month-day-name

In addition to its name representing its position within a week, each day has a name representing its position within a month. The month-day-name method gives this second name.

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 "26 Tre 1474" to the Julian calendar, you can code:


use Date::Calendar::Armenian;
use Date::Calendar::Julian;

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

$d-orig .= new(year  => 1474
             , month =>    9
             , day   =>   26);
$d-dest-push  = $d-orig.to-date("Date::Calendar::Julian");
$d-dest-pull .= new-from-date($d-orig);
say $d-orig, ' ', $d-dest-push, ' ', $d-dest-pull;
# --> "1474-09-26 2024-10-31 2024-10-31"

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. For the Gregorian calendar, instead of the core class Date, you can use the child class Date::Calendar::Gregorian which allows both push and pull styles.

strftime

The strftime method is similar to the strftime functions you in several languages (C, shell, etc) and to the strftime function described below. Please refer to this function. The only difference is the call syntax:


say $d.strftime("%04d blah blah blah %-25B"); # using the method
say strftime($d,"%04d blah blah blah %-25B"); # using the function

FUNCTIONS

The class exports only one function.

strftime

This function 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


strftime($d, "%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. By the way, you can drop the "at least" mention, because the longest month name is 10-char long, so the padding will always occur and will always include at least 15 spaces.

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 systems, these were used to give the extended or localized version of the date attribute. Here, they rather give alternate variants of the date attribute.
A mandatory type code.

The allowed type codes are:

%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 30).

%Ed

The name of the day within the month, corresponding to method month-day-name.

%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. The special value 13 represents the 5 additional days at the end of the year.

%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 365).

%m

The month as a two-digit decimal number (range 01 to 13), including a leading zero if necessary. The special value 13 represents the 5 additional days at the end of the year.

%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 classes 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.

PROBLEMS AND KNOWN ISSUES

Authoritative Sources

Finding authoritative sources about the Armenian calendar in French or in English is rather difficult. One of the French-speaking sources that I consider authoritative warns its readers that it is not authoritative enough. Here is my translation of the warning (at the beginning of chapter "Le calendrier").

Oddly enough, there are few references relative to the Armenian calendar. In addition, when we find them, they often contradict each other. I would believe that nobody has studied the topic seriously enough and everyone gives a personal interpretation.

Names

The name for sunday has changed over the times. At first, it was miašabatʿi and it changed to kiraki. The class uses the newer name.

When cross-referencing the names given by a webpage with the names given by another webpage, I do not consider that changes in transcription are significant. I do not mind reading kiraki and aweleacʿ at one place and giragi and Aveliats at another place.

Sarkawag Reform

The Armenian calendar had a reform proposed by Yovhannes Sarkawag in 1084, to add a leap day every 4 years.

According to the convertdate Python library, this leap day is added after the 5 usual additional days. This is similar to the Coptic, Ethiopian and French Revolutionary calendars.

According to the webpage https://icalendrier.fr/calendriers-saga/calendriers/armenien, the leap day is added between months Mehekan and Areg (months 7 and 8). The way it is written, this does not mean that the Mehekan month is lengthened to 31 days (like February is lengthened to 29 days in the Julian and Gregorian calendars or like Heshvan and Kislev vary between 29 and 30 days in the Hebrew calendar). This is a real additional day, yet unconnected to the regular 5 additional days. While the regular 5 additional days can be grouped together as a month-like period numbered 13, the leap day between month 7 (Mehekan) and month 8 (Areg) cannot be considered as an additional month-like period numbered 14 or 7.5 or whatever.

Because the authoritative sources (that is, more authoritative than me) disagree and because the representation of the leap day between Mehekan and Areg is rather awkward, I have decided not to write an additional class Date::Calendar::Armenian:Sarkawag.

Beginning of the day

As stated above, according to http://www.tacentral.com/astronomy.asp?story_no=3, days begin at sunrise. On the other hand, another webpage, https://icalendrier.fr/calendriers-saga/calendriers/armenien gives an array starting at 18h, rolling over at 24h and stopping at 17h, which suggests that days begin at sunset.

This class supposes that days begin at sunrise.

Definition of the week

No explicit definition of the week is given in the webpages I have read. Yet, the webpage https://icalendrier.fr/calendriers-saga/calendriers/armenien gives an array starting at "dimanche" (Sunday) and stopping at "samedi" (Saturday), so I consider that a week spans from Sunday to Saturday.

Security issues

As explained in the Date::Calendar::Strftime documentation, please ensure that format-string passed to strftime comes from a trusted source. Failing that, the untrusted source can include a outrageous length in a strftime specifier and can drain your PC's RAM very fast.

Relations with :ver<0.0.x> classes and with core class Date

Version 0.1.0 (and API 1) was introduced to ease the conversions with other calendars in which the day is defined as midnight-to-midnight. If all Date::Calendar::xxx classes use version 0.1.x and API 1, the conversions will be correct. But if some Date::Calendar::xxx classes use version 0.0.x and API 0, there might be problems.

A date from a 0.0.x class has no daypart attribute. But when "seen" from a 0.1.x class, the 0.0.x date seems to have a daypart attribute equal to daylight. When converted from a 0.1.x class to a 0.0.x class, the date may just shift from after-sunset (or before-sunrise) to daylight, or it may shift to the daylight part of the prior (or next) date. This means that a roundtrip with cascade conversions may give the starting date, or it may give the date prior or after the starting date.

If you install <Date::Calendar::Armenian:ver<0.1.0>>, why would you refrain from upgrading other Date::Calendar::xxxx classes? So actually, this issue applies mainly to the core class Date, because you may prefer avoiding the installation of Date::Calendar::Gregorian.

Time

This module and the Date::Calendar::xxx associated modules are still date modules, they are not date-time modules. The user has to give the daypart attribute as a value among before-sunrise, daylight or after-sunset. There is no provision to give a HHMMSS time and convert it to a daypart parameter.

AUTHOR

Jean Forget <J2N-FORGET at orange dot fr>

THANKS

Many thanks to all those who were involved in Perl 6 / Raku, Rakudo and Rakudo-Star.

Many thanks to Andrew, Laurent and brian for writing books that helped me learn Perl 6 / Raku.

And some additional thanks to Andrew, for writing Perl module Date::Converter

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

METHODS

Constructors

new

new-from-date

new-from-daycount

Accessors

gist

year, month, day

daycount

daypart

month-name

month-abbr

day-name

day-of-week

week-number

week-year

day-of-year

month-day-name

Other Methods

to-date

strftime

FUNCTIONS

strftime

PROBLEMS AND KNOWN ISSUES

Authoritative Sources

Names

Sarkawag Reform

Beginning of the day

Definition of the week

Security issues

Relations with :ver<0.0.x> classes and with core class Date

Time

SEE ALSO

Raku Software

Perl 5 Software

Other Software

Books

Internet

AUTHOR

THANKS

COPYRIGHT AND LICENSE

Date::Calendar::Armenian v0.1.0

Authors

License

Dependencies

Test Dependencies

Provides

Documentation