CharacterData Interface

Table 4-2 summarizes the methods of available through the CharacterData interface.

XmlDomAppendData

Append a string to the end of a CharacterData node's data. If the node is not Text, Comment or CDATA, or if the string to append is NULL, does nothing. The appended data should be in the data encoding. It will not be verified, converted, or checked.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and manager by the user, they are responsible for freeing it, which is why it is returned.

void XmlDomAppendData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data, 
   oratext **old)

xctx

IN

node

IN

data

IN

old

OUT

XmlDomDeleteData

Remove a range of characters from a CharacterData node's data. If the node is not text, comment or CDATA, or if the offset is outside of the original data, does nothing. The offset is zero-based, so offset zero refers to the start of the data. Both offset and count are in characters, not bytes. If the sum of offset and count exceeds the data length then all characters from offset to the end of the data are deleted.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.

void XmlDomDeleteData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext **old)

xctx

IN

node

IN

offset

IN

count

IN

old

OUT

XmlDomGetCharData

Returns the data for a CharacterData node (type text, comment or CDATA) in the data encoding. For other node types, or if there is no data, returns NULL.

oratext* XmlDomGetCharData(
   xmlctx *xctx,
   xmlnode *node)

xctx

IN

node

IN

(oratext *) character data of node [data encoding]

XmlDomGetCharDataLength

Returns the length of the data for a CharacterData node, type Text, Comment or CDATA) in characters, not bytes. For other node types, returns 0.

ub4 XmlDomGetCharDataLength(
   xmlctx *xctx,
   xmlnode *cdata)

xctx

IN

node

IN

(ub4) length in characters, not bytes, of node's data

XmlDomInsertData

Insert a string into a CharacterData node's data at the specified position. If the node is not Text, Comment or CDATA, or if the data to be inserted is NULL, or the offset is outside the original data, does nothing. The inserted data must be in the data encoding. It will not be verified, converted, or checked. The offset is specified as characters, not bytes. The offset is zero-based, so inserting at offset zero prepends the data.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it (which is why it's returned).

void XmlDomInsertData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   oratext *arg,
   oratext **old)

xctx

IN

node

IN

offset

IN

arg

IN

old

OUT

XmlDomReplaceData

Replaces a range of characters in a CharacterData node's data with a new string. If the node is not text, comment or CDATA, or if the offset is outside of the original data, or if the replacement string is NULL, does nothing. If the count is zero, acts just as XmlDomInsertData. The offset is zero-based, so offset zero refers to the start of the data. The replacement data must be in the data encoding. It will not be verified, converted, or checked. The offset and count are both in characters, not bytes. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced.

The new node data will be allocated and managed by DOM, but if the previous node value was allocated and managed by the user, they are responsible for freeing it, which is why it is returned.

void XmlDomReplaceData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset, 
   ub4 count,
   oratext *arg,
   oratext **old)

xctx

IN

node

IN

offset

IN

count

IN

arg

IN

old

OUT

XmlDomSetCharData

Sets data for a CharacterData node (type text, comment or CDATA), replacing the old data. For other node types, does nothing. The new data is not verified, converted, or checked; it should be in the data encoding.

void XmlDomSetCharData(
   xmlctx *xctx,
   xmlnode *node,
   oratext *data)

xctx

IN

node

IN

data

IN

XmlDomSubstringData

Returns a range of character data from a CharacterData node, type Text, Comment or CDATA. For other node types, or if count is zero, returns NULL. Since the data is in the data encoding, offset and count are in characters, not bytes. The beginning of the string is offset 0. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned.

The substring is permanently allocated in the node's document's memory pool. To free the substring, use XmlDomFreeString.

oratext* XmlDomSubstringData(
   xmlctx *xctx,
   xmlnode *node,
   ub4 offset,
   ub4 count)

xctx

IN

node

IN

offset

IN

count

IN

(oratext *) specified substring.