Structure System.TimeSpan

2025-06-21

Cet article fournit des remarques supplémentaires à la documentation de référence de cette API.

Un TimeSpan objet représente un intervalle de temps (durée ou temps écoulé) qui est mesuré sous la forme d’un nombre positif ou négatif de jours, d’heures, de minutes, de secondes et de fractions d’une seconde. La TimeSpan structure peut également être utilisée pour représenter l’heure du jour, mais uniquement si l’heure n’est pas liée à une date particulière. Sinon, la structure DateTime ou DateTimeOffset devrait être utilisée à la place. (Pour plus d’informations sur l’utilisation de la TimeSpan structure pour refléter l’heure de la journée, consultez Choix entre DateTime, DateTimeOffset, TimeSpan et TimeZoneInfo.)

Remarque

Une TimeSpan valeur représente un intervalle de temps et peut être exprimée sous la forme d’un nombre particulier de jours, d’heures, de minutes, de secondes et de millisecondes. Étant donné qu’il représente un intervalle général sans référence à un point de début ou de fin particulier, il ne peut pas être exprimé en termes d’années et de mois, dont les deux ont un nombre variable de jours. Il diffère d’une DateTime valeur, qui représente une date et une heure sans référence à un fuseau horaire particulier, ou une DateTimeOffset valeur, qui représente un moment spécifique de l’heure.

La plus grande unité de temps utilisée par la structure pour mesurer la TimeSpan durée est un jour. Les intervalles de temps sont mesurés en jours pour la cohérence, car le nombre de jours dans des unités de temps plus grandes, telles que des mois et des années, varie.

La valeur d’un objet TimeSpan correspond au nombre de cycles qui correspondent à l’intervalle de temps représenté. Un tick est égal à 100 nanosecondes, ou un dix-millionième de seconde. La valeur d’un TimeSpan objet peut être comprise entre TimeSpan.MinValue TimeSpan.MaxValue.

Instancier une valeur TimeSpan

Vous pouvez instancier une TimeSpan valeur de plusieurs façons :

En appelant son constructeur implicite sans paramètres. Cela crée un objet dont la valeur est TimeSpan.Zero, comme l’illustre l’exemple suivant.

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

En appelant l’un de ses constructeurs explicites. L’exemple suivant initialise une TimeSpan valeur à un nombre spécifié d’heures, de minutes et de secondes.

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

En appelant une méthode ou en effectuant une opération qui retourne une TimeSpan valeur. Par exemple, vous pouvez instancier une TimeSpan valeur qui représente l’intervalle entre deux valeurs de date et d’heure, comme l’illustre l’exemple suivant.

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

Vous pouvez également initialiser un objet TimeSpan à une valeur de temps zéro de cette façon, comme l’illustre l’exemple suivant.

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

TimeSpan Les valeurs sont retournées par des opérateurs arithmétiques et les méthodes des structures DateTime, DateTimeOffset, et TimeSpan.

En analysant la représentation sous forme de chaîne d’une TimeSpan valeur. Vous pouvez utiliser les méthodes Parse et TryParse pour convertir des chaînes qui contiennent des intervalles de temps en valeurs TimeSpan. L’exemple suivant utilise la Parse méthode pour convertir un tableau de chaînes en TimeSpan valeurs.

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'

En outre, vous pouvez définir le format précis de la chaîne d’entrée à analyser et à convertir en une valeur TimeSpan en appelant la méthode ParseExact ou TryParseExact.

Effectuer des opérations sur les valeurs TimeSpan

Vous pouvez ajouter et soustraire des durées de temps à l’aide des opérateurs Addition et Subtraction, ou en appelant les méthodes Add et Subtract. Vous pouvez également comparer deux durées en appelant les méthodes Compare, CompareTo, et Equals. La structure TimeSpan inclut également les méthodes Duration et Negate, qui convertissent les intervalles de temps en valeurs positives et négatives.

La plage de TimeSpan valeurs est MinValue à MaxValue.

Mettre en forme une valeur TimeSpan

Une TimeSpan valeur peut être représentée sous la forme [-]d.hh:mm:ss.ff, où le signe moins facultatif indique un intervalle de temps négatif, le composant d est le nombre de jours, hh est le nombre d'heures mesurées sur une horloge de 24 heures, mm est le nombre de minutes, ss est le nombre de secondes, et ff est une fraction de seconde. Autrement dit, un intervalle de temps se compose d’un nombre positif ou négatif de jours sans heure de jour, ou d’un certain nombre de jours avec une heure de jour, ou seulement une heure de jour.

À partir de .NET Framework 4, la structure TimeSpan prend en charge la mise en forme sensible aux paramètres régionaux grâce aux surcharges de sa méthode ToString, qui convertit une valeur TimeSpan en sa représentation sous forme de chaîne. La méthode par défaut TimeSpan.ToString() retourne un intervalle de temps à l’aide d’un format invariant identique à sa valeur de retour dans les versions précédentes de .NET Framework. La TimeSpan.ToString(String) surcharge vous permet de spécifier une chaîne de format qui définit la représentation sous forme de chaîne de l’intervalle de temps. La TimeSpan.ToString(String, IFormatProvider) surcharge vous permet de spécifier une chaîne de format et la culture dont les conventions de mise en forme sont utilisées pour créer la représentation sous forme de chaîne de l’intervalle de temps. TimeSpan prend en charge les chaînes de format standard et personnalisées. (Pour plus d’informations, consultez Chaînes de format timeSpan standard et chaînes de format TimeSpan personnalisées.) Toutefois, seules les chaînes de format standard respectent la culture.

Restaurer la mise en forme timeSpan héritée

Dans certains cas, le code qui met en forme les valeurs dans .NET Framework 3.5 et les versions antérieures échoue dans .NET Framework 4. Ceci est le plus fréquent dans le code qui appelle une méthode <TimeSpan_LegacyFormatMode> element pour formater une valeur TimeSpan avec une chaîne de format. L’exemple suivant met en forme une valeur TimeSpan dans .NET Framework 3.5 et versions antérieures, mais lève une exception dans .NET Framework 4 et versions ultérieures. Notez qu’il tente de mettre en forme une TimeSpan valeur à l’aide d’un spécificateur de format non pris en charge, qui est ignoré dans .NET Framework 3.5 et les versions antérieures.

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

Si vous ne pouvez pas modifier le code, vous pouvez restaurer la mise en forme héritée des TimeSpan valeurs de l’une des manières suivantes :

En créant un fichier de configuration qui contient <l'élément TimeSpan_LegacyFormatMode>. Définir l’attribut de enabled de cet élément à true restaure la mise en forme héritée TimeSpan pour chaque application.

En définissant le commutateur de compatibilité « NetFx40_TimeSpanLegacyFormatMode » lorsque vous créez un domaine d’application. Cela permet une mise en forme TimeSpan héritée par domaine d’application. L’exemple suivant crée un domaine d’application qui utilise la mise en forme héritée 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

Lorsque le code suivant s’exécute dans le nouveau domaine d’application, il revient au comportement de mise en forme hérité 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.

Partager via

Structure System.TimeSpan

Instancier une valeur TimeSpan

Effectuer des opérations sur les valeurs TimeSpan

Mettre en forme une valeur TimeSpan

Restaurer la mise en forme timeSpan héritée

Commentaires

Ressources supplémentaires