VcardDate Struct

Definition

Namespace: DataStandardizer.File.vCard

A DATE value (RFC 6350 §4.3.1): a calendar date, which may leave out its year, month or day.

Syntax

public readonly struct VcardDate : IEquatable<VcardDate>, ISpanFormattable

Remarks

Version Forms Standard
4.0 19850412, 1985-04, 1985, --0412, --04, ---12 RFC 6350 §4.3.1
3.0 1996-04-15, 19960415, and with one hyphen RFC 2425 §5.8.4
2.1 1995-04-15, 19950415 vCard 2.1 §2.2.4

1985-04-12 is not a vCard 4.0 date, and a reduced date is not a vCard 3.0 or 2.1 date. Each version is held to its own grammar. vCard 3.0 and 2.1 write the extended format.

The year runs from 0 to 9999, so a date can’t always become a DateTime. A date with no year allows 29 February, and year 0 is a leap year, as in ISO 8601.

Versions. Every parse and format method has an overload taking a VcardVersion. The overload without one uses vCard 4.0. IsDefinedIn says whether a version can write the value, and formatting one it can’t throws InvalidOperationException.

Forms. In Json, the form of jCard (RFC 7095 §3.5.3), a date is in the extended format where it applies: 1985-04-12, 1985-04, 1985, --04-12, --04 and ---12. In Xml, the form of xCard (RFC 6351 Appendix A), it is in the basic format, but with no year alone, so 1985 doesn’t parse in that form, and a date of a year alone throws InvalidOperationException when formatted in it. jCard and xCard represent vCard 4.0 alone, so those forms have no other version.

Parsing from a string. Parse and TryParse take a ReadOnlySpan<char>. A string converts implicitly on .NET Core and .NET Standard 2.1. On .NET Framework, call AsSpan().

Allocation. TryParse from a span and TryFormat into one do not allocate (covered by VcardValueAllocationTests).

On the net10.0 build the type implements ISpanFormattable. An empty format string or T gives the Text form.

Uninitialised instance. A default instance throws InvalidOperationException from Year, Month, Day, IsComplete and IsDefinedIn. TryFormat writes nothing and returns true, ToString() gives the type name, and two default instances are equal.

Constructors and factories

Member Notes
VcardDate(int year, int month, int day) A complete date.
FromYear, FromYearAndMonth, FromMonth, FromMonthAndDay, FromDay The other forms. An out-of-range part throws ArgumentOutOfRangeException.

Properties

Property Notes
int? Year, int? Month, int? Day A part, or null if the date leaves it out.
bool IsComplete Whether it has a year, a month and a day.

Methods

Method Notes
TryParse(value, format, out result) Parses a vCard 4.0 value. Returns false if it isn’t valid.
TryParse(value, format, version, out result) Parses a value by the grammar of a version.
Parse(value, format), Parse(value, format, version) As TryParse, and throws FormatException if the value isn’t valid.
TryFormat(destination, out charsWritten, format), TryFormat(destination, out charsWritten, format, version) Writes the value. Returns false if the destination is too short.
ToString(format), ToString(format, version) Formats the value as a string.
IsDefinedIn(version) Whether a version can write this value.

See the API reference.


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