Image

head

code

item

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

class WorkdayCalendar {
    has Str  $.file     is rw;
    has Date @.holidays is rw;
    has Str  @.workdays is rw = <Mon Tue Wed Thu Fri>;

    method clear {
        @.workdays = <Mon Tue Wed Thu Fri>;
        @.holidays = ();
    }

    multi method new(WorkdayCalendar: Str:D :$filename!) {
        my $c := WorkdayCalendar.new;
        $c.read($filename);
        $c
    }

    multi method new(WorkdayCalendar: Str:D $filename) {
        WorkdayCalendar.new(:$filename)
    }

    multi method raku(WorkdayCalendar:D:) {
        self.^name
          ~ '.new('
          ~ @.workdays.raku
          ~ ', '
          ~ @.holidays.raku
          ~ ', '
          ~ $.file.raku
          ~ ')'
    }

    method read(WorkdayCalendar:D: Str:D $calendar_filename) {
        .die without my $CAL := open $calendar_filename;
        LEAVE .close with $CAL;

        $.file = $calendar_filename;
        self.clear;

        #--- Comments are skipped
        for $CAL.lines.grep(!*.starts-with('#')) -> $line {

            my ($type, $data) = split /':'/, $line;
            given $type {
                when 'H' {
                    my ($year, $month, $day) = split /'/'|'-'/, $data; #--- Only Holidays '
                    try {
                        CATCH {
                            $*TESTING || note "ERROR: Specifying holiday date. Date $year-$month-$day skipped";
                            next;
                        }
                        push @.holidays, Date.new(:$year, :$month, :$day);
                    }
                }
                when 'W' {
                    try {
                        my @workweek_spec = split /','/, $data;
                        my $workweek_spec_failed = False;
                        for @workweek_spec -> $weekday {
                            if ($weekday ne any(<Mon Tue Wed Thu Fri Sat Sun>)) {
                                $*TESTING || warn "Workday '$weekday' not recognized";
                                $workweek_spec_failed = True;
                                last;
                            }
                        }
                        if ($workweek_spec_failed) {
                            $*TESTING || note "ERROR: Workweek specification not valid. Assuming Mon,Tue,Wed,Thu,Fri";
                            @.workdays = <Mon Tue Wed Thu Fri>;
                            next;
                        }
                        else {
                            @.workdays = @workweek_spec;
                        }
                    }
                }
            }
        }
        @.holidays .= sort;
    }

    method is-workday(WorkdayCalendar:D: Date:D $day){
        !(self.is-weekend($day) || self.is-holiday($day))
    }

    method is-weekend(WorkdayCalendar:D: Date:D $day) {
        my $weekday_name = <Mon Tue Wed Thu Fri Sat Sun>[$day.day-of-week - 1];
        not $weekday_name eq any(@.workdays)
    }

    method is-holiday(WorkdayCalendar:D: Date:D $day) {
        my @daycounts;
        push @daycounts, .daycount for @.holidays;
        $day.daycount == any(@daycounts)
    }

    method workdays-away(WorkdayCalendar:D:
      Date:D $start,
      Int:D $days
    --> Date:D) {
        return $start if $days == 0;

        my Date $current_day = $start;
        for 1..$days.abs {
            repeat {
                $current_day = ($days > 0) ?? $current_day.Date::succ
                                           !! $current_day.Date::pred;
            } until self.is-workday($current_day);
        }
        $current_day
    }

    method workdays-to(WorkdayCalendar:D:
      Date:D $start is copy,
      Date:D $target is copy
    --> Int:D) {
        return 0 if $start.daycount == $target.daycount;

        my int $sign = $start.daycount < $target.daycount
          ?? +1
          !! -1;
        my Date $current_day = $start;
        my int $count;
        repeat {
            $current_day = ($sign == +1) ?? $current_day.Date::succ
                                         !! $current_day.Date::pred;
            $count++ if self.is-workday($current_day);
        } until ($current_day.daycount == $target.daycount);

        $count * $sign
    }

    method networkdays(WorkdayCalendar:D:
      Date:D $start is copy,
      Date:D $target is copy
    --> Int:D) {
        if $start.daycount == $target.daycount {
             return self.is-workday($start).Int
        }
        my int $sign = +1;
        if $start.daycount > $target.daycount {
            $sign = -1;
            my Date $aux_day = $start;
            $start = $target;
            $target = $aux_day;
        }
        my Date $current_day = $start;
        my int $count;
        while $current_day.daycount <= $target.daycount {
            $count++ if self.is-workday($current_day);
            $current_day = $current_day.Date::succ;
        }

        $count * $sign;
    }

    method range(WorkdayCalendar:D: Date:D $begin, Date:D $end) {
        my Date @slice;
        my int $from = ($begin.daycount, $end.daycount).min;
        my int $to   = ($begin.daycount, $end.daycount).max;
        for @.holidays -> $date { #--- The holidays are already sorted
            push @slice, $date if $from <= $date.daycount <= $to;
        }
        my $result_calendar = self.clone; #-- Requires a customized version of clone
        $result_calendar.holidays = @slice;
        $result_calendar
    }

    method clone(WorkdayCalendar:D:) {
        my WorkdayCalendar $new = WorkdayCalendar.new;
        given self {
            $new.workdays = .workdays;
            $new.holidays = .holidays;
            $new.file     = .file;
        }
        $new
    }
}

#------------------------------------------------------------------------------#

class Workdate is Date {
    has WorkdayCalendar $.calendar is rw;

    method !add-calendar($calendar) {
        self.calendar = $calendar // WorkdayCalendar.new;
        self
    }

    # We try to provide the same constructors as the Date class
    multi method new(Workdate: :$year!, :$month, :$day, :$calendar) {
        self.Date::new(:$year, :$month, :$day)!add-calendar($calendar)
    }
    multi method new(Workdate: $year, $month, $day, $calendar?) {
        self.Date::new(:$year, :$month, :$day)!add-calendar($calendar)
    }
    multi method new(Workdate: Str:D $date, $calendar?) {
        self.Date::new($date)!add-calendar($calendar)
    }
    multi method new(Workdate: DateTime:D $dt, $calendar?) {
        self.Date::new($dt)!add-calendar($calendar)
    }
    multi method new(Date:D $d, $calendar) {
        self.Date::new($d)!add-calendar($calendar)
    }

    method succ() { $.calendar.workdays-away(self, +1) }
    method pred() { $.calendar.workdays-away(self, -1) }

    method is-workday() { $.calendar.is-workday(self) }
    method is-weekend() { $.calendar.is-weekend(self) }
    method is-holiday() { $.calendar.is-holiday(self) }

    method workdays-away(Int:D $days --> Int:D) {
        $.calendar.workdays-away(self, $days)
    }
    method workdays-to(Date:D $target --> Int:D) {
        $.calendar.workdays-to(self, $target)
    }
    method networkdays(Date:D $target --> Int:D) {
        $.calendar.networkdays(self, $target)
    }
    
    multi method raku(Workdate:D: --> Str:D) {
        self.^name
          ~ "($.year, $.month, $.day, $.calendar.raku())"
    }
}

#------------------------------------------------------------------------------#

multi infix:<eq>(WorkdayCalendar:D $wc1, WorkdayCalendar:D $wc2) is export {
    #--- No support for typed arrays yet AFAIK. Have to compare them in a "stringy" way
    my Str (@wc1_string_holidays, @wc2_string_holidays);
    for $wc1.holidays { push @wc1_string_holidays, .yyyy-mm-dd };
    for $wc2.holidays { push @wc2_string_holidays, .yyyy-mm-dd };

    $wc1.workdays ~~ $wc2.workdays
      && @wc1_string_holidays ~~ @wc2_string_holidays
}

multi infix:<ne>(WorkdayCalendar:D $wc1, WorkdayCalendar:D $wc2) is export {
    not $wc1 eq $wc2
}

multi infix:<->(Workdate:D $start, Workdate:D $target) is export {
    $start.calendar eq $target.calendar
      ?? -1 * $start.workdays-to($target)
      !! (die "Both Workdates must have equivalent calendars to substract them")
}



Date::WorkdayCalendar - Calendar and Date objects to handle business days, holidays and weekends


=begin code :lang<raku>

use Date::WorkdayCalendar;

# construct a default workday calendar
my $calendar = WorkdayCalendar.new;

# work out the next workday away from the given date
# 2016-11-18 is a Friday
$calendar.workdays-away(Date.new('2016-11-18'), 1);  # 2016-11-21

# construct a workday calendar from a file
my $calendar-from-file = WorkdayCalendar.new('days.cal');

# create a workdate from a date string
my $workdate = Workdate.new('2016-05-02');

# create a workdate from a Date object
my $date = Date.new('2016-11-18');
my $workdate-from-date = Workdate.new($date);

# is the day a workday?
$workdate = Workdate.new('2016-11-18');
$workdate.is-workday;  # True
$workdate.is-weekend;  # False
$workdate.is-holiday;  # False

=end code


The C<WorkdayCalendar> and C<Workdate> objects allow date calculations to be
made on a calendar that considers workdays (also called "business days").


Built on top of the C<Date> datatype, it uses a calendar file to specify how
many days a workweek has and which days are to be considered holidays.


By default, the workweek is composed of Monday, Tuesday, Wednesday,
Thursday, and Friday.  Saturday and Sunday form the weekend.


Although most countries have a Monday to Friday workweek, some have very
different ones.


More information about workweeks can be found at
L<http://en.wikipedia.org/wiki/Workweek>.


The module provides two classes: C<WorkdayCalendar> and C<Workday>.  Objects
of these classes allow date calculations to be made on a calendar that
takes workdays (also called "business days") into account.


By default, the I<workweek> is composed by B<Mon>, B<Tue>, B<Wed>, B<Thu>,
and B<Fri>.  B<Sat> and B<Sun> form the I<weekend>.


Alhough most countries have a workweek of B<Mon> to B<Fri>, some have very
different ones.


=begin code

# An example calendar file
W:Mon,Tue,Wed,Thu,Fri
H:2011/01/01
H:2011-04-05

=end code


This calendar specifies that B<Mon> to B<Fri> are to be considered workdays,
and that 2011/01/01 and 2011/04/05 are national holidays. You can use
C</> or C<-> as separators in a date. The format of the date B<must be> in
the order Year, Month, Day.


If the C<W:> specification is incorrect, the default workweek (B<Mon>,
B<Tue>, B<Wed>, B<Thu>, B<Fri>) is used. If a holiday (a row starting with
C<H:>) is not well defined, it is ignored.


Lines starting with C<#> are comments and will be ignored when parsing the file.


=begin code :lang<raku>

my $wdc1 = WorkdayCalendar.new;
my $wdc2 = WorkdayCalendar.new('calendar.cal');

=end code


Creates a new calendar. Optionally, accepts the name of a file using the
calendar format specified above. If a filename is not specified, the
calendar will have no holidays and a default workweek of B<Mon>, B<Tue>,
B<Wed>, B<Thu>, B<Fri>.


Empties the information for holidays and workdays, and resets the
workweek to the default: B<Mon>, B<Tue>, B<Wed>, B<Thu>, B<Fri>.


Reads the data of holidays and workdays from a calendar file.


Returns C<True> if the day is part of the workweek and not a holiday.


Returns C<True> if the day is not part of the workweek.


Returns C<True> if the day has been defined as holiday in the calendar file.


C<method workdays-away(Date $start, Int $days)>


Returns a C<Date> that corresponds to the workday at which C<$days> working
days have passed.  With this method you can ask questions like: "what is the
next working day for some date?" or "what is the previous working day of
some date?" or "what date is 2 working days from a date?".


Considering the workdays = B<Mon Tue Wed Thu Fri>...


=begin code

$start       : July 29, 2011 (it is a Friday)
$days        : +1
Return Value : Aug 1, 2011 (it is a Monday)

$start       : July 30, 2011 (it is a Saturday)
$days        : +1
Return Value : Aug 1, 2011 (it is a Monday)

=end code


This also works for a negative number of days.


C<method workdays-to(Date $start, Date $target)>


Returns the 'distance', in workdays, of C<$start> and C<$target> dates.


C<method networkdays(Date $start, Date $target)>


Works like the C<workdays-to> method, but emulates the NETWORKDAYS function in
Microsoft Excel.


=begin code

   Start     Target    workdays-to     networkdays
2011-07-07  2011-07-14     5              6
2011-07-07  2011-07-07     0              1
2011-07-07  2011-07-08     1              2
2011-07-07  2011-07-01    -4             -5
2011-01-01  2011-01-01     0              0
2011-01-01  2011-01-02     0              0
2011-01-01  2011-01-03     1              1

=end code


Returns a part of a calendar as a new C<WorkdayCalendar> object, between the
C<$start> and C<$end> dates, inclusive.  For example, if you have a calendar
that contains holiday information for 3 years, you can use C<range> to
obtain a new calendar that covers a period of 6 months of these 3 years.
Useful with the C<eq> operator for C<WorkdayCalendar> objects.


WorkdayCalendar

B<Date::Utils> - Provides helpful date routines for calendar creation


=begin code :lang<raku>

use Date::Utils;

=end code


B<Date::Utils> is a collection of routines to help users calculate
certain dates in relation to other dates provided by Raku's powerful
C<Date> class.


=begin code
sub nth-day-of-week-in-month(
     :$year!, :$month!, :$nth! is copy, 
     :$day-of-week! where {0 < $_ <= 7}, 
     :$debug
     --> Date) {...}
=end code


If C<$nth> is greater than the actual number of C<day-of-week>s in
the desired month or if that number is negative, the date of its last appearance in
that month is returned.


This library is free software; you may redistribute it or modify it under the Artistic License 2.0.


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

COPYRIGHT AND LICENSE

Date::Utils v0.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation