Table of Contents

Struct DynamoDbReader

Namespace
DynaSharp.Serialization
Assembly
DynaSharp.dll

Reads DynamoDB JSON: attribute values in their typed form, such as {"S":"abc"}, and items, which are JSON objects that map attribute names to attribute values.

public ref struct DynamoDbReader
Inherited Members

Remarks

This is the only code that parses DynamoDB JSON. AttributeValue, entities mapped by the source generator and custom converters (IDynamoDbConverter<T>) all read through it.

The reader is a cursor over the JSON tokens. Every Read* and TryRead* method first advances, then checks the token it arrived at; the Get* methods return the value at the current position without moving. An attribute value is read with ReadStartAttribute() (consumes { and the type descriptor and stops on the value), a getter or the elements of a list, map or set, and ReadEndAttribute() (consumes }): 

reader.ReadStartItem();
while (reader.TryReadAttributeName())
{
    if (reader.AttributeNameEquals("pk"u8))
    {
        var type = reader.ReadStartAttribute();   // positioned on the value
        pk = reader.GetString();                   // after checking type == AttributeType.String
        reader.ReadEndAttribute();
    }
    else
    {
        reader.SkipAttributeValue();
    }
}

JSON that does not have the shape of DynamoDB JSON, for example an unknown type descriptor or a value of the wrong JSON kind, throws JsonException. Escaped JSON text (\u0041) is handled everywhere. The getters do not know the attribute type: checking it is up to the caller.

DynaSharp passes instances to converters by reference.

Constructors

DynamoDbReader(ReadOnlySpan<byte>)

Initializes a new instance of the DynamoDbReader struct over complete JSON. DynaSharp creates readers for its own responses; use this to test a custom converter.

public DynamoDbReader(ReadOnlySpan<byte> utf8Json)

Parameters

utf8Json ReadOnlySpan<byte>

The JSON as UTF-8. It must stay valid while the reader is used.

Methods

AttributeNameEquals(ReadOnlySpan<byte>)

Compares the attribute name the reader is positioned on with a UTF-8 name, ordinally.

public readonly bool AttributeNameEquals(ReadOnlySpan<byte> utf8Name)

Parameters

utf8Name ReadOnlySpan<byte>

The name to compare with, typically a literal such as "pk"u8.

Returns

bool

true if the names are equal; escaped names compare by their unescaped text.

Exceptions

InvalidOperationException

The reader is not positioned on an attribute name.

GetAttributeName()

Gets the attribute name the reader is positioned on.

public readonly string GetAttributeName()

Returns

string

The unescaped name.

Exceptions

InvalidOperationException

The reader is not positioned on an attribute name.

GetAttributeNameUtf8()

Gets the attribute name the reader is positioned on as UTF-8, to compare it with known names without creating a string.

public readonly ReadOnlySpan<byte> GetAttributeNameUtf8()

Returns

ReadOnlySpan<byte>

The unescaped name. For a name without escape sequences, which is the normal case, this is a view of the input, valid until the reader moves on. A name with escapes (A) is unescaped into a new array.

Exceptions

InvalidOperationException

The reader is not positioned on an attribute name.

GetBinary()

Decodes a binary value (B) or binary set element from base64.

public readonly byte[] GetBinary()

Returns

byte[]

The bytes, a new array.

Exceptions

InvalidOperationException

The reader is not positioned on a JSON string.

JsonException

The text is not valid base64.

GetBool()

Gets the boolean of a boolean value (BOOL).

public readonly bool GetBool()

Returns

bool

The boolean.

Exceptions

InvalidOperationException

The reader is not positioned on a JSON boolean.

GetNumberText()

Gets the text of a number value (N) or number set element, exactly as transferred.

public readonly string GetNumberText()

Returns

string

The number as text. Use it for numbers beyond the range or precision of .NET types (up to 38 digits).

Exceptions

InvalidOperationException

The reader is not positioned on a JSON string.

GetNumber<T>()

Parses a number value (N) or number set element with the invariant culture.

public readonly T GetNumber<T>() where T : INumberBase<T>

Returns

T

The number. Exponent notation such as 1E+2 is accepted, also for integer types.

Type Parameters

T

The target number type.

Exceptions

InvalidOperationException

The reader is not positioned on a JSON string.

FormatException

The text is not a number.

OverflowException

The number is outside the range of T, has a fractional part and T is an integer type, or T is decimal and cannot hold its exact value, which takes 28 to 29 significant digits at most, where DynamoDB has 38. A binary floating-point type counts a number that rounds to infinity, and NaN, as out of range; it rounds any other number to the nearest value it holds, and one below its range reads as 0.

GetString()

Gets the string of a string value (S) or string set element.

public readonly string GetString()

Returns

string

The unescaped string.

Exceptions

InvalidOperationException

The reader is not positioned on a JSON string.

GetStringUtf8()

Gets the string of a string value (S) or string set element as UTF-8, to parse or compare it without creating a string.

public readonly ReadOnlySpan<byte> GetStringUtf8()

Returns

ReadOnlySpan<byte>

The unescaped text. For a string without escape sequences, which is the normal case, this is a view of the input, valid until the reader moves on. A string with escapes is unescaped into a new array.

Exceptions

InvalidOperationException

The reader is not positioned on a JSON string.

ReadAttribute<T, TConverter>()

Reads a complete attribute value of a known converter: the start, the value and the end.

public T ReadAttribute<T, TConverter>() where TConverter : IDynamoDbConverter<T>

Returns

T

The value.

Type Parameters

T

The .NET type of the value.

TConverter

The converter that reads the value, called directly through the type parameter.

Remarks

Call it after TryReadAttributeName() returned true and the name was recognized. The value is {"NULL":true} for a null that TConverter accepts, see NullableConverter<T, TConverter>.

Exceptions

JsonException

The attribute value is malformed, or TConverter does not support its type.

ReadEndAttribute()

Reads the end of an attribute value (}).

public void ReadEndAttribute()

Exceptions

JsonException

The next token is not the end of an object.

ReadStartAttribute()

Reads the start of an attribute value ({) and its type descriptor, and stops on the value.

public AttributeType ReadStartAttribute()

Returns

AttributeType

The type of the value. Read the value accordingly, then call ReadEndAttribute().

Exceptions

JsonException

The next token is not the start of an object, the type descriptor is unknown, or the value does not match the type (for example a list that is not a JSON array, or {"NULL":false}).

ReadStartItem()

Reads the start of an item ({), a plain JSON object of attribute names and values.

public void ReadStartItem()

Remarks

Then read the attributes with TryReadAttributeName(), which returns false at the end of the item.

Exceptions

JsonException

The next token is not the start of an object.

SkipAttributeValue()

Skips the next attribute value as a whole, including its braces: the value of the attribute name the reader is positioned on, or the next list element. Use it for attributes the caller does not know.

public void SkipAttributeValue()

Exceptions

JsonException

The next token is not the start of an object.

TryReadAttributeName()

Reads the next attribute name in an item or map, or the end of the item or map.

public bool TryReadAttributeName()

Returns

bool

true when positioned on an attribute name; read its value next, or skip it with SkipAttributeValue(). false at the end of the item or map (}), which is consumed.

Exceptions

JsonException

The next token is neither an attribute name nor the end of an object.

TryReadAttribute<T, TConverter>(out T)

Reads a complete attribute value of a known converter, or skips it when the converter counts it as missing.

public bool TryReadAttribute<T, TConverter>(out T value) where TConverter : IDynamoDbConverter<T>

Parameters

value T

The value, or the default value when the converter counts it as missing.

Returns

bool

false if CountsAsMissing(in DynamoDbReader, AttributeType) said so, and the reader is past the value either way.

Type Parameters

T

The .NET type of the value.

TConverter

The converter, asked and called directly through the type parameter, which also reaches a member it implements explicitly.

Remarks

Generated code calls this for a property whose converter answers, and ReadAttribute<T, TConverter>() for every other one.

Exceptions

JsonException

The attribute value is malformed, or TConverter does not support its type.

TryReadSetElement()

Reads the next element of a string, number or binary set, or the end of the set.

public bool TryReadSetElement()

Returns

bool

true when positioned on an element; get it with GetString(), GetNumber<T>(), GetNumberText() or GetBinary(). false at the end of the set (]), which is consumed; then call ReadEndAttribute() for the set itself.

Exceptions

JsonException

The next token is neither a JSON string nor the end of an array.

TryReadStartAttribute(out AttributeType)

Reads the start of the next list element and its type descriptor, and stops on the value; or reads the end of the list.

public bool TryReadStartAttribute(out AttributeType type)

Parameters

type AttributeType

The type of the element, or None at the end of the list.

Returns

bool

true when positioned on an element value; read it, then call ReadEndAttribute(). false at the end of the list (]), which is consumed; then call ReadEndAttribute() for the list itself.

Exceptions

JsonException

The next token is neither an attribute value nor the end of an array, or the element is malformed.

TryReadStartItem()

Reads the start of the next item ({) in an array of items, such as Items in a query response, or the end of the array.

public bool TryReadStartItem()

Returns

bool

true when positioned after the { of an item; read its attributes with TryReadAttributeName(), which consumes the closing }. false at the end of the array (]), which is consumed.

Exceptions

JsonException

The next token is neither the start of an item nor the end of an array.