Sdílet prostřednictvím

System.TimeSpan – struktura

Tento článek obsahuje doplňující poznámky k referenční dokumentaci pro toto rozhraní API.

Objekt TimeSpan představuje časový interval (dobu trvání času nebo uplynulého času), který se měří jako kladný nebo záporný počet dní, hodin, minut, sekund a zlomků sekundy. Strukturu TimeSpan lze také použít k vyjádření času dne, ale pouze v případě, že čas nesouvisí s konkrétním datem. Jinak by se měla použít struktura DateTime nebo DateTimeOffset. (Další informace o použití struktury TimeSpan k zobrazení času dne naleznete v tématu Volba mezi DateTime, DateTimeOffset, TimeSpan a TimeZoneInfo.)

Poznámka:

Hodnota TimeSpan představuje časový interval a dá se vyjádřit jako určitý počet dní, hodin, minut, sekund a milisekund. Vzhledem k tomu, že představuje obecný interval bez odkazu na konkrétní počáteční nebo koncový bod, nelze jej vyjádřit v letech a měsících, z nichž oba mají proměnlivý počet dnů. Liší se od hodnoty DateTime, která představuje datum a čas bez odkazu na konkrétní časové pásmo, nebo DateTimeOffset hodnotu, která představuje konkrétní okamžik času.

Největší časová jednotka, kterou struktura TimeSpan používá k měření doby trvání, je den. Časové intervaly se měří ve dnech pro konzistenci, protože počet dní ve větších jednotkách času, jako jsou měsíce a roky, se liší.

Hodnota objektu TimeSpan je počet záškrtů, které se shodují s reprezentovaným časovým intervalem. Tik se rovná 100 nanosekundám nebo jedné desetimiliontině sekundy. Hodnota objektu TimeSpan může být v rozsahu od TimeSpan.MinValue po TimeSpan.MaxValue.

Vytvoření instance hodnoty TimeSpan

Hodnotu TimeSpan můžete instanciovat několika způsoby:

  • Voláním implicitního konstruktoru bez parametrů Tím se vytvoří objekt, jehož hodnota je TimeSpan.Zero, jak ukazuje následující příklad.

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

  • Voláním jednoho z jeho explicitních konstruktorů. Následující příklad inicializuje hodnotu TimeSpan na zadaný počet hodin, minut a sekund.

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

  • Voláním metody nebo provedením operace, která vrací TimeSpan hodnotu. Můžete například vytvořit instanci TimeSpan hodnoty, která představuje interval mezi dvěma hodnotami data a času, jak ukazuje následující příklad.

    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($"{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

    Tímto způsobem můžete inicializovat objekt TimeSpan na nulovou časovou hodnotu, jak ukazuje následující příklad.

    Random rnd = new Random();

TimeSpan timeSpent = TimeSpan.Zero;

timeSpent += GetTimeBeforeLunch();
timeSpent += GetTimeAfterLunch();

Console.WriteLine($"Total time: {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

    Aritmetické operátory a metody struktur TimeSpan, DateTimea DateTimeOffset vrací TimeSpan hodnoty.

  • Analýzou řetězcové reprezentace hodnoty TimeSpan. Pomocí metod Parse a TryParse můžete převést řetězce obsahující časové intervaly na TimeSpan hodnoty. Následující příklad používá metodu Parse k převodu pole řetězců na TimeSpan hodnot.

    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($"'{value}' --> {ts}");
   }
   catch (FormatException) {
      Console.WriteLine($"Unable to parse '{value}'");
   }
   catch (OverflowException) {
      Console.WriteLine($"'{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'

    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'

    Kromě toho můžete definovat přesný formát vstupního řetězce, který se má analyzovat a převést na hodnotu TimeSpan voláním ParseExact nebo TryParseExact metody.

Provádění operací s hodnotami TimeSpan

Dobu trvání můžete přičíst a odečíst buď pomocí operátorů Addition a Subtraction, nebo voláním Add a Subtract metod. Můžete také porovnat dvě časové doby voláním metody Compare, CompareToa Equals. Struktura TimeSpan zahrnuje také Duration a Negate metody, které převádějí časové intervaly na kladné a záporné hodnoty,

Rozsah hodnot TimeSpan je od MinValue do MaxValue.

Formátujte hodnotu TimeSpan

Hodnotu TimeSpan lze reprezentovat jako [-]d.hh:mm:ss.ff, kde volitelné znaménko minus označuje záporný časový interval, d komponenta jsou dny, hh jsou hodiny měřené ve 24hodinovém formátu, mm jsou minuty, ss jsou sekundy a ff jsou zlomky sekundy. To znamená, že časový interval se skládá z kladného nebo záporného počtu dnů bez času dne, nebo počtu dnů s časem dne nebo pouze času dne.

Počínaje rozhraním .NET Framework 4 podporuje struktura TimeSpan kultuře citlivé formátování prostřednictvím přetížení metody ToString, která převádí hodnotu TimeSpan na její řetězcovou reprezentaci. Výchozí TimeSpan.ToString() metoda vrátí časový interval pomocí invariantního formátu, který je identický s jeho návratovou hodnotou v předchozích verzích rozhraní .NET Framework. Přetížení TimeSpan.ToString(String) umožňuje zadat formátovací řetězec, který definuje řetězcovou reprezentaci časového intervalu. Přetížení TimeSpan.ToString(String, IFormatProvider) vám umožňuje zadat formátovací řetězec a kulturu, jejíž konvence formátování se používají k vytvoření řetězcové reprezentace časového intervalu. TimeSpan podporuje standardní i vlastní formátovací řetězce. (Další informace najdete v tématu standardní řetězce formátu TimeSpan a vlastní řetězce formátu TimeSpan.) Pouze standardní řetězce formátu jsou však citlivé na jazykovou verzi.

Obnovení staršího formátování TimeSpan

V některých případech kód, který úspěšně formátuje TimeSpan hodnoty v rozhraní .NET Framework 3.5 a starších verzích, selže v rozhraní .NET Framework 4. To je nejběžnější v kódu, který volá <TimeSpan_LegacyFormatMode> prvek metodu k formátování hodnoty TimeSpan pomocí formátovacího řetězce. Následující příklad úspěšně naformátuje hodnotu TimeSpan v rozhraní .NET Framework 3.5 a starších verzích, ale vyvolá výjimku v rozhraní .NET Framework 4 a novějších verzích. Všimněte si, že se pokusí formátovat hodnotu TimeSpan pomocí nepodporovaného specifikátoru formátu, který je ignorován v rozhraní .NET Framework 3.5 a starších verzích.

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($"{value} --> {interval}");
    }
    catch (FormatException)
    {
        Console.WriteLine($"{value}: Bad Format");
    }
    catch (OverflowException)
    {
        Console.WriteLine($"{value}: Overflow");
    }
}

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

Pokud kód nemůžete upravit, můžete obnovit starší formátování TimeSpan hodnot jedním z následujících způsobů:

  • Vytvořením konfiguračního souboru, který obsahuje prvek <TimeSpan_LegacyFormatMode>. Nastavením atributu enabled tohoto prvku na true se obnoví starší formátování TimeSpan pro jednotlivé aplikace.

  • Nastavením přepínače kompatibility "NetFx40_TimeSpanLegacyFormatMode" při vytváření aplikační domény. Toto umožňuje starší formátování TimeSpan na základě jednotlivých domén aplikací. Následující příklad vytvoří doménu aplikace, která používá starší TimeSpan formátování.

    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

    Kód se v nové doméně aplikace spustí a vrátí se k původnímu formátovacímu chování 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.
  • Last updated on