Compartir a través de


Estructura System.TimeSpan

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.