[API Proposal]: `TimeSpan.ToString("c")` alternative that doesn't render days

[Tyrrrz]

Background and motivation

A lot of tools that work with time strings (e.g. FFmpeg), as well as data formats (e.g. SRT), use the following format for consuming and rendering timestamps:

hh:mm:ss.fff

This is pretty similar to .NET's built-in c format, except that the latter has a component for days too:

[d.]hh:mm:ss.fff

It would be incredibly convenient to have a separate built-in format that works exactly like c, but instead of rendering days, it should just render the total number of hours, even if they exceed a full day.

Because there is no formatting token for rendering hours beyond 24, currently the only workaround is to do something like this:

var value = TimeSpan.FromHours(27.123);

var str =
    Math.Floor(value.TotalHours).ToString("00") + ':' +
    value.Minutes.ToString("00") + ':' +
    value.Seconds.ToString("00") + '.' +
    value.Milliseconds.ToString("000");

This is pretty cumbersome. You can, of course, create an extension method to clean it up here, but that wouldn't work so well in the equivalent parsing scenario:

var str = "27:07:22.680";

var match = Regex.Match(str, @"(\d\d):(\d\d):(\d\d\.\d+)");
if (match.Success)
{
    var hours = int.Parse(totalDurationMatch.Groups[1].Value, CultureInfo.InvariantCulture);
    var minutes = int.Parse(totalDurationMatch.Groups[2].Value, CultureInfo.InvariantCulture);
    var seconds = double.Parse(totalDurationMatch.Groups[3].Value, CultureInfo.InvariantCulture);

    var value =
        TimeSpan.FromHours(hours) +
        TimeSpan.FromMinutes(minutes) +
        TimeSpan.FromSeconds(seconds);
}

API Proposal

I suggest adding a new standard format, for example ch C (I don't really care how it's called):

var value = TimeSpan.FromHours(27.123);
var str = value.ToString("C"); // 27:07:22.680

It should also be supported in TimeSpan.ParseExact(...) and related methods:

var str = "27:07:22.680";
var value = TimeSpan.ParseExact(str, "C", null);
// { Days: 1, Hours: 3, Minutes: 7, Seconds: 22, Milliseconds: 680 }

API Usage

See above

Alternative Designs

No response

Risks

No response

Tagging subscribers to this area: @dotnet/area-system-datetime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

A lot of tools that work with time strings (e.g. FFmpeg), as well as data formats (e.g. SRT), use the following format for rendering timestamps:

hh:mm:ss.fff

This is pretty similar to .NET's built-in c format, except that the latter has a component for days too:

[d.]hh:mm:ss.fff

It would be incredibly convenient to have a separate built-in format that works exactly like c, but instead of rendering days, it should just render the total number of hours, even if it's beyond 24 hours.

The current workaround is to do this:

var value = TimeSpan.FromHours(27.123);

var str =
    Math.Floor(value.TotalHours).ToString("00", formatProvider) + ':' +
    value.Minutes.ToString("00", formatProvider) + ':' +
    value.Seconds.ToString("00", formatProvider) + '.' +
    value.Milliseconds.ToString("000", formatProvider);

This is pretty cumbersome.

API Proposal

I suggest adding a new standard format, for example ch:

var value = TimeSpan.FromHours(27.123);
var str = value.ToString("ch"); // 27:07:22.680

API Usage

See above

Alternative Designs

No response

Risks

No response

Author:	Tyrrrz
Assignees:	-
Labels:	api-suggestion, untriaged, area-System.DateTime
Milestone:	-

[mattjohnsonpint]

I love this idea, but ch wouldn't work, because standard format strings have to be a single character. I propose capital C instead. (There is already precedence for lower-case vs upper-case standard format strings.) Or pick a new character completely.

Also, we'd have to solve a few related issues:

• We'd need a custom format specifier for just the hours component, so that one could compose strings such as "27:00" without the seconds or fractional seconds components. I suggest H and HH, which would work similarly to h and hh but, would allow exceeding 24 hours.
• We need to think through negative variations also. There's currently no custom format specifier for the sign, and it's not included with either h or hh. The docs currently call this out as a deficiency (in the second paragraph of the first blue "Important" box on the page).
• It's currently impossible to correctly parse a string with more than 24 hours. TimeSpan.Parse("24:00") fails outright. TimSpan.Parse("24:00:00") thinks that should be 24 days. TimeSpan.ParseExact with any parameters such as h or hh in the hours component fails because hours can't exceed 24.

[huoyaoyuan]

Note: a simpler workaround can be: $"{(int)value.TotalHours}:{value:mm\\:ss\\.fff}".

[kasperk81]

$"{(int)value.TotalHours:00}:{value:mm\\:ss\\.fff}" for desired padding

FFmpeg

see https://trac.ffmpeg.org/wiki/FFprobeTips#Duration. ffmpeg and srt don't use the exact same format. if there is something beyond srt using their format, or anything beyond ffmpeg using their (different) format, then by all means go for it, otherwise it looks too niche to assign a formatting character.

[Tyrrrz]

see trac.ffmpeg.org/wiki/FFprobeTips#Duration. ffmpeg and srt don't use the exact same format. if there is something beyond srt using their format, or anything beyond ffmpeg using their (different) format, then by all means go for it, otherwise it looks too niche to assign a formatting character.

Indeed, there are some subtle differences but they are generally negligible (for example, you can use both , and . in SRT to separate fractions). I think having a separate token for unbounded hours (e.g. HHH) would be nice to handle those things. But ultimately, I think even a standard format as described in the OP will be useful.

[crozone]

While having the new specifier wouldn't hurt for the common usecase, I think a better overall solution would be to go ahead and fix custom TimeSpan format strings. Currently custom TimeSpan format strings cannot even represent any of the standard format strings which is a major shortcoming. Extending the custom format functionality would probably solve the need for any new standard format string specifiers.