NET 6 -  TimeOnly : Usando apenas Time 

Hoje veremos o novo recurso TimeOnly do .NET 6 na linguagem C#.

Continuando o artigo anterior vejamos agora novo recurso TimeOnly do NET 6.

Se você trabalhou com datas e horas na plataforma .NET, provavelmente já usou DateTime, DateTimeOffset, TimeSpan e TimeZoneInfo. No artigo anterior apresentei o novo recurso DateOnly que permite trabalhar com apenas datas sem ser obrigado a usar horas.

O recurso TimeOnly permite representar apenas a parte relativa a horas de uma data. Assim se DateOnly for a parte relativa apenas a data de um DateTime, TimeOnly vai atuar na parte referente a hora no DateTime.

Esses dois novos tipos são structs (tipos de valor) e podem ser usados quando seu código lida com conceitos de data ou hora de forma independente. Ambos os tipos podem ser encontrados no namespace System.

O uso desses novos tipos pode se alinhar bem com a forma como os bancos de dados permitem que dados semelhantes sejam representados. Especificamente, esses tipos se alinham bem com os tipos de dados de date e time do SQL Server.

Usando TimeOnly

Nos exemplos a seguir estou usando o VS 2022 e a versão do NET 6 RC1 em um projeto Console.

A struct TimeOnly  representa uma hora do dia, como seria lida em um relógio, no intervalo de 00:00:00 a 23: 59: 59,9999999. Ela tem várias sobrecargas de construtor. Os mais comuns nos permitem criar uma data aceitando :

  1. a hora e o minuto
  2. a hora, o minuto e o segundo
  3. a hora, o minuto, o segundo e o milisegundo
  public TimeOnly(int hour, int minute)
  public TimeOnly(int hour, int minute, int second)
  public TimeOnly(int hour, int minute, int second, int millisecond)

Assim para representar 10:35 da manhã podemos criar uma instância de TimeOnly assim:

Espera-se que a parte das horas seja fornecida usando o formato de relógio de 24 horas.  Internamente, o TimeOnly armazena um long que representa o número de tiques (intervalos de 100 nanossegundos) que decorreram desde a meia-noite na hora definida. Por exemplo, 1h é 1 hora no início do dia e, portanto, 36.000.000.000 de tiques desde a meia-noite (00: 00: 00.0000000).

Vamos definir outra hora usando o construtor para informar os segundos:

Como temos a hora inicial e hora final vamos realizar alguns cálculos usando TimeOnly. Para isso podemos simplesmente subtrair as duas horas e usar o método TotalHours que representa o número total de horas:

Resultado obtido na execução do projeto:

Assim podemos subtrair para descobrir quanto tempo se passou entre duas vezes.  A ordem usada é importante, pois este é um relógio circular.  Assim no exemplo a seguir

Como vemos, a ordem usada para subtrais as duas instâncias de TimeOnly afeta o resultado final.

Outra tarefa que podemos realizar é verificar se um determinado TimeOnly cai dentro de uma janela de tempo.

Por exemplo, digamos que queremos verificar se a hora atual está entre as horas de início e de término já definidas. Assim como com DateOnly, podemos converter de um DateTime existente em um TimeOnly usando o método estático FromDateTime.  A seguir temos o método IsBetween que retorna true se o valor estiver contido no intervalo de horas.

Resultado da execução:

O método IsBetween aceita intervalos normais, bem como intervalos que vão da meia-noite, como 22:00-02:00.

Podemos também definir uma hora a partir de uma string, usando um formato válido, e também adicionar horas, minutos e segundos a uma hora inicial e obter a hora final.

Neste exemplo usamos o método AddHours(). Temos também os métodos AddMinutes().

Outro recurso que TimeOnly oferece são os operadores para comparar horas usando um relógio circular. Assim podemos comparar duas instâncias de TimeOnly :

Se a comparação for verdadeira será retornado True caso contrário False.

Resultado:

a

Apresentamos assim um visão geral sobre o TimeOnly. Existem outros recursos ele oferece e que iremos abordar em outro artigo.

Pegue o projeto aqui :   TimeOnly1.zip (sem as referências. Precisa do NET 6)

"Bem-aventurado o homem que sofre a tentação; porque, quando for provado, receberá a coroa da vida, a qual o Senhor tem prometido aos que o amam."
Tiago 1:12

Referências:

José Carlos Macoratti