System.TimeSpan struct

Um objeto TimeSpan 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 estrutura TimeSpan também pode ser usada para representar a hora do dia, mas apenas se a hora não estiver relacionada a uma data específica. Caso contrário, a estrutura DateTime ou DateTimeOffset deve ser usada. (Para obter mais informações sobre como usar a estrutura TimeSpan para refletir a hora do dia, consulte Escolhendo entre DateTime, DateTimeOffset, TimeSpan e TimeZoneInfo.)

A maior unidade de tempo que a estrutura TimeSpan usa para medir a duração é um dia. Os intervalos de tempo são medidos em dias para consistência, porque 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 ticks que correspondem ao intervalo de tempo representado. Um tic é igual a 100 nanossegundos, ou um décimo milionésimo de segundo. O valor de um objeto TimeSpan pode variar de TimeSpan.MinValue a TimeSpan.MaxValue.

Instanciar um valor de 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 valor TimeSpan 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 valor TimeSpan. Por exemplo, você pode instanciar um valor TimeSpan 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 objeto TimeSpan para um valor de tempo zero dessa maneira, 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, DateTimeOffsete TimeSpan.

• Ao analisar a representação em formato 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 método Parse para converter uma matriz de cadeias de caracteres em valores TimeSpan.

  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 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, CompareToe Equals. A estrutura TimeSpan também inclui os métodos Duration e Negate, que convertem intervalos de tempo em valores positivos e negativos,

O intervalo de valores de TimeSpan é MinValue a MaxValue.

Formatar um valor TimeSpan

Um valor TimeSpan pode ser representado como [-]d.hh:mm:ss.ff, onde o sinal de menos opcional indica um intervalo de tempo negativo, o componente d é dias, hh é horas medidas em um relógio de 24 horas, mm é minutos, ss é segundos e ff é frações de 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 oferece suporte à formatação sensível à cultura por meio das sobrecargas de seu método ToString, que converte um valor TimeSpan em sua representação de cadeia de caracteres. O método TimeSpan.ToString() padrão retorna um intervalo de tempo usando um formato invariante que é idêntico ao seu valor de retorno em versões anteriores do .NET Framework. A sobrecarga TimeSpan.ToString(String) permite especificar uma string de formato que define a representação do intervalo de tempo em forma de cadeia de caracteres. 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 suporta cadeias de caracteres de formato padrão e personalizado. (Para obter mais informações, consulte Strings de formato TimeSpan padrão e Strings de formato TimeSpan personalizadas.) No entanto, apenas strings de formato padrão são sensíveis à cultura.

Restaurar formatação TimeSpan herdada

Em alguns casos, o código que formata com êxito valores de TimeSpan no .NET Framework 3.5 e versões anteriores falha no .NET Framework 4. Isso é mais comum em código que chama um elemento TimeSpan_LegacyFormatMode <método> para formatar um valor TimeSpan com uma cadeia de caracteres de formato. O exemplo a seguir formata com êxito um valor de TimeSpan no .NET Framework 3.5 e versões anteriores, mas lança uma exceção no .NET Framework 4 e versões posteriores. Observe que ele tenta formatar um valor TimeSpan 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 não for possível modificar o código, poderá restaurar a formatação antiga dos valores de TimeSpan de uma das seguintes maneiras:

• Ao criar um arquivo de configuração que contém o elemento <TimeSpan_LegacyFormatMode>. Definir o atributo enabled deste elemento como true restaura a formatação TimeSpan herdada por aplicativo.

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

  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 reverte para o comportamento de formatação de TimeSpan herdado.

  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.