Struct System.TimeSpan

Article
01/11/2024

Cet article vous offre des remarques complémentaires à la documentation de référence pour 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, le ou DateTimeOffset la structure doit être utilisé à la DateTime 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 TimeSpan objet est le nombre de graduations qui sont égales à l’intervalle de temps représenté. Une graduation est égale à 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 sans paramètre implicite. 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("{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

Vous pouvez également initialiser un TimeSpan objet à une valeur zéro temps 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: {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 les valeurs sont retournées par des opérateurs arithmétiques et des méthodes du DateTime, DateTimeOffsetet TimeSpan des structures.

En analysant la représentation sous forme de chaîne d’une TimeSpan valeur. Vous pouvez utiliser les méthodes et TryParse les Parse méthodes pour convertir des chaînes qui contiennent des intervalles de temps en TimeSpan valeurs. 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("'{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'

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

Effectuer des opérations sur les valeurs TimeSpan

Vous pouvez ajouter et soustraire des durées de temps à l’aide des Addition opérateurs et Subtraction des opérateurs, ou en appelant les méthodes et Subtract les Add méthodes. Vous pouvez également comparer deux durées de temps en appelant les méthodes et les CompareméthodesCompareTo Equals. La TimeSpan structure inclut également les méthodes et Negate les Duration méthodes, 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 jours, hh est heures comme mesuré sur une horloge de 24 heures, mm est minutes, ss est secondes, et ff est des fractions 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.

À compter de .NET Framework 4, la TimeSpan structure prend en charge la mise en forme sensible à la culture par le biais des surcharges de sa ToString méthode, qui convertit une TimeSpan valeur 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 TimeSpan les valeurs dans .NET Framework 3.5 et les versions antérieures échoue dans .NET Framework 4. Ceci est le plus courant dans le code qui appelle une méthode d’élément <TimeSpan_LegacyFormatMode> pour mettre en forme une TimeSpan valeur avec une chaîne de format. L’exemple suivant met en forme une TimeSpan valeur 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("{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 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éfinition de l’attribut de enabled cet élément pour true restaurer la mise en forme héritée TimeSpan par application.

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

Struct 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