New function Add-WorkingDays +semver:minor

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- New function `Add-WorkingDays`
 
 ## [0.1.7] - 2022-04-14
 ### Changed

src/Public/Add-WorkingDays.ps1

@@ -0,0 +1,81 @@
+function Add-WorkingDays {
+    [CmdletBinding()]
+    <#
+    .SYNOPSIS
+        Add a number of working days onto a given date.
+    .DESCRIPTION
+        Add a number of working days onto a given date.
+
+        What constitutes a "working day" in terms of day of the week, or calendar date, is arbitrary and completely customisable.
+
+        In other words, the default parameters dictate normal working days, which are Monday through Friday.
+
+        You can also specify particular dates, or days of the week, to be regarded as non-working dates via the -NonWorkingDates and -NonWorkingDaysOfWeek parameters.
+    .PARAMETER Date
+        The starting date used for calculation.
+        
+        The default value is the current datetime.
+    .PARAMETER Days
+        The number of working days to add onto from the given date.
+        
+        Number can be negative in order to substract from the given date, too.
+    .PARAMETER NonWorkingDaysOfWeek
+        The days of the week, representated as strings e.g. 'Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday', which denotes non-working days of the week.
+        
+        Days specified in this parameter will not be considered as working days.
+
+        Default values are Saturday and Sunday.
+    .PARAMETER NonWorkingDates
+        An array of datetime objects which denote specific non-working dates.
+        
+        Dates specified in this parameter will not be considered as working days.
+    .EXAMPLE
+        Add-WorkingDays -Days 3
+        
+        Adds 3 working days onto the current date. For example, if today's date is 2022-04-07, then the returned datetime object will be 2022-04-12.
+    .EXAMPLE
+        Add-WorkingDays -Days -3
+
+        Minuses 3 working days from the current date. For example, if today's date is 2022-04-07, then the returned datetime object will be 2022-04-04.
+    .EXAMPLE
+        Add-WorkingDays -Date (Get-Date '2022-04-14') -Days 5 -NonWorkingDates (Get-Date '2022-04-15'),(Get-Date '2022-04-18')
+
+        Add 5 working days from 2022-04-14, discounting 2022-04-15 (Good Friday) and 2022-04-18 (Easter Monday) as working days. The returned datetime object will be 2022-04-25.
+    .EXAMPLE
+        Add-WorkingDays -Days 1 -NonWorkingDaysOfWeek 'Friday','Saturday','Sunday'
+
+        Add 1 working day onto the current date. For example, if today's date is 2022-04-07, then the returned datetime object will be 2022-04-11.
+    .INPUTS
+        This function does not accept pipeline input.
+    .OUTPUTS
+        System.DateTime
+    .NOTES
+        Chris Dent (@indented-automation) wrote this in the WinAdmins Discord
+        https://discord.com/channels/618712310185197588/618857671608500234/913855890384371712
+    #>
+    param (
+        [Parameter()]
+        [object]$Date = (Get-Date),
+
+        [Parameter(Mandatory)]
+        [int]$Days,
+
+        [Parameter()]
+        [ValidateSet('Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday')]
+        [String[]]$NonWorkingDaysOfWeek = @('Saturday','Sunday'),
+
+        [Parameter()]
+        [DateTime[]]$NonWorkingDates
+    )
+
+    $increment = $Days / [Math]::Abs($Days)
+    do {
+        $Date = $Date.AddDays($increment)
+
+        if ($NonWorkingDaysOfWeek -notcontains $Date.DayOfWeek -And $NonWorkingDates -notcontains $Date.Date) {
+            $Days -= $increment
+        }
+    } while ($Days)
+
+    return $Date
+}

src/Public/Get-ElapsedBusinessTime.ps1

@@ -24,12 +24,14 @@ function Get-ElapsedBusinessTime {
         Note: this parameter is a datetime object is, however only the time is used for calculation. The date is ignored.
     .PARAMETER FinishHour
         The final hour of a typical working day. The default final hour is 17:00.
-        
+                
         Note: this parameter is a datetime object is, however only the time is used for calculation. The date is ignored.
     .PARAMETER NonWorkingDaysOfWeek
         The days of the week, representated as strings e.g. 'Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday', which denotes non-working days of the week.
         
         Days specified in this parameter will not be considered as working days.
+
+        Default values are Saturday and Sunday.
     .PARAMETER NonWorkingDates
         An array of datetime objects which denote specific non-working dates.
         

src/Public/Get-WorkingDates.ps1

@@ -22,6 +22,8 @@ function Get-WorkingDates {
         The days of the week, representated as strings e.g. 'Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday', which denotes non-working days of the week.
         
         Days specified in this parameter will not be considered as working days.
+
+        Default values are Saturday and Sunday.
     .PARAMETER NonWorkingDates
         An array of datetime objects which denote specific non-working dates.
 

src/Public/Test-WorkingDay.ps1

@@ -26,6 +26,8 @@ function Test-WorkingDay {
         The days of the week, representated as strings e.g. 'Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday', which denotes non-working days of the week.
         
         Days specified in this parameter will not be considered as working days.
+
+        Default values are Saturday and Sunday.
     .PARAMETER NonWorkingDates
         An array of datetime objects which denote specific non-working dates.