Struct SetArrayConverter<T, TElement>

Namespace

DynaSharp.Serialization

Assembly

DynaSharp.dll

Converts T[] to and from a string set, number set or binary set, as TElement says. It is opt-in, with [DynamoDbConverter] on the property, since an array is a list by default.

public readonly struct SetArrayConverter<T, TElement> : IDynamoDbConverter<T[]>, IAddableConverter where TElement : IDynamoDbSetElementConverter<T>

Type Parameters

T

The element type.

TElement

The converter of the elements, which also decides the kind of set.

Implements

IDynamoDbConverter<T[]>

IAddableConverter

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

An array is much lighter than a HashSet<T>: a string[] of three elements takes about 48 bytes against about 176 for a set. The price is that the array does not stop duplicates: ["x", "x"] writes {"SS":["x","x"]}. DynamoDB rejects a set with duplicates (for numbers, with numerically equal elements) with a validation error, so the code that fills the array must keep its elements distinct. See HashSetConverter<T, TElement> for the other rules of sets, such as the empty set.

The array that is read has exactly the length of the set, in the order the service sent, which is not a stable order.

TElement is an IDynamoDbSetElementConverter<T>, which writes one element of a set, and not the converter of the type, which writes a whole attribute. The built-in ones are StringSetElement for a string[], NumberSetElement<T> for an array of numbers, BinarySetElement for a byte[][] and GuidSetElement for a Guid[]. A set of strings is [DynamoDbConverter(typeof(SetArrayConverter<string, StringSetElement>))] public string[] Tags { get; init; } = [];. StringConverter is not an element converter, so SetArrayConverter<string, StringConverter> does not compile: CS0315 on the constraint of TElement.

A converter of your own may call it, for a List<T> stored as a set, say: this one is no infrastructure.

Explicit Interface Implementations

Read(ref DynamoDbReader, AttributeType)

Reads the attribute value the reader is positioned on.

static T[] Read(ref DynamoDbReader reader, AttributeType type)

Parameters

reader DynamoDbReader

The reader, positioned on the value after ReadStartAttribute() or TryReadStartAttribute(out AttributeType). The caller reads the closing brace afterwards, so the converter must read the value completely (all elements of a list, map or set) and nothing more.

type AttributeType

The DynamoDB type of the value. Check it with Expect(AttributeType, AttributeType), which throws JsonException for types the converter does not support. Null is passed to the converter too, so it can map it to null where that makes sense.

Returns

T[]

The value.

Exceptions

JsonException

type is not the kind of set TElement reads, or an element fails to read.

TryReadMissing(out T[])

Finds out what a read of one attribute gives when the item does not have it. No value is the answer for most types, and the read then throws DynamoDbMappingException rather than make one up. A nullable type answers with null, because null is left out on write, and a set with an empty set, because DynamoDB has none.

static bool TryReadMissing(out T[] value)

Parameters

value T[]

The value, if there is one.

Returns

bool

true if a missing attribute has a value of this type.

Remarks

This is infrastructure of Select, which alone asks it, and the built-in converters and the generated handle of a version with Allow answer for themselves. A converter of your own needs it in one case: a converter of a set, because an empty set is a missing attribute in DynamoDB, so without an answer here a Select throws for every item whose set is empty. A read of the entity does not ask this: a property with a converter of your own keeps its initial value, or throws if it is required.

Write(DynamoDbWriter, T[])

Writes a value as one complete attribute value, for example with WriteNumber<T>(T).

static void Write(DynamoDbWriter writer, T[] value)

Parameters

writer DynamoDbWriter

The writer, positioned where a value is expected (after an attribute name, or inside a list). It is a ref struct, so it is never null and needs no check.

value T[]

The value.

Exceptions

ArgumentNullException

value is null.

InvalidOperationException

TElement does not return a set type from SetType.