VcardTime Struct

Definition

Namespace: DataStandardizer.File.vCard

A TIME value (RFC 6350 §4.3.2): a time of day, which may leave out its hour, minute or second, with an optional zone.

Syntax

public readonly struct VcardTime : IEquatable<VcardTime>, ISpanFormattable

Remarks

Version Forms Standard
4.0 102200, 1022, 10, -2200, -22, --00, each with nothing, Z or an offset such as -0800 RFC 6350 §4.3.2
3.0 10:22:00, 102200, with single colons allowed, an optional fraction 10:22:00,5, and an optional zone, whose Z may be in either case RFC 2425 §5.8.4
2.1 10:22:00 or 102200, with a zone in the same format vCard 2.1 §2.6.2, §2.4.5

A second of 60 is accepted at any time of day, since the value doesn’t say whether a leap second falls there. An hour of 24 is rejected: RFC 6350 §4.3.2 says midnight is always 00, and RFC 2425 §5.8.4 gives hours up to 23. vCard 2.1 follows ISO 8601, so 24:00:00, the end of a day, is valid there alone. An offset’s hour of 24 belongs to the TZ property of vCard 2.1 (§2.4.5), so a time rejects it.

Two times are equal if they say the same thing the same way, not if they are the same instant: 10Z and 10+00 differ. A fraction of more than 18 digits keeps its first 18.

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.4), a time is in the extended format where it applies, such as 10:22:00, 10:22 or -22:00, with nothing, Z or an offset such as -08:00 after it. In Xml, the form of xCard (RFC 6351 Appendix A), it is the content of a time element, in the basic format, such as 102200 or -2200. 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 its properties and IsDefinedIn. TryFormat writes nothing and returns true, ToString() gives the type name, and two default instances are equal.

Constructors

Constructor Notes
VcardTime(int? hour, int? minute, int? second) No zone. A combination with no form, such as an hour and a second but no minute, throws ArgumentException.
VcardTime(int? hour, int? minute, int? second, bool isUtc) true writes the zone as Z.
VcardTime(int? hour, int? minute, int? second, VcardUtcOffset offset) A VcardUtcOffset as the zone.

Properties

Property Notes
int? Hour, int? Minute, int? Second A part, or null if the time leaves it out.
decimal? SecondFraction The fraction of a second that only vCard 3.0 has, or null.
bool IsUtc Whether the zone is written Z.
VcardUtcOffset? UtcOffset The zone if it is an offset, 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.