/// <summary>
/// Write the provided string using the specified encoding type using the specified
/// tag corresponding to the encoding type.
/// </summary>
/// <param name="encodingType">
/// One of the enumeration values representing the encoding to use.
/// </param>
/// <param name="str">The string to write.</param>
/// <param name="tag">
/// The tag to write, or <see langword="null"/> for the universal tag that is appropriate to
/// the requested encoding type.
/// </param>
/// <exception cref="ArgumentOutOfRangeException">
/// <paramref name="encodingType"/> is not a restricted character string encoding type.
///
/// -or-
///
/// <paramref name="encodingType"/> is a restricted character string encoding type that is not
/// currently supported by this method.
/// </exception>
/// <exception cref="ArgumentException">
/// <paramref name="tag"/>.<see cref="Asn1Tag.TagClass"/> is
/// <see cref="TagClass.Universal"/>, but
/// <paramref name="tag"/>.<see cref="Asn1Tag.TagValue"/> is not correct for
/// the method.
/// </exception>
public void WriteCharacterString(UniversalTagNumber encodingType, ReadOnlySpan <char> str, Asn1Tag?tag = null)
{
CheckUniversalTag(tag, encodingType);
Text.Encoding encoding = AsnCharacterStringEncodings.GetEncoding(encodingType);
WriteCharacterStringCore(tag ?? new Asn1Tag(encodingType), encoding, str);
}
/// <summary>
/// Reads the next value as character string with the specified tag and
/// encoding type, returning the decoded string.
/// </summary>
/// <param name="source">The buffer containing encoded data.</param>
/// <param name="ruleSet">The encoding constraints to use when interpreting the data.</param>
/// <param name="encodingType">
/// One of the enumeration values which represents the value type to process.
/// </param>
/// <param name="bytesConsumed">
/// When this method returns, the total number of bytes for the encoded value.
/// This parameter is treated as uninitialized.
/// </param>
/// <param name="expectedTag">
/// The tag to check for before reading, or <see langword="null"/> for the universal tag that is
/// appropriate to the requested encoding type.
/// </param>
/// <returns>
/// The decoded value.
/// </returns>
/// <exception cref="ArgumentOutOfRangeException">
/// <paramref name="ruleSet"/> is not defined.
///
/// -or-
///
/// <paramref name="encodingType"/> is not a known character string type.
/// </exception>
/// <exception cref="AsnContentException">
/// the next value does not have the correct tag.
///
/// -or-
///
/// the length encoding is not valid under the current encoding rules.
///
/// -or-
///
/// the contents are not valid under the current encoding rules.
///
/// -or-
///
/// the string did not successfully decode.
/// </exception>
/// <exception cref="ArgumentException">
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
/// <see cref="TagClass.Universal"/>, but
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagValue"/> is not the same as
/// <paramref name="encodingType"/>.
/// </exception>
/// <seealso cref="TryReadPrimitiveCharacterStringBytes"/>
/// <seealso cref="TryReadCharacterStringBytes"/>
/// <seealso cref="TryReadCharacterString"/>
public static string ReadCharacterString(
ReadOnlySpan <byte> source,
AsnEncodingRules ruleSet,
UniversalTagNumber encodingType,
out int bytesConsumed,
Asn1Tag?expectedTag = null)
{
Text.Encoding encoding = AsnCharacterStringEncodings.GetEncoding(encodingType);
return(ReadCharacterStringCore(
source,
ruleSet,
expectedTag ?? new Asn1Tag(encodingType),
encodingType,
encoding,
out bytesConsumed));
}
/// <summary>
/// Reads a character string value from <paramref name="source"/> with a specified tag under
/// the specified encoding rules, copying the decoded string into a a provided destination buffer.
/// </summary>
/// <param name="source">The buffer containing encoded data.</param>
/// <param name="destination">The buffer in which to write.</param>
/// <param name="ruleSet">The encoding constraints to use when interpreting the data.</param>
/// <param name="encodingType">
/// One of the enumeration values which represents the value type to process.
/// </param>
/// <param name="bytesConsumed">
/// When this method returns, the total number of bytes for the encoded value.
/// This parameter is treated as uninitialized.
/// </param>
/// <param name="charsWritten">
/// When this method returns, the number of chars written to <paramref name="destination"/>.
/// This parameter is treated as uninitialized.
/// </param>
/// <param name="expectedTag">
/// The tag to check for before reading, or <see langword="null"/> for the universal tag that is
/// appropriate to the requested encoding type.
/// </param>
/// <returns>
/// <see langword="true"/> and advances the reader if <paramref name="destination"/> had sufficient
/// length to receive the value, otherwise
/// <see langword="false"/> and the reader does not advance.
/// </returns>
/// <exception cref="ArgumentOutOfRangeException">
/// <paramref name="ruleSet"/> is not defined.
///
/// -or-
///
/// <paramref name="encodingType"/> is not a known character string type.
/// </exception>
/// <exception cref="AsnContentException">
/// the next value does not have the correct tag.
///
/// -or-
///
/// the length encoding is not valid under the current encoding rules.
///
/// -or-
///
/// the contents are not valid under the current encoding rules.
///
/// -or-
///
/// the string did not successfully decode.
/// </exception>
/// <exception cref="ArgumentException">
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagClass"/> is
/// <see cref="TagClass.Universal"/>, but
/// <paramref name="expectedTag"/>.<see cref="Asn1Tag.TagValue"/> is not the same as
/// <paramref name="encodingType"/>.
/// </exception>
/// <seealso cref="TryReadPrimitiveCharacterStringBytes"/>
/// <seealso cref="ReadCharacterString"/>
public static bool TryReadCharacterString(
ReadOnlySpan <byte> source,
Span <char> destination,
AsnEncodingRules ruleSet,
UniversalTagNumber encodingType,
out int bytesConsumed,
out int charsWritten,
Asn1Tag?expectedTag = null)
{
Text.Encoding encoding = AsnCharacterStringEncodings.GetEncoding(encodingType);
return(TryReadCharacterStringCore(
source,
ruleSet,
expectedTag ?? new Asn1Tag(encodingType),
encodingType,
encoding,
destination,
out bytesConsumed,
out charsWritten));
}