Struktur System.TimeSpan

Artikel
01/08/2024

Artikel ini menyediakan keterangan tambahan untuk dokumentasi referensi untuk API ini.

Objek TimeSpan mewakili interval waktu (durasi waktu atau waktu yang berlalu) yang diukur sebagai jumlah hari, jam, menit, detik, dan pecahan positif atau negatif detik. Struktur TimeSpan juga dapat digunakan untuk mewakili waktu hari, tetapi hanya jika waktu tidak terkait dengan tanggal tertentu. Jika tidak, DateTime struktur atau DateTimeOffset harus digunakan sebagai gantinya. (Untuk informasi selengkapnya tentang menggunakan TimeSpan struktur untuk mencerminkan waktu hari, lihat Memilih Antara DateTime, DateTimeOffset, TimeSpan, dan TimeZoneInfo.)

Catatan

Nilai TimeSpan mewakili interval waktu dan dapat dinyatakan sebagai jumlah hari, jam, menit, detik, dan milidetik tertentu. Karena mewakili interval umum tanpa mereferensikan ke titik awal atau akhir tertentu, itu tidak dapat diekspresikan dalam hal tahun dan bulan, yang keduanya memiliki jumlah hari variabel. Ini berbeda dari DateTime nilai, yang mewakili tanggal dan waktu tanpa referensi ke zona waktu tertentu, atau DateTimeOffset nilai, yang mewakili momen waktu tertentu.

Unit waktu terbesar yang TimeSpan digunakan struktur untuk mengukur durasi adalah hari. Interval waktu diukur dalam hari untuk konsistensi, karena jumlah hari dalam satuan waktu yang lebih besar, seperti bulan dan tahun, bervariasi.

Nilai TimeSpan objek adalah jumlah tanda centang yang sama dengan interval waktu yang diwakili. Tanda centang sama dengan 100 nanodetik, atau sepuluh juta detik. Nilai TimeSpan objek dapat berkisar dari TimeSpan.MinValue hingga TimeSpan.MaxValue.

Membuat instans nilai TimeSpan

Anda dapat membuat TimeSpan instans nilai dalam sejumlah cara:

Dengan memanggil konstruktor tanpa parameter implisitnya. Ini membuat objek yang nilainya adalah TimeSpan.Zero, seperti yang ditunjukkan contoh berikut.

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

Dengan memanggil salah satu konstruktor eksplisitnya. Contoh berikut menginisialisasi TimeSpan nilai ke jumlah jam, menit, dan detik tertentu.

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

Dengan memanggil metode atau melakukan operasi yang mengembalikan TimeSpan nilai. Misalnya, Anda dapat membuat instans TimeSpan nilai yang mewakili interval antara dua nilai tanggal dan waktu, seperti yang ditunjukkan contoh berikut.

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

Anda juga dapat menginisialisasi TimeSpan objek ke nilai waktu nol dengan cara ini, seperti yang ditunjukkan contoh berikut.

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 nilai dikembalikan oleh operator aritmatika dan metode DateTimestruktur , , DateTimeOffsetdan TimeSpan .

Dengan mengurai representasi string dari nilai TimeSpan . Anda dapat menggunakan Parse metode dan TryParse untuk mengonversi string yang berisi interval waktu ke TimeSpan nilai. Contoh berikut menggunakan Parse metode untuk mengonversi array string menjadi TimeSpan nilai.

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'

Selain itu, Anda dapat menentukan format yang tepat dari string input yang akan diurai dan dikonversi ke TimeSpan nilai dengan memanggil ParseExact metode atau TryParseExact .

Melakukan operasi pada nilai TimeSpan

Anda dapat menambahkan dan mengurangi durasi waktu baik dengan menggunakan Addition operator dan Subtraction , atau dengan memanggil Add metode dan Subtract . Anda juga dapat membandingkan dua durasi waktu dengan memanggil Comparemetode , CompareTo, dan Equals . Struktur ini TimeSpan juga mencakup Duration metode dan Negate , yang mengonversi interval waktu menjadi nilai positif dan negatif,

Rentang TimeSpan nilai adalah MinValue ke MaxValue.

Memformat nilai TimeSpan

Nilai TimeSpan dapat direpresentasikan sebagai [-]d.hh:mm:ss.ff, di mana tanda minus opsional menunjukkan interval waktu negatif, komponen d adalah hari, hh adalah jam seperti yang diukur pada jam 24 jam, mm adalah menit, ss adalah detik, dan ff adalah pecahan detik. Artinya, interval waktu terdiri dari jumlah hari positif atau negatif tanpa waktu hari, atau sejumlah hari dengan waktu hari, atau hanya waktu hari.

Dimulai dengan .NET Framework 4, TimeSpan struktur mendukung pemformatan sensitif budaya melalui kelebihan beban metodenya ToString , yang mengonversi TimeSpan nilai ke representasi stringnya. Metode default TimeSpan.ToString() mengembalikan interval waktu dengan menggunakan format invarian yang identik dengan nilai pengembaliannya di versi .NET Framework sebelumnya. Kelebihan TimeSpan.ToString(String) beban memungkinkan Anda menentukan string format yang menentukan representasi string interval waktu. Kelebihan TimeSpan.ToString(String, IFormatProvider) beban memungkinkan Anda menentukan string format dan budaya yang konvensi pemformatannya digunakan untuk membuat representasi string interval waktu. TimeSpan mendukung string format standar dan kustom. (Untuk informasi selengkapnya, lihat String Format Rentang Waktu Standar dan String Format Rentang Waktu Kustom.) Namun, hanya string format standar yang peka terhadap budaya.

Memulihkan pemformatan TimeSpan warisan

Dalam beberapa kasus, kode yang berhasil memformat TimeSpan nilai dalam .NET Framework 3.5 dan versi yang lebih lama gagal di .NET Framework 4. Ini paling umum dalam kode yang memanggil <metode elemen TimeSpan_LegacyFormatMode> untuk memformat TimeSpan nilai dengan string format. Contoh berikut berhasil memformat TimeSpan nilai dalam .NET Framework 3.5 dan versi yang lebih lama, tetapi melemparkan pengecualian di .NET Framework 4 dan versi yang lebih baru. Perhatikan bahwa ia mencoba memformat TimeSpan nilai dengan menggunakan penentu format yang tidak didukung, yang diabaikan dalam .NET Framework 3.5 dan versi yang lebih lama.

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

Jika Anda tidak dapat mengubah kode, Anda dapat memulihkan pemformatan nilai warisan TimeSpan dengan salah satu cara berikut:

Dengan membuat file konfigurasi yang berisi <elemen TimeSpan_LegacyFormatMode>. Mengatur atribut elemen enabled ini untuk true memulihkan pemformatan warisan TimeSpan berdasarkan per aplikasi.

Dengan mengatur sakelar kompatibilitas "NetFx40_TimeSpanLegacyFormatMode" saat Anda membuat domain aplikasi. Ini memungkinkan pemformatan warisan TimeSpan berdasarkan per-application-domain. Contoh berikut membuat domain aplikasi yang menggunakan pemformatan warisan 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

Ketika kode berikut dijalankan di domain aplikasi baru, kode tersebut kembali ke perilaku pemformatan warisan 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.

Struktur System.TimeSpan

Membuat instans nilai TimeSpan

Melakukan operasi pada nilai TimeSpan

Memformat nilai TimeSpan

Memulihkan pemformatan TimeSpan warisan

Saran dan Komentar

Sumber Daya Tambahan: