Export (0) Print
Expand All
Expand Minimize

New-TimeSpan

Updated: December 3, 2014

Applies To: Windows PowerShell 4.0

New-TimeSpan

Creates a TimeSpan object.

Syntax

Parameter Set: Date
New-TimeSpan [[-Start] <DateTime> ] [[-End] <DateTime> ] [ <CommonParameters>]

Parameter Set: Time
New-TimeSpan [-Days <Int32> ] [-Hours <Int32> ] [-Minutes <Int32> ] [-Seconds <Int32> ] [ <CommonParameters>]




Detailed Description

The New-TimeSpan cmdlet creates a TimeSpan object that represents a time interval You can use a TimeSpan object to add or subtract time from DateTime objects.

Without parameters, a "New-Timespan" command returns a timespan object that represents a time interval of zero.

Parameters

-Days<Int32>

Indicates the days in the time span. The default is 0.


Aliases

none

Required?

false

Position?

named

Default Value

0

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-End<DateTime>

Indicates the end of a time span. The default is the current date and time.


Aliases

none

Required?

false

Position?

2

Default Value

Current date and time

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Hours<Int32>

Indicates the hours in the time span. The default is zero.


Aliases

none

Required?

false

Position?

named

Default Value

0

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Minutes<Int32>

Indicates the minutes in the time span. The default is 0.


Aliases

none

Required?

false

Position?

named

Default Value

0

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Seconds<Int32>

Indicates the length of the time span in seconds. The default is 0.


Aliases

none

Required?

false

Position?

named

Default Value

0

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Start<DateTime>

Indicates the start of a time span. Enter a string that represents the date and time, such as "3/15/09" or a DateTime object, such as one from a Get-Date command. The default is the current date and time.

You can use Start or its alias, LastWriteTime. The LastWriteTime alias lets you pipe objects that have a LastWriteTime property, such as files in the file system (System.Io.FileIO), to the Start parameter of New-TimeSpan.


Aliases

none

Required?

false

Position?

1

Default Value

Current date and time

Accept Pipeline Input?

true (ByValue, ByPropertyName)

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.DateTime

    You can pipe a DateTime object that represents that start time to New-TimeSpan.


Outputs

The output type is the type of the objects that the cmdlet emits.

  • System.TimeSpan

    New-TimeSpan returns an object that represents the time span.


Examples

-------------------------- EXAMPLE 1 --------------------------

This command creates a TimeSpan object with a duration of 1 hour and 25 minutes and stores it in a variable named $timespan. It displays a representation of the TimeSpan object.


PS C:\> $timespan = new-timespan -hour 1 -minute 25

-------------------------- EXAMPLE 2 --------------------------

This example creates a new TimeSpan object that represents the interval between the time that the command is run and January 1, 2010.

This command does not require the Start parameter, because the default value of the Start parameter is the current date and time.


PS C:\> new-timespan -end (get-date -year 2010 -month 1 -day 1)

-------------------------- EXAMPLE 3 --------------------------

These commands return the date that is 90 days after the current date.


PS C:\> $90days = new-timespan -days 90
PS C:\>(get-date) + $90days

-------------------------- EXAMPLE 4 --------------------------

This command tells you how long it has been since the about_remote.help.txt file was last updated. You can use this command format on any file, and on any other object that has a LastWriteTime property.

This command works because the Start parameter of New-TimeSpan has an alias of LastWriteTime. When you pipe an object that has a LastWriteTime property to New-TimeSpan, Windows PowerShell uses the value of the LastWriteTime property as the value of the Start parameter.


PS C:\> dir $pshome\en-us\about_remote.help.txt | new-timespan

Days              : 321
Hours             : 21
Minutes           : 59
Seconds           : 22
Milliseconds      : 312
Ticks             : 278135623127728
TotalDays         : 321.916230471907
TotalHours        : 7725.98953132578
TotalMinutes      : 463559.371879547
TotalSeconds      : 27813562.3127728
TotalMilliseconds : 27813562312.7728

# Equivalent to:

PS C:\>new-timespan -start (dir $pshome\en-us\about_remote.help.txt).lastwritetime

Related topics



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft