We have a bit of a tricky time talking about sets and dictionaries, because while they don't guarantee a particular ordering (the elements may appear to be in any order regardless of how you add them, and that order may change between different executions of the same program), individual instances are ordered: If you iterate the elements of a single dictionary multiple times, you get the elements in the same order every time.

elementsEqual is a method from the Sequence protocol that simply iterates over two sequences and compares the elements of each as they're produced, and its semantic guarantee is that it returns true when two sequences have the same elements in the same order. It isn't a protocol requirement, so Dictionary and Set can't truly customize their implementations in a way that would work consistently.

The == operator has a different semantic guarantee: it returns true when its two operands are equal, which in Swift means that they are substitutable. Individual types are free to figure out what substitutable means for them, and the order of the elements isn't important when determining whether two sets or dictionaries are equal. Therefore, == for dictionaries is written using a different algorithm than elementsEqual—it iterates over one dictionary's keys, then makes sure that both dictionaries have the same value for that key.

We definitely need better documentation on elementsEqual, clearly indicating the semantics and probably calling out that these aren't a good idea to use for sets and dictionaries. Another step would be to make elementsEqual a protocol requirement, so it could be customized, but that opens up some other questions: Should startsWith and lexicographicallyPrecedes also be customized? Is it a problem if elementsEqual returns true, but the .first element of two dictionaries is different? etc.

cc @airspeedswift

Agree with everything @natecook1000 is saying here, and believe a documentation fix is the only appropriate fix.

Alternatives would involve constructing a more elaborate scheme where we had an OrderedSequence that declared that ordering was meaningful, and conform some collections to that but not others. But this would lead to all sorts of other complications and I doubt it would be worth it. Dynamically dispatching elementsEqual for Dictionary to perform == also would be inconsistent in other ways – it wouldn't work for comparing an arbitrary "ordered" Sequence to a Dictionary or comparing, say, Dictionary.Keys to a Set.

@natecook1000 and @airspeedswift Certainly warning me off in the documentation would have helped, though I still rather wish the compiler would alert me (or even stop me) when I try to use `elementsEqual` on a dictionary (or set). Thanks!