ImfDateTime Struct

Definition

Namespace: DataStandardizer.File.InternetMessage

A date-time (RFC 5322 §3.3), as in a Date or Resent-Date header field or at the end of a Received header field, such as Fri, 21 Nov 1997 09:55:06 -0600.

Syntax

public readonly struct ImfDateTime : IComparable<ImfDateTime>, IEquatable<ImfDateTime>

Remarks

This keeps what DateTimeOffset can’t represent: a leap second, whether a day of the week was given, a year after 9999, an offset of more than 14 hours, and the difference between +0000 and -0000, which says that the local offset is unknown (RFC 5322 §3.3).

The obsolete syntax (RFC 5322 §4.3) is read: a two- or three-digit year, a zone name, and comments and white space between the parts. A zone name is read as its numeric zone, and a military zone as -0000, because its meaning was defined wrongly in RFC 822. The name itself is not kept. No other zone name is in the grammar, so §4.3’s advice on them doesn’t apply and they are rejected. A year too large for an Int32 is also rejected.

ToString() writes the modern form.

Two values are equal only if they would be written the same way, so +0000 and -0000 differ, and so do the same moment at two offsets. The ordering is by moment, with a leap second after the second before it and before the one after it. Values at the same moment are then ordered by offset, then with an unknown offset last, then with a day of the week last, so that only equal values compare as 0. A value made with default holds no date-time: it equals only another such value, and comes before every other value. Its other members throw InvalidOperationException, but for ToString(), which gives the name of the type.

Constructors

Constructor Notes
ImfDateTime(DateTimeOffset value) Initializes a new date-time from a DateTimeOffset, with its offset and with no day of the week given. Any fraction of a second is dropped, as RFC 5322 §3.3 has no form for it. An offset of zero is +0000, not -0000. Throws ArgumentOutOfRangeException: The year of value is before 1900 (RFC 5322 §3.3).

Properties

Property Signature Notes
Day int Day { get; } Gets the day of the month, from 1. Throws InvalidOperationException: This value was made with default.
DayOfWeek DayOfWeek DayOfWeek { get; } Gets the day of the week implied by the date, whether or not one was given. Throws InvalidOperationException: This value was made with default.
HasDayOfWeek bool HasDayOfWeek { get; } Gets a flag indicating if a day of the week was given. Throws InvalidOperationException: This value was made with default.
Hour int Hour { get; } Gets the hour, from 0 to 23. Throws InvalidOperationException: This value was made with default.
IsOffsetUnknown bool IsOffsetUnknown { get; } Gets a flag indicating if the local offset is unknown, as for -0000 and the military zones (RFC 5322 §3.3 and §4.3). Throws InvalidOperationException: This value was made with default.
Minute int Minute { get; } Gets the minute, from 0 to 59. Throws InvalidOperationException: This value was made with default.
Month int Month { get; } Gets the month, from 1 to 12. Throws InvalidOperationException: This value was made with default.
Offset TimeSpan Offset { get; } Gets the offset from Universal Time. If IsOffsetUnknown is true, this is zero, because -0000 gives the date and time in Universal Time (RFC 5322 §3.3). It is then not the offset of the place the date-time came from, which is unknown, so check IsOffsetUnknown before using it as one. Throws InvalidOperationException: This value was made with default.
Second int Second { get; } Gets the second, from 0 to 60, where 60 is a leap second. It is 0 if the seconds were left out. Throws InvalidOperationException: This value was made with default.
Year int Year { get; } Gets the year, which is 1900 or later. Throws InvalidOperationException: This value was made with default.

Methods

Method Returns Notes
CompareTo(ImfDateTime other) int Compares this date-time with another, by moment and then by the differences that make them unequal. Returns: A negative number if this one comes first, zero if they are equal, or a positive number if the other comes first.
Equals(ImfDateTime other) bool Indicates whether this date-time equals another: they would be written the same way.
static Parse(string value) ImfDateTime Parses a date-time. Returns: The date-time. value: The date-time, which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600. Throws ArgumentNullException: value is null. Throws FormatException: The value is not a valid date-time.
static Parse(ReadOnlySpan<byte> value) ImfDateTime Parses a date-time. Returns: The date-time. value: The date-time as UTF-8 (RFC 6532), which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600. Throws FormatException: The value is not a valid date-time.
static Parse(string value, ImfOptions options) ImfDateTime Parses a date-time. Returns: The date-time. value: The date-time, which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600. options: The options, of which this uses ImfOptions.AllowInvalidValues. Throws ArgumentNullException: value or options is null. Throws FormatException: The value is not a valid date-time.
static Parse(ReadOnlySpan<byte> value, ImfOptions options) ImfDateTime Parses a date-time. Returns: The date-time. value: The date-time as UTF-8 (RFC 6532), which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600. options: The options, of which this uses ImfOptions.AllowInvalidValues. Throws ArgumentNullException: options is null. Throws FormatException: The value is not a valid date-time.
ToDateTimeOffset() DateTimeOffset Converts the date-time to a DateTimeOffset. A leap second becomes second 59 of the same minute, as DateTimeOffset has no leap seconds. Returns: The date and time, with their offset. Throws InvalidOperationException: The local offset is unknown, the date-time is outside what DateTimeOffset can represent, or this value was made with default.
ToDateTimeOffset(bool treatUnknownOffsetAsUniversalTime) DateTimeOffset Converts the date-time to a DateTimeOffset. A leap second becomes second 59 of the same minute, as DateTimeOffset has no leap seconds. Returns: The date and time, with their offset. treatUnknownOffsetAsUniversalTime: true to convert an unknown local offset as if it were +0000; false to throw. Throws InvalidOperationException: The local offset is unknown and treatUnknownOffsetAsUniversalTime is false, the date-time is outside what DateTimeOffset can represent, or this value was made with default.
ToString() string Formats the date-time in the modern form, such as Fri, 21 Nov 1997 09:55:06 -0600, with a day of the week if one was given. Returns: The date-time, or the name of this type if this value was made with default.
ToString(bool includeDayOfWeek) string Formats the date-time in the modern form, such as Fri, 21 Nov 1997 09:55:06 -0600. Returns: The date-time, or the name of this type if this value was made with default. includeDayOfWeek: true to write a day of the week even if none was given; false to write one only if it was.
static TryParse(string? value, out ImfDateTime result) bool Parses a date-time. Returns: true if the value is a valid date-time; otherwise false, including for null. value: The date-time, which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600.
static TryParse(ReadOnlySpan<byte> value, out ImfDateTime result) bool Parses a date-time. Returns: true if the value is a valid date-time; otherwise false. value: The date-time as UTF-8 (RFC 6532), which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600.
static TryParse(string? value, ImfOptions options, out ImfDateTime result) bool Parses a date-time. Returns: true if the value is a valid date-time; otherwise false, including for null. value: The date-time, which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600. options: The options, of which this uses ImfOptions.AllowInvalidValues. Throws ArgumentNullException: options is null.
static TryParse(ReadOnlySpan<byte> value, ImfOptions options, out ImfDateTime result) bool Parses a date-time. Returns: true if the value is a valid date-time; otherwise false. value: The date-time as UTF-8 (RFC 6532), which may be folded, such as Fri, 21 Nov 1997 09:55:06 -0600. options: The options, of which this uses ImfOptions.AllowInvalidValues. Throws ArgumentNullException: options is null.

Operators

Operator Returns Notes
operator !=(ImfDateTime left, ImfDateTime right) bool Indicates whether two date-times differ.
operator <(ImfDateTime left, ImfDateTime right) bool Indicates whether one date-time comes before another.
operator <=(ImfDateTime left, ImfDateTime right) bool Indicates whether one date-time comes before another or equals it.
operator ==(ImfDateTime left, ImfDateTime right) bool Indicates whether two date-times are equal.
operator >(ImfDateTime left, ImfDateTime right) bool Indicates whether one date-time comes after another.
operator >=(ImfDateTime left, ImfDateTime right) bool Indicates whether one date-time comes after another or equals it.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. The nullable reference annotations apply to the netstandard2.1 and net10.0 builds.

See also


This site uses Just the Docs, a documentation theme for Jekyll.