NAME

AmberDB::Date - Date manipulation, chronological ID generation, range calculation, and formatting utility

SYNOPSIS

# 1. Direct usage via AmberDB instance ($adb inherits AmberDB::Date):
my $today_id   = $adb->day_id;                   # "20260828"
my $now_sec_id = $adb->second_id;                # "20260828143015"
my $date_id    = $adb->str2dateid('2026-08-28'); # "20260828"
my $human_str  = $adb->dateid2str('20260828');   # "28/08/2026"
my @days       = $adb->day_range('20260101', '20260131');
my $past_id    = $adb->offset2date('-7D');       # Date ID 7 days ago

# 2. Standalone usage:
use AmberDB::Date;
my $date = AmberDB::Date->new();
my $curr_day = $date->day_id;

DESCRIPTION

AmberDB::Date provides methods for date parsing, compact chronological date ID conversions (fixed-width numeric format YYYYMMDDHHMMSS), range calculations, relative offset dates (e.g. "-2D", "1M"), ISO week numbers, and localized date string formatting.

Inheritance Note: AmberDB inherits from AmberDB::Date via use parent. All methods and timestamp accessors documented below can be invoked directly on any $adb instance (e.g. $adb->day_id), as well as on standalone AmberDB::Date objects.

CONSTRUCTOR

new([%options | $hashref])

Creates and returns a new AmberDB::Date instance initialized with the current timestamp (or a custom timestamp passed via time => $epoch).

my $date = AmberDB::Date->new();
my $custom_date = AmberDB::Date->new(time => 1700000000);

DATE ACCESSORS (GETTERS)

All accessor methods return the formatted component for the instance's active timestamp. Optionally, passing an explicit Unix timestamp ($epoch) calculates the value for that specific time on the fly.

day_id([$epoch])

Returns the 8-digit numeric date ID (YYYYMMDD).

my $id = $adb->day_id; # e.g. "20260828"

second_id([$epoch])

Returns the 14-digit full timestamp ID (YYYYMMDDHHMMSS).

my $id = $adb->second_id; # e.g. "20260828143015"

minute_id([$epoch]) / hour_id([$epoch]) / month_id([$epoch])

Returns the corresponding numeric ID:

• month_id: 6 digits (YYYYMM)

• hour_id: 10 digits (YYYYMMDDHH)

• minute_id: 12 digits (YYYYMMDDHHMM)

year([$epoch]) / month([$epoch]) / day([$epoch])

Returns 4-digit year, 2-digit zero-padded month (01..12), or 2-digit day (01..31).

hour([$epoch]) / minute([$epoch]) / second([$epoch])

Returns 2-digit zero-padded hour (00..23), minute (00..59), or second (00..59).

str([$epoch]) / short([$epoch]) / only_time([$epoch])

• short: Returns "DD/MM/YYYY" format.

• only_time: Returns "HH:MM:SS" format.

• str: Returns combined "DD/MM/YYYY - HH:MM:SS" format.

epoch()

Returns the underlying Unix epoch timestamp (integer seconds).

monthname([$epoch]) / dayname([$epoch])

Returns the localized full month name (e.g. "January", "Ağustos") or day name (e.g. "Friday", "Cuma").

METHODS

get_date([$timestamp])

Generates and returns a blessed AmberDB::Date hash containing all parsed date components (year, month, day, hour, minute, second, daynumber, monthname, dayname, IDs, and formatted strings).

my $d = $adb->get_date(time());
print $d->{day_id}, " - ", $d->{monthname};

str2dateid($datestr)

Parses human-readable date strings (e.g. "28/08/2026", "2026-08-28", "28.08.2026 14:30") into a compact numeric date ID (YYYYMMDD or YYYYMMDDHHMMSS).

my $id = $adb->str2dateid("2026-08-28");          # "20260828"
my $id = $adb->str2dateid("28/08/2026 14:30:00"); # "20260828143000"

dateid2str($dateid)

Converts a numeric date ID back into a formatted human-readable string based on its digit length:

• 14 digits (YYYYMMDDHHMMSS) -> "DD/MM/YYYY - HH:MM:SS"

• 12 digits (YYYYMMDDHHMM) -> "DD/MM/YYYY - HH:MM"

• 8 digits (YYYYMMDD) -> "DD/MM/YYYY"

• 6 digits (YYYYMM) -> "MonthName YYYY"

my $str = $adb->dateid2str("20260828");         # "28/08/2026"
my $str = $adb->dateid2str("20260828143015");   # "28/08/2026 - 14:30:15"

time2str([$timestamp])

Formats a Unix epoch timestamp into an HTTP / RFC 1123 compliant date string suitable for HTTP headers and email timestamps.

my $http_date = $adb->time2str(time());
# => "Fri, 28 Aug 2026 11:30:00 GMT"

day_range($start_dateid, $end_dateid)

Generates a chronological list of 8-digit date IDs (YYYYMMDD) between $start_dateid and $end_dateid inclusive, handling leap years and multi-year spans accurately.

my @days = $adb->day_range("20260226", "20260302");
# => ("20260226", "20260227", "20260228", "20260301", "20260302")

dateid2week($dateid)

Calculates the ISO 8601 week number and day index for a given date ID. In list context, returns ($week_number, $weekday_index, $day_of_year).

my $week = $adb->dateid2week("20260828"); # e.g. 35

offset2date($offset_string)

Calculates a new 8-digit date ID (YYYYMMDD) relative to the current timestamp using offset syntax (e.g. "-2D" for 2 days ago, "10D" for 10 days later, "1M" for 1 month later, "-1Y" for 1 year ago).

my $yesterday = $adb->offset2date("-1D");
my $next_week = $adb->offset2date("7D");

MonthDaysInYear([$year_offset])

Returns the 0-indexed month index and a 12-element list containing the number of days in each month for the specified year offset (default is current year, 0). Handles leap years.

my ($current_mon, @days_in_months) = $adb->MonthDaysInYear();
# @days_in_months = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)

AUTHOR

Maruf Cetin <marufcetin@gmail.com>

LICENSE AND COPYRIGHT

Copyright (C) 2008-2026 Maruf Cetin.

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

cpanm AmberDB

perl -MCPAN -e shell
install AmberDB