Skip to main content
Version: 4.0 (next)

Produce spoken dates and clock times

Orientation​

Use date ordinal words when a calendar date should read naturally, and clock notation when a TimeOnly value should become a phrase such as “twenty-five past one.” These are localized presentation operations, distinct from relative time and numeric ordinal suffixes.

Example​

Date ordinal words use ambient culture. Humanizer 4 can pass a culture directly to clock notation; this executable demonstrates that overload while also scoping both ambient cultures for the date API:

Program.cs
using System.Globalization;
using Humanizer;

var culture = CultureInfo.GetCultureInfo("en-US");
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;

var date = new DateTime(2022, 1, 25).ToOrdinalWords();
var dateInGenitive = new DateOnly(2022, 1, 25).ToOrdinalWords(GrammaticalCase.Genitive);
var time = new TimeOnly(13, 23)
    .ToClockNotation(ClockNotationRounding.NearestFiveMinutes, culture);

AssertEqual("January 25th, 2022", date);
AssertEqual("January 25th, 2022", dateInGenitive);
AssertEqual("twenty-five past one", time);

Console.WriteLine($"{date}; {dateInGenitive}; {time}");

static void AssertEqual(string expected, string actual)
{
    if (actual != expected)
        throw new InvalidOperationException($"Expected '{expected}', got '{actual}'.");
}

Date ordinal words​

DateTime.ToOrdinalWords() and DateOnly.ToOrdinalWords() order the day, month, and year for CurrentCulture. A GrammaticalCase overload is available for locales whose date converter supports case-sensitive wording; because date words have no culture argument, scope CurrentCulture and CurrentUICulture together at the boundary.

Clock notation​

TimeOnly.ToClockNotation() renders the exact minute. ClockNotationRounding.NearestFiveMinutes first rounds to the nearest five-minute boundary, then selects the phrase. Rounding can cross an hour or day-period boundary. The Humanizer 4 overload that also accepts a CultureInfo avoids changing ambient culture.

Pitfall​

Every culture listed by Configurator.IsCultureSupported supplies date ordinal words, the grammatical-case overload, and clock notation. A locale whose date form does not vary by grammatical case returns the same authored date text. Supported same-language descendants inherit their parent locale's behavior; no supported non-English culture reaches the English default. Unsupported cultures can use a configured registry default, so the completeness guarantee applies only when Configurator.IsCultureSupported returns true.

Version notes​

DateTime.ToOrdinalWords predates the documented corpus. DateOnly date words begin with its framework support in 2.11.10. Clock notation appears in 2.13.14; the explicit-culture clock overload is available in Humanizer 4.