Compartilhar via

Struct System.TimeSpan

Este artigo fornece comentários complementares à documentação de referência para esta API.

Um TimeSpan objeto representa um intervalo de tempo (duração do tempo ou tempo decorrido) que é medido como um número positivo ou negativo de dias, horas, minutos, segundos e frações de segundo. A TimeSpan estrutura também pode ser usada para representar a hora do dia, mas somente se a hora não estiver relacionada a uma data específica. Caso contrário, a estrutura DateTime ou DateTimeOffset deverá ser usada. (Para obter mais informações sobre como usar a TimeSpan estrutura para refletir a hora do dia, consulte Escolhendo entre DateTime, DateTimeOffset, TimeSpan e TimeZoneInfo.)

Observação

Um TimeSpan valor representa um intervalo de tempo e pode ser expresso como um número específico de dias, horas, minutos, segundos e milissegundos. Como representa um intervalo geral sem referência a um determinado ponto inicial ou final, ele não pode ser expresso em termos de anos e meses, ambos com um número variável de dias. Ele difere de um DateTime valor, que representa uma data e hora sem referência a um fuso horário específico ou um DateTimeOffset valor, que representa um momento específico de tempo.

A maior unidade de tempo que a TimeSpan estrutura usa para medir a duração é um dia. Os intervalos de tempo são medidos em dias para consistência, pois o número de dias em unidades maiores de tempo, como meses e anos, varia.

O valor de um objeto TimeSpan é o número de tiques que são iguais ao intervalo de tempo representado. Um tique é igual a 100 nanossegundos, ou 10 milionésimos de segundo. O valor de um TimeSpan objeto pode variar de TimeSpan.MinValue até TimeSpan.MaxValue.

Instanciar um valor TimeSpan

Você pode instanciar um valor de TimeSpan de várias maneiras:

  • Chamando seu construtor implícito sem parâmetros. Isso cria um objeto cujo valor é TimeSpan.Zero, como mostra o exemplo a seguir.

    TimeSpan interval = new TimeSpan();
Console.WriteLine(interval.Equals(TimeSpan.Zero));    // Displays "True".

    let interval = TimeSpan()
printfn $"{interval.Equals TimeSpan.Zero}"    // Displays "True".

    Dim interval As New TimeSpan()
Console.WriteLine(interval.Equals(TimeSpan.Zero))     ' Displays "True".

  • Chamando um de seus construtores explícitos. O exemplo a seguir inicializa um TimeSpan valor para um número especificado de horas, minutos e segundos.

    TimeSpan interval = new TimeSpan(2, 14, 18);
Console.WriteLine(interval.ToString());              

// Displays "02:14:18".

    let interval = TimeSpan(2, 14, 18)
printfn $"{interval}"              

// Displays "02:14:18".

    Dim interval As New TimeSpan(2, 14, 18)
Console.WriteLine(interval.ToString())                ' Displays "02:14:18".

  • Chamando um método ou executando uma operação que retorna um TimeSpan valor. Por exemplo, você pode criar uma instância de um TimeSpan valor que representa o intervalo entre dois valores de data e hora, como mostra o exemplo a seguir.

    DateTime departure = new DateTime(2010, 6, 12, 18, 32, 0);
DateTime arrival = new DateTime(2010, 6, 13, 22, 47, 0);
TimeSpan travelTime = arrival - departure;  
Console.WriteLine($"{arrival} - {departure} = {travelTime}");      

// The example displays the following output:
//       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

    let departure = DateTime(2010, 6, 12, 18, 32, 0)
let arrival = DateTime(2010, 6, 13, 22, 47, 0)
let travelTime = arrival - departure  
printfn $"{arrival} - {departure} = {travelTime}"

// The example displays the following output:
//       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

    Dim departure As DateTime = #06/12/2010 6:32PM#
Dim arrival As DateTime = #06/13/2010 10:47PM#
Dim travelTime As TimeSpan = arrival - departure
Console.WriteLine("{0} - {1} = {2}", arrival, departure, travelTime)
' The example displays the following output:
'       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

    Você também pode inicializar um TimeSpan objeto para um valor de tempo zero dessa forma, como mostra o exemplo a seguir.

    Random rnd = new Random();

TimeSpan timeSpent = TimeSpan.Zero;

timeSpent += GetTimeBeforeLunch();
timeSpent += GetTimeAfterLunch();

Console.WriteLine($"Total time: {timeSpent}");

TimeSpan GetTimeBeforeLunch()
{
    return new TimeSpan(rnd.Next(3, 6), 0, 0);
}

TimeSpan GetTimeAfterLunch()
{
    return new TimeSpan(rnd.Next(3, 6), 0, 0);
}

// The example displays output like the following:
//        Total time: 08:00:00

    open System

let rnd = Random()

let getTimeBeforeLunch () =
    TimeSpan(rnd.Next(3, 6), 0, 0)

let getTimeAfterLunch() =
    TimeSpan(rnd.Next(3, 6), 0, 0)

do
    let timeSpent = TimeSpan.Zero

    let timeSpent = timeSpent + getTimeBeforeLunch ()
    let timeSpent = timeSpent + getTimeAfterLunch ()

    printfn $"Total time: {timeSpent}"


// The example displays output like the following:
//        Total time: 08:00:00

    Module Example
   Dim rnd As New Random()
   
   Public Sub Main()
      Dim timeSpent As TimeSpan = TimeSpan.Zero

      timeSpent += GetTimeBeforeLunch()
      timeSpent += GetTimeAfterLunch()

      Console.WriteLine("Total time: {0}", timeSpent)
   End Sub
   
   Private Function GetTimeBeforeLunch() As TimeSpan
      Return New TimeSpan(rnd.Next(3, 6), 0, 0)
   End Function
   
   Private Function GetTimeAfterLunch() As TimeSpan
      Return New TimeSpan(rnd.Next(3, 6), 0, 0)
   End Function
End Module
' The example displays output like the following:
'       Total time: 08:00:00

    TimeSpan valores são retornados por operadores aritméticos e métodos das estruturas DateTime, DateTimeOffset, e TimeSpan.

  • Analisando a representação de cadeia de caracteres de um valor TimeSpan. Você pode usar os métodos Parse e TryParse para converter cadeias de caracteres que contêm intervalos de tempo em valores TimeSpan. O exemplo a seguir usa o Parse método para converter uma matriz de cadeias de caracteres em TimeSpan valores.

    string[] values = { "12", "31.", "5.8:32:16", "12:12:15.95", ".12"};
foreach (string value in values)
{
   try {
      TimeSpan ts = TimeSpan.Parse(value);
      Console.WriteLine($"'{value}' --> {ts}");
   }
   catch (FormatException) {
      Console.WriteLine($"Unable to parse '{value}'");
   }
   catch (OverflowException) {
      Console.WriteLine($"'{value}' is outside the range of a TimeSpan.");
   }   
}

// The example displays the following output:
//       '12' --> 12.00:00:00
//       Unable to parse '31.'
//       '5.8:32:16' --> 5.08:32:16
//       '12:12:15.95' --> 12:12:15.9500000
//       Unable to parse '.12'

    let values = [| "12"; "31."; "5.8:32:16"; "12:12:15.95"; ".12" |]
for value in values do
    try
        let ts = TimeSpan.Parse value
        printfn $"'{value}' --> {ts}"
    with 
    | :? FormatException ->
        printfn $"Unable to parse '{value}'"
    | :? OverflowException ->
        printfn $"'{value}' is outside the range of a TimeSpan."

// The example displays the following output:
//       '12' --> 12.00:00:00
//       Unable to parse '31.'
//       '5.8:32:16' --> 5.08:32:16
//       '12:12:15.95' --> 12:12:15.9500000
//       Unable to parse '.12'

    Dim values() As String = {"12", "31.", "5.8:32:16", "12:12:15.95", ".12"}
For Each value As String In values
    Try
        Dim ts As TimeSpan = TimeSpan.Parse(value)
        Console.WriteLine("'{0}' --> {1}", value, ts)
    Catch e As FormatException
        Console.WriteLine("Unable to parse '{0}'", value)
    Catch e As OverflowException
        Console.WriteLine("'{0}' is outside the range of a TimeSpan.", value)
    End Try
Next
' The example displays the following output:
'       '12' --> 12.00:00:00
'       Unable to parse '31.'
'       '5.8:32:16' --> 5.08:32:16
'       '12:12:15.95' --> 12:12:15.9500000
'       Unable to parse '.12'

    Além disso, você pode definir o formato preciso da cadeia de caracteres de entrada a ser analisada e convertida em um valor TimeSpan chamando o método ParseExact ou o método TryParseExact.

Executar operações em valores TimeSpan

Você pode adicionar e subtrair durações de tempo usando os operadores Addition e Subtraction, ou chamando os métodos Add e Subtract. Você também pode comparar duas durações de tempo chamando os métodos Compare, CompareTo e Equals. A TimeSpan estrutura também inclui os métodos Duration e Negate, que convertem intervalos de tempo em valores positivos e negativos.

O intervalo de TimeSpan valores é MinValue para MaxValue.

Formatar um valor de intervalo de tempo

Um valor TimeSpan pode ser representado como [-]d.hh:mm:ss.ff, onde o sinal de subtração opcional indica um intervalo de tempo negativo, o componente d é dias, hh é horas conforme medido em um relógio de 24 horas, mm é minutos, ss é segundos e ff é frações de um segundo. Ou seja, um intervalo de tempo consiste em um número positivo ou negativo de dias sem uma hora do dia, ou um número de dias com uma hora do dia, ou apenas uma hora do dia.

A partir do .NET Framework 4, a estrutura TimeSpan dá suporte à formatação sensível à cultura através das sobrecargas de seu método ToString, que converte um valor TimeSpan em sua representação em formato de texto. O método padrão TimeSpan.ToString() retorna um intervalo de tempo usando um formato invariável idêntico ao seu valor retornado em versões anteriores do .NET Framework. A sobrecarga TimeSpan.ToString(String) permite especificar uma cadeia de caracteres de formato que define a representação de cadeia de caracteres do intervalo de tempo. A sobrecarga TimeSpan.ToString(String, IFormatProvider) permite especificar uma cadeia de caracteres de formato e a cultura cujas convenções de formatação são usadas para criar a representação de cadeia de caracteres do intervalo de tempo. TimeSpan dá suporte a cadeias de caracteres de formato padrão e personalizado. (Para obter mais informações, consulte Cadeias de caracteres de formato TimeSpan Padrão e cadeias de caracteres de formato TimeSpan Personalizadas.) No entanto, somente cadeias de caracteres de formato padrão são sensíveis à cultura.

Restaurar a formatação herdada do TimeSpan

Em alguns casos, o código que formata TimeSpan valores com êxito no .NET Framework 3.5 e versões anteriores falha no .NET Framework 4. Isso é mais comum no código que chama um método <TimeSpan_LegacyFormatMode> element para formatar um valor TimeSpan com uma cadeia de caracteres de formato. O exemplo a seguir formata com êxito um TimeSpan valor no .NET Framework 3.5 e versões anteriores, mas gera uma exceção no .NET Framework 4 e versões posteriores. Observe que ele tenta formatar um TimeSpan valor usando um especificador de formato sem suporte, que é ignorado no .NET Framework 3.5 e versões anteriores.

ShowFormattingCode();
// Output from .NET Framework 3.5 and earlier versions:
//       12:30:45
// Output from .NET Framework 4:
//       Invalid Format    

Console.WriteLine("---");

ShowParsingCode();
// Output:
//       000000006 --> 6.00:00:00

void ShowFormattingCode()
{
    TimeSpan interval = new TimeSpan(12, 30, 45);
    string output;
    try
    {
        output = String.Format("{0:r}", interval);
    }
    catch (FormatException)
    {
        output = "Invalid Format";
    }
    Console.WriteLine(output);
}

void ShowParsingCode()
{
    string value = "000000006";
    try
    {
        TimeSpan interval = TimeSpan.Parse(value);
        Console.WriteLine($"{value} --> {interval}");
    }
    catch (FormatException)
    {
        Console.WriteLine($"{value}: Bad Format");
    }
    catch (OverflowException)
    {
        Console.WriteLine($"{value}: Overflow");
    }
}

let showFormattingCode () =
    let interval = TimeSpan(12, 30, 45)
    try
        $"{interval:r}"
    with :? FormatException ->
        "Invalid Format"
    |> printfn "%s"

let showParsingCode () =
    let value = "000000006"
    try
        let interval = TimeSpan.Parse value
        printfn $"{value} --> {interval}"
    with
    | :? FormatException ->
        printfn $"{value}: Bad Format"
    | :? OverflowException ->
        printfn $"{value}: Overflow"

showFormattingCode ()
// Output from .NET Framework 3.5 and earlier versions:
//       12:30:45
// Output from .NET Framework 4:
//       Invalid Format    

printfn "---"

showParsingCode ()
// Output:
//       000000006 --> 6.00:00:00

Dim interval As New TimeSpan(12, 30, 45)
Dim output As String
Try
    output = String.Format("{0:r}", interval)
Catch e As FormatException
    output = "Invalid Format"
End Try
Console.WriteLine(output)
' Output from .NET Framework 3.5 and earlier versions:
'       12:30:45
' Output from .NET Framework 4:
'       Invalid Format

Se você não puder modificar o código, poderá restaurar a formatação herdada de valores TimeSpan em uma das seguintes maneiras:

  • Criando um arquivo de configuração que contém o <elemento TimeSpan_LegacyFormatMode>. Definir o atributo enabled deste elemento para true restaura a formatação herdada TimeSpan com base em cada aplicativo.

  • Definindo a opção de compatibilidade "NetFx40_TimeSpanLegacyFormatMode" ao criar um domínio de aplicativo. Isso permite a formatação herdada TimeSpan por domínio de aplicativo. O exemplo a seguir cria um domínio de aplicativo que usa a formatação herdada TimeSpan .

    using System;

public class Example2
{
    public static void Main()
    {
        AppDomainSetup appSetup = new AppDomainSetup();
        appSetup.SetCompatibilitySwitches(new string[] { "NetFx40_TimeSpanLegacyFormatMode" });
        AppDomain legacyDomain = AppDomain.CreateDomain("legacyDomain",
                                                        null, appSetup);
        legacyDomain.ExecuteAssembly("ShowTimeSpan.exe");
    }
}

    open System

let appSetup = AppDomainSetup()
appSetup.SetCompatibilitySwitches [| "NetFx40_TimeSpanLegacyFormatMode" |]
let legacyDomain = AppDomain.CreateDomain("legacyDomain", null, appSetup)
legacyDomain.ExecuteAssembly "ShowTimeSpan.exe" |> ignore

    Module Example3
    Public Sub Main()
        Dim appSetup As New AppDomainSetup()
        appSetup.SetCompatibilitySwitches({"NetFx40_TimeSpanLegacyFormatMode"})
        Dim legacyDomain As AppDomain = AppDomain.CreateDomain("legacyDomain",
                                                             Nothing, appSetup)
        legacyDomain.ExecuteAssembly("ShowTimeSpan.exe")
    End Sub
End Module

    Quando o código a seguir é executado no novo domínio do aplicativo, ele é revertido para o comportamento de formatação herdado TimeSpan .

    using System;

public class Example3
{
   public static void Main()
   {
      TimeSpan interval = DateTime.Now - DateTime.Now.Date;
      string msg = String.Format("Elapsed Time Today: {0:d} hours.",
                                 interval);
      Console.WriteLine(msg);
   }
}
// The example displays the following output:
//       Elapsed Time Today: 01:40:52.2524662 hours.

    open System

let interval = DateTime.Now - DateTime.Now.Date
printfn $"Elapsed Time Today: {interval:d} hours."
// The example displays the following output:
//       Elapsed Time Today: 01:40:52.2524662 hours.

    Module Example4
    Public Sub Main()
        Dim interval As TimeSpan = Date.Now - Date.Now.Date
        Dim msg As String = String.Format("Elapsed Time Today: {0:d} hours.",
                                         interval)
        Console.WriteLine(msg)
    End Sub
End Module
' The example displays output like the following:
'       Elapsed Time Today: 01:40:52.2524662 hours.
  • Last updated on