Manipulación de Fechas y Horas en C# - Parte 3/5: La Estructura DateTimeOffset

Índice

1. Introducción
2. Palabras Clave
3. Estructura DateTimeOffset
4. Instanciación de Objetos DateTimeOffset
5. Métodos static
6. Campos static
7. Aritmética con Objetos DateTimeOffset
8. Conclusiones
9. Literatura & Enlaces

1. Introducción

Esta tercera parte de artículos C# -Manipulación de Fechas y Horas- describe la estructura DateTimeOffset. Esta estructura es útil para presentar un instante de tiempo respecto al sistema UTC. Este artículo se enfoca en la creación de una instancia, aritmética de instancias, operaciones y propiedades de interés.

2. Palabras Clave

• Estructura
• Fecha
• Hora
• Tiempo
• UTC

3. Estructura DateTimeOffset

DateTimeOffset es una estructura para la representación de un instante en el tiempo. Este instante de tiempo se expresa en dos partes: fecha y hora. Estas dos partes se expresan respecto al sistema UTC (Coordinated Universal Time) ("DateTimeOffset Structure", 2016). Se encuentra definida en el namespace System.

Además, esta estructura es inmutable, y tiene una resolución de 100 nanosegundos (ns) y cubre un rango de años desde 0001 hasta 9999 (Albahari, 2012).

4. Instanciación de Objetos DateTimeOffset

La estructura DateTimeOffset cuenta hasta con 6 constructores: 

Figura 1. Constructores de DateTimeOffset ("DateTimeOffset Structure", 2016).

Nótese cómo las dos primeras versiones de estos constructores inicializan una instancia especificando como argumento un objeto de la estructura DateTime (Manipulación de Fechas y Horas en C#/5: La Estructura DateTime), esto se debe a que la estructura DateTimeOffset incluye valores, por medio de propiedades, de tipo DateTime y Offset para representar la fecha y hora, y el valor de compensación (i.e., offset); en conjunto definen la diferencia entre la instancia actual de DateTimeOffset y el sistema UTC.

Ejemplo de uso: 

DateTimeOffset dto = new DateTimeOffset(DateTime.Now);

Esta sentencia crea un objeto DateTimeOffset usando el constructor que recibe como argumento un objeto de tipo DateTime; en este caso corresponde con el valor de la fecha y hora actual. Al inspeccionar el valor de la variable dto en este momento en LINQPad se obtiene: 

7/11/2016 8:57:49 PM -05:00

Alternativamente se puede crear un objeto convirtiendo implícitamente un objeto de tipo DateTime a DateTimeOffset: 

dto = DateTime.Now;

Nuevamente al revisar el valor de dto se obtiene: 

7/11/2016 9:01:23 PM -05:00

O también se puede crear un objeto específico de DateTime y asignar, a través de una conversión implícita, la instancia a un objeto de DateTimeOffset: 

DateTimeOffset dto = new DateTime(2016, 7, 1);

Y al inspeccionar este valor en LINQPad (a través de su depurador) se obtiene: 

7/1/2016 12:00:00 AM -05:00

De acuerdo con Albahari (2012) la conversión implícita enunciada resulta de utilidad debido a que la mayor parte de Microsoft .NET Framework soporta DateTime y no la estructura DateTimeOffset.

5. Método static

Existen varios métodos static definidos en DateTimeOffset para la conversión desde una representación en cadena de texto u otros tipos de datos hacia este tipo de estructura. Entre los métodos static se tiene: 

• Compare(DatetimeOffset, DateTimeOffset), 
• FromUnixTimeSeconds(Int64), 
• Parse(String), 
• ParseExact(String, String, IFormatProvider), 
• TryParse() (método sobrecargado).

En el caso de este último, una de sus versiones recibe como argumento una cadena de texto.

Ejemplo de uso: 

string strDto = "7/1/2016 12:00:00 AM -05:00";

var dto = DateTimeOffset.Parse(strDto);

Una vez se realice la conversión, el valor de la variable dto es: 

7/1/2016 12:00:00 AM -05:00

6. Campos static

DateTimeOffset posee dos campos static para obtener el valor mínimo y máximo que son posibles representar con esta estructura.

Figura 2. Campos static de DateTimeOffset ("DateTimeOffset Structure", 2016).

Al escribir estos campos como expresiones en LINQPad se obtiene: 

DateTimeOffset.MinValue.ToString().Dump();

DateTimeOffset.MaxValue.ToString().Dump();

1/1/0001 12:00:00 AM +00:00

12/31/9999 11:59:59 PM +00:00

Vale agregar que DateTimeOffset por ser de tipo struct, una vez definida una variable sin inicializar, los valores por defecto corresponde con DateTimeOffset.MinValue y un offset (i.e., compensación) igual a TimeSpan.Zero.

7. Aritmética con Objetos DateTimeOffset

Este ejemplo de uso describe cómo efectuar aritmética con objetos de la estructura DateTimeOffset: 

Archivo C# AritmeticaDateTimeOffset.cs [Enlace alternativo][Enlace alternativo]: 

El método de interés es Aritmetica (líneas 21-38): 

• Líneas 23-25: Define variables DateTime, DateTimeOffset y TimeSpan para la demostración de la aritmética entre estos tipos.
• Línea 28: Obtiene la fecha y hora actuales a través de la invocación de la propiedad Now de DateTime.
• Línea 29: Obtiene la fecha y hora actuales respecto a UTC con la propiedad UtcNow.
• Líneas 34-35: Realiza las operaciones análogas a las líneas 28-29 pero esta vez con la estructura DateTimeOffset.

Mientras que la aritmética con DateTime se lleva a cabo con la hora actual de Bogotá (Colombia) y la hora actual de UTC-0, con la estructura DateTimeOffset la diferencia se calcula con UTC-0.

Este es el resultado de una prueba de ejecución: 

Figura 3. Prueba ejecución AritmeticaDateTimeOffset.exe.

8. Conclusiones

Se ha estudiado cómo la estructura DateTimeOffset facilita la creación de representación de fecha y hora relativa al sistema UTC. Queda claro, además, que Microsoft .NET Framework tiene mayor soporte para DateTime que para DateTimeOffset. Al final de este artículo se demostró cómo realizar aritmética entre objetos de estas dos estructuras.

El próximo artículo de esta serie se centra en el estudio de fechas y zonas horarias.

9. Literatura & Enlaces

Albahari, J., Albahari, B. (2012). C# 5.0 in a Nutshell. United States: O'Reilly Media.
DateTimeOffset Structure (System) (2016, julio 11). Recuperado desde: https://msdn.microsoft.com/en-us/library/system.datetimeoffset(v=vs.110).aspx
Manipulación de Fechas y Horas en C#/5: La Estructura DateTime (2016, julio 11). Recuperado desde: https://ortizol.blogspot.com.co/2016/06/manipulacion-de-fechas-y-horas-en-csharp-parte-2-5-la-estructura-datetime.html

O