Skip to content

Format-TimeSpan

SYNOPSIS

Formats a TimeSpan object into a human-readable string.

SYNTAX

__AllParameterSets

Format-TimeSpan [-TimeSpan] <timespan> [[-Precision] <int>] [[-BaseUnit] <string>]
 [[-Format] <string>] [-IncludeZeroValues] [<CommonParameters>]

ALIASES

This cmdlet has the following aliases, {{Insert list of aliases}}

DESCRIPTION

This function converts a TimeSpan object into a formatted string based on a chosen unit or precision. By default, it shows all units that have non-zero values. You can specify a base unit, the number of precision levels, and the format for displaying units. If the TimeSpan is negative, it is prefixed with a minus sign.

EXAMPLES

EXAMPLE 1

New-TimeSpan -Minutes 90 | Format-TimeSpan

Output:

1h 30m

Formats the given TimeSpan showing all non-zero units with symbols (default behavior).

EXAMPLE 2

New-TimeSpan -Minutes 90 | Format-TimeSpan -Format Abbreviation

Output:

1hr 30min

Formats the given TimeSpan showing all non-zero units using abbreviations instead of symbols.

EXAMPLE 3

New-TimeSpan -Hours 2 -Minutes 30 -Seconds 10 | Format-TimeSpan -Format FullName

Output:

2 hours 30 minutes 10 seconds

Shows all non-zero units in full name format.

EXAMPLE 4

New-TimeSpan -Hours 2 -Minutes 30 -Seconds 10 | Format-TimeSpan -Format FullName -IncludeZeroValues

Output:

2 hours 30 minutes 10 seconds 0 milliseconds 0 microseconds

Shows all units including those with zero values when the IncludeZeroValues switch is used.

EXAMPLE 5

[TimeSpan]::FromSeconds(3661) | Format-TimeSpan -Precision 2 -Format FullName

Output:

1 hour 1 minute

Returns the TimeSpan formatted into exactly 2 components using full unit names.

EXAMPLE 6

New-TimeSpan -Minutes 90 | Format-TimeSpan -Precision 1

Output:

2h

When precision is explicitly set to 1, uses the traditional behavior of showing only the most significant unit (rounded).

PARAMETERS

-BaseUnit

Specifies the base unit to use for formatting the TimeSpan.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 2
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Format

Specifies the format for displaying time units.

Type: System.String
DefaultValue: Symbol
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 3
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-IncludeZeroValues

Includes units with zero values in the output. By default, only non-zero units are shown.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Precision

Specifies the number of precision levels to include in the output. If not specified, automatically shows all units with non-zero values.

Type: System.Int32
DefaultValue: 0
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-TimeSpan

The TimeSpan object to format.

Type: System.TimeSpan
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: true
  ValueFromPipeline: true
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.TimeSpan

{{ Fill in the Description }}

OUTPUTS

System.String

{{ Fill in the Description }}

NOTES

The formatted string representation of the TimeSpan.