6 Package Range APIs for C

Package Range contains APIs for two interfaces.

This chapter contains the following sections:

DocumentRange Interface
Range Interface

DocumentRange Interface

Table 6-1 summarizes the methods available through the DocumentRange interface.

CAXML5836 Table 6-1 Summary of DocumentRange Methods; Package Range

Function	Summary
XmlDomCreateRange()	Create `Range` object.

CAXML5837

XmlDomCreateRange()

The only one method of DocumentRange interface, used to create a Range object.

CAXML5838Syntax

xmlrange* XmlDomCreateRange(
   xmlctx *xctx, 
   xmlrange *range, 
   xmldocnode *doc);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	existing NodeIterator, or `NULL` to allocate new
doc	IN	document to which the new `Range` is attached

CAXML5839Returns

(xmlrange *) original or new Range object.

CAXML5840

Range Interface

Table 6-2 summarizes the methods available through the Range interface.

CAXML5841 Table 6-2 Summary of Range Methods; Package Range

Function	Summary
XmlDomRangeClone()	Clone a range.
XmlDomRangeCloneContents()	Clone contents selected by a range.
XmlDomRangeCollapse()	Collapse range to either start point or end point.
XmlDomRangeCompareBoundaryPoints()	Compare boundary points of two ranges.
XmlDomRangeDeleteContents()	Delete content selected by a range.
XmlDomRangeDetach()	Detach a range.
XmlDomRangeExtractContents()	Extract contents selected by a range.
XmlDomRangeGetCollapsed()	Return whether the range is collapsed.
XmlDomRangeGetCommonAncestor()	Return deepest common ancestor node of two boundary points.
XmlDomRangeGetDetached()	Return whether the range is detached.
XmlDomRangeGetEndContainer()	Return range end container node.
XmlDomRangeGetEndOffset()	Return range end offset.
XmlDomRangeGetStartContainer()	Return range start container node.
XmlDomRangeGetStartOffset()	Return range start offset.
XmlDomRangeIsConsistent()	Return whether the range is consistent.
XmlDomRangeSelectNode()	Select a node as a range.
XmlDomRangeSelectNodeContents()	Define range to select node contents.
XmlDomRangeSetEnd()	Set the end point.
XmlDomRangeSetEndBefore()	Set the end point before a node.
XmlDomRangeSetStart()	Set the start point.
XmlDomRangeSetStartAfter()	Set the start point after a node.
XmlDomRangeSetStartBefore()	Set the start point before a node.

CAXML5842

XmlDomRangeClone()

Clone a Range. Clones the range without affecting the content selected by the original range. Returns NULL if an error.

CAXML5843Syntax

xmlrange* XmlDomRangeClone(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5844Returns

(xmlrange *) new range that clones the old one

CAXML5845

XmlDomRangeCloneContents()

Clone contents selected by a range. Clones but does not delete contents selected by a range. Performs the range consistency check and sets retval to an error code if an error.

CAXML5846Syntax

xmlnode* XmlDomRangeCloneContents(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5847Returns

(xmlnode *) cloned contents

CAXML5848

XmlDomRangeCollapse()

Collapses the range to either start point or end point. The point where it is collapsed to is assumed to be a valid point in the document which this range is attached to.

CAXML5849Syntax

xmlerr XmlDomRangeCollapse(
   xmlctx *xctx, 
   xmlrange *range, 
   boolean tostart);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
tostart	IN	indicates whether to collapse to start (`TRUE`) or to end (`FALSE`)

CAXML5850Returns

(xmlerr) numeric return code

CAXML5851

XmlDomRangeCompareBoundaryPoints()

Compares two boundary points of two different ranges. Returns -1,0,1 depending on whether the corresponding boundary point of the range (range) is before, equal, or after the corresponding boundary point of the second range (srange). It returns ~(int)0 if two ranges are attached to two different documents or if one of them is detached.

CAXML5852Syntax

sb4 XmlDomRangeCompareBoundaryPoints(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlcmphow how, 
   xmlrange *srange, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
how	IN	`xmlcmphow` value; how to compare
srange	IN	range object with which to compare
xerr	OUT	numeric return code

CAXML5853Returns

(sb4) strcmp-like comparison result

CAXML5854

XmlDomRangeDeleteContents()

Deletes content selected by a range. Performs the range consistency check and sets retval to an error code if an error.

CAXML5855Syntax

xmlerr XmlDomRangeDeleteContents(
   xmlctx *xctx, 
   xmlrange *range);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object

CAXML5856Returns

(xmlerr) numeric return code

CAXML5857

XmlDomRangeDetach()

Detaches the range from the document and places it (range) in invalid state.

CAXML5858Syntax

xmlerr XmlDomRangeDetach(
   xmlctx *xctx, 
   xmlrange *range);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object

CAXML5859Returns

(xmlerr) numeric return code

CAXML5860

XmlDomRangeExtractContents()

Extract contents selected by a range. Clones and deletes contents selected by a range. Performs the range consistency check and sets retval to an error code if an error.

CAXML5861Syntax

xmlnode* XmlDomRangeExtractContents(
   xmlctx *xctx, 
   xmlrange *range,
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5862Returns

(xmlnode *) extracted

CAXML5863

XmlDomRangeGetCollapsed()

Returns TRUE if the range is collapsed and is not detached, otherwise returns FALSE.

CAXML5864Syntax

boolean XmlDomRangeGetCollapsed(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5865Returns

(boolean) TRUE if the range is collapsed, FALSE otherwise

CAXML5866

XmlDomRangeGetCommonAncestor()

Returns deepest common ancestor node of two boundary points of the range if the range is not detached, otherwise returns NULL. It is assumed that the range is in a consistent state.

CAXML5867Syntax

xmlnode* XmlDomRangeGetCommonAncestor(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5868Returns

(xmlnode *) deepest common ancestor node [or NULL]

CAXML5869

XmlDomRangeGetDetached()

Return whether the range is detached. Returns TRUE if the range is detached and is not NULL. Otherwise returns FALSE.

CAXML5870Syntax

ub1 XmlDomRangeGetDetached(
   xmlctx *xctx, 
   xmlrange *range);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object

CAXML5871Returns

(ub1) TRUE if the range is detached, FALSE otherwise

CAXML5872

XmlDomRangeGetEndContainer()

Returns range end container node if the range is not detached, otherwise returns NULL.

CAXML5873Syntax

xmlnode* XmlDomRangeGetEndContainer(
   xmlctx *xctx, 
   xmlrange *range,
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5874Returns

(xmlnode *) range end container node [or NULL]

CAXML5875

XmlDomRangeGetEndOffset()

Returns range end offset if the range is not detached, otherwise returns ~(ub4)0 [the maximum ub4 value].

CAXML5876Syntax

ub4 XmlDomRangeGetEndOffset(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5877Returns

(ub4) range end offset [or ub4 maximum]

CAXML5878

XmlDomRangeGetStartContainer()

Returns range start container node if the range is valid and is not detached, otherwise returns NULL.

CAXML5879Syntax

xmlnode* XmlDomRangeGetStartContainer(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5880Returns

(xmlnode *) range start container node

CAXML5881

XmlDomRangeGetStartOffset()

Returns range start offset if the range is not detached, otherwise returns ~(ub4)0 [the maximum ub4 value].

CAXML5882Syntax

ub4 XmlDomRangeGetStartOffset(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5883Returns

(ub4) range start offset [or ub4 maximum]

CAXML5884

XmlDomRangeIsConsistent()

Return whether the range is consistent. Returns TRUE if the range is consistent: both points are under the same root and the start point is before or equal to the end point. Otherwise returns FALSE.

CAXML5885Syntax

boolean XmlDomRangeIsConsistent(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
xerr	OUT	numeric return code

CAXML5886Returns

(ub1) TRUE if the range is consistent, FALSE otherwise

CAXML5887

XmlDomRangeSelectNode()

Sets the range end point and start point so that the parent node of this node becomes the container node, and the offset is the offset of this node among the children of its parent. The range becomes collapsed. It is assumed that the node is a valid node of its document. If the range is detached, it is ignored, and the range becomes attached.

CAXML5888Syntax

xmlerr XmlDomRangeSelectNode(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
node	IN	XML node

CAXML5889Returns

(xmlerr) numeric return code

CAXML5890

XmlDomRangeSelectNodeContents()

Sets the range start point to the start of the node contents and the end point to the end of the node contents. It is assumed that the node is a valid document node. If the range is detached, it is ignored, and the range becomes attached.

CAXML5891Syntax

xmlerr XmlDomRangeSelectNodeContents(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
node	IN	XML node

CAXML5892Returns

(xmlerr) numeric return code

CAXML5893

XmlDomRangeSetEnd()

Sets the range end point. If it has a root container other than the current one for the range, the range is collapsed to the new position. If the end is set to be at a position before the start, the range is collapsed to that position. Returns xmlerr value. according to the description where this type is defined. It is assumed that the start point of the range is a valid start point.

CAXML5894Syntax

xmlerr XmlDomRangeSetEnd(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node, 
   ub4 offset);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
node	IN	XML node
offset	IN	ending offset

CAXML5895Returns

(xmlerr) numeric return code

CAXML5896

XmlDomRangeSetEndBefore()

Sets the range end point before a node. If it has a root container other than the current one for the range, the range is collapsed to the new position. If the before node sets the end to be at a position before the start, the range is collapsed to new position. Returns xmlerr value according to the description where this type is defined. It is assumed that the start point of the range is a valid start point.

CAXML5897Syntax

xmlerr XmlDomRangeSetEndBefore(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
node	IN	XML node

CAXML5898Returns

(xmlerr) numeric return code

CAXML5899

XmlDomRangeSetStart()

Sets the range start point. If it has a root container other than the current one for the range, the range is collapsed to the new position. If the start is set to be at a position after the end, the range is collapsed to that position. Returns xmlerr value according to the description where this type is defined. It is assumed that the end point of the range is a valid end point.

CAXML5900Syntax

xmlerr XmlDomRangeSetStart(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node, 
   ub4 offset);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
node	IN	XML node
offset	IN	starting offset

CAXML5901Returns

(xmlerr) numeric return code

CAXML5902

XmlDomRangeSetStartAfter()

Sets the range start point after a node. If it has a root container other than the current one, the range is collapsed to the new position. If the previous node sets the start after the end, the range is collapsed to a new position. It is assumed that the end point of the range is a valid end point.

CAXML5903Syntax

xmlerr XmlDomRangeSetStartAfter(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
node	IN	XML node

CAXML5904Returns

(xmlerr) numeric return code

CAXML5905

XmlDomRangeSetStartBefore()

Sets the range start point before a node. If it has a root container other than the current one, the range is collapsed to the new position with offset 0. If the previous node sets the start after the end, the range is collapsed to a new position. It is assumed that the end point of the range is a valid end point.

CAXML5906Syntax

xmlerr XmlDomRangeSetStartBefore(
   xmlctx *xctx, 
   xmlrange *range, 
   xmlnode *node);

Parameter	In/Out	Description
xctx	IN	XML context
range	IN	range object
node	IN	XML node

CAXML5907Returns

(xmlerr) numeric return code