In order to access this site you need to enable JavaScript!

You are here: Reference > JavaScript > client-side > selection and ranges > methods > compareBoundaryPoints (Range)

compareBoundaryPoints method (Range)

Browser support:

9

Compares the placement of the start or end point of the current Range object with the placement of the start or end point of another Range object.

Note: The Range object and its compareBoundaryPoints method are supported in Internet Explorer from version 9.

Unfortunately, the compareBoundaryPoints method works differently in Safari earlier than version 4 than the W3C standard specifies (compareBoundaryPoints). See the description of the type parameter below for details.
To fix this bug, you need a small workaround. A possible solution can be found in Example 2.

In Internet Explorer before version 9 (and in newer ones as well), the compareEndPoints method provides similar functionality.

If you want to compare the placement of two nodes not two Range objects, use the compareDocumentPosition.

Syntax:

object.compareBoundaryPoints (type, rangeToCompare);

You can find the related objects in the Supported by objects section below.

Parameters:

type

Required. Integer that specifies the two boundary points to compare.

Predefined constants are available for the possible values of this parameter, in the scope of the Range object. See the page for the Range object for details.

One of the following values (the value of a predefined constant appears in parentheses after the constant):

START_TO_START (0)

Compares the start point of the current Range to the start point of the Range specified by the rangeToCompare parameter.

START_TO_END (1)

Compares the start point of the current Range to the end point of the Range specified by the rangeToCompare parameter in Safari earlier than version 4.
Compares the end point of the current Range to the start point of the Range specified by the rangeToCompare parameter in Firefox, Internet Explorer, Opera, Google Chrome and in Safari from version 4.

END_TO_END (2)

Compares the end point of the current Range to the end point of the Range specified by the rangeToCompare parameter.

END_TO_START (3)

Compares the end point of the current Range to the start point of the Range specified by the rangeToCompare parameter in Safari earlier than version 4.
Compares the start point of the current Range to the end point of the Range specified by the rangeToCompare parameter in Firefox, Internet Explorer, Opera, Google Chrome and in Safari from version 4.

rangeToCompare

Required. Specifies the Range object to compare with.

Return value:

Integer that retrieves the placement of the two points in the DOM hierarchy.

One of the following values:

-1	The first point is before the second point.
0	The two boundary points are located at the same position.
1	The first point is after the second point.

Example HTML code 1:

This example illustrates the use of the compareBoundaryPoints method. For a similar example in Internet Explorer before version 9, see the page for the compareEndPoints method.

<head>
    <script type="text/javascript">
        function TestPlacement () {
            var boldText = document.getElementById ("boldText");

            if (document.createRange) {         // all browsers, except IE before version 9
                var boldRange = document.createRange ();
                    // select the contents of the text node inside the bold tag
                    // it is the smallest range that contains the entire text 
                boldRange.selectNodeContents (boldText.firstChild);

                var selection = window.getSelection ();
                if (selection.rangeCount > 0) {
                    var selRange = selection.getRangeAt (0);
                    if (selRange.compareBoundaryPoints (Range.START_TO_END, boldRange) <= 0) {
                        alert ("The selection is before the bold text.");
                    }
                    else {
                        if (selRange.compareBoundaryPoints (Range.END_TO_START, boldRange) >= 0) {
                            alert ("The selection is after the bold text.");
                        }
                        else {
                            var startPoints = selRange.compareBoundaryPoints (Range.START_TO_START, boldRange);
                            var endPoints = selRange.compareBoundaryPoints (Range.END_TO_END, boldRange);

                            if (startPoints < 0) {
                                if (endPoints < 0) {
                                    alert ("The selection is before the bold text but intersects it.");
                                }
                                else {
                                    alert ("The selection contains the bold text.");
                                }
                            }
                            else {
                                if (endPoints > 0) {
                                    alert ("The selection is after the bold text but intersects it.");
                                }
                                else {
                                    if (startPoints == 0 && endPoints == 0) {
                                        alert ("The selected text and the bold text are the same.");
                                    }
                                    else {
                                        alert ("The selection is inside the bold text.");
                                    }
                                }
                            }
                        }
                    }
                }
                else {
                    alert ("Please select some content!");
                }
            }
            else {
                alert ("Your browser does not support this example!");
            }
        }
    </script>
</head>
<body>
    Select some text on this page and use the following button to get information about 
    the placement of the <b id="boldText">bold text</b> relative to the selection.
    <br /><br />
    <button onclick="TestPlacement ();">Test placement</button>
</body>

Copy Code

Preview

Syntax Highlighter

Did you find this example helpful? yes no

Example HTML code 2:

This example fixes the bug of the compareBoundaryPoints method that exists in Safari earlier than version 4:

<head>
    <script type="text/javascript">
        if (typeof (Range) != "undefined") {
                // The compareBoundaryPointsEx method fixes the bug in the compareBoundaryPoints method
            Range.prototype.compareBoundaryPointsEx = function (type, rangeToCompare) {
                if (this.bugInCompareBoundary === undefined) {
                    var bodyRange = document.createRange ();
                    bodyRange.selectNode (document.body);
                    var result = bodyRange.compareBoundaryPoints (Range.START_TO_END, bodyRange);
                    Range.prototype.bugInCompareBoundary = (result == -1);
                }

                if (this.bugInCompareBoundary) {    // in Safari earlier than version 4
                    switch (type) {
                    case Range.START_TO_END:
                        type = Range.END_TO_START;
                        break;
                    case Range.END_TO_START:
                        type = Range.START_TO_END;
                        break;
                    };
                }
                return this.compareBoundaryPoints (type, rangeToCompare);
            };
        }

        function Test () {
            var testNode = document.getElementById ("test");

            if (document.createRange) {
                var testRange = document.createRange ();
                testRange.selectNode (testNode);

                var message = "";
                var result = testRange.compareBoundaryPointsEx (Range.START_TO_END, testRange);
                message += "START_TO_END: " + result + "<br />";
                result = testRange.compareBoundaryPointsEx (Range.END_TO_START, testRange);
                message += "END_TO_START: " + result + "<br />";

                var info = document.getElementById ("info");
                info.innerHTML = message;
            }
            else {
                alert ("Your browser does not support this example!");
            }
        }
    </script>
</head>
<body>
    <span id="test">The start and end points of this element will be tested.</span>
    <br /><br />
    <button onclick="Test ();">Test compareBoundaryPointsEx method</button>
    <br /><br />
    The required result is:<br />
    START_TO_END: 1<br />
    END_TO_START: -1<br />
    The result of the test:<br />
    <div id="info" style="background-color:#d0e0c0;"></div>
</body>