System.TimeSpan, struktura

Artykuł
01/08/2024

Ten artykuł zawiera dodatkowe uwagi dotyczące dokumentacji referencyjnej dla tego interfejsu API.

TimeSpan Obiekt reprezentuje przedział czasu (czas trwania lub czas, który upłynął), mierzony jako dodatnia lub ujemna liczba dni, godzin, minut, sekund i ułamków sekundy. Struktura TimeSpan może być również używana do reprezentowania godziny dnia, ale tylko wtedy, gdy godzina nie jest powiązana z określoną datą. DateTime W przeciwnym razie należy użyć struktury lubDateTimeOffset. (Aby uzyskać więcej informacji na temat używania TimeSpan struktury do odzwierciedlenia godziny dnia, zobacz Wybieranie między datetime, DateTimeOffset, TimeSpan i TimeZoneInfo).

Uwaga

TimeSpan Wartość reprezentuje przedział czasu i może być wyrażona jako określona liczba dni, godzin, minut, sekund i milisekund. Ponieważ reprezentuje ogólny interwał bez odniesienia do określonego punktu początkowego lub końcowego, nie można go wyrazić w kategoriach lat i miesięcy, z których obie mają zmienną liczbę dni. Różni się DateTime od wartości, która reprezentuje datę i godzinę bez odwołania do określonej strefy czasowej lub DateTimeOffset wartość, która reprezentuje określony moment czasu.

Największa jednostka czasu używana przez TimeSpan strukturę do mierzenia czasu to dzień. Przedziały czasu są mierzone w dniach dla spójności, ponieważ liczba dni w większych jednostkach czasu, takich jak miesiące i lata, różni się.

Wartość TimeSpan obiektu to liczba znaczników, które są równe reprezentowanym interwale czasu. Kleszcz jest równy 100 nanosekundom lub dziesiątej części sekundy. Wartość TimeSpan obiektu może wahać się od TimeSpan.MinValue do TimeSpan.MaxValue.

Tworzenie wystąpienia wartości TimeSpan

Możesz utworzyć wystąpienie TimeSpan wartości na wiele sposobów:

Wywołując niejawny konstruktor bez parametrów. Spowoduje to utworzenie obiektu, którego wartość to TimeSpan.Zero, jak pokazano w poniższym przykładzie.

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

Wywołując jeden z jego jawnych konstruktorów. Poniższy przykład inicjuje TimeSpan wartość do określonej liczby godzin, minut i 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".

Wywołując metodę lub wykonując operację zwracającą TimeSpan wartość. Można na przykład utworzyć wystąpienie TimeSpan wartości reprezentującej interwał między dwiema wartościami daty i godziny, jak pokazano w poniższym przykładzie.

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

W ten sposób można również zainicjować TimeSpan obiekt na wartość zero czasu, jak pokazano w poniższym przykładzie.

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 wartości są zwracane przez operatory arytmetyczne i metody DateTimestruktur , DateTimeOffseti TimeSpan .

Analizowanie ciągu reprezentacji TimeSpan wartości. Metody i TryParse umożliwiają Parse konwertowanie ciągów zawierających interwały czasowe na TimeSpan wartości. W poniższym przykładzie użyto Parse metody , aby przekonwertować tablicę ciągów na TimeSpan wartości.

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'

Ponadto można zdefiniować dokładny format ciągu wejściowego, który ma zostać przeanalizowany i przekonwertowany na wartość, wywołując ParseExact metodę TimeSpan orTryParseExact.

Wykonywanie operacji na wartościach timeSpan

Można dodawać i odejmować czasy trwania przy użyciu Addition operatorów i lub wywołując Add metody i Subtraction Subtract. Możesz również porównać dwa czasy trwania, wywołując Comparemetody , CompareToi Equals . Struktura TimeSpan obejmuje Duration również metody i Negate , które konwertują interwały czasu na wartości dodatnie i ujemne,

Zakres TimeSpan wartości to MinValue MaxValue.

Formatowanie wartości timeSpan

TimeSpan Wartość może być reprezentowana jako [-]d.hh:mm:ss.ff, gdzie opcjonalny znak minus wskazuje ujemny interwał czasu, składnik d jest dni, hh jest godzinami mierzonymi na zegarze 24-godzinnym, mm jest minut, ss jest sekund, a ff jest ułamkami sekundy. Oznacza to, że interwał czasu składa się z dodatniej lub ujemnej liczby dni bez godziny dnia lub liczby dni z godziną dnia lub tylko godziną dnia.

Począwszy od programu .NET Framework 4, TimeSpan struktura obsługuje formatowanie wrażliwe na kulturę przez przeciążenia metody ToString , która konwertuje wartość na reprezentację TimeSpan ciągu. Metoda domyślna TimeSpan.ToString() zwraca interwał czasu przy użyciu niezmiennego formatu, który jest identyczny z jego wartością zwracaną w poprzednich wersjach programu .NET Framework. Przeciążenie TimeSpan.ToString(String) umożliwia określenie ciągu formatu definiującego reprezentację ciągu interwału czasu. Przeciążenie TimeSpan.ToString(String, IFormatProvider) umożliwia określenie ciągu formatu i kultury, której konwencje formatowania są używane do tworzenia reprezentacji ciągu interwału czasu. TimeSpan obsługuje zarówno ciągi formatu standardowego, jak i niestandardowego. (Aby uzyskać więcej informacji, zobacz Standardowe ciągi formatu TimeSpan i niestandardowe ciągi formatu TimeSpan. Jednak tylko standardowe ciągi formatu są wrażliwe na kulturę.

Przywracanie starszego formatowania TimeSpan

W niektórych przypadkach kod, który pomyślnie formatuje TimeSpan wartości w programie .NET Framework 3.5 i starszych wersjach, kończy się niepowodzeniem w programie .NET Framework 4. Jest to najczęściej spotykane w kodzie, który wywołuje metodę <elementu TimeSpan_LegacyFormatMode> w celu formatowania TimeSpan wartości za pomocą ciągu formatu. Poniższy przykład pomyślnie formatuje TimeSpan wartość w programie .NET Framework 3.5 i starszych wersjach, ale zgłasza wyjątek w programie .NET Framework 4 i nowszych wersjach. Należy pamiętać, że próbuje sformatować TimeSpan wartość przy użyciu nieobsługiwanego specyfikatora formatu, który jest ignorowany w programie .NET Framework 3.5 i starszych wersjach.

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

Jeśli nie możesz zmodyfikować kodu, możesz przywrócić starsze formatowanie TimeSpan wartości w jeden z następujących sposobów:

Tworząc plik konfiguracji zawierający <element TimeSpan_LegacyFormatMode>. Ustawienie atrybutu tego elementu w celu true przywrócenia enabled starszego TimeSpan formatowania dla poszczególnych aplikacji.

Ustawiając przełącznik zgodności "NetFx40_TimeSpanLegacyFormatMode" podczas tworzenia domeny aplikacji. Umożliwia to starsze TimeSpan formatowanie dla poszczególnych domen aplikacji. Poniższy przykład tworzy domenę aplikacji, która używa starszego TimeSpan formatowania.

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

Gdy poniższy kod zostanie wykonany w nowej domenie aplikacji, zostanie przywrócony do starszego TimeSpan zachowania formatowania.

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.

System.TimeSpan, struktura

Tworzenie wystąpienia wartości TimeSpan

Wykonywanie operacji na wartościach timeSpan

Formatowanie wartości timeSpan

Przywracanie starszego formatowania TimeSpan

Opinia

Dodatkowe zasoby