| 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 |
|
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:00New TimeSpan(0, 0, 30, 0) -> 00:30:00New 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]
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]
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]
See Also
Formatting Types
Custom TimeSpan Format Strings
Parsing Strings