Add Get-TimeSpan function for calculating time differences from target DateTime

[Copilot]

This PR implements a new Get-TimeSpan function that calculates the time difference between a target DateTime and the current time, addressing the need for countdown timers and age calculations.

Features

The function provides a clean interface for time difference calculations:

# Countdown to future event
$futureTime = [DateTime]::Now.AddMinutes(30)
Get-TimeSpan -Target $futureTime
# Returns: 00:30:00

# Past events return Zero by default
$pastTime = [DateTime]::Now.AddMinutes(-30)
Get-TimeSpan -Target $pastTime
# Returns: 00:00:00

# Allow negative values for past events
Get-TimeSpan -Target $pastTime -AllowNegative
# Returns: -00:30:00

# Calculate elapsed time (age)
Get-TimeSpan -Target $pastTime -AsAge
# Returns: 00:30:00

Implementation Details

• Core calculation: Target - Now for countdown, Now - Target for age
• Negative handling: Returns [TimeSpan]::Zero by default for past dates, matching the pattern described in the issue
• Pipeline support: Accepts DateTime objects from pipeline
• Parameter validation: Full parameter documentation and type safety

Parameters

• Target [DateTime] - The target datetime to calculate difference from (required)
• AllowNegative [switch] - Returns actual negative TimeSpan instead of Zero for past dates
• AsAge [switch] - Calculates elapsed time (Now - Target) instead of remaining time

Integration

Works seamlessly with existing module functions:

$countdown = Get-TimeSpan -Target $eventTime
Format-TimeSpan $countdown -Precision 2 -FullNames
# Returns: "2 hours 30 minutes"

Testing

Added comprehensive test coverage with 7 test cases covering:

• Future datetime calculations
• Past datetime handling (default and AllowNegative)
• Age calculations with AsAge parameter
• Pipeline support
• Edge cases and integration scenarios

All new tests pass, confirming the implementation works correctly for all specified requirements.

Fixes #5.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Marius Storhaug (MariusStorhaug)]

Lets change this abit. I want it to:

• Default to allow negative. Have a switch to stop at null if it is negative.
• Instead of hardcoding that Start is [DateTime]::Now, lets add that as a parameter. Start = [DateTime]::Now, End = [DateTime]::Now, if neither Start nor End is provided, return a [TimeSpan]::Zero.

[Copilot]

Lets change this abit. I want it to:

• Default to allow negative. Have a switch to stop at null if it is negative.
• Instead of hardcoding that Start is [DateTime]::Now, lets add that as a parameter...

I've refactored the Get-TimeSpan function according to your feedback:

1. Default behavior changed: Now allows negative values by default, with a new -StopAtZero switch to return Zero for negative results
2. Start/End parameters: Added Start and End parameters, both defaulting to [DateTime]::Now
3. Zero default case: Returns [TimeSpan]::Zero when both Start and End use their default values (neither parameter provided)
4. Calculation: Uses End - Start for the time difference
5. Pipeline support: Updated to bind DateTime values to the End parameter

The function now supports flexible usage patterns:

• Get-TimeSpan → Returns Zero (both defaults)
• Get-TimeSpan -End $future → Positive countdown to future time
• Get-TimeSpan -End $past → Negative time (past event)
• Get-TimeSpan -End $past -StopAtZero → Zero for past events
• Get-TimeSpan -Start $start -End $end → Duration between times

All tests updated and passing. Commit: 55f7dfc