You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
/// Marks a struct as unique for content generation. When applied to structs used in <see cref="IContent{T}"/> implementations,
5
+
/// the source generator will override the record struct's default equality behavior to use array index-based comparison
6
+
/// instead of comparing all properties.
7
+
/// </summary>
8
+
/// <remarks>
9
+
/// <para>
10
+
/// The <see cref="UniqueAttribute"/> should be applied to record structs that represent content items in arrays
11
+
/// where position determines identity. This is particularly useful for static content resources where:
12
+
/// </para>
13
+
/// <list type="bullet">
14
+
/// <item><description>The struct's position in the content array uniquely identifies it</description></item>
15
+
/// <item><description>Performance-critical equality comparisons are needed (O(1) instead of O(n))</description></item>
16
+
/// <item><description>The struct is used as a key in collections or lookups</description></item>
17
+
/// <item><description>The struct is used as a key in <see cref="ISubContent{TKey, TValue}"/> implementations</description></item>
18
+
/// </list>
19
+
/// <para>
20
+
/// When this attribute is present, the source generator creates:
21
+
/// </para>
22
+
/// <list type="number">
23
+
/// <item><description>A static dictionary mapping struct names to their array indices</description></item>
24
+
/// <item><description>Custom <see cref="object.Equals(object)"/> and <see cref="object.GetHashCode"/> implementations that use the array index</description></item>
25
+
/// <item><description>Optimized implementation based on whether the struct is declared as readonly</description></item>
26
+
/// </list>
27
+
/// <para>
28
+
/// <strong>Performance Benefits:</strong>
29
+
/// </para>
30
+
/// <list type="bullet">
31
+
/// <item><description>Equality comparison: O(1) integer comparison vs O(n) property comparison</description></item>
/// <item><description>Dictionary/HashSet operations: Significantly faster lookups and insertions</description></item>
34
+
/// <item><description><strong>ISubContent optimization:</strong> When used as keys in <see cref="ISubContent{TKey, TValue}.ByKey"/> dictionaries, provides dramatically improved performance for dictionary operations due to optimized hashing and equality</description></item>
35
+
/// </list>
36
+
/// <para>
37
+
/// <strong>Readonly vs Non-Readonly Optimization:</strong>
38
+
/// </para>
39
+
/// <list type="bullet">
40
+
/// <item><description><strong>Readonly structs:</strong> Direct dictionary lookup on each access, eliminates defensive copying</description></item>
41
+
/// <item><description><strong>Non-readonly structs:</strong> Cached index lookup for repeated operations, potential defensive copying</description></item>
/// When structs marked with <see cref="UniqueAttribute"/> are used as keys in <see cref="ISubContent{TKey, TValue}"/>
48
+
/// implementations, the performance improvement is substantial:
49
+
/// </para>
50
+
/// <list type="bullet">
51
+
/// <item><description><strong>Dictionary.TryGetValue():</strong> Much faster key lookup due to optimized hash codes</description></item>
52
+
/// <item><description><strong>Dictionary.Add():</strong> Faster insertion with reduced hash collisions</description></item>
53
+
/// <item><description><strong>Dictionary enumeration:</strong> More predictable performance due to consistent hashing</description></item>
54
+
/// <item><description><strong>Memory efficiency:</strong> Reduced memory allocation from fewer hash collisions and bucket redistributions</description></item>
55
+
/// </list>
56
+
/// <para>
57
+
/// <strong>Usage Requirements:</strong>
58
+
/// </para>
59
+
/// <list type="bullet">
60
+
/// <item><description>Must be applied to record structs that implement or are used with content interfaces</description></item>
61
+
/// <item><description>The struct must have a <c>Name</c> property that matches the content item's identifier</description></item>
62
+
/// <item><description>Content items should be defined in static arrays where order is meaningful</description></item>
63
+
/// <item><description>Declaring the struct as <c>readonly</c> is optional but recommended for optimal performance</description></item>
64
+
/// <item><description>Particularly beneficial when the struct implements <see cref="INamed"/> and is used as a key type in <see cref="ISubContent{TKey, TValue}"/></description></item>
65
+
/// </list>
66
+
/// </remarks>
67
+
/// <example>
68
+
/// <code>
69
+
/// // Readonly version (recommended for best performance)
70
+
/// [Unique]
71
+
/// public readonly partial record struct Material(string Name, int Durability, Color Color) : INamed;
72
+
///
73
+
/// // Non-readonly version (still optimized with caching)
74
+
/// [Unique]
75
+
/// public partial record struct Material(string Name, int Durability, Color Color) : INamed;
76
+
///
77
+
/// public partial class Materials : IContent<Material>
78
+
/// {
79
+
/// public static Material[] All = [
80
+
/// new("Iron", 100, Color.Gray),
81
+
/// new("Gold", 50, Color.Yellow),
82
+
/// new("Diamond", 500, Color.White)
83
+
/// ];
84
+
/// }
85
+
///
86
+
/// // Usage with ISubContent for high-performance lookups:
87
+
/// public class MaterialProperties : ISubContent<Material, PropertyData>
88
+
/// {
89
+
/// public Dictionary<Material, PropertyData> ByKey { get; } = new()
90
+
/// {
91
+
/// [Materials.Iron] = new PropertyData(/* ... */),
92
+
/// [Materials.Gold] = new PropertyData(/* ... */),
93
+
/// // Fast dictionary operations due to optimized Material equality/hashing
94
+
/// };
95
+
///
96
+
/// public PropertyData this[Material key] => ByKey[key]; // O(1) lookup
97
+
/// }
98
+
///
99
+
/// // Generated code enables fast index-based equality:
100
+
/// var iron1 = materials.Iron;
101
+
/// var iron2 = materials.Get(MaterialsType.Iron);
102
+
/// var areEqual = iron1.Equals(iron2); // Uses index comparison, not all properties
0 commit comments