Meziantou.FrameworkRelativeDate Struct
Represents a date and time that can be formatted as a human-readable relative time string (e.g., "2 hours ago", "in 3 days").
public readonly struct RelativeDate : IComparable, IComparable<RelativeDate>, IEquatable<RelativeDate>, IFormattableRemarks
This type provides localized relative date/time strings for multiple languages: Dutch, English, French, German, Italian, Japanese, Korean, Portuguese, Simplified Chinese, Spanish and Turkish. The default localization can be customized by setting LocalizationProvider.Current.
Equality and ordering are defined over the instant alone. The time provider is display state: two instances that compare equal, and hash the same, can still render differently.
Example
// Basic usage
var pastDate = RelativeDate.Get(DateTime.UtcNow.AddHours(-2));
Assert.Equal("2 hours ago", pastDate.ToString(null, CultureInfo.InvariantCulture));
// With localization
var date = RelativeDate.Get(DateTime.UtcNow.AddMinutes(-30));
Assert.Equal("il y a 30 minutes", date.ToString(null, CultureInfo.GetCultureInfo("fr")));
Assert.Equal("30 minutes ago", date.ToString(null, CultureInfo.InvariantCulture));
// With custom TimeProvider for testing
var fakeTimeProvider = new FakeTimeProvider();
fakeTimeProvider.SetUtcNow(new DateTimeOffset(2024, 1, 1, 12, 0, 0, TimeSpan.Zero));
var testDate = RelativeDate.Get(new DateTime(2024, 1, 1, 10, 0, 0, DateTimeKind.Utc), fakeTimeProvider);
Assert.Equal("2 hours ago", testDate.ToString(null, CultureInfo.InvariantCulture));
var futureDate = RelativeDate.Get(new DateTime(2024, 1, 4, 12, 0, 0, DateTimeKind.Utc), fakeTimeProvider);
Assert.Equal("in 3 days", futureDate.ToString(null, CultureInfo.InvariantCulture));Constructors
| Name | Description |
|---|---|
| RelativeDate(DateTime) | Initializes a new instance of the RelativeDate struct with the specified date and system time provider. |
| RelativeDate(DateTime, TimeProvider?) | Initializes a new instance of the RelativeDate struct with the specified date and time provider. |
RelativeDate overloads
RelativeDate(DateTime)
RelativeDate.csInitializes a new instance of the RelativeDate struct with the specified date and system time provider.
public RelativeDate(DateTime dateTime)Parameters
dateTimeDateTime- The date and time. Must have
DateTimeKind.LocalorDateTimeKind.Utc.
Exceptions
ArgumentExceptiondateTimehasDateTimeKind.Unspecified.
RelativeDate(DateTime, TimeProvider?)
RelativeDate.csInitializes a new instance of the RelativeDate struct with the specified date and time provider.
public RelativeDate(DateTime dateTime, TimeProvider? timeProvider)Parameters
dateTimeDateTime- The date and time. Must have
DateTimeKind.LocalorDateTimeKind.Utc. timeProviderTimeProvider?- The time provider to use for calculating the relative time. If
null,TimeProvider.Systemis used. ADateTimeKind.LocaldateTimeis interpreted in this provider'sTimeProvider.LocalTimeZone.
Exceptions
ArgumentExceptiondateTimehasDateTimeKind.Unspecified.
Methods
| Name | Description |
|---|---|
| CompareTo(RelativeDate) | Compares this instance to another RelativeDate and returns an integer that indicates their relative order. |
| Equals(RelativeDate) | Determines whether the specified RelativeDate is equal to the current instance. |
| Equals(object?) | Determines whether the specified object is a RelativeDate equal to the current instance. |
| Get(DateTime) | Creates a RelativeDate from a RelativeDate.DateTime using the system time provider. |
| Get(DateTime, TimeProvider?) | Creates a RelativeDate from a RelativeDate.DateTime with a custom time provider. |
| Get(DateTimeOffset) | Creates a RelativeDate from a DateTimeOffset using the system time provider. |
| Get(DateTimeOffset, TimeProvider?) | Creates a RelativeDate from a DateTimeOffset with a custom time provider. |
| GetHashCode() | Returns a hash code derived from the instant, consistent with RelativeDate.Equals. |
| System.IComparable.CompareTo(object?) | |
| ToString() | Returns a localized string representation of the relative date (e.g., "2 hours ago", "in 3 days"). |
| ToString(string?, IFormatProvider?) | Formats the relative date using the specified format and culture. |
CompareTo(RelativeDate)
RelativeDate.csCompares this instance to another RelativeDate and returns an integer that indicates their relative order.
public int CompareTo(RelativeDate other)Parameters
otherRelativeDate- The
RelativeDateto compare with this instance.
Returns
int A value less than zero if this instance is earlier than other; zero if they represent the same date and time; greater than zero if this instance is later than other.
Remarks
Only the instant is compared. The time provider is display state and takes no part in the ordering.
Equals overloads
Equals(RelativeDate)
RelativeDate.csDetermines whether the specified RelativeDate is equal to the current instance.
public bool Equals(RelativeDate other)Parameters
otherRelativeDate
Returns
Remarks
Only the instant is compared, so two equal instances built with different time providers can still produce different strings from RelativeDate.ToString.
Equals(object?)
RelativeDate.csDetermines whether the specified object is a RelativeDate equal to the current instance.
Parameters
objobject?
Returns
Remarks
Only the instant is compared, so two equal instances built with different time providers can still produce different strings from RelativeDate.ToString.
Get overloads
Get(DateTime)
RelativeDate.csCreates a RelativeDate from a RelativeDate.DateTime using the system time provider.
public static RelativeDate Get(DateTime dateTime)Parameters
dateTimeDateTime- The date and time. Must have
DateTimeKind.LocalorDateTimeKind.Utc.
Returns
RelativeDate A new RelativeDate instance.
Exceptions
ArgumentExceptiondateTimehasDateTimeKind.Unspecified.
Get(DateTime, TimeProvider?)
RelativeDate.csCreates a RelativeDate from a RelativeDate.DateTime with a custom time provider.
public static RelativeDate Get(DateTime dateTime, TimeProvider? timeProvider)Parameters
dateTimeDateTime- The date and time. Must have
DateTimeKind.LocalorDateTimeKind.Utc. timeProviderTimeProvider?- The time provider to use for calculating the relative time. If
null,TimeProvider.Systemis used.
Returns
RelativeDate A new RelativeDate instance.
Exceptions
ArgumentExceptiondateTimehasDateTimeKind.Unspecified.
Get(DateTimeOffset)
RelativeDate.csCreates a RelativeDate from a DateTimeOffset using the system time provider.
public static RelativeDate Get(DateTimeOffset dateTime)Parameters
dateTimeDateTimeOffset- The date and time offset.
Returns
RelativeDate A new RelativeDate instance.
Get(DateTimeOffset, TimeProvider?)
RelativeDate.csCreates a RelativeDate from a DateTimeOffset with a custom time provider.
public static RelativeDate Get(DateTimeOffset dateTime, TimeProvider? timeProvider)Parameters
dateTimeDateTimeOffset- The date and time offset.
timeProviderTimeProvider?- The time provider to use for calculating the relative time. If
null,TimeProvider.Systemis used.
Returns
RelativeDate A new RelativeDate instance.
GetHashCode()
RelativeDate.csReturns a hash code derived from the instant, consistent with RelativeDate.Equals.
public override int GetHashCode()Returns
System.IComparable.CompareTo(object?)
RelativeDate.csToString overloads
ToString()
RelativeDate.csToString(string?, IFormatProvider?)
RelativeDate.csFormats the relative date using the specified format and culture.
public string ToString(string? format, IFormatProvider? formatProvider)Parameters
formatstring?- The format string. Only
null, an empty string and"G"are supported; the output does not vary between them. formatProviderIFormatProvider?- An
IFormatProviderthat supplies culture-specific formatting information, typically aCultureInfo. A provider that returns aCultureInfofromIFormatProvider.GetFormatis also honored. Whennull,CultureInfo.CurrentUICultureis used.
Returns
string A localized relative date string.
Exceptions
FormatExceptionformatis notnull, empty or"G".
Remarks
The method returns strings like:
- "now" - for the current moment
- "one second ago" / "in one second" - for ±1 second
- "X seconds ago" / "in X seconds" - for <1 minute
- "a minute ago" / "in a minute" - for 1-2 minutes
- "X minutes ago" / "in X minutes" - for <45 minutes
- "an hour ago" / "in an hour" - for 45-120 minutes
- "X hours ago" / "in X hours" - for 2-24 hours
- "yesterday" / "tomorrow" - for 24-48 hours
- "X days ago" / "in X days" - for <30 days
- "one month ago" / "in one month" - for 30-60 days
- "X months ago" / "in X months" - for <365 days
- "one year ago" / "in one year" - for 365-730 days
- "X years ago" / "in X years" - for ≥730 days
Operators
| Name | Description |
|---|---|
| operator ==(RelativeDate, RelativeDate) | Determines whether two RelativeDate instances are equal. |
| operator >(RelativeDate, RelativeDate) | Determines whether one RelativeDate is greater than another. |
| operator >=(RelativeDate, RelativeDate) | Determines whether one RelativeDate is greater than or equal to another. |
| operator !=(RelativeDate, RelativeDate) | Determines whether two RelativeDate instances are not equal. |
| operator <(RelativeDate, RelativeDate) | Determines whether one RelativeDate is less than another. |
| operator <=(RelativeDate, RelativeDate) | Determines whether one RelativeDate is less than or equal to another. |
operator ==(RelativeDate, RelativeDate)
RelativeDate.csDetermines whether two RelativeDate instances are equal.
public static bool operator ==(RelativeDate date1, RelativeDate date2)operator >(RelativeDate, RelativeDate)
RelativeDate.csDetermines whether one RelativeDate is greater than another.
public static bool operator >(RelativeDate left, RelativeDate right)operator >=(RelativeDate, RelativeDate)
RelativeDate.csDetermines whether one RelativeDate is greater than or equal to another.
public static bool operator >=(RelativeDate left, RelativeDate right)operator !=(RelativeDate, RelativeDate)
RelativeDate.csDetermines whether two RelativeDate instances are not equal.
public static bool operator !=(RelativeDate date1, RelativeDate date2)operator <(RelativeDate, RelativeDate)
RelativeDate.csDetermines whether one RelativeDate is less than another.
public static bool operator <(RelativeDate left, RelativeDate right)operator <=(RelativeDate, RelativeDate)
RelativeDate.csDetermines whether one RelativeDate is less than or equal to another.
public static bool operator <=(RelativeDate left, RelativeDate right)