Range.compareBoundaryPoints() is counter-intuitive

I've just written the following paragraph for the description of
Range.compareBoundaryPoints() in my JavaScript book.  If anyone
disagrees with my assessment of compareBoundaryPoints() as
counter-intuitive, please help me understand why it is not.  I believe
I'm describing the spec as it is written and as it is implemented by
Mozilla.  (Note, that I'm not proposing that the spec be modified in
anyway: I just want to verify that I'm correctly interpreting its
counter-intuitive nature.)

	David Flanagan
--------------------------

      The return value of this method is a number that specifies the
      relative position of this Range to the specified
      <replaceable>sourceRange</replaceable>.  Therefore, you might
      expect the Range constants for the <replaceable>how</replaceable>
      argument to specify the boundary point for this range first and
      the boundary point for <literal>sourceRange</literal> second.
      Counter-intuitively, however, the sense of the return value and
      the <replaceable>how</replaceable> constants are opposite of one
      another, and the <literal>Range.START_TO_END</literal> contant
      specifies a comparison of the <emphasis>end</emphasis> point of
      this range with the <emphasis>start</emphasis> point of the
      specified <replaceable>sourceRange</replaceable>.  Similarly, the
      <literal>Range.END_TO_START</literal> constant specifies a
      comparison of the <emphasis>start</emphasis> point of this range
      with the <emphasis>end</emphasis> point of the specified range.

Received on Sunday, 12 August 2001 18:37:54 UTC