TimeSpan em C#

Em C#, a estrutura TimeSpan é usada para representar intervalos de tempo, como a diferença entre duas datas ou a duração de um evento. Ao contrário de DateTime, que armazena um ponto específico no tempo (como uma data e hora), o TimeSpan foca em representar durações — sejam elas dias, horas, minutos, segundos ou até frações de segundo. Neste post, aprenda tudo sobre TimeSpan em C#.

O que é TimeSpan?

TimeSpan é uma estrutura que representa um intervalo de tempo como uma quantidade de dias, horas, minutos, segundos e milissegundos. Ela é útil para calcular durações e realizar operações matemáticas com base em tempo.

Exemplo simples:

using System;

class Program
{
    static void Main()
    {
        TimeSpan duracao = new TimeSpan(2, 3, 15);  // 2 horas, 3 minutos e 15 segundos
        Console.WriteLine("Duração: " + duracao);  // Saída: Duração: 02:03:15
    }
}

Neste exemplo, criamos um TimeSpan que representa uma duração de 2 horas, 3 minutos e 15 segundos.

Criando instâncias de TimeSpan

Há várias maneiras de criar um TimeSpan, seja especificando dias, horas, minutos, segundos e milissegundos, ou calculando a diferença entre dois valores de DateTime.

1. Usando o construtor

O TimeSpan possui vários construtores que permitem especificar diferentes partes de um intervalo de tempo.

// Construtor com horas, minutos e segundos
TimeSpan tempo1 = new TimeSpan(2, 30, 0);  // 2 horas e 30 minutos

// Construtor com dias, horas, minutos, segundos e milissegundos
TimeSpan tempo2 = new TimeSpan(1, 5, 30, 45, 500);  // 1 dia, 5 horas, 30 minutos, 45 segundos, e 500 milissegundos

Console.WriteLine("Tempo 1: " + tempo1);
Console.WriteLine("Tempo 2: " + tempo2);

2. Diferença entre datas

Você também pode criar um TimeSpan ao calcular a diferença entre dois objetos DateTime.

DateTime inicio = DateTime.Now;
DateTime fim = inicio.AddHours(3).AddMinutes(15);

TimeSpan duracao = fim - inicio;
Console.WriteLine("Duração: " + duracao);  // Saída: Duração: 03:15:00

Aqui, criamos dois objetos DateTime (inicio e fim) e subtraímos um do outro para obter um TimeSpan que representa a diferença entre eles.

3. Métodos estáticos para criar TimeSpan

A classe TimeSpan oferece métodos estáticos para facilitar a criação de instâncias:

• TimeSpan.FromDays(double days)
• TimeSpan.FromHours(double hours)
• TimeSpan.FromMinutes(double minutes)
• TimeSpan.FromSeconds(double seconds)
• TimeSpan.FromMilliseconds(double milliseconds)

TimeSpan intervaloDias = TimeSpan.FromDays(2.5);  // 2 dias e 12 horas
TimeSpan intervaloHoras = TimeSpan.FromHours(5.5);  // 5 horas e 30 minutos

Console.WriteLine("Intervalo em dias: " + intervaloDias);
Console.WriteLine("Intervalo em horas: " + intervaloHoras);

Propriedades do TimeSpan

O TimeSpan oferece diversas propriedades úteis que permitem acessar suas diferentes partes.

• Days: Retorna o número de dias.
• Hours: Retorna o número de horas (não contando os dias).
• Minutes: Retorna o número de minutos (não contando horas ou dias).
• Seconds: Retorna o número de segundos (não contando minutos, horas ou dias).
• Milliseconds: Retorna o número de milissegundos.
• Ticks: Retorna o número total de “ticks” (unidade mínima de tempo no .NET, onde 1 tick = 100 nanosegundos).
• TotalDays, TotalHours, TotalMinutes, TotalSeconds, TotalMilliseconds: Retornam o total do intervalo representado pela instância em termos de dias, horas, minutos, etc., incluindo suas frações.

Exemplo:

TimeSpan intervalo = new TimeSpan(1, 15, 42, 30);  // 1 dia, 15 horas, 42 minutos e 30 segundos

Console.WriteLine("Dias: " + intervalo.Days);
Console.WriteLine("Horas: " + intervalo.Hours);
Console.WriteLine("Minutos: " + intervalo.Minutes);
Console.WriteLine("Total de horas: " + intervalo.TotalHours);  // Inclui fração de horas

Operações com TimeSpan

Você pode realizar operações matemáticas com TimeSpan, como adicionar, subtrair e comparar intervalos de tempo.

Soma de TimeSpan

TimeSpan t1 = new TimeSpan(1, 30, 0);  // 1 hora e 30 minutos
TimeSpan t2 = new TimeSpan(0, 45, 0);  // 45 minutos

TimeSpan soma = t1 + t2;
Console.WriteLine("Soma: " + soma);  // Saída: Soma: 02:15:00

Subtração de TimeSpan

TimeSpan t1 = new TimeSpan(3, 0, 0);  // 3 horas
TimeSpan t2 = new TimeSpan(1, 30, 0);  // 1 hora e 30 minutos

TimeSpan diferenca = t1 - t2;
Console.WriteLine("Diferença: " + diferenca);  // Saída: Diferença: 01:30:00

Comparação de TimeSpan

Você pode comparar dois TimeSpan usando operadores de comparação (<, >, <=, >=, ==, !=).

TimeSpan t1 = new TimeSpan(2, 0, 0);  // 2 horas
TimeSpan t2 = new TimeSpan(1, 30, 0);  // 1 hora e 30 minutos

if (t1 > t2)
{
    Console.WriteLine("t1 é maior que t2");
}

Formatação de TimeSpan

Você pode formatar a saída de um TimeSpan para personalizar a exibição dos intervalos de tempo.

TimeSpan t = new TimeSpan(1, 12, 45, 30);  // 1 dia, 12 horas, 45 minutos e 30 segundos
Console.WriteLine(t.ToString("c"));  // Saída: 1.12:45:30 (formato compacto)
Console.WriteLine(t.ToString(@"hh\:mm\:ss"));  // Saída: 12:45:30

Mais exemplos

Um objeto TimeSpan armazena internamente uma duração na forma de ticks (100 nanosegundos). Possui várias sobrecargas:

TimeSpan t = new TimeSpan();//mostra 00:00:00
TimeSpan t = new TimeSpan(0, 5, 45);//mostra 00:05:45 - zero hora, 5 minutos e 45 segundos
TimeSpan t = t.Ticks;//mostra a qtde. de ticks
TimeSpan t = new TimeSpan(900000000L)//mostra 00:01:30 - (900000000 ticks) - "L" representa tipo "Long"
TimeSpan t = new TimeSpan(2, 1, 21, 40)//mostra 2.01:21:40 - dois dia, uma hora, 21 minutos e 40 segundos
TimeSpan t = new TimeSpan(2, 1, 21, 40, 458)//mostra 2.01:21:40.4580000 - dois dia, uma hora, 21 minutos, 40 segundos e 458 milissegundos

Instanciando o TimeSpan utilizando métodos From:

TimeSpan t = TimeSpan.FromDays(1.5); //cria TimeSpan equivalente a 1.5 dia (1.12:00:00)
TimeSpan t = TimeSpan.FromHours(2.5); //cria TimeSpan equivalente a 2.5 horas (02:30:00)
TimeSpan t = TimeSpan.FromMinutes(2.5); //cria TimeSpan equivalente a 2.5 minutos (00:02:30)
TimeSpan t = TimeSpan.FromSeconds(2.5); //cria TimeSpan equivalente a 2.5 segundos (00:00:02.5000000)
TimeSpan t = TimeSpan.FromMilliseconds(1); //cria TimeSpan equivalente a 1 milisegundos (00:00:00.0010000)
TimeSpan t = TimeSpan.FromTicks(900000000L); //cria TimeSpan equivalente a um minuto e meio (00:01:30)

Propriedades:

TimeSpan t1 = TimeSpan.MaxValue;//pega valor máximo possível de se armazenar em um TimeSpan
TimeSpan t2 = TimeSpan.MinValue;//pega valor mínimo possível de se armazenar em um TimeSpan
TimeSpan t3 = TimeSpan.Zero;//duração zero (00:00:00)
    
TimeSpan t =  new TimeSpan(2, 3, 5, 7, 11);//instancia TimeSpan 2 dias, 3h, 5min, 7s, 11mils
t.Days; //mostra qtde. de dias
t.Hours; //mostra qtde. de horas
t.Minutes; //mostra qtde. de minutos
t.Seconds; //mostra qtde. de segundos
t.Milliseconds; //mostra qtde. milisegundos
t.Ticks; //mostra qtde. de Ticks
t.TotalDays; //mostra o total de dias
t.TotalHours; //mostra o total de horas
t.TotalMinutes; //mostra o total de minutos
t.TotalSeconds; //mostra o total de segundos
t.TotalMilliseconds; //mostra o total de milisegundos 

Operações:

TimeSpan t1 =  new TimeSpan(5, 10, 50);//instancia TimeSpan 5h, 10min, 50s
TimeSpan t2 =  new TimeSpan(7, 11, 12);//instancia TimeSpan 7h, 11min, 12s    
TimeSpan soma = t1.Add(t2);//soma t1 com t2
TimeSpan diferenca = t1.Subtract(t2);//subtrai t2 de t1
TimeSpan multiplicar = t1.Multiply(3.0);//multiplica t1 por 3
TimeSpan dividir = t1.Divide(4.0);//divide t1 por 4

O TimeSpan em C# é uma ferramenta essencial para trabalhar com intervalos de tempo de maneira eficiente e clara. Desde cálculos de duração até formatações personalizadas, ele oferece uma maneira robusta de lidar com tempo no seu código.

Usando suas propriedades e métodos, você pode realizar operações complexas e criar aplicações que envolvem a manipulação de tempo com facilidade.

Dúvidas ou sugestões sobre TimeSpan em C#? Deixem nos comentários! Para mais dicas, acesse o nosso canal no YouTube:
https://youtube.com/criandobits

Tags: timespan