PSBusinessTime.psm1
|
#region Private functions function GetElapsedTime { [CmdletBinding()] param ( [Parameter(Mandatory)] [DateTime]$StartDate, [Parameter(Mandatory)] [DateTime]$EndDate, [Parameter(Mandatory)] [DateTime]$StartHour, [Parameter(Mandatory)] [DateTime]$FinishHour ) $Subtractor = New-TimeSpan $StartHourDifference = $StartHour.TimeOfDay - $StartDate.TimeOfDay if ($StartHourDifference -gt 0) { $Subtractor += $StartHourDifference } $FinishHourDifference = $EndDate.TimeOfDay - $FinishHour.TimeOfDay if ($FinishHourDifference -gt 0) { $Subtractor += $FinishHourDifference } (New-TimeSpan -Start $StartDate -End $EndDate) - $Subtractor } #endregion #region Public functions function Get-ElapsedBusinessTime { <# .SYNOPSIS Get the elapsed time between two dates, where the time measured is only inbetween "business hours". .DESCRIPTION Get the elapsed time between two dates, where the time measured is only inbetween "business hours". This is helpful to measure the amount of time past from a start datetime, to an end datetime, while only considering "business hours". What constitutes a "business hours" in terms of day of the week, or calendar date, including working hours, is arbitrary and completely customisable. In other words, the default parameters dictate normal working days are Monday through Friday and 08:00 through 17:00. You can also specify particular dates, or days of the week, to be regarded as non-working dates via the -NonWorkingDates and -NonWorkingDaysOfWeek parameters. This function does consider both date and time while calculating the elapsed time. .PARAMETER StartDate The datetime object to start calculating the elapsed time from. It must be an older datetime than -EndDate. .PARAMETER EndDate The datetime object to end calculating the elapsed time to. It must be a newer datetime than -StartDate. .PARAMETER StartHour The starting hour of a typical working day. The default starting hour is 08:00 (AM). 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. .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 Get-ElapsedBusinessTime -StartDate (Get-Date '2022-04-11 10:00:00') -EndDate (Get-Date '2022-04-11 10:37:00') The function will return a timespan object of 37 minutes. 2022-04-11 is a Monday and the whole time inbetween the date range given is within the default parameters. .EXAMPLE Get-ElapsedBusinessTime -StartDate (Get-Date '2022-04-11 08:00:00') -EndDate (Get-Date '2022-04-12 08:00:00') The function will return a timespan object of 9 hours. 2022-04-11 is a Monday and 2022-04-12 is a Tuesday, and only 9 hours is considered "working hours" within the default parameters. .EXAMPLE Get-ElapsedBusinessTime -StartDate (Get-Date '2022-04-11 13:00:00') -EndDate (Get-Date '2022-04-13 13:00:00') The function will return a timespan object of 18 hours. 2022-04-11 through 2022-04-13 is Monday through Wednesday, and only 18 hours is considered "working hours" within the default parameters. .EXAMPLE Get-ElapsedBusinessTime -StartDate (Get-Date '2022-04-01 00:00:00') -EndDate (Get-Date '2022-04-30 23:59:59') -NonWorkingDates (Get-Date '2022-04-15'), (Get-Date '2022-04-18') The function will return a timespan object of 162 hours. 2022-04-01 through 2022-04-30 is an entire calendar month, and only 162 hours is considered "working hours" within the defined parameters. '2022-04-15' and '2022-04-18' are considered non-working dates. .EXAMPLE Get-ElapsedBusinessTime -StartDate (Get-Date '2022-01-01 00:00:00') -EndDate (Get-Date '2022-12-31 23:59:59') -NonWorkingDates (Get-Date '2022-01-03'), (Get-Date '2022-04-15'), (Get-Date '2022-04-18'), (Get-Date '2022-05-02'), (Get-Date '2022-06-02'), (Get-Date '2022-06-03'), (Get-Date '2022-08-29'), (Get-Date '2022-12-26'), (Get-Date '2022-12-27') The function will return a timespan object of 2259 hours. 2022-01-01 through 2022-12-31 is an entire year, and only 2259 hours is considered "working hours" within the defined parameters. All dates passed to -NonWorkingDates are considered non-working dates (public holidays in the UK for 2022). .EXAMPLE Get-ElapsedBusinessTime -StartDate (Get-Date '2022-01-01 00:00:00') -EndDate (Get-Date '2022-12-31 23:59:59') -NonWorkingDaysOfWeek 'Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday' The function will return a timespan object of 0 hours. 2022-01-01 through 2022-12-31 is an entire year, and 0 hours is considered "working hours" within the defined parameters. All days passed to -NonWorkingDaysOfWeek are considered non-working days, hence the result of 0 hours. .INPUTS This function does not accept pipeline input. .OUTPUTS System.TimeSpan #> [CmdletBinding()] param( [Parameter(Mandatory)] [datetime]$StartDate, [Parameter(Mandatory)] [ValidateScript({ if ($StartDate -gt $_) { throw "-StartDate must be less than -EndDate." } else { return $true } })] [datetime]$EndDate, [Parameter()] [DateTime]$StartHour = '08:00:00', [Parameter()] [DateTime]$FinishHour = '17:00:00', [Parameter()] [ValidateSet('Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday')] [String[]]$NonWorkingDaysOfWeek = @('Saturday','Sunday'), [Parameter()] [DateTime[]]$NonWorkingDates ) $CommonParams = @{ NonWorkingDaysOfWeek = $NonWorkingDaysOfWeek NonWorkingDates = $NonWorkingDates } $WorkingHours = New-TimeSpan -Start $StartHour -End $FinishHour $WorkingDays = Get-WorkingDates -StartDate $StartDate -EndDate $EndDate @CommonParams if ($null -eq $WorkingDays) { New-TimeSpan } elseif ($WorkingDays.Count -eq 1) { $Params = @{ StartDate = $StartDate EndDate = $EndDate StartHour = $StartHour FinishHour = $FinishHour } GetElapsedTime @Params } else { $NumberOfWorkingDays = $WorkingDays.Count $ElapsedTime = New-TimeSpan if (Test-WorkingDay -Date $StartDate -StartHour $StartHour -FinishHour $FinishHour @CommonParams) { $FirstDayEndDate = Get-Date ('{0}/{1}/{2} {3}:{4}:{5}' -f $StartDate.Year, $StartDate.Month, $StartDate.Day, $FinishHour.Hour, $FinishHour.Minute, $FinishHour.Second) $Params = @{ StartDate = $StartDate EndDate = $FirstDayEndDate StartHour = $StartHour FinishHour = $FinishHour } $ElapsedTime += (GetElapsedTime @Params) $NumberOfWorkingDays-- } if (Test-WorkingDay -Date $EndDate -StartHour $StartHour -FinishHour $FinishHour @CommonParams) { $LastDayStartDate = Get-Date ('{0}/{1}/{2} {3}:{4}:{5}' -f $EndDate.Year, $EndDate.Month, $EndDate.Day, $StartHour.Hour, $StartHour.Minute, $StartHour.Second) $Params = @{ StartDate = $LastDayStartDate EndDate = $EndDate StartHour = $StartHour FinishHour = $FinishHour } $ElapsedTime += (GetElapsedTime @Params) $NumberOfWorkingDays-- } $InBetweenHours = $NumberOfWorkingDays * $WorkingHours.Hours (New-TimeSpan -Hours $InBetweenHours) + $ElapsedTime } } function Get-WorkingDates { <# .SYNOPSIS Return all the working dates between two given datetimes. .DESCRIPTION Return all the working dates between two given datetimes. This is helpful to identify the specific dates between two dates which are considered to be "working day(s)". What constitutes a "working day" in terms of day of the week, or calendar date, including working hours, is arbitrary and completely customisable. In other words, the default parameters dictate normal working days 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. This function does not consider the time, only the date, when determining whether it is a working date or not. .PARAMETER StartDate The datetime object to identify all the working dates from. It must be an older datetime than -EndDate. .PARAMETER EndDate The datetime object to identify all the working dates to. It must be a newer datetime than -StartDate. .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. .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 Get-WorkingDates -StartDate (Get-Date '2022-04-11') -EndDate (Get-Date '2022-04-11') The function will return a datetime object of date '2022-04-11' because '2022-04-11' is considered a working date, as it is a date within the default parameters, and is the only working date within the provided range. '2022-04-11' is a Monday. .EXAMPLE Get-WorkingDates -StartDate (Get-Date '2022-04-09') -EndDate (Get-Date '2022-04-09') The function will not produce any output (null) because '2022-04-09' is not considered a working day within the default parameters and the given range. '2022-04-09' is a Saturday. .EXAMPLE Get-WorkingDates -StartDate (Get-Date '2022-04-04') -EndDate (Get-Date '2022-04-17') The function will return an array of 10 datetime objects for '2022-04-04' through to '2022-04-08', and '2022-04-11' through to '2022-04-15'. These are considered working dates within the default parameters. '2022-04-04' through to '2022-04-08' is Monday through to Friday, and '2022-04-11' through to '2022-04-15' is Monday through to Friday. .EXAMPLE Get-WorkingDates -StartDate (Get-Date '2022-04-04') -EndDate (Get-Date '2022-04-17') -NonWorkingDates (Get-Date '2022-04-05') The function will return an array of 9 datetime objects for '2022-04-04', '2022-04-06' through to '2022-04-08', and and '2022-04-11' through to '2022-04-15'. These are considered working dates within the defined parameters. '2022-04-05' is considered a non-working date, whereas every other date inbetween the range is considered a working date. .EXAMPLE Get-WorkingDates -StartDate (Get-Date '2022-04-04') -EndDate (Get-Date '2022-04-17') -NonWorkingDaysOfWeek 'Saturday','Sunday','Monday' The function will return an array of 8 datetime objects for '2022-04-05' through to '2022-04-08', and '2022-04-12' through to '2022-04-15'. These are considered working dates within the defined parameters. Saturdays, Sundays, and Mondays, are considered non-working days, therefore every other date inbetween the range is considered a working date. .INPUTS This function does not accept pipeline input. .OUTPUTS System.DateTime[] #> [CmdletBinding()] param ( [Parameter(Mandatory)] [DateTime]$StartDate, [Parameter(Mandatory)] [ValidateScript({ if ($StartDate -gt $_) { throw "-StartDate must be less than -EndDate." } else { return $true } })] [DateTime]$EndDate, [Parameter()] [ValidateSet('Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday')] [String[]]$NonWorkingDaysOfWeek = @('Saturday','Sunday'), [Parameter()] [DateTime[]]$NonWorkingDates ) if ($StartDate.TimeOfDay -eq $EndDate.TimeOfDay) { # This can return 1 less than intended if we do not do this change. # For example, if the dates in between are 3 working days, # but the time span between them are 2 whole days, # this returns 2 instead of 3 $EndDate = $EndDate.AddSeconds(1) } $TimeSpan = New-TimeSpan -Start $StartDate -End $EndDate $Days = [Math]::Ceiling($TimeSpan.TotalDays) $Date = $StartDate $WorkingDays = do { if ($NonWorkingDaysOfWeek -notcontains $Date.DayOfWeek -And $NonWorkingDates -notcontains $Date.Date) { $Date.Date } $Date = $Date.AddDays(1) $Days-- } while ($Days) $WorkingDays } function Test-WorkingDay { <# .SYNOPSIS Determine whether a given datetime is a working day. .DESCRIPTION Determine whether a given datetime is a working day. What constitutes a "working day" in terms of day of the week, or calendar date, including working hours, is arbitrary and completely customisable. In other words, the default parameters dictate normal working days are Monday through Friday, and normal working hours are 08:00 through 17:00. You can also specify particular dates, or days of the week, to be regarded as non-working dates via the -NonWorkingDates and -NonWorkingDaysOfWeek parameters. If the datetime of -Date falls outside of these parameters, you'll receive a boolean result. .PARAMETER Date The datetime to determine whether it is a working day or not. .PARAMETER StartHour The starting hour of a typical working day. The default starting hour is 08:00 (AM). 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. .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 Test-WorkingDay -Date (Get-Date '2022-04-11 09:00:00') The function will return true because the datetime is within the default parameters. 2022-04-11 is a Monday, and 09:00 is between 08:00 and 17:00. .EXAMPLE Test-WorkingDay -Date (Get-Date '2022-04-10 11:00:00') The function will return false because the datetime is outside the default parameters. 2022-04-10 is a Sunday, and therefore is not a working day, regardless of the hour/minute. .EXAMPLE Test-WorkingDay -Date (Get-Date '2022-04-11 22:00:00') -StartHour (Get-Date '08:00:00') -FinishHour Get-Date '23:00:00' The function will return true because the datetime is within the defined parameters. 2022-04-11 is a Monday, and 22:00 is between 08:00 and 23:00. Note: a datetime object is passed for both -StartHour and -FinishHour, however only the time is used for calculation. The date is ignored. .EXAMPLE Test-WorkingDay -Date (Get-Date '2022-04-11 09:00:00') -NonWorkingDaysOfWeek 'Saturday','Sunday','Monday' The function will return false because the datetime is outside the defined parameters. 2022-04-11 is a Monday, and is considered a non working day of the week. .EXAMPLE Test-WorkingDay -Date (Get-Date '2022-04-11 09:00:00') -NonWorkingDates (Get-Date '2022-04-11') The function will return false because the datetime is outside the defined parameters. 2022-04-11 is a Monday, and is considered a non working date. .INPUTS This function does not accept pipeline input. .OUTPUTS System.Boolean #> [CmdletBinding()] param ( [Parameter(Mandatory)] [DateTime]$Date, [Parameter()] [DateTime]$StartHour = '08:00:00', [Parameter()] [DateTime]$FinishHour = '17:00:00', [Parameter()] [ValidateSet('Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday')] [String[]]$NonWorkingDaysOfWeek = @('Saturday','Sunday'), [Parameter()] [DateTime[]]$NonWorkingDates ) $NonWorkingDaysOfWeek -notcontains $Date.DayOfWeek -And $Date.TimeOfDay -ge $StartHour.TimeOfDay -And $Date.TimeOfDay -lt $FinishHour.TimeOfDay -And $NonWorkingDates -notcontains $Date.Date } #endregion #region Types functions #endregion |