System.TimeSpan struct

Artigo
01/11/2024

Este artigo fornece observações complementares à documentação de referência para essa 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 apenas se a hora não estiver relacionada a uma data específica. Caso contrário, a DateTime estrutura ou DateTimeOffset deve ser usada em vez disso. (Para obter mais informações sobre como usar a estrutura para refletir a TimeSpan 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 determinado número de dias, horas, minutos, segundos e milissegundos. Por representar um intervalo geral sem referência a um ponto inicial ou final específico, 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 valor, que representa uma data e hora sem referência a um fuso horário específico, ou um valor, que representa um DateTime DateTimeOffset momento específico do tempo.

A maior unidade de tempo que a estrutura usa para medir a TimeSpan 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 TimeSpan objeto é o número de ticks que são iguais ao intervalo de tempo representado. Um carrapato é igual a 100 nanossegundos, ou um décimo milionésimo de segundo. O valor de um TimeSpan objeto pode variar de TimeSpan.MinValue a TimeSpan.MaxValue.

Instanciar um valor TimeSpan

Você pode instanciar um TimeSpan valor 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 para um TimeSpan 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 instanciar 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("{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

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 para um TimeSpan 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: {0}", 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 do DateTime, DateTimeOffsete TimeSpan estruturas.

Analisando a representação de cadeia de caracteres de um TimeSpan valor. Você pode usar os Parse métodos e TryParse para converter cadeias de caracteres que contêm intervalos de tempo em TimeSpan valores. 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("'{0}' --> {1}", value, ts);
   }
   catch (FormatException) {
      Console.WriteLine("Unable to parse '{0}'", value);
   }
   catch (OverflowException) {
      Console.WriteLine("'{0}' is outside the range of a TimeSpan.", value);
   }   
}

// 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 TimeSpan valor chamando o ParseExact método or TryParseExact .

Executar operações em valores de TimeSpan

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

O intervalo de TimeSpan valores é MinValue para MaxValue.

Formatar um valor TimeSpan

Um TimeSpan valor 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 oferece suporte à formatação sensível à TimeSpan cultura por meio das sobrecargas de seu ToString método, que converte um TimeSpan valor em sua representação de cadeia de caracteres. O método padrão TimeSpan.ToString() 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 TimeSpan.ToString(String) sobrecarga permite especificar uma cadeia de caracteres de formato que define a representação de cadeia de caracteres do intervalo de tempo. A TimeSpan.ToString(String, IFormatProvider) sobrecarga 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 Cadeias de caracteres de formato TimeSpan padrão e cadeias de caracteres de formato TimeSpan personalizadas.) No entanto, apenas cadeias de caracteres de formato padrão são sensíveis à cultura.

Restaurar formatação de TimeSpan herdada

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 de elemento TimeSpan_LegacyFormatMode para formatar um<TimeSpan valor 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 lança uma exceção no .NET Framework 4 e versões posteriores. Observe que ele tenta formatar um valor usando um TimeSpan 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("{0} --> {1}", value, interval);
    }
    catch (FormatException)
    {
        Console.WriteLine("{0}: Bad Format", value);
    }
    catch (OverflowException)
    {
        Console.WriteLine("{0}: Overflow", value);
    }
}

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 pode modificar o código, você pode restaurar a formatação herdada de valores de TimeSpan uma das seguintes maneiras:

Criando um arquivo de configuração que contém o <elemento TimeSpan_LegacyFormatMode>. A definição do enabled atributo desse elemento restaura a true formatação herdada TimeSpan por 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 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 reverte para o comportamento de formatação herdada 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.

Compartilhar via

System.TimeSpan struct

Instanciar um valor TimeSpan

Executar operações em valores de TimeSpan

Formatar um valor TimeSpan

Restaurar formatação de TimeSpan herdada

Recursos adicionais