Permalink
Fetching contributors…
Cannot retrieve contributors at this time
136 lines (103 sloc) 11.3 KB
title ms.custom ms.date ms.prod ms.reviewer ms.suite ms.technology ms.tgt_pltfrm ms.topic helpviewer_keywords ms.assetid caps.latest.revision author ms.author manager
Standard TimeSpan Format Strings
03/30/2017
.net
dotnet-standard
article
format specifiers, standard time interval
format strings
standard time interval format strings
standard format strings, time intervals
format specifiers, time intervals
time intervals [.NET Framework], formatting
time [.NET Framework], formatting
formatting [.NET Framework], time
standard TimeSpan format strings
formatting [.NET Framework], time intervals
9f6c95eb-63ae-4dcc-9c32-f81985c75794
16
rpetrusha
ronpet
wpickett

Standard TimeSpan Format Strings

A standard xref:System.TimeSpan format string uses a single format specifier to define the text representation of a xref:System.TimeSpan value that results from a formatting operation. Any format string that contains more than one character, including white space, is interpreted as a custom xref:System.TimeSpan format string. For more information, see Custom TimeSpan Format Strings .

The string representations of xref:System.TimeSpan values are produced by calls to the overloads of the xref:System.TimeSpan.ToString%2A?displayProperty=nameWithType method, as well as by methods that support composite formatting, such as xref:System.String.Format%2A?displayProperty=nameWithType. For more information, see Formatting Types and Composite Formatting. The following example illustrates the use of standard format strings in formatting operations.

[!code-csharpConceptual.TimeSpan.Standard#2] [!code-vbConceptual.TimeSpan.Standard#2]

Standard xref:System.TimeSpan format strings are also used by the xref:System.TimeSpan.ParseExact%2A?displayProperty=nameWithType and xref:System.TimeSpan.TryParseExact%2A?displayProperty=nameWithType methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations.

[!code-csharpConceptual.TimeSpan.Standard#3] [!code-vbConceptual.TimeSpan.Standard#3]

The following table lists the standard time interval format specifiers.

Format specifier Name Description Examples
"c" Constant (invariant) format This specifier is not culture-sensitive. It takes the form [-][d’.’]hh’:’mm’:’ss[‘.’fffffff].

(The "t" and "T" format strings produce the same results.)

More information: The Constant ("c") Format Specifier.
TimeSpan.Zero -> 00:00:00

New TimeSpan(0, 0, 30, 0) -> 00:30:00

New TimeSpan(3, 17, 25, 30, 500) -> 3.17:25:30.5000000
"g" General short format This specifier outputs only what is needed. It is culture-sensitive and takes the form [-][d’:’]h’:’mm’:’ss[.FFFFFFF].

More information: The General Short ("g") Format Specifier.
New TimeSpan(1, 3, 16, 50, 500) -> 1:3:16:50.5 (en-US)

New TimeSpan(1, 3, 16, 50, 500) -> 1:3:16:50,5 (fr-FR)

New TimeSpan(1, 3, 16, 50, 599) -> 1:3:16:50.599 (en-US)

New TimeSpan(1, 3, 16, 50, 599) -> 1:3:16:50,599 (fr-FR)
"G" General long format This specifier always outputs days and seven fractional digits. It is culture-sensitive and takes the form [-]d’:’hh’:’mm’:’ss.fffffff.

More information: The General Long ("G") Format Specifier.
New TimeSpan(18, 30, 0) -> 0:18:30:00.0000000 (en-US)

New TimeSpan(18, 30, 0) -> 0:18:30:00,0000000 (fr-FR)

The Constant ("c") Format Specifier

The "c" format specifier returns the string representation of a xref:System.TimeSpan value in the following form:

[-][d.]hh:mm:ss[.fffffff]

Elements in square brackets ([ and ]) are optional. The period (.) and colon (:) are literal symbols. The following table describes the remaining elements.

Element Description
- An optional negative sign, which indicates a negative time interval.
d The optional number of days, with no leading zeros.
hh The number of hours, which ranges from "00" to "23".
mm The number of minutes, which ranges from "00" to "59".
ss The number of seconds, which ranges from "0" to "59".
fffffff The optional fractional portion of a second. Its value can range from "0000001" (one tick, or one ten-millionth of a second) to "9999999" (9,999,999 ten-millionths of a second, or one second less one tick).

Unlike the "g" and "G" format specifiers, the "c" format specifier is not culture-sensitive. It produces the string representation of a xref:System.TimeSpan value that is invariant and that is common to all previous versions of the .NET Framework before the [!INCLUDEnet_v40_long]. "c" is the default xref:System.TimeSpan format string; the xref:System.TimeSpan.ToString?displayProperty=nameWithType method formats a time interval value by using the "c" format string.

[!NOTE] xref:System.TimeSpan also supports the "t" and "T" standard format strings, which are identical in behavior to the "c" standard format string.

The following example instantiates two xref:System.TimeSpan objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the xref:System.TimeSpan value by using the "c" format specifier.

[!code-csharpConceptual.TimeSpan.Standard#1] [!code-vbConceptual.TimeSpan.Standard#1]

Back to table

The General Short ("g") Format Specifier

The "g" xref:System.TimeSpan format specifier returns the string representation of a xref:System.TimeSpan value in a compact form by including only the elements that are necessary. It has the following form:

[-][d:]h:mm:ss[.FFFFFFF]

Elements in square brackets ([ and ]) are optional. The colon (:) is a literal symbol. The following table describes the remaining elements.

Element Description
- An optional negative sign, which indicates a negative time interval.
d The optional number of days, with no leading zeros.
h The number of hours, which ranges from "0" to "23", with no leading zeros.
mm The number of minutes, which ranges from "00" to "59"..
ss The number of seconds, which ranges from "00" to "59"..
. The fractional seconds separator. It is equivalent to the specified culture's xref:System.Globalization.NumberFormatInfo.NumberDecimalSeparator%2A property without user overrides.
FFFFFFF The fractional seconds. As few digits as possible are displayed.

Like the "G" format specifier, the "g" format specifier is localized. Its fractional seconds separator is based on either the current culture or a specified culture's xref:System.Globalization.NumberFormatInfo.NumberDecimalSeparator%2A property.

The following example instantiates two xref:System.TimeSpan objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the xref:System.TimeSpan value by using the "g" format specifier. In addition, it formats the xref:System.TimeSpan value by using the formatting conventions of the current system culture (which, in this case, is English - United States or en-US) and the French - France (fr-FR) culture.

[!code-csharpConceptual.TimeSpan.Standard#4] [!code-vbConceptual.TimeSpan.Standard#4]

Back to table

The General Long ("G") Format Specifier

The "G" xref:System.TimeSpan format specifier returns the string representation of a xref:System.TimeSpan value in a long form that always includes both days and fractional seconds. The string that results from the "G" standard format specifier has the following form:

[-]d:hh:mm:ss.fffffff

Elements in square brackets ([ and ]) are optional. The colon (:) is a literal symbol. The following table describes the remaining elements.

Element Description
- An optional negative sign, which indicates a negative time interval.
d The number of days, with no leading zeros.
hh The number of hours, which ranges from "00" to "23".
mm The number of minutes, which ranges from "00" to "59".
ss The number of seconds, which ranges from "00" to "59".
. The fractional seconds separator. It is equivalent to the specified culture's xref:System.Globalization.NumberFormatInfo.NumberDecimalSeparator%2A property without user overrides.
fffffff The fractional seconds.

Like the "G" format specifier, the "g" format specifier is localized. Its fractional seconds separator is based on either the current culture or a specified culture's xref:System.Globalization.NumberFormatInfo.NumberDecimalSeparator%2A property.

The following example instantiates two xref:System.TimeSpan objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the xref:System.TimeSpan value by using the "G" format specifier. In addition, it formats the xref:System.TimeSpan value by using the formatting conventions of the current system culture (which, in this case, is English - United States or en-US) and the French - France (fr-FR) culture.

[!code-csharpConceptual.TimeSpan.Standard#5] [!code-vbConceptual.TimeSpan.Standard#5]

Back to table

See Also

Formatting Types
Custom TimeSpan Format Strings
Parsing Strings