Estructura System.TimeSpan

  • Artículo

En este artículo se proporcionan comentarios adicionales a la documentación de referencia de esta API.

Un TimeSpan objeto representa un intervalo de tiempo (duración del tiempo o tiempo transcurrido) que se mide como un número positivo o negativo de días, horas, minutos, segundos y fracciones de un segundo. La TimeSpan estructura también se puede usar para representar la hora del día, pero solo si la hora no está relacionada con una fecha determinada. De lo contrario, se debe usar la DateTime estructura o DateTimeOffset en su lugar. (Para obtener más información sobre el uso de la TimeSpan estructura para reflejar la hora del día, vea Elegir entre DateTime, DateTimeOffset, TimeSpan y TimeZoneInfo).

Nota:

Un TimeSpan valor representa un intervalo de tiempo y se puede expresar como un número determinado de días, horas, minutos, segundos y milisegundos. Dado que representa un intervalo general sin referencia a un punto inicial o final determinado, no se puede expresar en términos de años y meses, ambos que tienen un número variable de días. Difiere de un DateTime valor, que representa una fecha y hora sin referencia a una zona horaria determinada, o un DateTimeOffset valor, que representa un momento específico de la hora.

La unidad de tiempo más grande que usa la TimeSpan estructura para medir la duración es un día. Los intervalos de tiempo se miden en días para la coherencia, ya que el número de días en unidades de tiempo mayores, como meses y años, varía.

El valor de un TimeSpan objeto es el número de tics que equivalen al intervalo de tiempo representado. Un tic es igual a 100 nanosegundos, o un diez millones de segundos. El valor de un TimeSpan objeto puede oscilar entre TimeSpan.MinValue y TimeSpan.MaxValue.

Creación de una instancia de un valor TimeSpan

Puede crear instancias de un TimeSpan valor de varias maneras:

  • Mediante una llamada a su constructor sin parámetros implícito. Esto crea un objeto cuyo valor es TimeSpan.Zero, como se muestra en el ejemplo siguiente.

    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".

  • Llamando a uno de sus constructores explícitos. En el ejemplo siguiente se inicializa un TimeSpan valor en un número especificado de horas, minutos y 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".

  • Llamando a un método o realizando una operación que devuelve un TimeSpan valor. Por ejemplo, puede crear instancias de un TimeSpan valor que represente el intervalo entre dos valores de fecha y hora, como se muestra en el ejemplo siguiente.

    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

    También puede inicializar un TimeSpan objeto en un valor de hora cero de esta manera, como se muestra en el ejemplo siguiente.

    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 Los operadores aritméticos y los métodos de las DateTimeestructuras , DateTimeOffsety TimeSpan devuelven valores.

  • Al analizar la representación de cadena de un TimeSpan valor. Puede usar los Parse métodos y TryParse para convertir cadenas que contienen intervalos de tiempo en TimeSpan valores. En el ejemplo siguiente se usa el Parse método para convertir una matriz de cadenas en 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'

    Además, puede definir el formato preciso de la cadena de entrada que se va a analizar y convertir en un TimeSpan valor llamando al ParseExact método o TryParseExact .

Realizar operaciones en valores timeSpan

Puede agregar y restar duraciones de tiempo mediante los Addition operadores y Subtraction o llamando a los Add métodos y Subtract . También puede comparar dos duraciones de tiempo llamando a los Comparemétodos , CompareToy Equals . La TimeSpan estructura también incluye los Duration métodos y Negate , que convierten intervalos de tiempo en valores positivos y negativos,

El intervalo de TimeSpan valores es MinValue para MaxValue.

Dar formato a un valor TimeSpan

Un TimeSpan valor se puede representar como [-]d. hh:mm:ss. FF, donde el signo menos opcional indica un intervalo de tiempo negativo, el d es el componente de día, hh son las horas en un reloj de 24 horas, mm es minutos, ss es segundos, y ff fracciones de segundo. Es decir, un intervalo de tiempo consta de un número positivo o negativo de días sin una hora del día, o un número de días con una hora del día o solo una hora del día.

A partir de .NET Framework 4, la TimeSpan estructura admite el formato que distingue la referencia cultural a través de las sobrecargas de su ToString método, que convierte un TimeSpan valor en su representación de cadena. El método predeterminado TimeSpan.ToString() devuelve un intervalo de tiempo mediante un formato invariable que es idéntico a su valor devuelto en versiones anteriores de .NET Framework. La TimeSpan.ToString(String) sobrecarga permite especificar una cadena de formato que define la representación de cadena del intervalo de tiempo. La TimeSpan.ToString(String, IFormatProvider) sobrecarga le permite especificar una cadena de formato y la referencia cultural cuyas convenciones de formato se usan para crear la representación de cadena del intervalo de tiempo. TimeSpan admite cadenas de formato estándar y personalizado. (Para obtener más información, consulte Cadenas de formato TimeSpan estándar y cadenas de formato TimeSpan personalizadas). Sin embargo, solo las cadenas de formato estándar distinguen la referencia cultural.

Restauración del formato timeSpan heredado

En algunos casos, se produce un error en el código que da formato TimeSpan a los valores de .NET Framework 3.5 y versiones anteriores en .NET Framework 4. Esto es más común en el código que llama a un <método de elemento TimeSpan_LegacyFormatMode> para dar formato a un TimeSpan valor con una cadena de formato. En el ejemplo siguiente se da formato correctamente a un TimeSpan valor en .NET Framework 3.5 y versiones anteriores, pero se produce una excepción en .NET Framework 4 y versiones posteriores. Tenga en cuenta que intenta dar formato a un TimeSpan valor mediante un especificador de formato no admitido, que se omite en .NET Framework 3.5 y versiones 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

Si no puede modificar el código, puede restaurar el formato heredado de los valores de TimeSpan una de las maneras siguientes:

  • Mediante la creación de un archivo de configuración que contiene el <elemento TimeSpan_LegacyFormatMode>. Establecer el atributo de enabled este elemento para true restaurar el formato heredado TimeSpan por aplicación.

  • Al establecer el modificador de compatibilidad "NetFx40_TimeSpanLegacyFormatMode" al crear un dominio de aplicación. Esto permite el formato heredado TimeSpan por dominio de aplicación. En el ejemplo siguiente se crea un dominio de aplicación que usa el formato heredado 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

    Cuando el código siguiente se ejecuta en el nuevo dominio de aplicación, se revierte al comportamiento de formato heredado 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.