ImfPhraseList Class

Definition

Namespace: DataStandardizer.File.InternetMessage

An ordered, read-only list of phrases, as in a Keywords header field (RFC 5322 §3.6.5).

Syntax

public sealed class ImfPhraseList : IEquatable<ImfPhraseList>, IReadOnlyList<string>

Remarks

Each element holds the words of one phrase, separated by a space. The empty elements of the obsolete form (RFC 5322 §4.1) are not kept, and that form allows no phrases at all, so a parsed list can be empty. The modern form needs at least one, so an empty list formats as an empty string.

Each element holds the text of any RFC 2047 encoded words in the phrase (RFC 2047 §5(3)), and a quoted-string of that form stays plain text. A word that can’t be decoded stays as written (RFC 2047 §6.2), as ImfOptions.AllowMalformedEncodedWords describes. Decoded text can hold anything that the words encode, including control characters and line breaks, so check it before using it where those matter.

Constructors

Constructor Notes
ImfPhraseList(IEnumerable<string> phrases) Initializes a new list. Throws ArgumentNullException: phrases is null. Throws ArgumentException: phrases is empty, as RFC 5322 §3.6.5 needs at least one phrase, holds a null element, or holds one with a control character other than tab or an unpaired surrogate.

Properties

Property Signature Notes
Count int Count { get; } The number of items.
this[] string this[int index] { get; } The item at an index.

Methods

Method Returns Notes
Equals(ImfPhraseList? other) bool Indicates whether this list equals another: it has the same phrases in the same order, compared case-sensitively as text, so =?UTF-8?Q?a?= and a are equal.
GetEnumerator() IEnumerator<string> Gets an enumerator over the items.
static Parse(string value) ImfPhraseList Parses a list of phrases. Returns: The list. value: The list, which may be folded, such as first, "second one". Throws ArgumentNullException: value is null. Throws FormatException: The value is not a valid list of phrases.
static Parse(ReadOnlySpan<byte> value) ImfPhraseList Parses a list of phrases. Returns: The list. value: The list as UTF-8 (RFC 6532), which may be folded, such as first, "second one". Throws FormatException: The value is not a valid list of phrases.
static Parse(string value, ImfOptions options) ImfPhraseList Parses a phrase list. Returns: The phrase list. value: The phrase list, which may be folded, such as first, "second one". options: The options, of which this uses ImfOptions.AllowMalformedEncodedWords and ImfOptions.CharsetResolver. Throws ArgumentNullException: value or options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved. Throws FormatException: The value is not a valid phrase list.
static Parse(ReadOnlySpan<byte> value, ImfOptions options) ImfPhraseList Parses a phrase list. Returns: The phrase list. value: The phrase list, which may be folded, such as first, "second one". Bytes that aren’t valid UTF-8 are decoded with ImfOptions.HeaderFallbackCharset before any encoded word is read, if ImfOptions.AllowEightBitHeaders is true. options: The options, of which this uses ImfOptions.AllowEightBitHeaders, ImfOptions.AllowMalformedEncodedWords, ImfOptions.CharsetResolver and ImfOptions.HeaderFallbackCharset. Throws ArgumentNullException: options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved. Throws FormatException: The value is not a valid phrase list.
ToString() string Formats the list in the modern form, such as first, "second one". An encoded word stays as it was read, and any other text is written as it is, which may be UTF-8. A word right next to a period is the exception: the phrase is written as new encoded words, as only the obsolete form could keep it. Use ToString(ImfHeaderEncoding) to choose. Returns: The list.
ToString(ImfHeaderEncoding encoding) string Formats the list in the modern form, for a writer with the given header encoding. With ImfHeaderEncoding.EncodedWords, a phrase that isn’t US-ASCII is written as RFC 2047 encoded words, in UTF-8, whatever form it was read in. With ImfHeaderEncoding.Utf8, it is written as UTF-8 (RFC 6532), and an encoded word that was read is written as its text. A control character in a phrase has no form that can be written here, so it is left out. Returns: The list, unfolded. Throws ArgumentOutOfRangeException: encoding is not an ImfHeaderEncoding member.
static TryParse(string? value, out ImfPhraseList? result) bool Parses a list of phrases. Returns: true if the value is a valid list of phrases; otherwise false, including for null. value: The list, which may be folded, such as first, "second one".
static TryParse(ReadOnlySpan<byte> value, out ImfPhraseList? result) bool Parses a list of phrases. Returns: true if the value is a valid list of phrases; otherwise false. value: The list as UTF-8 (RFC 6532), which may be folded, such as first, "second one".
static TryParse(string? value, ImfOptions options, out ImfPhraseList? result) bool Parses a phrase list. Returns: true if the value is a valid phrase list; otherwise false, including for null. value: The phrase list, which may be folded, such as first, "second one". options: The options, of which this uses ImfOptions.AllowMalformedEncodedWords and ImfOptions.CharsetResolver. Throws ArgumentNullException: options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved.
static TryParse(ReadOnlySpan<byte> value, ImfOptions options, out ImfPhraseList? result) bool Parses a phrase list. Returns: true if the value is a valid phrase list; otherwise false. value: The phrase list, which may be folded, such as first, "second one". Bytes that aren’t valid UTF-8 are decoded with ImfOptions.HeaderFallbackCharset before any encoded word is read, if ImfOptions.AllowEightBitHeaders is true. options: The options, of which this uses ImfOptions.AllowEightBitHeaders, ImfOptions.AllowMalformedEncodedWords, ImfOptions.CharsetResolver and ImfOptions.HeaderFallbackCharset. Throws ArgumentNullException: options is null. Throws ArgumentException: options has no ImfOptions.CharsetResolver, or a ImfOptions.HeaderFallbackCharset that is needed and can’t be resolved.

Operators

Operator Returns Notes
operator !=(ImfPhraseList? left, ImfPhraseList? right) bool Indicates whether two lists differ.
operator ==(ImfPhraseList? left, ImfPhraseList? right) bool Indicates whether two lists are equal.

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.

See also


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