NAME

Date::MonthSet - simple interface to a collection of months

SYNOPSIS

 my $set = new Date::MonthSet;

 # accessors: capitalized and lowercase forms.  long and short forms.

 $set->january(1);
 $set->february(1);
 $set->March(1);
 $set->September(1);
 $set->Nov(1);
 $set->dec(1);

 my $s = "$set"; # JFM-----S-ND

 $set->add('June');
 $set->mark('July');

 my $s = "$set"; # JFM--JJ-S-ND

 # configurable placeholder

 $set->placeholder('*');

 my $s = "$set"; # JFM**JJ*S*ND

 $set->remove(qw(jun jul november December));
 $set->clear('march', 'sep');

 my $s = "$set"; # JFM*********

 # testing for members
 
 $set->contains(qw(jan feb));    # true
 $set->contains(2, 3);           # true
 $set->contains(1, 2, 3, 'dec'); # false

 # extracting data
 
 $set->months; # (January February March);
 $set->months_numeric; # (1, 2, 3);

 # numerification (january is the least significant bit)

 my $i = $set + 0; # 7

 $set->march(0);
 my $i = $set + 0; # 3

 $set->february(0);
 my $i = $set + 0; # 1

 $set->jan(0);
 my $i = $set + 0; # 0

---

 my $a;
 my $b;
 my $c;
 my $d;

 # initialization of Date::MonthSet objects

 $a = new Date::MonthSet integer => 4;    # march
 $a = new Date::MonthSet integer => 5;    # january and march
 $a = new Date::MonthSet integer => 4095; # twelve set bits: all months

 $b = new Date::MonthSet string => 'JFM---JAS---';
 $b = new Date::MonthSet string => '000111000111';                     # inversed
 $b = new Date::MonthSet string => '###AMJ###OND', placeholder => '#'; # the same

 $c = new Date::MonthSet set => [ 1 .. 12 ];       # all months
 $c = new Date::MonthSet set => [ qw(April sep) ]; # april and september
 $c = new Date::MonthSet set => [ 'jan', 2 .. 3 ]; # the first quarter

 # comparison between Date::MonthSet objects

 $d = new Date::MonthSet set => [ qw(apr may jun oct nov dec)  ];
 $d == $a; # false (six months vs twelve)
 $d == $b; # true (same six months)
 $a == $c; # false (six months vs three)

 $d < $a; # true (six months vs twelve)
 $d < $b; # false (equal)
 $d < $c; # false (six months vs three)

 $d = new Date::MonthSet set => [ qw(oct nov dec) ];
 $d == $a; # false (three months vs twelve)
 $d == $b; # false (three months vs six)
 $d == $c; # false (not the same three months)

 $d < $a; # true (three months vs twelve)
 $d < $b; # true (three months vs six)
 $d < $c; # false ($d is later in the year than $c)

 # addition and subtraction return new Date::MonthSet objects

 $a - $d; # JFMAMJJAS---
 $a - $b; # JFM---JAS---

 $b + $c;      # JFMAMJ---OND
 $b + $c - $d; # JFMAMJ------

DESCRIPTION

METHODS

new

instantiate a new Date::MonthSet object. if no arguments are supplied, an empty Date::MonthSet object will be created with the placeholder set to a dash '-'.

a Date::MonthSet object can be initialized in several ways. the constructor accepts the following options, passed as a hash:

placeholder

defines the placeholder value to be used during the parsing of string values and the generation of flattened strings. the default placeholder is a single dash ('-', 0x2d).

integer

initialize the Date::MonthSet object according to a single 12-bit integer value describing the months in the collection. the least significant bit represents January while the most significant bit represents December.

string

initializes the Date::MonthSet object according to a string value describing the months in the collection. two formats are accepted.

the first format is a simple twelve character sequence of zeroes and ones. the first byte in the sequence represents January while the twelfth byte represents December. if more that twelve bytes are specified, the constructor will die.

the second format is identifical to the format produced by stringification of a Date::MonthSet object. the value of the placeholder is taken into account. if the month values deviate from the standard JFMAMJJASOND, the constructor will die. if more values are parsed out of the string than there should be, the constructor will die.

set

initializes the Date::MonthSet object according to an array of long month names, short month names, and/or numerical indices. all three forms may be combined. duplicates are ignored.

months

months_numeric

mark/add

clear/remove

contains

placeholder

format

gets/sets the format used in stringification. when setting the format, the first argument defines the format to be used when the month is contained within the set while the second argument defines the format to be used when the month is not contained within the set. if undef is specified for either of them, the current setting is unchanged.

stringify

numerify

equal

compare

addition

subtraction

AUTHOR

Mike Eldridge <diz@cpan.org>

LICENSE

this library is free software. you may distribute it and/or modify it under the same terms as perl itself.