Skip to content

A simple method for creating TimeSpan objects to enable more user-friendly and simple usage of time-dependent Cmdlets #12305

@schuelermine

Description

@schuelermine

Summary of the new feature/enhancement

Motivation

Cmdlets such as Start-Sleep offer both -Seconds and -Milliseconds as parameters.
This style of time input is functional, but has a few issues:

  • Expanding the number of units requires updating the argument handling and the function body itself
  • Implementation in custom scripts or cmdlets requires boilerplate
  • Available options may not be consistent across cmdlets

Proposed solution

A new syntax expansion that adds support for TimeSpan literals, and cmdlets such as Start-Sleep accepting TimeSpan objects by default.
This entails adding new suffixes to numeric literals as described here

Preliminary list of suffixes:

  • min minutes
  • sec seconds
  • ms milliseconds
  • tick ticks
  • h hours
  • day days
  • year years (365 days, notably debatable due to calendar and culture issues)

Examples:

Items in each line are equivalent:

10sec = New-TimeSpan -Seconds 10 = [TimeSpan]100000000
15min = New-TimeSpan -Minutes 15 = [TimeSpan]9000000000
0xFFyear = New-TimeSpan -Days (0xFF * 365) = [TimeSpan]80416800000000000

Advantage over New-TimeSpan

This solution is significantly more concise than using New-TimeSpan (see above).
The semantics of this method are more clear, as cmdlets with the New verb are usually used in variable assignments, i.e. for persistent objects.

Considerations

Start-Sleep's parameter structure must be updated. Ideally, a non-TimeSpan input should be interpreted as seconds, while explicitly providing the suffixes remains possible.
These suffixes ideally do not interfere with the existing suffixes, as the types of the numbers would already be determined by the time unit. For example, tick will always be Int64 (or in case of future changes the type used for TimeSpan's Ticks property)

Postscriptum

This issue pairs well with issue #10712.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Breaking-Changebreaking change that may affect usersCommittee-ReviewedPS-Committee has reviewed this and made a decisionIssue-Enhancementthe issue is more of a feature request than a bugResolution-No ActivityIssue has had no activity for 6 months or moreWG-Languageparser, language semantics

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions