VcardDateAndOrTime Struct
Definition
Namespace: DataStandardizer.File.vCard
A DATE-AND-OR-TIME value (RFC 6350 §4.3.4): a date and time, a date, or a time written with a T before it. BDAY and ANNIVERSARY use it.
Syntax
public readonly struct VcardDateAndOrTime : IEquatable<VcardDateAndOrTime>, ISpanFormattable
Remarks
vCard 3.0 and 2.1 have no such type. Their BDAY property is a date or a date-time, so in those versions this type reads and writes those two and has no form for a time alone.
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.6), a value is a date, a date and time, or a time after a T, such as --02-03 or T12:30. In Xml, the form of xCard (RFC 6351 Appendix A), it is the content of a date, date-time or time element, with no T before a time alone, such as --0203 or 1230; parsing tries a date first, so --12 is December, and a date of a year alone has no form there. 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 Kind, Date, Time and IsDefinedIn. TryFormat writes nothing and returns true, ToString() gives the type name, and two default instances are equal.
Constructors
| Constructor | Notes |
|---|---|
VcardDateAndOrTime(VcardDate), VcardDateAndOrTime(VcardTime), VcardDateAndOrTime(VcardDateTime) | Throws ArgumentException if the argument isn’t initialised, or if it is a time that vCard 4.0, the only version with a time alone, can’t write. |
Properties
| Property | Notes |
|---|---|
VcardDateAndOrTimeKind Kind | What it holds. See VcardDateAndOrTimeKind. |
VcardDate? Date, VcardTime? Time | The parts it holds, otherwise null. |
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.