In this article

Custom TimeSpan Format Strings

In this article

A TimeSpan format string defines the string representation of a TimeSpan value that results from a formatting operation. A custom format string consists of one or more custom TimeSpan format specifiers along with any number of literal characters. Any string that is not a standard TimeSpan format string is interpreted as a custom TimeSpan format string.

Important

The custom TimeSpan format specifiers do not include placeholder separator symbols, such as the symbols that separate days from hours, hours from minutes, or seconds from fractional seconds. Instead, these symbols must be included in the custom format string as string literals. For example, "dd\.hh\:mm" defines a period (.) as the separator between days and hours, and a colon (:) as the separator between hours and minutes.

Custom TimeSpan format specifiers also do not include a sign symbol that enables you to differentiate between negative and positive time intervals. To include a sign symbol, you have to construct a format string by using conditional logic. The Other Characters section includes an example.

Custom TimeSpan format strings are also used by the TimeSpan.ParseExact and TimeSpan.TryParseExact 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.

The "d" Custom Format Specifier

The "d" custom format specifier outputs the value of the TimeSpan.Days property, which represents the number of whole days in the time interval. It outputs the full number of days in a TimeSpan value, even if the value has more than one digit. If the value of the TimeSpan.Days property is zero, the specifier outputs "0".

If the "d" custom format specifier is used alone, specify "%d" so that it is not misinterpreted as a standard format string. The following example provides an illustration.

The "dd"-"dddddddd" Custom Format Specifiers

The "dd", "ddd", "dddd", "ddddd", "dddddd", "ddddddd", and "dddddddd" custom format specifiers output the value of the TimeSpan.Days property, which represents the number of whole days in the time interval.

The output string includes a minimum number of digits specified by the number of "d" characters in the format specifier, and it is padded with leading zeros as needed. If the digits in the number of days exceed the number of "d" characters in the format specifier, the full number of days is output in the result string.

The following example uses these format specifiers to display the string representation of two TimeSpan values. The value of the days component of the first time interval is zero; the value of the days component of the second is 365.

The "h" Custom Format Specifier

The "h" custom format specifier outputs the value of the TimeSpan.Hours property, which represents the number of whole hours in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the TimeSpan.Hours property is 0 through 9, and it returns a two-digit string value if the value of the TimeSpan.Hours property ranges from 10 to 23.

If the "h" custom format specifier is used alone, specify "%h" so that it is not misinterpreted as a standard format string. The following example provides an illustration.

Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%h" custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration.

Dim value As String = "8"
Dim interval As TimeSpan
If TimeSpan.TryParseExact(value, "%h", Nothing, interval) Then
Console.WriteLine(interval.ToString("c"))
Else
Console.WriteLine("Unable to convert '{0}' to a time interval",
value)
End If
' The example displays the following output:
' 08:00:00

The following example illustrates the use of the "h" custom format specifier.

The "hh" Custom Format Specifier

The "hh" custom format specifier outputs the value of the TimeSpan.Hours property, which represents the number of whole hours in the time interval that is not counted as part of its day component. For values from 0 through 9, the output string includes a leading zero.

Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "hh" custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration.

Dim value As String = "08"
Dim interval As TimeSpan
If TimeSpan.TryParseExact(value, "hh", Nothing, interval) Then
Console.WriteLine(interval.ToString("c"))
Else
Console.WriteLine("Unable to convert '{0}' to a time interval",
value)
End If
' The example displays the following output:
' 08:00:00

The following example illustrates the use of the "hh" custom format specifier.

The "m" Custom Format Specifier

The "m" custom format specifier outputs the value of the TimeSpan.Minutes property, which represents the number of whole minutes in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the TimeSpan.Minutes property is 0 through 9, and it returns a two-digit string value if the value of the TimeSpan.Minutes property ranges from 10 to 59.

If the "m" custom format specifier is used alone, specify "%m" so that it is not misinterpreted as a standard format string. The following example provides an illustration.

Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%m" custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration.

Dim value As String = "3"
Dim interval As TimeSpan
If TimeSpan.TryParseExact(value, "%m", Nothing, interval) Then
Console.WriteLine(interval.ToString("c"))
Else
Console.WriteLine("Unable to convert '{0}' to a time interval",
value)
End If
' The example displays the following output:
' 00:03:00

The following example illustrates the use of the "m" custom format specifier.

The "mm" Custom Format Specifier

The "mm" custom format specifier outputs the value of the TimeSpan.Minutes property, which represents the number of whole minutes in the time interval that is not included as part of its hours or days component. For values from 0 through 9, the output string includes a leading zero.

Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "mm" custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration.

Dim value As String = "05"
Dim interval As TimeSpan
If TimeSpan.TryParseExact(value, "mm", Nothing, interval) Then
Console.WriteLine(interval.ToString("c"))
Else
Console.WriteLine("Unable to convert '{0}' to a time interval",
value)
End If
' The example displays the following output:
' 00:05:00

The following example illustrates the use of the "mm" custom format specifier.

The "s" Custom Format Specifier

The "s" custom format specifier outputs the value of the TimeSpan.Seconds property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. It returns a one-digit string value if the value of the TimeSpan.Seconds property is 0 through 9, and it returns a two-digit string value if the value of the TimeSpan.Seconds property ranges from 10 to 59.

If the "s" custom format specifier is used alone, specify "%s" so that it is not misinterpreted as a standard format string. The following example provides an illustration.

Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "%s" custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration.

Dim value As String = "9"
Dim interval As TimeSpan
If TimeSpan.TryParseExact(value, "%s", Nothing, interval) Then
Console.WriteLine(interval.ToString("c"))
Else
Console.WriteLine("Unable to convert '{0}' to a time interval",
value)
End If
' The example displays the following output:
' 00:00:09

The following example illustrates the use of the "s" custom format specifier.

The "ss" Custom Format Specifier

The "ss" custom format specifier outputs the value of the TimeSpan.Seconds property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. For values from 0 through 9, the output string includes a leading zero.

Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "ss" custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration.

Dim values() As String = { "49", "9", "06" }
Dim interval As TimeSpan
For Each value As String In values
If TimeSpan.TryParseExact(value, "ss", Nothing, interval) Then
Console.WriteLine(interval.ToString("c"))
Else
Console.WriteLine("Unable to convert '{0}' to a time interval",
value)
End If
Next
' The example displays the following output:
' 00:00:49
' Unable to convert '9' to a time interval
' 00:00:06

The following example illustrates the use of the "ss" custom format specifier.

The"f" Custom Format Specifier

The "f" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the input string must contain exactly one fractional digit.

If the "f" custom format specifier is used alone, specify "%f" so that it is not misinterpreted as a standard format string.

The following example uses the "f" custom format specifier to display the tenths of a second in a TimeSpan value. "f" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string.

The "ff" Custom Format Specifier

The "ff" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the input string must contain exactly two fractional digits.

The following example uses the "ff" custom format specifier to display the hundredths of a second in a TimeSpan value. "ff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string.

The "fff" Custom Format Specifier

The "fff" custom format specifier (with three "f" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the input string must contain exactly three fractional digits.

The following example uses the "fff" custom format specifier to display the milliseconds in a TimeSpan value. "fff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string.

The "ffff" Custom Format Specifier

The "ffff" custom format specifier (with four "f" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the input string must contain exactly four fractional digits.

The following example uses the "ffff" custom format specifier to display the ten-thousandths of a second in a TimeSpan value. "ffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string.

The "fffff" Custom Format Specifier

The "fffff" custom format specifier (with five "f" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the input string must contain exactly five fractional digits.

The following example uses the "fffff" custom format specifier to display the hundred-thousandths of a second in a TimeSpan value. "fffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string.

The "ffffff" Custom Format Specifier

The "ffffff" custom format specifier (with six "f" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the input string must contain exactly six fractional digits.

The following example uses the "ffffff" custom format specifier to display the millionths of a second in a TimeSpan value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string.

The "fffffff" Custom Format Specifier

The "fffffff" custom format specifier (with seven "f" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the input string must contain exactly seven fractional digits.

The following example uses the "fffffff" custom format specifier to display the fractional number of ticks in a TimeSpan value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string.

The "F" Custom Format Specifier

The "F" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If the value of the time interval's tenths of a second is zero, it is not included in the result string. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the presence of the tenths of a second digit is optional.

If the "F" custom format specifier is used alone, specify "%F" so that it is not misinterpreted as a standard format string.

The following example uses the "F" custom format specifier to display the tenths of a second in a TimeSpan value. It also uses this custom format specifier in a parsing operation.

The "FF" Custom Format Specifier

The "FF" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the presence of the tenths and hundredths of a second digit is optional.

The following example uses the "FF" custom format specifier to display the hundredths of a second in a TimeSpan value. It also uses this custom format specifier in a parsing operation.

The "FFF" Custom Format Specifier

The "FFF" custom format specifier (with three "F" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the presence of the tenths, hundredths, and thousandths of a second digit is optional.

The following example uses the "FFF" custom format specifier to display the thousandths of a second in a TimeSpan value. It also uses this custom format specifier in a parsing operation.

The "FFFF" Custom Format Specifier

The "FFFF" custom format specifier (with four "F" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the presence of the tenths, hundredths, thousandths, and ten-thousandths of a second digit is optional.

The following example uses the "FFFF" custom format specifier to display the ten-thousandths of a second in a TimeSpan value. It also uses the "FFFF" custom format specifier in a parsing operation.

The "FFFFF" Custom Format Specifier

The "FFFFF" custom format specifier (with five "F" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the presence of the tenths, hundredths, thousandths, ten-thousandths, and hundred-thousandths of a second digit is optional.

The following example uses the "FFFFF" custom format specifier to display the hundred-thousandths of a second in a TimeSpan value. It also uses the "FFFFF" custom format specifier in a parsing operation.

The "FFFFFF" Custom Format Specifier

The "FFFFFF" custom format specifier (with six "F" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the presence of the tenths, hundredths, thousandths, ten-thousandths, hundred-thousandths, and millionths of a second digit is optional.

The following example uses the "FFFFFF" custom format specifier to display the millionths of a second in a TimeSpan value. It also uses this custom format specifier in a parsing operation.

The "FFFFFFF" Custom Format Specifier

The "FFFFFFF" custom format specifier (with seven "F" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the TimeSpan.ParseExact or TimeSpan.TryParseExact method, the presence of the seven fractional digits in the input string is optional.

The following example uses the "FFFFFFF" custom format specifier to display the fractional parts of a second in a TimeSpan value. It also uses this custom format specifier in a parsing operation.

Other Characters

Any other unescaped character in a format string, including a white-space character, is interpreted as a custom format specifier. In most cases, the presence of any other unescaped character results in a FormatException.

There are two ways to include a literal character in a format string:

Enclose it in single quotation marks (the literal string delimiter).

Precede it with a backslash ("\"), which is interpreted as an escape character. This means that, in C#, the format string must either be @-quoted, or the literal character must be preceded by an additional backslash.

In some cases, you may have to use conditional logic to include an escaped literal in a format string. The following example uses conditional logic to include a sign symbol for negative time intervals.

.NET does not define a grammar for separators in time intervals. This means that the separators between days and hours, hours and minutes, minutes and seconds, and seconds and fractions of a second must all be treated as character literals in a format string.

The following example uses both the escape character and the single quote to define a custom format string that includes the word "minutes" in the output string.