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.


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