NAME

Time::Keeper::YearMonth - a year and a month

VERSION

Version 0.11

SYNOPSIS

use Time::Keeper;

my $ym = Time::Keeper::YearMonth->new(year => 2026, month => 10);
my $ym = Time::Keeper::YearMonth->parse('2026-10');
my $ym = $t->to_year_month;

$ym->days_in_month;             # 31
$ym->plus(months => 3);         # 2027-01
$ym->on(15);                    # a Time::Keeper::Date, 2026-10-15
$ym->last_day;                  # 2026-10-31
$ym->format('MMMM y');          # October 2026
"$ym";                          # 2026-10

DESCRIPTION

A year and a month: a billing period, a statement, a month in a report. It has no day, so nothing that needs one: no day of the week, no week, no date formats that write a day. "on" and "last_day" give a Time::Keeper::Date when a day is chosen.

CONSTRUCTORS

new

Time::Keeper::YearMonth->new(year => 2026, month => 10);
Time::Keeper::YearMonth->new(year => 2026, month => 10, locale => 'fr');

Both are required.

parse

strptime

parse_cldr

Time::Keeper::YearMonth->parse('2026-10');
Time::Keeper::YearMonth->strptime('10/2026', '%m/%Y');
Time::Keeper::YearMonth->parse_cldr('octobre 2026', 'MMMM y', locale => 'fr');

parse reads YYYY-MM and refuses a day, a week, a time or a zone in the text, and a year alone. Under a pattern a day the pattern reads is dropped. Each takes locale.

try_new

try_parse

try_strptime

try_parse_cldr

As the method without try_, but undef where it would die, with $@ left as it was.

ACCESSORS

year

month

quarter

is_leap_year

days_in_month

days_in_year

days_in_quarter

locale

month_name

month_abbr

era_name

era_abbr

quarter_name

quarter_abbr

As Time::Keeper::Date's.

NEW VALUES FROM OLD

with

$ym->with(month => 12);
$ym->with(year => 2027);

in_locale

The same year and month in another locale.

on

last_day

$ym->on(15);          # a Time::Keeper::Date
$ym->on('last');
$ym->last_day;        # the same

The date of that day of the month; a day the month does not have is an error.

ARITHMETIC

plus

minus

$ym->plus(months => 11);
$ym->plus(years => 1);
$ym->minus($other);          # a duration of months

Years and months, by name or as a Time::Keeper::Duration; days and smaller are an error. + and - do the same.

truncate

round

end_of

To a year or a quarter: the first month of it, the nearest, the last.

COMPARING AND PRINTING

compare

As "compare" in Time::Keeper::Date, between years and months only.

iso8601

TO_JSON

2026-10; "$ym" is the same.

FORMATTING

strftime

format

format_date

format_skeleton

$ym->format('MMMM y');
$ym->strftime('%B %Y');
$ym->format_date('medium');      # Oct 2026, the locale's yMMM skeleton
$ym->format_skeleton('yMMM');

A letter that needs a day, a time or a zone is an error naming it. format_date uses the locale's yMMMM (full and long), yMMM (medium) and yM (short) skeletons.

SERIALISATION

STORABLE_freeze

STORABLE_thaw

FREEZE

THAW