The W3C DOM Range objectsimilar in concept to the IE TextRange objectrepresents a sequence of zero or more rendered text characters in a document. When a text range consists of zero characters, it represents an insertion point between two characters (or before the first or after the last character of the document). The Range object automatically keeps track of the node and character offset references for the start and end points of the range, so its methods can copy existing content, delete the range's contents, or insert new contents (in node form) into the existing range while maintaining the integrity of the document tree at every step. Nodeness is important to the Range object, but most of those concerns are handled for you.

Returns Boolean true if the range's start and end points are at the same location, encompassing zero characters. A collapsed range can be located anywhere within the document.

Returns a reference to a document tree node that is the next outermost container that encompasses the current range's start and end points. If the start and end points are, themselves, in the same node (for example, the same text node), the commonAncestorContainer property returns a reference to that node's parent node. IE TextRange equivalent is parentElement( ).

Returns a reference to a document tree node that contains the current range's end point.

Returns an integer count of characters or nodes for the end point's location within the node reported by the endContainer property. If the endContainer is a text node, the endOffset property counts the number of characters to the right of the first character of that text node. If the endContainer is an element node, the endOffset property counts the number of nodes between the start of the containing node's content and the end point.

Returns a reference to a document tree node that contains the current range's start point.

Returns an integer count of characters or nodes for the start point's location within the node reported by the startContainer property. If the startContainer is a text node, the startOffset property counts the number of characters to the right of the first character of that text node. If the startContainer is an element node, the startOffset property counts the number of nodes between the start of the containing node's content and the start point. See endOffset for more details.

Returns a DocumentFragment node containing a copy of the contents from the current range. Any dangling nodes are resolved as part of the cloning process.

Returns a Range object that is a carbon copy of the current range, including references to associated containers. This method lets you preserve a copy of a Range object's specifications while creating a new Range object. Similar to the IE TextRange object's duplicate( ) method.

Shrinks the current range to an insertion point (start and end points are in the same node at the same offset). The Boolean parameter controls whether the range collapses to the start point (true) or end point (false) of the current range. A script working its way through a document (e.g., using the String.indexOf( ) method to search for the next instance of a string) usually collapses to the end point before shifting the end point to the end of the body to perform the next String.indexOf( ) search.

Returns an integer code indicating the relative positioning of one boundary point of the current range's against a boundary point of a different text range. In the simplest case, the two end points (one from each range) share the same ancestor container. In such a case, the first parameter determines which end points from the two ranges get compared. Use the constants supplied with every Range object, as shown in the following table.

A Netscape-only method that returns an integer code indicating the relative position of some other node with respect to the current range. Four plain-language constants are members of every Netscape Range object, and can be used for comparisons of values returned by the compareNode( ) method. Note that the returned values are from the point of view of the node passed as a parameter, rather than from that of the current range.

A Netscape-only method that returns an integer code indicating the relative position of some other node and offset within that node with respect to the current range. Note that the returned values are from the point of view of the node (more specifically, the point signified by the offset within the node) passed as parameters, rather than from that of the current range.

The createContextualFragment( ) method was initially designed as an alternative to the innerHTML convenience property (because the W3C DOM provides little in the way of support for content strings consisting of tags). This method accepts any stringincluding tagged contentas a parameter, and returns a DocumentFragment type of node, ready for appending or inserting into the document tree. Subsequent adoption of the innerHTML property by the Mozilla browser makes this method redundant, except that it is more consistent with the overall nodeness of the W3C DOM.

Removes the contents of the current text range from the document tree. If the range is an element node (e.g., with boundaries established via the selectNode( ) method), invoking deleteContents( ) on the range removes the node from the document tree and collapses the range. The Range object remains in memory, but without any content. If you want to capture the content prior to its deletion, do so with other Range object methods (such as cloneRange( ) and, when it works correctly, cloneContents( )).

Destroys the current Range object to the extent that invoking most methods on the object or accessing its properties throw a RangeException of type INVALID_STATE_ERR.

Returns a DocumentFragment node containing the contents of the current range, after removing the contents from the document tree. Not working in Netscape as of Version 6.2 except when the range boundaries are set via the selectNodeContents( ) method.

Inserts a node at the start of the current text range. Most useful when the range is already collapsed as a text insertion pointer. The node being inserted can be created fresh (via document.createElement( )) or fetched from elsewhere in the document tree, in which case it is removed from its old position and inserted into the current range. If you insert a text node adjacent to a spot that also happens to be an existing text node, you can wind up with two adjacent text nodes. Invoke the normalize( ) method on the parent to consolidate the text nodes.

Returns Boolean true if any part of the current range overlaps with the text or element node that is passed as a parameter. If your script detects an intersection, it can use the compareNode( ) method to obtain more detail about the intersection.

Returns Boolean true if the location denoted by the parameter values (a node in the document tree and an offset location within that node) is within the current range.

Sets the range's boundary points to encompass a node or just the node's contents. Despite the methods' names, no body text in the rendered document is highlighted.

Establish the document tree locations for the individual boundary points of an existing Range object. Similar to the IE TextRange object's setEndPoint( ) method. The mapping of a location relies upon a node reference and an offset value relative to that node's starting point and type. Offset values count child nodes when the nodeReference is an element node; they count characters when the nodeReference is a text node. To set a boundary at a node edge, the associated methods (setEndAfter( ) and three others) are more convenient.

Establish the document tree locations for the individual boundary points of an existing Range object with respect to a node's edges. These methods assume that you are interested in setting a range's boundaries to places immediately before or after an existing node, and not concerned with other kinds of offsets. Range boundaries do not have to be symmetrical, allowing you to specify the start boundary relative to one node and the end boundary relative to a completely different node later in the document.

Encapsulates the current range with a new container, usually a new element node created via the document.createElement( ) method. End points of the current range should have the same parent container prior to applying this method.

Returns a string of the body content contained by the range. No tags or attributes accompany the returned value.