VcardUtcOffset Struct
Definition
Namespace: DataStandardizer.File.vCard
A UTC-OFFSET value (RFC 6350 §4.7): a signed difference from UTC in hours and, optionally, minutes.
Syntax
public readonly struct VcardUtcOffset : IEquatable<VcardUtcOffset>, ISpanFormattable
Remarks
| Version | Forms | Standard |
|---|---|---|
| 4.0 | -05, -0500 | RFC 6350 §4 |
| 3.0 | -05:00 only | RFC 2426 §2.4.4 |
| 2.1 | -05, -0500, -05:00, with hours up to 24 | vCard 2.1 §2.4.5 |
An offset keeps what was written: -05 and -0500 are different values with the same Offset. RFC 6350 doesn’t forbid a negative zero, so -00 is valid and differs from +00. vCard 3.0 always writes the minutes.
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.11), an offset has a colon between its hours and minutes: -05:00, or -05 with no minutes. In Xml, the form of xCard (RFC 6351 Appendix A), it is the content of a utc-offset element, in the basic format, such as -0500. 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 |
|---|---|
VcardUtcOffset(bool isNegative, int hours, int? minutes) | Hours from 0 to 23 and minutes from 0 to 59, or null to write only the hours. |
Properties
| Property | Notes |
|---|---|
bool IsNegative, int Hours, int? Minutes | The parts. |
TimeSpan Offset | The offset. Positive offsets are ahead of UTC. |
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.