feat(function): Add function to measure the average runtime of a scriptblock.

Returns rich object with average runtime, number of iterations, minimum runtime, and maximum runtime.

Author: SamErde

…ippets/Average Time to Run a Command.ps1 General/Measure-AverageExecutionTime.ps1Snippets/Average Time to Run a Command.ps1 renamed to General/Measure-AverageExecutionTime.ps1 Snippets/Average Time to Run a Command.ps1 renamed to General/Measure-AverageExecutionTime.ps1

@@ -1,4 +1,4 @@
-function Get-AverageExecutionTime {
+function Measure-AverageExecutionTime {
     <#
     .SYNOPSIS
         Get the average execution time for running a script block multiple times.
@@ -13,11 +13,18 @@ function Get-AverageExecutionTime {
 
     .EXAMPLE
         [scriptblock]$Scriptblock = { $TypeAccelerators = [System.Management.Automation.PSObject].Assembly.GetType("System.Management.Automation.TypeAccelerators")::Get | Sort-Object }
-        Get-AverageExecutionTime $Scriptblock
+        Measure-AverageExecutionTime $Scriptblock
 
+    .EXAMPLE
+        [scriptblock]$Scriptblock = { Get-Process | Where-Object CPU -gt 10 }
+        Measure-AverageExecutionTime -Scriptblock $Scriptblock -Count 100 -Verbose
+
+    .LINK
+        Measure-Command
+        https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/measure-command
     #>
     [CmdletBinding()]
-    [OutputType([double])]
+    [OutputType([PSCustomObject])]
     param (
         [Parameter(
             Mandatory = $true,
@@ -29,23 +36,35 @@ function Get-AverageExecutionTime {
             Mandatory = $false,
             HelpMessage = 'Specify the number of times to run the scriptblock. (Default 50)'
         )]
+        [ValidateRange(1, [int]::MaxValue)]
         [int]$Count = 50
     )
 
     begin {
         [timespan]$TotalTime = New-TimeSpan
+        [double]$MinTime = [double]::MaxValue
+        [double]$MaxTime = 0
     }
 
     process {
         # Run the command $Count times
         for ($i = 0; $i -lt $Count; $i++) {
             # Measure the execution time
             $RunTime = Measure-Command -Expression { $Scriptblock.Invoke() }
+            $RunTimeMs = $RunTime.TotalMilliseconds
 
-            Write-Verbose "The total runtime for run $($i + 1) was $($RunTime.TotalMilliseconds) ms."
+            Write-Verbose "The total runtime for run $($i + 1) was $RunTimeMs ms."
 
             # Add the execution time to the total time
             $TotalTime = $TotalTime.Add($RunTime)
+
+            # Track minimum and maximum times
+            if ($RunTimeMs -lt $MinTime) {
+                $MinTime = $RunTimeMs
+            }
+            if ($RunTimeMs -gt $MaxTime) {
+                $MaxTime = $RunTimeMs
+            }
         }
 
         # Calculate the average execution time in milliseconds
@@ -54,6 +73,14 @@ function Get-AverageExecutionTime {
 
     end {
         Write-Verbose "The average execution time for your scriptblock was $AverageTime ms."
-        return $AverageTime
+
+        # Return detailed statistics
+        [PSCustomObject]@{
+            AverageMilliseconds = $AverageTime
+            TotalMilliseconds   = $TotalTime.TotalMilliseconds
+            MinimumMilliseconds = $MinTime
+            MaximumMilliseconds = $MaxTime
+            Iterations          = $Count
+        }
     }
 }