Measuring Distance
The Distance primitive (0x000B) is used to find the distance between two objects, where one of the objects is typically a Sim.
Common examples include finding the nearest sink/toilet to a Sim. Players/Modders then get confused when the code does not perform as expected, as they fail to understand that the primitive returns the absolute distance in a straight line between the two objects and NOT the length of the path a Sim must traverse between the objects.
The distance between the Sim and the plain purple carpet square is only 1, as the primitive ignores the wall between them. If there was a sink on each of the coloured tiles, the Sim would walk past two nearer sinks (at 8 and 6) to use the nearest one at 1!
Note also that the game considers different levels to be 10 tiles apart, which, IMHO, is not enough and explains why a Sim will walk up a level on a larger (community) lot to use a toilet or a till, rather than one on the same level.
When writing code to find the nearest of anything, it is probably best to first look for it within the same room, then on the same level, then anywhere. One way to do this would be to add 25 to the absolute distance if the object is not in the same room, and 100 if not on the same level (code to find an object's level is available here).
Hope these notes are of use to someone. Enjoy!