Include example of Built Collections comparison

[kwill39]

resolves #277

[kwill39]

@davidmorgan, do you think I should go through the effort of expanding the ". . ." in the code example with an actual implementation showing the code for comparison? In the second half of the code example, I could copy/paste the implementation from the first half, but then comment that it gives a runtime/compilation error. (not sure yet which error it gives, I'll have to test it out personally to see)

[davidmorgan]

Thanks K! Some suggestions:

I think the nested collections may be distracting, how about instead using a custom type so that the example can talk about operator==?

e.g.

BuiltList<CustomType> list1;
BuiltList<CustomType> list2;

then say these are deep comparable, meaning they will be compared by calling the operator== implementation of CustomType. In particular, if it compares by value, they will be compared by value.

For the "doesn't compare" example, how about

BuiltSet<CustomType> set1;

then remark that it will never be equal to list1 or list2, even if the contents are identical, because it is a different collection type?

Thanks.

[kwill39]

Hey, @davidmorgan 👋. What do you think about the changes I just introduced?

[davidmorgan]

I think we want to keep it short--there are quite a few sections on the page for readers to get through. Maybe focus more on examples? Maybe something like:

Built Collections do a deep comparison against other Built Collections of the same type using Dart's equality operator (==).

// true: same contents according to `int.operator==`, `MyClass.operator==`
BuiltList([1, 2, 3]) == BuiltList([1, 2, 3]);
BuiltList([MyClass(1), MyClass(2)]) == BuiltList([MyClass(1), MyClass(2)]);

// false: BuiltList and BuiltSet are never equal
BuiltList([1, 2, 3]) == BuiltSet([1, 2, 3]); 
// false: different contents according to `int.operator==`
BuiltList([1, 2, 3]) == BuiltList([2, 3, 4]); 

[kwill39]

@davidmorgan, I replaced the example with your example code. What do you think?

[davidmorgan]

Looks good, thanks!