Format-TimeSpan¶
SYNOPSIS¶
Formats a TimeSpan object into a human-readable string.
SYNTAX¶
Format-TimeSpan [-TimeSpan] <TimeSpan> [[-Precision] <Int32>] [[-BaseUnit] <String>] [[-Format] <String>]
[-IncludeZeroValues] [-ProgressAction <ActionPreference>] [<CommonParameters>]
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¶
-TimeSpan¶
The TimeSpan object to format.
Type: TimeSpan
Parameter Sets: (All)
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
-Precision¶
Specifies the number of precision levels to include in the output. If not specified, automatically shows all units with non-zero values.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: 2
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-BaseUnit¶
Specifies the base unit to use for formatting the TimeSpan.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Format¶
Specifies the format for displaying time units.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 4
Default value: Symbol
Accept pipeline input: False
Accept wildcard characters: False
-IncludeZeroValues¶
Includes units with zero values in the output. By default, only non-zero units are shown.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction¶
{{ Fill ProgressAction Description }}
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters¶
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS¶
OUTPUTS¶
System.String¶
NOTES¶
The formatted string representation of the TimeSpan.