/ 
NepaliDateTime-0.01
/ NepaliDateTime::Date

NAME

NepaliDateTime::Date - Bikram Sambat date object

SYNOPSIS

use NepaliDateTime::Date;

# Construction
my $d = NepaliDateTime::Date->new(2081, 3, 15);

# Today in BS
my $today = NepaliDateTime::Date->today();

# From AD date
my $bs = NepaliDateTime::Date->from_ad(2024, 7, 15);

# Convert to AD
my ($y, $m, $day) = $bs->to_ad();

# From ordinal (days since BS 1975-01-01)
my $d2 = NepaliDateTime::Date->from_ordinal(1);

# Arithmetic
my $d3 = $d->add_days(10);
my $d4 = $d->add_months(3);
my $d5 = $d->add_years(1);
my $diff = $d3 - $d;   # integer days

# Comparison
print "equal\n" if $d == $d2;
print "later\n" if $d3 > $d;

# Formatting
print $d->isoformat(), "\n";       # 2081-03-15
print $d->strftime('%B %Y'), "\n"; # Asar 2081
print $d->format_devanagari(), "\n";

# Weekday info
print $d->weekday(), "\n";         # 0=Sun .. 6=Sat
print $d->day_name(), "\n";        # "Wednesday"
print $d->day_name_np(), "\n";     # Devanagari

# Month info
print $d->month_name(), "\n";
print $d->days_in_month(), "\n";
print $d->days_in_year(), "\n";

# Nepal fiscal year (Shrawan 1 – Ashadh end)
my ($fy_start, $fy_end) = $d->fiscal_year();  # e.g. (2080, 2081)
my $fq = $d->fiscal_quarter();                 # 1..4

# Calendar quarter  (Q1=Bai-Asa, Q2=Shr-Asw, Q3=Kar-Pou, Q4=Mag-Cha)
print $d->quarter(), "\n";

# Date-range list
my @dates = NepaliDateTime::Date->date_range($start, $end);

# Print a calendar for this month
$d->print_calendar();

DESCRIPTION

NepaliDateTime::Date represents a date in the Bikram Sambat calendar.

Supported range: BS 1975-01-01 to BS 2100-12-30.

CONSTRUCTOR

new($year, $month, $day)

Creates a new BS date. Croaks if the date is out of the supported range.

CLASS METHODS

today()

Returns today's date in BS (using Nepal Standard Time UTC+05:45).

from_ad($year, $month, $day)

Convert an AD (Gregorian) date to BS.

my $bs = NepaliDateTime::Date->from_ad(2024, 7, 15);

from_ordinal($n)

Construct a date from its BS ordinal (BS 1975-01-01 == 1).

from_timestamp($epoch)

Construct from a Unix timestamp, converting to Nepal Standard Time.

from_iso($string)

Parse an ISO-8601 BS date string YYYY-MM-DD.

date_range($start_date, $end_date)

Returns a list of all NepaliDateTime::Date objects from $start_date up to and including $end_date. Both arguments must be NepaliDateTime::Date objects.

my @week = NepaliDateTime::Date->date_range($start, $end);

min()

Returns the minimum supported date (BS 1975-01-01).

max()

Returns the maximum supported date (BS 2100-12-30).

ACCESSORS

year() / month() / day()

CONVERSION METHODS

to_ad()

Returns ($year, $month, $day) in the Gregorian (AD) calendar.

to_ad_string()

Returns the AD date as "YYYY-MM-DD".

toordinal()

Returns the BS ordinal: BS 1975-01-01 = 1.

to_timestamp()

Returns approximate Unix timestamp for midnight of this date in Nepal time.

DATE ATTRIBUTES

weekday()

Day of the week: 0=Sunday, 1=Monday, …, 6=Saturday.

(Note: this follows the Python nepali_datetime convention where Sunday=0, unlike Python's standard datetime where Monday=0.)

weekday_iso()

ISO weekday: 1=Monday … 7=Sunday.

day_name()

Full English weekday name, e.g. "Wednesday".

day_name_abbr()

Abbreviated English weekday name, e.g. "Wed".

day_name_np()

Weekday name in Nepali (Devanagari).

month_name()

Full English month name, e.g. "Asar".

month_name_abbr()

Abbreviated English month name, e.g. "Asa".

month_name_np()

Month name in Nepali (Devanagari).

days_in_month()

Number of days in the current month.

days_in_year()

Total number of days in the current BS year.

day_of_year()

Day number within the year (1-based).

week_of_year()

Week number within the year (1-based, week starts on Sunday).

quarter()

Calendar quarter (1..4):

Q1: Baishakh – Asar   (months 1–3)
Q2: Shrawan  – Aswin  (months 4–6)
Q3: Kartik   – Poush  (months 7–9)
Q4: Magh     – Chaitra (months 10–12)

fiscal_year()

Returns ($fy_start_year, $fy_end_year) for Nepal's fiscal year.

Nepal's fiscal year runs from 1 Shrawan (month 4) to the last day of Ashadh (month 3) of the next year.

my ($fy_s, $fy_e) = $date->fiscal_year();
# e.g. for a date in 2081, month 6 → (2081, 2082)
# e.g. for a date in 2081, month 2 → (2080, 2081)

fiscal_quarter()

Returns the quarter (1..4) within Nepal's fiscal year:

FQ1: Shrawan  – Aswin   (months 4–6)
FQ2: Kartik   – Poush   (months 7–9)
FQ3: Magh     – Asar    (months 10–3 spanning the year boundary)
FQ4: Baishakh – Ashadh  (months 1–3, i.e. the second half of FQ3 and FQ4)

More precisely: FQ1: months 4,5,6 FQ2: months 7,8,9 FQ3: months 10,11,12 FQ4: months 1,2,3

is_weekend()

Returns true (1) if the day is Saturday (the Nepal weekend day). (Friday is a half-day in Nepal; returns 0 for Friday unless $include_friday is set.)

is_holiday()

Placeholder – returns 0. Override in a subclass or supply a holiday list.

ARITHMETIC

add_days($n)

Returns a new date $n days in the future (or past for negative $n).

add_months($n)

Returns a new date $n months in the future (negative for past).

If the resulting month has fewer days than the current day, the day is clamped to the last day of that month.

add_years($n)

Returns a new date $n years in the future (negative for past). Day is clamped to month end if necessary.

month_start()

Returns the first day of the current month.

month_end()

Returns the last day of the current month.

year_start()

Returns 1 Baishakh of the current year.

year_end()

Returns the last day of Chaitra (month 12) of the current year.

fiscal_year_start()

Returns the start of the fiscal year this date falls in (1 Shrawan).

fiscal_year_end()

Returns the end of the fiscal year this date falls in (last day of Ashadh).

age_from($birth_date)

Returns the age in complete years from $birth_date to this date.

my $age = NepaliDateTime::Date->today()->age_from($birth);

days_until($other)

Returns the number of days from this date to $other (positive if $other is in the future).

days_since($other)

Returns the number of days from $other to this date.

nth_weekday_of_month($n, $weekday)

Returns the $n-th occurrence (1-based) of $weekday (0=Sun..6=Sat) in the same year/month as this date. Returns undef if no such occurrence exists (e.g. 5th Saturday in a short month).

my $first_sat = $d->nth_weekday_of_month(1, 6);   # first Saturday
my $second_sun = $d->nth_weekday_of_month(2, 0);  # second Sunday

last_weekday_of_month($weekday)

Returns the last occurrence of $weekday in the current month.

next_weekday($weekday)

Returns the next occurrence of $weekday on or after this date.

prev_weekday($weekday)

Returns the previous occurrence of $weekday on or before this date.

replace(%fields)

Returns a new date with some fields replaced. Valid keys: year, month, day.

my $d2 = $d->replace(day => 1);

FORMATTING

isoformat()

Returns the date as "YYYY-MM-DD" in BS.

to_string()

Alias for isoformat(). Also used by string overloading ("$date").

ctime()

Returns a ctime-style string, e.g. "Wed Asa 15 00:00:00 2081".

strftime($format)

Format using a strftime-like format string.

Supported directives:

%a   Abbreviated weekday name (Sun Mon Tue …)
%A   Full weekday name (Sunday Monday …)
%G   Full weekday name in Nepali
%w   Weekday as integer (0=Sun .. 6=Sat)
%d   Day of month, zero-padded (01-32)
%D   Day of month in Devanagari numerals
%b   Abbreviated month name (Bai Jes Asa …)
%B   Full month name (Baishakh Jestha Asar …)
%N   Month name in Nepali
%m   Month number, zero-padded (01-12)
%n   Month number in Devanagari
%y   2-digit year
%Y   4-digit year
%k   2-digit year in Devanagari
%K   4-digit year in Devanagari
%j   Day of year (001-366)
%U   Week number (Sunday start)
%H   Hour 00-23     (00 for date-only)
%I   Hour 01-12     (00 for date-only)
%p   AM/PM          (AM for date-only)
%M   Minute 00-59   (00 for date-only)
%S   Second 00-59   (00 for date-only)
%f   Microseconds   (000000 for date-only)
%%   Literal %

strptime($class, $string, $format)

Parse a BS date string using a format string. Returns a new NepaliDateTime::Date. Supports the same directives as strftime.

my $d = NepaliDateTime::Date->strptime('2081-03-15', '%Y-%m-%d');
my $d = NepaliDateTime::Date->strptime('15 Asar 2081', '%d %B %Y');

format_devanagari()

Returns a nicely formatted date string entirely in Devanagari script:

e.g. "२०८१ असार १५, बुधवार"

format_nepali_date()

Returns the date as "DD Month YYYY" in English month names.

CALENDAR

Prints a month calendar to STDOUT.

Options (key-value pairs):

devanagari => 1    Use Devanagari month name and digits
highlight  => 1    Highlight today (ANSI colour; default on if $date == today)
width      => 4    Column width (default 4)

Prints calendars for all 12 months of the year, 3 months per row.

UTILITY FUNCTIONS

NepaliDateTime::Date::days_in_month_for($year, $month)

Returns the number of days in the given BS year/month.

NepaliDateTime::Date::is_valid($year, $month, $day)

Returns true if ($year, $month, $day) is a valid BS date.

clone()

Returns a copy of this date object.

stringify()

Human-readable string (same as isoformat()). Also invoked by "$date".

SUPPORTED B.S. DATE RANGE

1975-01-01 (= AD 1918-04-13) to 2100-12-30 (= AD 2044-04-13 approx.)

WEEKDAY CONVENTION

0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday

This matches the Python nepali_datetime convention (not Python's standard datetime, where Monday=0).

SEE ALSO

NepaliDateTime::DateTime