FSet has several operations that combine two collections into a third: union, intersection, map-union, map-intersection,
bag union, bag
intersection, bag-sum, and bag-product.
All of these implement left preference: for any case where equal elements or map keys
appear in both collections, the result will use the instance from the left operand. This also
applies to equal values associated with a given map key. i’m emphasizing “equal” here,
because it’s important to understand that the left preference rule is not about what value is
returned, in the sense of values that FSet can distinguish. Rather, it’s about what instance
is chosen to represent a value in the cases where FSet is given values that compare equal.
That is, it applies only when the argument collections contain distinct Lisp objects (distinguished
by eq) that nonetheless compare equal. If that situation doesn’t arise in your code, left
preference will have no effect.
The motivation for FSet offering this guarantee has to do with the fact that if you’re using
define-equality-slots for your class, there’s no requirement that you include all the slots
of the class. But if you don’t, the non-equality slots function as metadata: they’re not part of
the values represented, but they get carried around with those values anyway.
Thus, if you were, for instance, unioning two sets of instances of such a class, and you had some instances that had been decorated with metadata and some that had been newly constructed, you would probably want the union to retain the ones with the metadata and discard the new ones, in cases where there was overlap. Left preference gives you a way to do that.
I must add that I don’t necessarily recommend doing things this way. It’s probably cleaner to take the equality slots, pull them out into a new class — so that class can have the property that all of its slots are equality slots — and then use a separate map to relate instances of that smaller class to the metadata you want to associate with them. Then you won’t have to worry about which instances of the class are which; they’ll be equivalent. But FSet lets you do it either way.