IcalContentLine Class
Definition
Namespace: DataStandardizer.File.iCal
A content line (RFC 5545 §3.1): a property name, its parameters and its value. This is the allocating, immutable form of a line. It is what IcalContentLineReader.ReadLine returns and IcalContentLineWriter.WriteLine takes, and every property of an IcalComponent is held as one.
Syntax
public sealed class IcalContentLine
Remarks
Values. Value is the value as it appears in the content line once unfolded. TEXT escaping is left in place, because whether it applies depends on the value type. Call GetTextValue for a single TEXT value. When you build a line yourself, pass the value already escaped.
Parameters. Parameters holds the decoded parameter values: RFC 6868 caret encoding removed, and enclosing double quotes removed. A line read by IcalContentLineReader also keeps its parameters exactly as they appeared in the source, and IcalContentLineWriter writes that original text, so a line read and written back keeps its quoting and caret encoding. A line you build, or one converted from xCal or jCal, has its parameters encoded afresh when written.
Validation. The constructors check only for null. Names and characters are checked when the line is written: IcalContentLineWriter throws IcalFileException for a name that is not one or more letters, digits or hyphens, or for a control character (other than tab) or lone surrogate in the value.
Line numbers. LineNumber and PhysicalLineNumber record where a line read from .ics data came from. A line read by XcalReader has the line of the XML document as its LineNumber and 0 as its PhysicalLineNumber. A line read by JcalReader, or built in code, has 0 for both.
Thread safety. Instances are immutable, so they may be shared between threads.
Constructors
| Constructor | Notes |
|---|---|
IcalContentLine(string name, string value) | A line with no parameters. value is as it appears in the content line, with any TEXT escaping in place. Throws ArgumentNullException if name or value is null. |
IcalContentLine(string name, IEnumerable<IcalContentLineParameter> parameters, string value) | The parameters are copied, in order. Throws ArgumentNullException if name, parameters or value is null, or ArgumentException if parameters contains null. |
Properties
| Property | Signature | Notes |
|---|---|---|
LineNumber | long LineNumber { get; } | The 1-based number of the logical (unfolded) line this was read from, or 0 if it was not read from a source. For xCal, the line of the XML document. |
Name | string Name { get; } | The property name, as written. Property names are case-insensitive. |
Parameters | IReadOnlyList<IcalContentLineParameter> Parameters { get; } | The parameters, in the order they appear. The list is read-only: it can’t be cast to an array or a writable list and changed. |
PhysicalLineNumber | long PhysicalLineNumber { get; } | The 1-based number of the physical line on which this line starts in its .ics source, or 0 if it was not read from .ics data. |
Value | string Value { get; } | The value as it appears in the content line once unfolded, with TEXT escaping left in place. |
Methods
| Method | Returns | Notes |
|---|---|---|
GetParameter(string name) | IcalContentLineParameter? | The first parameter with that name, compared case-insensitively (ordinal), or null if there is none. Throws ArgumentNullException if name is null. |
GetFormatType() | MimeMediaType? | The media type in the FMTTYPE parameter (RFC 5545 §3.2.8), or null if there is none. The value must be a type and subtype whose names follow RFC 4288 §4.2, so it can’t have media type parameters. Throws IcalFileException if the line has more than one FMTTYPE parameter, or the parameter has more than one value or a value that isn’t valid; its Data holds LineNumber, PhysicalLineNumber and PropertyName. To read a value that doesn’t follow this, use GetParameter. A value in double quotes gives the same media type, though RFC 5545 §3.2.8 has no quoted form; IcalReader and IcalWriter reject one unless IcalOptions.AllowQuotedParameterValues is set. |
GetTextValue() | string | The value with RFC 5545 §3.3.11 TEXT escaping removed: \\, \; and \, become the escaped character, and \n or \N a line feed. Returns Value itself when it holds no backslash. Use it only for a single TEXT value; for a list of TEXT values or REQUEST-STATUS, split Value on its unescaped commas or semicolons first. Throws IcalFileException if a backslash does not start a valid escape sequence, or a comma or semicolon is not escaped; its Data holds LineNumber, PhysicalLineNumber (the physical line of the bad escape or the comma or semicolon) and PropertyName. |
Applies to
Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0. The nullable reference annotations apply to the netstandard2.1 and net10.0 builds.