/// Converts the value of this instance to a <see cref="string"/>.
/// </summary>
/// <remarks>
- /// Returns the underlying UTF-16 encoded string.
- /// </remarks>
- /// <remarks>
/// Returns an empty string on a default instance of <see cref="JsonEncodedText"/>.
/// </remarks>
+ /// <returns>
+ /// Returns the underlying UTF-16 encoded string.
+ /// </returns>
public override string ToString()
=> _value ?? string.Empty;
/// </summary>
/// <remarks>
/// For JSON strings (including property names), this points to before the start quote.
- /// </remarks>
- /// <remarks>
/// For comments, this points to before the first comment delimiter (i.e. '/').
/// </remarks>
public long TokenStartIndex { get; private set; }
/// or if the current depth exceeds the recursive limit set by the max depth.
/// </exception>
/// <remarks>
- /// If the reader did not have enough data to completely skip the children of the current token,
- /// it will be reset to the state it was in before the method was called.
- /// </remarks>
- /// <remarks>
- /// When <see cref="TokenType"/> is <see cref="JsonTokenType.PropertyName" />, the reader first moves to the property value.
- /// When <see cref="TokenType"/> (originally, or after advancing) is <see cref="JsonTokenType.StartObject" /> or
- /// <see cref="JsonTokenType.StartArray" />, the reader advances to the matching
- /// <see cref="JsonTokenType.EndObject" /> or <see cref="JsonTokenType.EndArray" />.
+ /// <para>
+ /// If the reader did not have enough data to completely skip the children of the current token,
+ /// it will be reset to the state it was in before the method was called.
+ /// </para>
+ /// <para>
+ /// When <see cref="TokenType"/> is <see cref="JsonTokenType.PropertyName" />, the reader first moves to the property value.
+ /// When <see cref="TokenType"/> (originally, or after advancing) is <see cref="JsonTokenType.StartObject" /> or
+ /// <see cref="JsonTokenType.StartArray" />, the reader advances to the matching
+ /// <see cref="JsonTokenType.EndObject" /> or <see cref="JsonTokenType.EndArray" />.
///
- /// For all other token types, the reader does not move. After the next call to <see cref="Read"/>, the reader will be at
- /// the next value (when in an array), the next property name (when in an object), or the end array/object token.
+ /// For all other token types, the reader does not move. After the next call to <see cref="Read"/>, the reader will be at
+ /// the next value (when in an array), the next property name (when in an object), or the end array/object token.
+ /// </para>
/// </remarks>
public bool TrySkip()
{
/// <seealso cref="TokenType" />
/// </exception>
/// <remarks>
- /// If the look up text is invalid UTF-8 text, the method will return false since you cannot have
- /// invalid UTF-8 within the JSON payload.
- /// </remarks>
- /// <remarks>
- /// The comparison of the JSON token value in the source and the look up text is done by first unescaping the JSON value in source,
- /// if required. The look up text is matched as is, without any modifications to it.
+ /// <para>
+ /// If the look up text is invalid UTF-8 text, the method will return false since you cannot have
+ /// invalid UTF-8 within the JSON payload.
+ /// </para>
+ /// <para>
+ /// The comparison of the JSON token value in the source and the look up text is done by first unescaping the JSON value in source,
+ /// if required. The look up text is matched as is, without any modifications to it.
+ /// </para>
/// </remarks>
public bool ValueTextEquals(ReadOnlySpan<byte> utf8Text)
{
/// <seealso cref="TokenType" />
/// </exception>
/// <remarks>
- /// If the look up text is invalid UTF-8 text, the method will return false since you cannot have
- /// invalid UTF-8 within the JSON payload.
- /// </remarks>
- /// <remarks>
- /// The comparison of the JSON token value in the source and the look up text is done by first unescaping the JSON value in source,
- /// if required. The look up text is matched as is, without any modifications to it.
+ /// <para>
+ /// If the look up text is invalid UTF-8 text, the method will return false since you cannot have
+ /// invalid UTF-8 within the JSON payload.
+ /// </para>
+ /// <para>
+ /// The comparison of the JSON token value in the source and the look up text is done by first unescaping the JSON value in source,
+ /// if required. The look up text is matched as is, without any modifications to it.
+ /// </para>
/// </remarks>
public bool ValueTextEquals(string utf8Text)
{
/// <seealso cref="TokenType" />
/// </exception>
/// <remarks>
- /// If the look up text is invalid or incomplete UTF-16 text (i.e. unpaired surrogates), the method will return false
- /// since you cannot have invalid UTF-16 within the JSON payload.
- /// </remarks>
- /// <remarks>
- /// The comparison of the JSON token value in the source and the look up text is done by first unescaping the JSON value in source,
- /// if required. The look up text is matched as is, without any modifications to it.
+ /// <para>
+ /// If the look up text is invalid or incomplete UTF-16 text (i.e. unpaired surrogates), the method will return false
+ /// since you cannot have invalid UTF-16 within the JSON payload.
+ /// </para>
+ /// <para>
+ /// The comparison of the JSON token value in the source and the look up text is done by first unescaping the JSON value in source,
+ /// if required. The look up text is matched as is, without any modifications to it.
+ /// </para>
/// </remarks>
public bool ValueTextEquals(ReadOnlySpan<char> text)
{
/// This method makes a copy of the data the reader acted on, so there is no caller
/// requirement to maintain data integrity beyond the return of this method.
/// </para>
- /// </remarks>
- /// <remarks>
- /// The <see cref="JsonReaderOptions"/> used to create the instance of the <see cref="Utf8JsonReader"/> take precedence over the <see cref="JsonSerializerOptions"/> when they conflict.
- /// Hence, <see cref="JsonReaderOptions.AllowTrailingCommas"/>, <see cref="JsonReaderOptions.MaxDepth"/>, <see cref="JsonReaderOptions.CommentHandling"/> are used while reading.
+ ///
+ /// <para>
+ /// The <see cref="JsonReaderOptions"/> used to create the instance of the <see cref="Utf8JsonReader"/> take precedence over the <see cref="JsonSerializerOptions"/> when they conflict.
+ /// Hence, <see cref="JsonReaderOptions.AllowTrailingCommas"/>, <see cref="JsonReaderOptions.MaxDepth"/>, <see cref="JsonReaderOptions.CommentHandling"/> are used while reading.
+ /// </para>
/// </remarks>
public static TValue ReadValue<TValue>(ref Utf8JsonReader reader, JsonSerializerOptions options = null)
{
/// This method makes a copy of the data the reader acted on, so there is no caller
/// requirement to maintain data integrity beyond the return of this method.
/// </para>
- /// </remarks>
- /// <remarks>
- /// The <see cref="JsonReaderOptions"/> used to create the instance of the <see cref="Utf8JsonReader"/> take precedence over the <see cref="JsonSerializerOptions"/> when they conflict.
- /// Hence, <see cref="JsonReaderOptions.AllowTrailingCommas"/>, <see cref="JsonReaderOptions.MaxDepth"/>, <see cref="JsonReaderOptions.CommentHandling"/> are used while reading.
+ /// <para>
+ /// The <see cref="JsonReaderOptions"/> used to create the instance of the <see cref="Utf8JsonReader"/> take precedence over the <see cref="JsonSerializerOptions"/> when they conflict.
+ /// Hence, <see cref="JsonReaderOptions.AllowTrailingCommas"/>, <see cref="JsonReaderOptions.MaxDepth"/>, <see cref="JsonReaderOptions.CommentHandling"/> are used while reading.
+ /// </para>
/// </remarks>
public static object ReadValue(ref Utf8JsonReader reader, Type returnType, JsonSerializerOptions options = null)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteString(JsonEncodedText propertyName, DateTime value)
=> WriteStringHelper(propertyName.EncodedUtf8Bytes, value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(string propertyName, DateTime value)
=> WriteString(propertyName.AsSpan(), value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(ReadOnlySpan<char> propertyName, DateTime value)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTime"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(ReadOnlySpan<byte> utf8PropertyName, DateTime value)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteString(JsonEncodedText propertyName, DateTimeOffset value)
=> WriteStringHelper(propertyName.EncodedUtf8Bytes, value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(string propertyName, DateTimeOffset value)
=> WriteString(propertyName.AsSpan(), value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(ReadOnlySpan<char> propertyName, DateTimeOffset value)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="DateTimeOffset"/> using the round-trippable ('O') <see cref="StandardFormat"/> , for example: 2017-06-12T05:30:45.7680000-07:00.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(ReadOnlySpan<byte> utf8PropertyName, DateTimeOffset value)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="decimal"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteNumber(JsonEncodedText propertyName, decimal value)
=> WriteNumberHelper(propertyName.EncodedUtf8Bytes, value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="decimal"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(string propertyName, decimal value)
=> WriteNumber(propertyName.AsSpan(), value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="decimal"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<char> propertyName, decimal value)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="decimal"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, decimal value)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="double"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteNumber(JsonEncodedText propertyName, double value)
=> WriteNumberHelper(propertyName.EncodedUtf8Bytes, value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="double"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(string propertyName, double value)
=> WriteNumber(propertyName.AsSpan(), value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="double"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<char> propertyName, double value)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="double"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, double value)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="float"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteNumber(JsonEncodedText propertyName, float value)
=> WriteNumberHelper(propertyName.EncodedUtf8Bytes, value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="float"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(string propertyName, float value)
=> WriteNumber(propertyName.AsSpan(), value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="float"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<char> propertyName, float value)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="float"/> using the default <see cref="StandardFormat"/> (i.e. 'G').
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, float value)
{
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="utf8FormattedNumber">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="long"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
internal void WriteNumber(ReadOnlySpan<char> propertyName, ReadOnlySpan<byte> utf8FormattedNumber)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="utf8FormattedNumber">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="long"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
internal void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, ReadOnlySpan<byte> utf8FormattedNumber)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="Guid"/> using the default <see cref="StandardFormat"/> (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn.
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteString(JsonEncodedText propertyName, Guid value)
=> WriteStringHelper(propertyName.EncodedUtf8Bytes, value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="Guid"/> using the default <see cref="StandardFormat"/> (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(string propertyName, Guid value)
=> WriteString(propertyName.AsSpan(), value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="Guid"/> using the default <see cref="StandardFormat"/> (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(ReadOnlySpan<char> propertyName, Guid value)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON string as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="Guid"/> using the default <see cref="StandardFormat"/> (i.e. 'D'), as the form: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteString(ReadOnlySpan<byte> utf8PropertyName, Guid value)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="long"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteNumber(JsonEncodedText propertyName, long value)
=> WriteNumberHelper(propertyName.EncodedUtf8Bytes, value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="long"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(string propertyName, long value)
=> WriteNumber(propertyName.AsSpan(), value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="long"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<char> propertyName, long value)
{
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="long"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, long value)
{
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="int"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
public void WriteNumber(JsonEncodedText propertyName, int value)
=> WriteNumber(propertyName, (long)value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="int"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(string propertyName, int value)
=> WriteNumber(propertyName.AsSpan(), (long)value);
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="int"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<char> propertyName, int value)
=> WriteNumber(propertyName, (long)value);
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="int"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
public void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, int value)
=> WriteNumber(utf8PropertyName, (long)value);
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="ulong"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(JsonEncodedText propertyName, ulong value)
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="ulong"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(string propertyName, ulong value)
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="ulong"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(ReadOnlySpan<char> propertyName, ulong value)
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="ulong"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, ulong value)
/// </summary>
/// <param name="propertyName">The JSON encoded property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
- /// </remarks>
/// <exception cref="InvalidOperationException">
/// Thrown if this would result in an invalid JSON to be written (while validation is enabled).
/// </exception>
/// <remarks>
/// Writes the <see cref="uint"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name should already be escaped when the instance of <see cref="JsonEncodedText"/> was created.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(JsonEncodedText propertyName, uint value)
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="uint"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(string propertyName, uint value)
/// </summary>
/// <param name="propertyName">The property name of the JSON object to be transcoded and written as UTF-8.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="uint"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(ReadOnlySpan<char> propertyName, uint value)
/// </summary>
/// <param name="utf8PropertyName">The UTF-8 encoded property name of the JSON object to be written.</param>
/// <param name="value">The value to be written as a JSON number as part of the name/value pair.</param>
- /// <remarks>
- /// The property name is escaped before writing.
- /// </remarks>
/// <exception cref="ArgumentException">
/// Thrown when the specified property name is too large.
/// </exception>
/// </exception>
/// <remarks>
/// Writes the <see cref="uint"/> using the default <see cref="StandardFormat"/> (i.e. 'G'), for example: 32767.
+ /// The property name is escaped before writing.
/// </remarks>
[CLSCompliant(false)]
public void WriteNumber(ReadOnlySpan<byte> utf8PropertyName, uint value)
/// Provides a high-performance API for forward-only, non-cached writing of UTF-8 encoded JSON text.
/// </summary>
/// <remarks>
- /// It writes the text sequentially with no caching and adheres to the JSON RFC
- /// by default (https://tools.ietf.org/html/rfc8259), with the exception of writing comments.
- /// </remarks>
- /// <remarks>
- /// When the user attempts to write invalid JSON and validation is enabled, it throws
- /// an <see cref="InvalidOperationException"/> with a context specific error message.
- /// </remarks>
- /// <remarks>
- /// To be able to format the output with indentation and whitespace OR to skip validation, create an instance of
- /// <see cref="JsonWriterOptions"/> and pass that in to the writer.
+ /// <para>
+ /// It writes the text sequentially with no caching and adheres to the JSON RFC
+ /// by default (https://tools.ietf.org/html/rfc8259), with the exception of writing comments.
+ /// </para>
+ /// <para>
+ /// When the user attempts to write invalid JSON and validation is enabled, it throws
+ /// an <see cref="InvalidOperationException"/> with a context specific error message.
+ /// </para>
+ /// <para>
+ /// To be able to format the output with indentation and whitespace OR to skip validation, create an instance of
+ /// <see cref="JsonWriterOptions"/> and pass that in to the writer.
+ /// </para>
/// </remarks>
[DebuggerDisplay("{DebuggerDisplay,nq}")]
public sealed partial class Utf8JsonWriter : IDisposable, IAsyncDisposable
/// Commits any left over JSON text that has not yet been flushed and releases all resources used by the current instance.
/// </summary>
/// <remarks>
- /// In the case of IBufferWriter, this advances the underlying <see cref="IBufferWriter{Byte}" /> based on what has been written so far.
- /// In the case of Stream, this writes the data to the stream and flushes it.
- /// </remarks>
- /// <remarks>
- /// The <see cref="Utf8JsonWriter"/> instance cannot be re-used after disposing.
+ /// <para>
+ /// In the case of IBufferWriter, this advances the underlying <see cref="IBufferWriter{Byte}" /> based on what has been written so far.
+ /// In the case of Stream, this writes the data to the stream and flushes it.
+ /// </para>
+ /// <para>
+ /// The <see cref="Utf8JsonWriter"/> instance cannot be re-used after disposing.
+ /// </para>
/// </remarks>
public void Dispose()
{
/// Asynchronously commits any left over JSON text that has not yet been flushed and releases all resources used by the current instance.
/// </summary>
/// <remarks>
- /// In the case of IBufferWriter, this advances the underlying <see cref="IBufferWriter{Byte}" /> based on what has been written so far.
- /// In the case of Stream, this writes the data to the stream and flushes it.
- /// </remarks>
- /// <remarks>
- /// The <see cref="Utf8JsonWriter"/> instance cannot be re-used after disposing.
+ /// <para>
+ /// In the case of IBufferWriter, this advances the underlying <see cref="IBufferWriter{Byte}" /> based on what has been written so far.
+ /// In the case of Stream, this writes the data to the stream and flushes it.
+ /// </para>
+ /// <para>
+ /// The <see cref="Utf8JsonWriter"/> instance cannot be re-used after disposing.
+ /// </para>
/// </remarks>
public async ValueTask DisposeAsync()
{
projects / platform / upstream / dotnet / runtime.git / commitdiff