Range#
Range.compareBoundaryPoints()#
Metoda compareBoundaryPoints() zwraca liczbę całkowitą (wartość -1, 0, 1) zależną od tego, czy punkt graniczny w danym zakresie znajduje się przed, jest równy, lub znajduje się za punktem granicznym w przekazanym zakresie (drugi argument). Wybór porównywanych punktów granicznych ustala się za pomocą przekazanej liczby całkowitej (pierwszy argument).
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var value = range.compareBoundaryPoints(how, sourceRange);gdzie poszczególne człony oznaczają:
- value - liczba całkowita, której wartość oznacza relację między punktami granicznymi w porównywanych zakresach. Dostępne są następujące możliwości:
-1- punkt graniczny w range znajduje się przed punktem granicznym w sourceRange.0- punkt graniczny w range jest równy punktowi granicznemu w sourceRange.1- punkt graniczny w range znajduje się za punktem granicznym w sourceRange.
- range - zakres będący obiektem kontekstu.
- how - liczba całkowita, której wartość oznacza relację między konkretnymi węzłami granicznymi w obydwu zakresach. Najwygodniej skorzystać z odpowiedniej stałej.
- sourceRange - referencja do drugiego zakresu, względem którego porównywane są punkty graniczne.
Algorytm wywołania metody compareBoundaryPoints(how, sourceRange) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Jeśli hownie ma jednej z wartości wskazywanych przez START_TO_START, START_TO_END, END_TO_END lub END_TO_START, to zrzuć wyjątek
"NotSupportedError". - Jeśli korzeń w obiekcie kontekstu nie jest taki sam jak korzeń w sourceRange, to zrzuć wyjątek
"WrongDocumentError". Jeśli how ma wartość:
- START_TO_START:
Niech this point będzie początkiem w obiekcie kontekstu.
Niech other point będzie początkiem w sourceRange.
- START_TO_END:
Niech this point będzie końcem w obiekcie kontekstu.
Niech other point będzie początkiem w sourceRange.
- END_TO_END:
Niech this point będzie końcem w obiekcie kontekstu.
Niech other point będzie końcem w sourceRange.
- END_TO_START:
Niech this point będzie początkiem w obiekcie kontekstu.
Niech other point będzie końcem w sourceRange.
Jeśli pozycja this point względem other point jest:
Przypominam tylko, że porównywany jest punkt graniczny w danym zakresie względem punktu granicznego w przekazanym zakresie. Trzeba uważać na nazwy stałych, gdyż pierwsza jej część, ta po lewej stronie symbolu "_", dotyczy punktu granicznego w przekazanym zakresie, natomiast część po prawej stronie dotyczy danego zakresu, na którym metoda compareBoundaryPoints() jest wywoływana. Wszystkie te niuanse bardzo ładnie prezentuje powyższy algorytm, ale dla szybszej orientacji umieściłem kompaktowe opisy w wykazie stałych.
Prosty przykład:
<script>
// Tworzymy nowe zakresy
var range1 = document.createRange();
range1.setEnd(document.firstChild.firstChild, 0);
var range2 = document.createRange();
range2.setStart(document.firstChild, 0);
document.write(range1.compareBoundaryPoints(Range.START_TO_START, range2)); // -1 (początek 'range1' przed początkiem 'range2')
document.write("<br>");
document.write(range1.compareBoundaryPoints(Range.START_TO_END, range2)); // 1 (koniec 'range1' za początkiem 'range2')
document.write("<br>");
document.write(range1.compareBoundaryPoints(Range.END_TO_END, range2)); // 1 (koniec 'range1' za końcem 'range2')
document.write("<br>");
document.write(range1.compareBoundaryPoints(Range.END_TO_START, range2)); // -1 (początek 'range1' przed końcem 'range2')
document.write("<br><br>");
document.write(range1.compareBoundaryPoints(0, range2)); // -1 (początek 'range1' przed początkiem 'range2')
document.write("<br>");
document.write(range1.compareBoundaryPoints(1, range2)); // 1 (koniec 'range1' za początkiem 'range2')
document.write("<br>");
document.write(range1.compareBoundaryPoints(2, range2)); // 1 (koniec 'range1' za końcem 'range2')
document.write("<br>");
document.write(range1.compareBoundaryPoints(3, range2)); // -1 (początek 'range1' przed końcem 'range2')
document.write("<br><br>");
document.write(range1.compareBoundaryPoints(0, range1)); // 0 (początek 'range1' równy początkowi 'range1')
document.write("<br>");
document.write(range1.compareBoundaryPoints(1, range1)); // 1 (koniec 'range1' za początkiem 'range1')
document.write("<br>");
document.write(range1.compareBoundaryPoints(2, range1)); // 0 (koniec 'range1' równy końcowi 'range1')
document.write("<br>");
document.write(range1.compareBoundaryPoints(3, range1)); // -1 (początek 'range1' przed końcem 'range1')
document.write("<br><br>");
try{ // Sprawdzamy zakres z innym korzeniem
var newEl = document.createElement("div");
var range3 = document.createRange();
range3.setStart(newEl, 0);
document.write(range1.compareBoundaryPoints(0, range3));
}
catch(e){
document.write("Przekazanie do metody compareBoundaryPoints() zakresu z innym korzeniem zrzuca błąd:" + "<br>");
document.write(e); // opis zależny od przeglądarki
document.write("<br>");
document.write(e.constructor); // function DOMException() { [native code] }
}
</script>Składnia Web IDL#
interface Range { short compareBoundaryPoints(unsigned short how, Range sourceRange); }